1Options 2======= 3 4GDAL's format drivers have many `configuration options`_. 5These options come in two flavors: 6 7 * **Configuration options** are used to alter the default behavior of GDAL 8 and OGR and are generally treated as global environment variables by GDAL. These 9 are set through a :class:`rasterio.Env()` context block in Python. 10 11 * **Creation options** are passed into the driver at dataset creation time as 12 keyword arguments to ``rasterio.open(mode='w')``. 13 14Configuration Options 15--------------------- 16 17GDAL options are typically set as environment variables. While 18environment variables will influence the behavior of ``rasterio``, we 19highly recommended avoiding them in favor of defining behavior programatically. 20 21The preferred way to set options for rasterio is via :class:`rasterio.Env()`. 22Options set on entering the context are deleted on exit. 23 24.. code-block:: python 25 26 import rasterio 27 28 with rasterio.Env(GDAL_TIFF_INTERNAL_MASK=True): 29 # GeoTIFFs written here will have internal masks, not the 30 # .msk sidecars. 31 # ... 32 33 # Option is gone and the default (False) returns. 34 35Use native Python forms (``True`` and ``False``) for boolean options. Rasterio 36will convert them GDAL's internal forms. 37 38See the `configuration options`_ page for a complete list of available options. 39 40Creation options 41---------------- 42 43Each format has it's own set of driver-specific creation options that can be used to 44fine tune the output rasters. For details on a particular driver, see the `formats list`_. 45 46For the purposes of this document, we will focus on the `GeoTIFF creation options`_. 47Some of the common GeoTIFF creation options include: 48 49 * ``TILED``, ``BLOCKXSIZE``, and ``BLOCKYSIZE`` to define the internal tiling 50 * ``COMPRESS`` to define the compression method 51 * ``PHOTOMETRIC`` to define the band's color interpretation 52 53To specify these creation options in python code, you pass them as keyword arguments 54to the :func:`rasterio.open()` command in write mode. 55 56.. code-block:: python 57 58 with rasterio.open("output.tif", 'w', **src.meta, compress="JPEG", 59 tiled=True, blockxsize=256, blockysize=256, 60 photometric="YCBCR") as dataset: 61 # Write data to the dataset. 62 63.. note:: The GeoTIFF format requires that *blockxsize* and *blockysize* be multiples of 16. 64 65On the command line, ``rio`` commands will accept multiple ``--co`` options. 66 67.. code-block:: bash 68 69 $ rio copy source.tif dest.tif --co tiled=true 70 71These keyword arguments may be lowercase or uppercase, as you prefer. 72 73.. attention:: Some options may at a glance appear to be boolean, but are not. The GeoTIFF format's BIGTIFF option is one of these. The value must be YES, NO, IF_NEEDED, or IF_SAFER. 74 75.. note:: Some *configuration* options also have an effect on driver behavior at creation time. 76 77.. _configuration options: https://trac.osgeo.org/gdal/wiki/ConfigOptions 78.. _formats list: http://gdal.org/formats_list.html 79.. _GeoTIFF creation options: http://gdal.org/frmt_gtiff.html 80