.. _gdal_driver_gti_create:

================================================================================
``gdal driver gti create``
================================================================================

.. versionadded:: 3.11

.. only:: html

    Create an index of raster datasets compatible of the GDAL Tile Index (GTI) driver.

.. Index:: gdal driver gti create

Synopsis
--------

.. program-output:: gdal driver gti create --help-doc

Description
-----------

:program:`gdal driver gti create` creates a vector dataset with a record for each
input raster file, an attribute containing the filename, and a polygon geometry
outlining the raster, to be used as input for the :ref:`GTI <raster.gti>` driver.

This is an extension of :ref:`gdal_raster_index`.

There are two possibilities:

- either use directly a vector tile index generated by :program:`gdal driver gti create` as the input
  of the GTI driver

- or generate a small XML .gti wrapper file, for easier use with non-file-based
  formats such as databases, or for vector formats that do not support setting
  layer metadata items.

Formats that support layer metadata are for example GeoPackage (``--of GPKG``),
FlatGeoBuf (``--of FlatGeoBuf``) or PostGIS (``--of PG``)

Setting :option:`--resolution` and :option:`--ot` is recommended to avoid the GTI
driver to have to deduce them by opening the first tile in the index. If the tiles
have nodata or mask band,  :option:`--nodata` and :option:`--mask` should also
be set.

In a GTI context, the extent of all tiles referenced in the tile index must
be expressed in a single CRS. Consequently, if input tiles may have different
CRS, :option:`--output-crs` must be specified.


The following options are available:

Standard options
++++++++++++++++


.. include:: gdal_options/of_vector.rst

.. include:: gdal_options/co.rst

.. include:: options/lco.rst

.. include:: gdal_options/overwrite.rst

.. option:: --update

    Whether the output dataset must be opened in update mode. Implies that
    it already exists.

.. option:: --overwrite-layer

    Whether overwriting the existing output vector layer is allowed.

.. option:: --append

    Whether appending features to the existing output vector layer is allowed

.. option:: -l, --nln, --layer <LAYER>

    Provides a name for the output vector layer.

.. option:: --recursive

    Whether input directories should be explored recursively.

.. option:: --filename-filter <FILENAME-FILTER>

    Pattern that the filenames contained in input directories should follow.
    '*' is a wildcard character that matches any number of any characters
    including none. '?' is a wildcard character that matches a single character.
    Comparisons are done in a case insensitive way.
    Several filters may be specified.

    For example: ``--filename-filter "*.tif,*.tiff"``

.. option:: --min-pixel-size <val>

    Minimum pixel size in term of geospatial extent per pixel (resolution) that
    a raster should have to be selected. The pixel size
    is evaluated after reprojection of its extent to the target CRS defined
    by :option:`--output-crs`.

.. option:: --max-pixel-size <val>

    Maximum pixel size in term of geospatial extent per pixel (resolution) that
    a raster should have to be selected. The pixel size
    is evaluated after reprojection of its extent to the target CRS defined
    by :option:`--output-crs`.

.. option:: -location-name <LOCATION-NAME>

    The output field name to hold the file path/location to the indexed
    rasters. The default field name is ``location``.

.. option:: --absolute-path

    The absolute path to the raster files is stored in the index file.
    By default the raster filenames will be put in the file exactly as they
    are specified on the command line.

.. option:: --output-crs <OUTPUT-CRS>

    Geometries of input files will be transformed to the desired target
    coordinate reference system.
    Default creates simple rectangular polygons in the same coordinate reference
    system as the input rasters.

.. option:: --metadata <KEY>=<VALUE>

    Write an arbitrary layer metadata item, for formats that support layer
    metadata.
    This option may be repeated.


.. option:: --xml-filename <name>

    Filename of the XML Virtual Tile Index file to generate, that can be used
    as an input for the GDAL GTI / Virtual Raster Tile Index driver.
    This can be useful when writing the tile index in a vector format that
    does not support writing layer metadata items.

.. option:: --resolution <xres,<yres>

    Target resolution in CRS unit per pixel.

    Written in the XML Virtual Tile Index if :option:`--xml-filename`
    is specified, or as ``RESX`` and ``RESY`` layer metadata items for formats that
    support layer metadata.

.. option:: --bbox <xmin>,<ymin>,<xmax>,<ymax>

    Target extent in CRS unit.

    'x' is longitude values for geographic CRS and easting for projected CRS.
    'y' is latitude values for geographic CRS and northing for projected CRS.

    Written in the XML Virtual Tile Index if :option:`--xml-filename`
    is specified, or as ``MINX``, ``MINY``, ``MAXX`` and ``MAXY`` layer metadata
    items for formats that support layer metadata.

.. option:: --ot, --datatype, --output-data-type <datatype>

    Data type of the tiles of the tile index: ``Byte``, ``Int8``, ``UInt16``,
    ``Int16``, ``UInt32``, ``Int32``, ``UInt64``, ``Int64``, ``Float32``, ``Float64``, ``CInt16``,
    ``CInt32``, ``CFloat32`` or ``CFloat64``

    Written in the XML Virtual Tile Index if :option:`--xml-filename`
    is specified, or as ``DATA_TYPE`` layer metadata item for formats that
    support layer metadata.

.. option:: --band-count <val>

    Number of bands of the tiles of the tile index.

    Written in the XML Virtual Tile Index if :option:`--xml-filename`
    is specified, or as ``BAND_COUNT`` layer metadata item for formats that
    support layer metadata.

    A mix of tiles with N and N+1 bands is allowed, provided that the color
    interpretation of the (N+1)th band is alpha. The N+1 value must be written
    as the band count in that situation.

    If :option:`--nodata` or :option:`--color-interpretation` are specified and have multiple
    values, the band count is also inferred from that number.

.. option:: --nodata <val>[,<val>...]

    Nodata value of the tiles of the tile index.

    Written in the XML Virtual Tile Index if :option:`--xml-filename`
    is specified, or as ``NODATA`` layer metadata item for formats that
    support layer metadata.

.. option:: --color-interpretation <val>[,<val>...]

    Color interpretation of of the tiles of the tile index:
    ``red``, ``green``, ``blue``, ``alpha``, ``gray``, ``undefined``.

    Written in the XML Virtual Tile Index if :option:`--xml-filename`
    is specified, or as ``COLOR_INTERPRETATION`` layer metadata item for formats that
    support layer metadata.

.. option:: --mask

    Whether tiles in the tile index have a mask band.

    Written in the XML Virtual Tile Index if :option:`--xml-filename`
    is specified, or as ``MASK_BAND`` layer metadata item for formats that
    support layer metadata.

.. option:: --fetched-metadata <gdal_md_name>,<fld_name>,<fld_type>

    Fetch a metadata item from the raster tile and write it as a field in the
    tile index.

    <gdal_md_name> should be the name of the raster metadata item.
    ``{PIXEL_SIZE}`` may be used as a special name to indicate the pixel size.

    <fld_name> should be the name of the field to create in the tile index.

    <fld_type> should be the name of the type to create.
    One of ``String``, ``Integer``, ``Integer64``, ``Real``, ``Date``, ``DateTime``

    This option may be repeated.

    For example: ``--fetched-metadata TIFFTAG_DATETIME,creation_date,DateTime``

.. Return status code
.. ------------------

.. include:: return_code.rst

Examples
--------

.. example::

   Make a tile index from GeoTIFF files, with metadata suitable
   for use by the GDAL GTI / Virtual Raster Tile Index driver.

   .. code-block:: bash

       gdal driver gti create --ot Byte --resolution=60,60 --band-count=3 --color-interpretation=Red,Green,Blue *.tif tile_index.gti.gpkg
