[Gdal-dev] GDAL General Command Line Processor

[Frank Warmerdam]

Folks,

Some GDAL commandlines (especially creation ones with lots of "-co" creation
options) can get pretty long and complex, so Matt Wilke suggested a
mechanism be added to read options from a file.

I decided I wanted this ability to work in all utilities if it was going
to work in any.  But if I was going to bundle up some special commandline
options in the library, I decided this would be a good time to give a number
of utilities some general GDAL commandline options.  The result is the
GDALGeneralCmdLineProcessor() function which implements the following options:

    --version: report version of GDAL in use.
    --formats: report all format drivers configured.
    --format [format]: report details of one format driver.
    --optfile filename: expand an option file into the argument list.
    --config key value: set system configuration option.
    --debug [on/off/value]: set debug level.
    --help-general: report detailed help on general options.

I have created a Python wrapper (gdal.GeneralCmdLineProcessor()) and updated
all the GDAL C/C++ and Python utilities to use the new function.

The --optfile option basically reads the file referred to, tokenizes it and
shoves the tokens into the argument list in the place of the --optfile
option.

The --formats is the usual list of formats, but the --format option allows
a query of detailed information available about a format.  For a complex
format like GeoTIFF the result looks like this:

warmerda at gdal2200[145]% gdalinfo --format gtiff
Format Details:
   Short Name: GTiff
   Long Name: GeoTIFF
   Extension: tif
   Mime Type: image/tiff
   Help Topic: frmt_gtiff.html
   Supports: Create() - Create writeable dataset.
   Supports: CreateCopy() - Create dataset by copying another.
   Creation Datatypes: Byte UInt16 Int16 UInt32 Int32 Float32 Float64 CInt16 CInt32 CFloat32 CFloat64

<CreationOptionList>
   <Option name="COMPRESS" type="string-select">
     <Value>NONE</Value>
     <Value>PACKBITS</Value>
     <Value>JPEG</Value>
     <Value>LZW</Value>
     <Value>DEFLATE</Value>
   </Option>
   <Option name="INTERLEAVE" type="string-select">
     <Value>BAND</Value>
     <Value>PIXEL</Value>
   </Option>
   <Option name="TILED" type="boolean" description="Switch to tiled format"/>
   <Option name="TFW" type="boolean" description="Write out world file"/>
   <Option name="BLOCKXSIZE" type="int" description="Tile Width"/>
   <Option name="BLOCKYSIZE" type="int" description="Tile/Strip Height"/>
   <Option name="PHOTOMETRIC" type="string-select">
     <Value>MINISBLACK</Value>
     <Value>MINISWHITE</Value>
     <Value>RGB</Value>
     <Value>CMYK</Value>
     <Value>YCBCR</Value>
     <Value>CIELAB</Value>
     <Value>ICCLAB</Value>
     <Value>ITULAB</Value>
   </Option>
</CreationOptionList>

This should be useful as a quick way of checking outs some details
about a format, though the detailed writeup is still in the html file.

The --config allows settings various GDAL configuration options on the
commandline.  This calls CPLSetConfigOption() internally, which can
affect a variety of things that might normally be defined as environment
variables, such as GDAL_DATA, and GDAL_CACHEMAX.

The --debug can be used to turn debug information on and off for a given
run.  eg.  gdalinfo --debug on utm.tif
       or   gdalinfo --debug off utm.tif

Anyone wanting to add this consistent commandline option support to their
own programs should read up on the GDALGeneralCmdLineProcessor() function.

Best regards,
-- 
---------------------------------------+--------------------------------------
I set the clouds in motion - turn up   | Frank Warmerdam, warmerdam at pobox.com
light and sound - activate the windows | http://pobox.com/~warmerdam
and watch the world go round - Rush    | Geospatial Programmer for Rent