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