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