wiki:ConfigOptions

Version 18 (modified by Even Rouault, 11 years ago) ( diff )

Document OGR_ENABLE_PARTIAL_REPROJECTION

Configuration Options

This page discussed runtime configuration options for GDAL, and is distinct from options to the build-time configure script. Runtime configuration options apply on all platforms, and are evaluated at runtime. They can be set programmatically, by commandline switches or in the environment by the user.

ConfigOptions are normally used to alter the default behavior of GDAL and OGR drivers and in some cases the GDAL and OGR core. They are essentially global variables the user can set.

Setting ConfigOptions

One example of a config option is the GDAL_CACHEMAX option. It controls the size of the GDAL block cache, in megabytes. It can be set in the environment on unix (bash/bourne) shell like this:

export GDAL_CACHEMAX=64

In a DOS/Windows command shell it is done like this:

set GDAL_CACHEMAX=64

It can also be set on the commandline for most GDAL and OGR utilities with the --config switch, though in a few cases these switches are not evaluated in time to affect behavior.

gdal_translate --config GDAL_CACHEMAX 64 in.tif out.tif

In C/C++ configuration switches can be set programmatically like this:

#include "cpl_conv.h"
...
    CPLSetConfigOption( "GDAL_CACHEMAX", "64" );

Normally a configuration option applies to all threads active in a program, but they can be limited to only the current thread this way:

    CPLSetThreadLocalConfigOption( "GDAL_CACHEMAX", "64" );

For boolean options, the values YES, TRUE or ON can be used to turn the option on; NO, FALSE or OFF to turn it off.

What Configuration Options Exist?

Traditionally there hasn't been a good registry of configuration options, and they are often added adhoc to drivers to provide particular workarounds. Below are some of the software wide configuration options. In some cases particular format drivers will document their configuration options, if any, in the user documentation - as is done for the JP2KAK and ECW drivers.

Generic Options

CPL_DEBUG

This may be set to ON, OFF or specific prefixes. If it is ON, all debug messages are reported to stdout. If it is OFF or unset no debug messages are reported. If it is set to a particular value, then only debug messages with that "type" value will be reported. For instance debug messages from the HFA driver are normally reported with type "HFA" (seen in the message).

At the commandline this can also be set with --debug <value> as well as with --config CPL_DEBUG <value>.

CPL_LOG

CPL_LOG_ERRORS

CPL_TIMESTAMP

CPL_MAX_ERROR_REPORTS

CPL_ACCUM_ERROR_MSG

CPL_TMPDIR

GDAL_DATA

Path to directory containing various GDAL data files (EPSG CSV files, S-57 definition files, DXF header and footer files, ...).

This option is read by the GDAL and OGR driver registration functions. It is used to expand EPSG codes into their description in the OSR model (WKT based).

On some builds (Unix), the value can be hard-coded at compilation time to point to the path after installation (/usr/share/gdal/data for example). On Windows platform, this option must be generally declared.

GDAL_DISABLE_CPLLOCALEC

If set to YES (deafault is NO) this option will disable the normal behavior of the CPLLocaleC class which forces the numeric locale to "C" for selected chunks of code using the setlocale() call. Behavior of setlocale() in multi-threaded applications may be undependable but use of this option may result in problem formatting and interpreting numbers properly.

GDAL_FILENAME_IS_UTF8

This option only has an effect on Windows systems (using cpl_vsil_win32.cpp). If set to "NO" (default is YES) then filenames passed to functions like VSIFOpenL() will be passed on directly to CreateFile() instead of being converted from UTF-8 to wchar_t and passed to CreateFileW(). This effectively restores the pre-GDAL1.8 behavior for handling filenames on Windows and might be appropriate for applications that treat filenames as being in the local encoding.

GEOTIFF_CSV

GDAL Options

GDAL_DISABLE_READDIR_ON_OPEN

Defaults to FALSE.

By default (GDAL_DISABLE_READDIR_ON_OPEN=FALSE), GDAL establishes a list of all the files in the directory of the file passed to GDALOpen(). This can result in speed-ups in some use cases, but also to major slow downs when the directory contains thousands of other files. When set to TRUE, GDAL will not try to establish the list of files.

GDAL_CACHEMAX

This option controls the default GDAL raster block cache size. If its value is small (less than 10000 in 1.7 and earlier, 100000 in 1.8 and later), it is assumed to be measured in megabytes, otherwise in bytes. Note that this value is only consulted the first time the cache size is requested overriding the initial default (40MB in GDAL 1.7, but often changing for each release). To change this value programmatically during operation of the program it is better to use GDALSetCacheMax(int nNewSize) (always in bytes). Before GDAL 1.8.0, the maximum cache size that can be specified is 2 GB, so when specifying in megabytes, don't try setting values bigger than 2047. Since GDAL 1.8.0, it is possible to specify a 64bit value through GDAL_CACHEMAX or with GDALSetCacheMax64(GIntBig nNewSize) (but the maximum practical value on 32 bit OS is between 2 and 4 GB. It is the responsibility of the user to set a consistant value)

GDAL_SKIP

Used by GDALDriverManager::AutoSkipDrivers()

This option can be used to unregister one or several GDAL drivers. This can be useful when a driver tries to open a dataset that it should not recognize, or when several drivers are built-in that can open the same datasets (for example JP2MrSID, JP2ECW, JPEG2000 and JP2KAK for JPEG2000 datasets). The value of this option must be a space delimited list of the short name of the GDAL drivers to unregister.

This option must be set before calling GDALAllRegister(), or an explicit call to GDALDriverManager::AutoSkipDrivers() will be required.

GDAL_DRIVER_PATH

Used by GDALDriverManager::AutoLoadDrivers()

This function will automatically load drivers from shared libraries. It searches the "driver path" for .so (or .dll) files that start with the prefix "gdal_X.so". It then tries to load them and then tries to call a function within them called GDALRegister_X() where the 'X' is the same as the remainder of the shared library basename ('X' is case sensitive), or failing that to call GDALRegisterMe().

There are a few rules for the driver path. If the GDAL_DRIVER_PATH environment variable it set, it is taken to be a list of directories to search separated by colons on UNIX, or semi-colons on Windows. Otherwise the /usr/local/lib/gdalplugins directory, and (if known) the lib/gdalplugins subdirectory of the gdal home directory are searched on UNIX and $(BINDIR)\gdalplugins on Windows.

This option must be set before calling GDALAllRegister(), or an explicit call to GDALDriverManager::AutoLoadDrivers() will be required.

GDAL_FORCE_CACHING

Defaults to NO.

When set to YES, the GDALDataset::RasterIO() and GDALRasterBand::RasterIO() will use cached IO (access block by block through GDALRasterBand::IReadBlock() API) instead of a potential driver specific implementation of IRasterIO(). This will only have an effect on drivers that specialize IRasterIO() at the dataset or raster band level, for example JP2KAK, NITF, HFA, WCS, ECW, MrSID, JPEG, ...

GDAL_VALIDATE_CREATION_OPTIONS

Defaults to YES.

When using GDALDriver::Create() or GDALDriver::CreateCopy() (for example when using the -co option of gdal_translate or gdalwarp utilies) , GDAL checks by default that the passed creation options match the syntax of the allowed options declared by the driver. If they don't match the syntax, a warning will be emitted. There should be hardly any reason to set this option to FALSE, as it's either a sign of a user typo, or an error in the declared options of the driver. The latter should be worth a bug report.

GDAL_IGNORE_AXIS_ORIENTATION

GMLJP2OVERRIDE

GDAL_PAM_MODE

GDAL_PAM_PROXY_DIR

GDAL_MAX_DATASET_POOL_SIZE

Defaults to 100. Used by gcore/gdalproxypool.cpp

Number of datasets that can be opened simultaneously by the GDALProxyPool mechanism (used by VRT for example). Can be increased to get better random I/O performance with VRT mosaics made of numerous underlying raster files. Be careful : on Linux systems, the number of file handles that can be opened by a process is generally limited to 1024.

GDAL_SWATH_SIZE

Defaults to 10000000 (10 MB). Used by gcore/rasterio.cpp

Size of the swath when copying raster data from one dataset to another one (in bytes). Should not be smaller than GDAL_CACHEMAX

USE_RRD

Defaults to NO. Used by gcore/gdaldefaultoverviews.cpp

Can be set to YES to use Erdas Imagine format (.aux) as overview format. See gdaladdo documentation.

GeoTIFF driver options

All the below options are documented in the GTiff driver documentation.

GTIFF_IGNORE_READ_ERRORS

ESRI_XML_PAM

JPEG_QUALITY_OVERVIEW

GDAL_TIFF_INTERNAL_MASK

GDAL_TIFF_INTERNAL_MASK_TO_8BIT

TIFF_USE_OVR

GTIFF_POINT_GEO_IGNORE

GTIFF_REPORT_COMPD_CS

GDAL_ENABLE_TIFF_SPLIT

GDAL_TIFF_OVR_BLOCKSIZE

OGR Options

PROJSO

Used by ogr/ogrct.cpp

The name of the PROJ.4 DLL or shared library to try and load at runtime. For example "/home/bob/libproj.so". If not set, OGR will try to load :

  • libproj.so on Linux/Unix platforms
  • proj.dll on Windows platforms
  • libproj.dylib on MacOSX platforms
  • libproj-0.dll on MinGW32 builds
  • cygproj-0.dll on Cygwin builds

CENTER_LONG

CHECK_WITH_INVERT_PROJ

Used by ogr/ogrct.cpp and apps/gdalwarp.cpp. Added in GDAL/OGR 1.7.0

This option can be used to control the behaviour of gdalwarp when warping global datasets or when transforming from/to polar projections, which causes coordinates discontinuities. See http://trac.osgeo.org/gdal/ticket/2305.

The background is that proj.4 does not guarantee that converting from src_srs to dst_srs and then from dst_srs to src_srs will yield to the initial coordinates. This can cause to errors in the computation of the target bounding box of gdalwarp, or to visual artifacts.

If CHECK_WITH_INVERT_PROJ option is not set, gdalwarp will check that the the computed coordinates of the edges of the target image are in the validity area of the target projection. If they are not, it will retry computing them by setting CHECK_WITH_INVERT_PROJ=TRUE that forces ogrct.cpp to check the consistency of each requested projection result with the invert projection.

If set to NO, gdalwarp will behave like GDAL/OGR < 1.7.0

THRESHOLD

Used by ogr/ogrct.cpp. Added in GDAL/OGR 1.7.0

Used in combination with CHECK_WITH_INVERT_PROJ=TRUE. Define the acceptable threshold used to check if the roundtrip from src_srs to dst_srs and from dst_srs to srs_srs yield to the initial coordinates. The value must be expressed in the units of the source SRS (typically degrees for a geographic SRS, meters for a projected SRS)

OGR_DEBUG_ORGANIZE_POLYGONS

Used by OGRGeometryFactory::organizePolygons(). Defaults to NO.

If set to YES, ogranizePolygons(), which is in particular used when reading Shapefiles with Polygon geometry, will use GEOS to check the topological relationship of the subparts of multipolygons. This will slow down processing. There should be no reason to set this option to YES, except for debugging purposes.

OGR_ARC_STEPSIZE

OGR_ENABLE_PARTIAL_REPROJECTION

Used by OGRLineString::transform(). Defaults to NO. Added in GDAL/OGR 1.8.0

Can be set to YES to remove points that can't be reprojected. See #3758 for the purpose of this option.

OGR_FORCE_ASCII

Used by OGRGetXML_UTF8_EscapedString() function and by GPX, KML, GeoRSS and GML drivers. Defaults to YES

Those XML based drivers should write UTF8 content. If they are provided with non UTF8 content, they will replace each non-ASCII character by '?' when OGR_FORCE_ASCII=YES.

Set to NO to preserve the content, but beware that the resulting XML file will not be valid and will require manual edition of the encoding in the XML header.

SHAPE_ENCODING

Added in GDAL/OGR 1.9.0.

This may be set to a OGR Character Encoding name in order to force all DBF files opened with the shapefile driver to be treated as having that encoding instead of trying to interpret the encoding setting of the file itself.

DXF_ENCODING

This may be set to a OGR Character Encoding name in order to force all DXF files opened with the DXF driver to be treated as having that encoding instead of trying to interpret the encoding setting of the file itself.

GML_INVERT_AXIS_ORDER_IF_LAT_LONG

Added in GDAL/OGR 1.8.0. See GML driver documentation. Also impacts WFS driver behaviour.

GML_CONSIDER_EPSG_AS_URN

Added in GDAL/OGR 1.8.0. See GML driver documentation. Also impacts WFS driver behaviour.

GML_SAVE_RESOLVED_TO

Added in GDAL/OGR 1.8.0. See GML driver documentation.

GML_SKIP_RESOLVE_ELEMS

Added in GDAL/OGR 1.8.0. See GML driver documentation.

GML_FIELDTYPES

See GML driver documentation.

OGR_WFS_PAGING_ALLOWED

Added in GDAL/OGR 1.8.0. See WFS driver documentation.

OGR_WFS_PAGE_SIZE

Added in GDAL/OGR 1.8.0. See WFS driver documentation.

OGR_WFS_LOAD_MULTIPLE_LAYER_DEFN

Added in GDAL/OGR 1.9.0. Can be set to OFF to prevent emitting DescribeFeatureType for multiple layers at once (which is the new behaviour of the WFS driver in OGR 1.9.0 for better efficiency)

OGR_EDIGEO_FONT_SIZE_FACTOR

Added in GDAL/OGR 1.9.0. See EDIGEO driver documentation.

OGR_EDIGEO_CREATE_LABEL_LAYERS

Added in GDAL/OGR 1.9.0. See EDIGEO driver documentation.

OGR_EDIGEO_RECODE_TO_UTF8

Added in GDAL/OGR 1.9.0. Can be set to OFF to prevent recoding strings in LATIN-1 to UTF-8.

Note: See TracWiki for help on using the wiki.