1.. _rfc-70: 2 3============================================================================ 4RFC 70: Guessing output format from output file name extension for utilities 5============================================================================ 6 7======================= ========================== 8Author: Even Rouault 9Contact: even.rouault@spatialys.com 10Started: Aug 2017 11Status: Adopted, implemented 12Implementation version: 2.3.0 13======================= ========================== 14 15Summary 16------- 17 18This proposal is to add syntaxic sugar to make GDAL and OGR command line 19utilities, so they take into account the extension of the output 20filename to guess which output driver to use, when it is not explicitly 21specified with -f / -of switch. 22 23Motivation 24---------- 25 26Currently command line utilities require to explicitly specify the 27output format when not wishing to use the default format (generally 28GeoTIFF for raster, and Shapefile for vector). But this is rather 29counter-intuitive. For example "gdal_translate in.tif out.png" will 30generate a GeoTIFF, and "ogr2ogr out.gpkg in.shp" a shapefile. So you 31have to specify respectively -of PNG and -f GPKG to get the expected 32result. 33 34Guessing the output format from the extension of the output filename is 35for example a behavior found in ImageMagick convert utility, or in 36OpenJPEG opj_compress/opj_decompress utilities. 37 38Changes in C/C++ and Python utilities 39------------------------------------- 40 41Command line utilities, when neither -f nor -of are specified (note: 42since r39878 both switches can be indifferently used), will loop through 43the registered drivers and check if one or several drivers, with output 44capabilities, declare to recognize the extension of the output filename. 45 46- When one and only one driver declares this extension (.tif, .png, 47 .jpg etc), it will be used automatically 48- When several drivers declare this extension (for example KML and 49 LIBKML for .kml), the utility will select the first registered driver 50 (except netCDF instead of GMT for .nc files), and a warning is 51 emitted specifying which driver is used 52- When no driver declares this extension, and the extension is not 53 empty (e.g a .mpg filename), the utility will error out 54 55For completeness: 56 57- When there's no extension, and no prefix is recognized (see below), 58 the default output driver will be silently used, as currently 59 60Since at least GDAL 1.10, the base of this logic already exists since a 61warning is emitted for C/C++ utilities, when the extension of the output 62format is known to be recognized by another driver than the default 63output driver. 64 65Similarly, for vector output, if doing something like "ogr2ogr 66PG:dbname=mydb out.shp", a PG:dbname=mydb directory is created with 67shapefiles, instead of ingesting the shapefile into PostgreSQL. A 68warning is emitted in that case since the PG driver declares the PG: 69prefix in its metadata. The new behavior will be to imply the -update 70switch in such situation. 71 72When the utilities are available as library functions (GDALTranslate(), 73etc.), output format guessing will also be applied if the -f/-of switch 74is not specified 75 76Changes in SWIG bindings 77------------------------ 78 79For librarified utilities (gdal.Translate, etc.), the format argument 80now defaults to None. 81 82Potential issues 83---------------- 84 85There might be some fragility with the new logic in the situation where 86a GDAL version has only one driver that supports extension xxx, but a 87later version adds another driver that also supports extension xxx (or 88another distribution of the same version has a plugin that handles xxx). 89So scripts that did "gdal_translate in out.xxx" would now error out in 90the next version since several drivers are available. 91 92Bottom line: always specify the output driver when 93reliability/reproducibility is desired. 94 95This RFC mostly helps for interactive conversions where the less you 96type the better. 97 98Backward compatibility 99---------------------- 100 101This will break scripts that use an output filename whose extension is 102matched by a driver which is not the default one. This incompatibility 103is rather unlikely since previous GDAL versions already emit a warning 104in this situation (for C/C++ utilities only. for Python utilities 105default driver is silently used), so people have likely specified the 106output driver if they really want to do "gdal_translate in.tif out.png 107-of GTiff". 108 109MIGRATION_GUIDE.TXT will mention those potential caveats. 110 111Testing 112------- 113 114The existing autotest suite should continue to pass (with a few changes 115related to tests for the current behavior) 116 117Implementation 118-------------- 119 120Implementation will be done by Even Rouault 121 122Proposed implementation is in 123`https://github.com/rouault/gdal2/tree/rfc70 <https://github.com/rouault/gdal2/tree/rfc70>`__ 124 125Diff: 126`https://github.com/OSGeo/gdal/compare/trunk...rouault:rfc70 <https://github.com/OSGeo/gdal/compare/trunk...rouault:rfc70>`__ 127 128Voting history 129-------------- 130 131+1 from JukkaR, TamasS, DanielM and EvenR 132