diff --git a/doc/.gitignore b/doc/.gitignore index 1af82a28d28c..dd6bda754be8 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,5 +1,4 @@ -build/ +build +data source/drivers/raster/driver_summary.rst source/drivers/vector/driver_summary.rst -source/user/configoptions_index_generated.rst -.doxygen_up_to_date diff --git a/doc/source/conf.py b/doc/source/conf.py index 7218d202100b..bb6a618cd218 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -12,6 +12,7 @@ # import datetime import os +import shutil import sys sys.path.insert(0, os.path.abspath("_extensions")) @@ -185,6 +186,57 @@ author_tamass = "Tamas Szekeres " man_pages = [ + # New gdal commands and subcommands + ( + "programs/gdal", + "gdal", + "Main gdal entry point", + [author_evenr], + 1, + ), + ( + "programs/gdal_info", + "gdal-info", + "Get information on a dataset", + [author_evenr], + 1, + ), + ( + "programs/gdal_raster", + "gdal-raster", + "Entry point for raster commands", + [author_evenr], + 1, + ), + ( + "programs/gdal_raster_info", + "gdal-raster-info", + "Get information on a raster dataset", + [author_evenr], + 1, + ), + ( + "programs/gdal_raster_convert", + "gdal-raster-convert", + "Convert a raster dataset", + [author_evenr], + 1, + ), + ( + "programs/gdal_vector", + "gdal-vector", + "Entry point for vector commands", + [author_evenr], + 1, + ), + ( + "programs/gdal_vector_info", + "gdal-vector-info", + "Get information on a vector dataset", + [author_evenr], + 1, + ), + # Traditional utilities ( "programs/gdalinfo", "gdalinfo", @@ -593,3 +645,24 @@ nb_mime_priority_overrides = [ ("spelling", "text/plain", 0), ] + +# -- copy data files ----------------------------------------------------- + +data_dir = os.path.join(os.path.dirname(__file__), "..", "data") +os.makedirs(data_dir, exist_ok=True) +data_dir_with_stats = os.path.join(data_dir, "with_stats") +os.makedirs(data_dir_with_stats, exist_ok=True) + +target_filename = os.path.join(data_dir, "utmsmall.tif") +shutil.copy( + os.path.join(os.path.dirname(__file__), "../../autotest/gcore/data/utmsmall.tif"), + target_filename, +) +if os.path.exists(target_filename + ".aux.xml"): + os.unlink(target_filename + ".aux.xml") + +target_filename = os.path.join(data_dir_with_stats, "utmsmall.tif") +shutil.copy( + os.path.join(os.path.dirname(__file__), "../../autotest/gcore/data/utmsmall.tif"), + target_filename, +) diff --git a/doc/source/programs/gdal.rst b/doc/source/programs/gdal.rst new file mode 100644 index 000000000000..5188c071b3d1 --- /dev/null +++ b/doc/source/programs/gdal.rst @@ -0,0 +1,53 @@ +.. _gdal_program: + +================================================================================ +gdal +================================================================================ + +.. versionadded:: 3.11 + +.. only:: html + + Main "gdal" entry point. + +.. Index:: gdal + +Synopsis +-------- + +.. code-block:: + + Usage: gdal + where is one of: + - convert: Convert a dataset (shortcut for 'gdal raster convert' or 'gdal vector convert'). + - info: Return information on a dataset (shortcut for 'gdal raster info' or 'gdal vector info'). + - pipeline: Execute a pipeline (shortcut for 'gdal vector pipeline'). + - raster: Raster commands. + - vector: Vector commands. + + 'gdal ' can also be used as a shortcut for 'gdal info '. + And 'gdal read ! ...' as a shortcut for 'gdal pipeline ! ...'. + +Examples +-------- + +.. example:: + :title: Getting information on the file :file:`utm.tif` (with JSON output) + + .. code-block:: console + + $ gdal info utm.tif + +.. example:: + :title: Converting file :file:`utm.tif` to GeoPackage raster + + .. code-block:: console + + $ gdal convert utm.tif utm.gpkg + +.. example:: + :title: Getting information on all available commands and subcommands as a JSON document. + + .. code-block:: console + + $ gdal --json-usage diff --git a/doc/source/programs/gdal_info.rst b/doc/source/programs/gdal_info.rst new file mode 100644 index 000000000000..80d01c0b9e95 --- /dev/null +++ b/doc/source/programs/gdal_info.rst @@ -0,0 +1,54 @@ +.. _gdal_info_command: + +================================================================================ +"gdal info" command +================================================================================ + +.. versionadded:: 3.11 + +.. only:: html + + Get information on a dataset. + +.. Index:: gdal info + +Acts as a shortcut for :ref:`gdal_raster_info_subcommand` or +:ref:`gdal_vector_info_subcommand` depending on the nature of the specified dataset. + +Synopsis +-------- + +.. code-block:: + + Usage: gdal info [OPTIONS] + + Return information on a dataset (shortcut for 'gdal raster info' or 'gdal vector info'). + + Positional arguments: + -i, --input Input raster, vector or multidimensional raster dataset [required] + + Common Options: + -h, --help Display help message and exit + --json-usage Display usage as JSON document and exit + + Options: + -f, --of, --format, --output-format Output format. OUTPUT-FORMAT=json|text (default: json) + + For all options, run 'gdal raster info --help' or 'gdal vector info --help' + +Examples +-------- + +.. example:: + :title: Getting information on the file :file:`utm.tif` (with JSON output) + + .. code-block:: console + + $ gdal info utm.tif + +.. example:: + :title: Getting information on the file :file:`poly.gpkg` (with text output), listing all features + + .. code-block:: console + + $ gdal info --format=text --features poly.gpkg diff --git a/doc/source/programs/gdal_options/co.rst b/doc/source/programs/gdal_options/co.rst new file mode 100644 index 000000000000..67be1480e285 --- /dev/null +++ b/doc/source/programs/gdal_options/co.rst @@ -0,0 +1,17 @@ +.. option:: --co = + + Many formats have one or more optional creation options that can be + used to control particulars about the file created. For instance, + the GeoTIFF driver supports creation options to control compression, + and whether the file should be tiled. + + May be repeated. + + The creation options available vary by format driver, and some + simple formats have no creation options at all. A list of options + supported for a format can be listed with the + :ref:`--formats ` + command line option but the documentation for the format is the + definitive source of information on driver creation options. + See :ref:`raster_drivers` format + specific documentation for legal creation options for each format. diff --git a/doc/source/programs/gdal_options/if.rst b/doc/source/programs/gdal_options/if.rst new file mode 100644 index 000000000000..187bc2bc4912 --- /dev/null +++ b/doc/source/programs/gdal_options/if.rst @@ -0,0 +1,10 @@ +.. option:: --if + + Format/driver name to be attempted to open the input file(s). It is generally + not necessary to specify it, but it can be used to skip automatic driver + detection, when it fails to select the appropriate driver. + This option can be repeated several times to specify several candidate drivers. + Note that it does not force those drivers to open the dataset. In particular, + some drivers have requirements on file extensions. + + May be repeated. diff --git a/doc/source/programs/gdal_options/of_raster_create_copy.rst b/doc/source/programs/gdal_options/of_raster_create_copy.rst new file mode 100644 index 000000000000..32f34e75fec7 --- /dev/null +++ b/doc/source/programs/gdal_options/of_raster_create_copy.rst @@ -0,0 +1,5 @@ + +.. option:: -f, --of, --format, --output-format + + Which output raster format to use. Allowed values may be given by + ``gdal --formats | grep "\-raster\-" | grep "rw" | sort`` diff --git a/doc/source/programs/gdal_options/oo.rst b/doc/source/programs/gdal_options/oo.rst new file mode 100644 index 000000000000..43f929acae31 --- /dev/null +++ b/doc/source/programs/gdal_options/oo.rst @@ -0,0 +1,5 @@ +.. option:: --oo = + + Dataset open option (format specific). + + May be repeated. diff --git a/doc/source/programs/gdal_options/overwrite.rst b/doc/source/programs/gdal_options/overwrite.rst new file mode 100644 index 000000000000..3b010e47235a --- /dev/null +++ b/doc/source/programs/gdal_options/overwrite.rst @@ -0,0 +1,6 @@ +.. option:: --overwrite + + Allow program to overwrite existing target file or dataset. + Otherwise, by default, :program:`gdal` errors out if the target file or + dataset already exists. + diff --git a/doc/source/programs/gdal_raster.rst b/doc/source/programs/gdal_raster.rst new file mode 100644 index 000000000000..5b7eea40e074 --- /dev/null +++ b/doc/source/programs/gdal_raster.rst @@ -0,0 +1,46 @@ +.. _gdal_raster_command: + +================================================================================ +"gdal raster" command +================================================================================ + +.. versionadded:: 3.11 + +.. only:: html + + Entry point for raster commands + +.. Index:: gdal raster + +Synopsis +-------- + +.. code-block:: + + Usage: gdal raster + where is one of: + - convert: Convert a raster dataset. + - info: Return information on a raster dataset. + +Available sub-commands +---------------------- + +- :ref:`gdal_raster_info_subcommand` +- :ref:`gdal_raster_convert_subcommand` + +Examples +-------- + +.. example:: + :title: Getting information on the file :file:`utm.tif` (with JSON output) + + .. code-block:: console + + $ gdal raster info utm.tif + +.. example:: + :title: Converting file :file:`utm.tif` to GeoPackage raster + + .. code-block:: console + + $ gdal raster convert utm.tif utm.gpkg diff --git a/doc/source/programs/gdal_raster_convert.rst b/doc/source/programs/gdal_raster_convert.rst new file mode 100644 index 000000000000..1d2e9a20218d --- /dev/null +++ b/doc/source/programs/gdal_raster_convert.rst @@ -0,0 +1,90 @@ +.. _gdal_raster_convert_subcommand: + +================================================================================ +"gdal raster convert" sub-command +================================================================================ + +.. versionadded:: 3.11 + +.. only:: html + + Convert a raster dataset. + +.. Index:: gdal raster convert + +Synopsis +-------- + +.. code-block:: + + Usage: gdal raster convert [OPTIONS] + + Convert a raster dataset. + + Positional arguments: + -i, --input Input raster dataset [required] + -o, --output Output raster dataset (created by algorithm) [required] + + Common Options: + -h, --help Display help message and exit + --json-usage Display usage as JSON document and exit + --progress Display progress bar + + Options: + -f, --of, --format, --output-format Output format + --co, --creation-option = Creation option [may be repeated] + --overwrite Whether overwriting existing output is allowed + Mutually exclusive with --append + --append Append as a subdataset to existing output + Mutually exclusive with --overwrite + + Advanced Options: + --oo, --open-option Open options [may be repeated] + --if, --input-format Input formats [may be repeated] + +Description +----------- + +:program:`gdal raster convert` can be used to convert raster data between +different formats. + +The following options are available: + +Standard options +++++++++++++++++ + +.. include:: gdal_options/of_raster_create_copy.rst + +.. include:: gdal_options/co.rst + +.. include:: gdal_options/overwrite.rst + +.. option:: --append + + Append input raster as a new subdataset to existing output file. + Only works with drivers that support adding subdatasets such as + :ref:`raster.gtiff` and :ref:`raster.gpkg` + +Advanced options +++++++++++++++++ + +.. include:: gdal_options/oo.rst + +.. include:: gdal_options/if.rst + +Examples +-------- + +.. example:: + :title: Converting file :file:`utm.tif` to a cloud-optimized GeoTIFF using JPEG compression + + .. code-block:: console + + $ gdal raster convert --format=COG --co COMPRESS=JPEG utm.tif utm_cog.tif + +.. example:: + :title: Converting file :file:`utm.tif` to GeoPackage raster + + .. code-block:: console + + $ gdal raster convert utm.tif utm.gpkg diff --git a/doc/source/programs/gdal_raster_info.rst b/doc/source/programs/gdal_raster_info.rst new file mode 100644 index 000000000000..716b513ba1fc --- /dev/null +++ b/doc/source/programs/gdal_raster_info.rst @@ -0,0 +1,193 @@ +.. _gdal_raster_info_subcommand: + +================================================================================ +"gdal raster info" sub-command +================================================================================ + +.. versionadded:: 3.11 + +.. only:: html + + Get information on a raster dataset. + +.. Index:: gdal raster info + +Synopsis +-------- + +.. code-block:: + + Usage: gdal raster info [OPTIONS] + + Return information on a raster dataset. + + Positional arguments: + -i, --input Input raster dataset [required] + + Common Options: + -h, --help Display help message and exit + --json-usage Display usage as JSON document and exit + + Options: + -f, --of, --format, --output-format Output format. OUTPUT-FORMAT=json|text (default: json) + --mm, --min-max Compute minimum and maximum value + --stats Retrieve or compute statistics, using all pixels + Mutually exclusive with --approx-stats + --approx-stats Retrieve or compute statistics, using a subset of pixels + Mutually exclusive with --stats + --hist Retrieve or compute histogram + + Advanced Options: + --oo, --open-option Open options [may be repeated] + --if, --input-format Input formats [may be repeated] + --no-gcp Suppress ground control points list printing + --no-md Suppress metadata printing + --no-ct Suppress color table printing + --no-fl Suppress file list printing + --checksum Compute pixel checksum + --list-mdd List all metadata domains available for the dataset + --mdd Report metadata for the specified domain. 'all' can be used to report metadata in all domains + + Esoteric Options: + --no-nodata Suppress retrieving nodata value + --no-mask Suppress mask band information + --subdataset Use subdataset of specified index (starting at 1), instead of the source dataset itself + +Description +----------- + +:program:`gdal raster info` lists various information about a GDAL supported +raster dataset. + +The following items will be reported (when known): + +- The format driver used to access the file. +- Raster size (in pixels and lines). +- The coordinate system for the file (in OGC WKT). +- The geotransform associated with the file (rotational coefficients + are currently not reported). +- Corner coordinates in georeferenced, and if possible lat/long based + on the full geotransform (but not GCPs). +- Ground control points. +- File wide (including subdatasets) metadata. +- Band data types. +- Band color interpretations. +- Band block size. +- Band descriptions. +- Band min/max values (internally known and possibly computed). +- Band checksum (if computation asked). +- Band NODATA value. +- Band overview resolutions available. +- Band unit type (i.e.. "meters" or "feet" for elevation bands). +- Band pseudo-color tables. + +The following options are available: + +Standard options +++++++++++++++++ + +.. option:: -f, --of, --format, --output-format json|text + + Which output format to use. Default is JSON. + +.. option:: --mm, --min-max + + Force computation of the actual min/max values for each band in the + dataset. + +.. option:: --stats + + Read and display image statistics. Force computation if no + statistics are stored in an image. + +.. option:: --approx-stats + + Read and display image statistics. Force computation if no + statistics are stored in an image. However, they may be computed + based on overviews or a subset of all tiles. Useful if you are in a + hurry and don't want precise stats. + +.. option:: --hist + + Report histogram information for all bands. + +Advanced options +++++++++++++++++ + +.. include:: gdal_options/oo.rst + +.. include:: gdal_options/if.rst + +.. option:: --no-gcp + + Suppress ground control points list printing. It may be useful for + datasets with huge amount of GCPs, such as L1B AVHRR or HDF4 MODIS + which contain thousands of them. + +.. option:: --no-md + + Suppress metadata printing. Some datasets may contain a lot of + metadata strings. + +.. option:: --no-ct + + Suppress printing of color table. + +.. option:: --no-rat + + Suppress printing of raster attribute table. + +.. option:: --no-fl + + Only display the first file of the file list. + +.. option:: --checksum + + Force computation of the checksum for each band in the dataset. + +.. option:: --list-mdd + + List all metadata domains available for the dataset. + +.. option:: --mdd |all + + adds metadata using: + + ``domain`` Report metadata for the specified domain. + + ``all`` Report metadata for all domains. + +Esoteric options +++++++++++++++++ + +.. option:: --no-nodata + + Suppress nodata printing. Implies :option:`--no-mask`. + + Can be useful for example when querying a remove GRIB2 dataset that has an + index .idx side-car file, together with :option:`--no-md` + +.. option:: --no-mask + + Suppress band mask printing. Is implied if :option:`--no-nodata` is specified. + +.. option:: --subdataset + + If the input dataset contains several subdatasets read and display + a subdataset with specified ``n`` number (starting from 1). + This is an alternative of giving the full subdataset name. + +Examples +-------- + +.. example:: + :title: Getting information on the file :file:`utmsmall.tif` as JSON output + + .. command-output:: gdal raster info utmsmall.tif + :cwd: ../../data + +.. example:: + :title: Getting information on the file :file:`utmsmall.tif` as text output, including statistics + + .. command-output:: gdal raster info --format=text --stats utmsmall.tif + :cwd: ../../data/with_stats diff --git a/doc/source/programs/gdal_vector.rst b/doc/source/programs/gdal_vector.rst new file mode 100644 index 000000000000..7b8bd722e4f4 --- /dev/null +++ b/doc/source/programs/gdal_vector.rst @@ -0,0 +1,48 @@ +.. _gdal_vector_command: + +================================================================================ +"gdal vector" command +================================================================================ + +.. versionadded:: 3.11 + +.. only:: html + + Entry point for vector commands + +.. Index:: gdal vector + +Synopsis +-------- + +.. code-block:: + + Usage: gdal vector + where is one of: + - convert: Convert a vector dataset. + - filter: Filter a vector dataset. + - info: Return information on a vector dataset. + - pipeline: Process a vector dataset. + - reproject: Reproject a vector dataset. + +Available sub-commands +---------------------- + +- :ref:`gdal_vector_info_subcommand` + +Examples +-------- + +.. example:: + :title: Getting information on the file :file:`poly.gpkg` (with JSON output) + + .. code-block:: console + + $ gdal vector info poly.gpkg + +.. example:: + :title: Converting file :file:`poly.gpkg` to Esri File Geodatabase + + .. code-block:: console + + $ gdal vector convert --format=OpenFileGDB poly.gpkg poly.gdb diff --git a/doc/source/programs/gdal_vector_info.rst b/doc/source/programs/gdal_vector_info.rst new file mode 100644 index 000000000000..a5d10e0d455d --- /dev/null +++ b/doc/source/programs/gdal_vector_info.rst @@ -0,0 +1,117 @@ +.. _gdal_vector_info_subcommand: + +================================================================================ +"gdal vector info" sub-command +================================================================================ + +.. versionadded:: 3.11 + +.. only:: html + + Get information on a vector dataset. + +.. Index:: gdal vector info + +Synopsis +-------- + +.. code-block:: + + Usage: gdal vector info [OPTIONS] + + Return information on a vector dataset. + + Positional arguments: + -i, --input Input vector dataset [required] + + Common Options: + -h, --help Display help message and exit + --json-usage Display usage as JSON document and exit + + Options: + -f, --of, --format, --output-format Output format. OUTPUT-FORMAT=json|text (default: json) + -l, --layer Layer name [may be repeated] + Mutually exclusive with --sql + --features List all features (beware of RAM consumption on large layers) + --sql Execute the indicated SQL statement and return the result + Mutually exclusive with --layer + --where |<@filename> Attribute query in a restricted form of the queries used in the SQL WHERE statement + --dialect SQL dialect + --update Open the dataset in update mode + + Advanced Options: + --oo, --open-option Open options [may be repeated] + --if, --input-format Input formats [may be repeated] + +Description +----------- + +:program:`gdal vector info` lists various information about a GDAL supported +vector dataset. + +The following options are available: + +Standard options +++++++++++++++++ + +.. option:: -f, --of, --format, --output-format json|text + + Which output format to use. Default is JSON. + +.. option:: -l, --layer + + Name of one or more layers to inspect. If no layer names are passed and + :option:`--sql` is not specified, then all layers will be selected. + +.. option:: --features + + List all features. Beware of RAM consumption on large layers when using + JSON output. + +.. option:: -sql |@ + + Execute the indicated SQL statement and return the result. The + ``@`` syntax can be used to indicate that the content is + in the pointed filename (e.g ``@my_select.txt`` where my_select.txt is a file + in the current directory). Data can also be edited with SQL INSERT, UPDATE, + DELETE, DROP TABLE, ALTER TABLE etc if the dataset is opened in update mode. + Editing capabilities depend on the selected + dialect with :option:`--dialect`. + +.. option:: --where |@ + + An attribute query in a restricted form of the queries used in the SQL + `WHERE` statement. Only features matching the attribute query will be + reported. The ``@`` syntax can be used to indicate that the + content is in the pointed filename. + + Example of ``--where`` and quoting: + + .. code-block:: console + + --where "\"Corner Point Identifier\" LIKE '%__00_00'" + +.. option:: --dialect + + SQL dialect. In some cases can be used to use (unoptimized) :ref:`ogr_sql_dialect` instead + of the native SQL of an RDBMS by passing the ``OGRSQL`` dialect value. + The :ref:`sql_sqlite_dialect` can be selected with the ``SQLITE`` + and ``INDIRECT_SQLITE`` dialect values, and this can be used with any datasource. + + +Advanced options +++++++++++++++++ + +.. include:: gdal_options/oo.rst + +.. include:: gdal_options/if.rst + +Examples +-------- + +.. example:: + :title: Getting information on the file :file:`poly.gpkg` (with text output), listing all features + + .. code-block:: console + + $ gdal vector info --format=text --features poly.gpkg diff --git a/doc/source/programs/index.rst b/doc/source/programs/index.rst index a6ab1e221b56..49dc763461c8 100644 --- a/doc/source/programs/index.rst +++ b/doc/source/programs/index.rst @@ -4,8 +4,40 @@ Programs ================================================================================ +"gdal" application +------------------ + +Starting with GDAL 3.11, parts of the GDAL utilities are available from a new +single :program:`gdal` program that accepts commands and subcommands. + +.. toctree:: + :maxdepth: 1 + :hidden: + + gdal + gdal_info + gdal_raster + gdal_raster_info + gdal_raster_convert + gdal_vector + gdal_vector_info + +.. only:: html + + - :ref:`gdal_program`: Main "gdal" entry point + - :ref:`gdal_info_command`: Get information on a dataset + - :ref:`gdal_raster_command`: Entry point for raster commands + - :ref:`gdal_raster_info_subcommand`: Get information on a raster dataset + - :ref:`gdal_raster_convert_subcommand`: Convert a raster dataset + - :ref:`gdal_vector_command`: Entry point for vector commands + - :ref:`gdal_vector_info_subcommand`: Get information on a vector dataset + + +"Traditional" applications +-------------------------- + General -------- ++++++++ .. toctree:: :maxdepth: 1 @@ -17,8 +49,9 @@ General - :ref:`argument_syntax` + Raster programs ---------------- ++++++++++++++++ .. toctree:: :maxdepth: 1 @@ -104,7 +137,7 @@ Raster programs - :ref:`rgb2pct`: Convert a 24bit RGB image to 8bit paletted. Multidimensional Raster programs --------------------------------- +++++++++++++++++++++++++++++++++ .. toctree:: :maxdepth: 1 @@ -119,7 +152,7 @@ Multidimensional Raster programs - :ref:`gdalmdimtranslate`: Converts multidimensional data between different formats, and perform subsetting. Vector programs ---------------- ++++++++++++++++ .. toctree:: :maxdepth: 1 @@ -144,7 +177,7 @@ Vector programs - :ref:`ogr_layer_algebra`: Performs various Vector layer algebraic operations. Geographic network programs ---------------------------- ++++++++++++++++++++++++++++ .. toctree:: :maxdepth: 1 @@ -159,7 +192,7 @@ Geographic network programs - :ref:`gnmanalyse`: Analyses networks Other utilities ---------------- ++++++++++++++++ .. toctree:: :maxdepth: 1