diff --git a/doc/source/programs/gdal_raster_resize.rst b/doc/source/programs/gdal_raster_resize.rst index beff39eaa48a..c8efb4dd2c2d 100644 --- a/doc/source/programs/gdal_raster_resize.rst +++ b/doc/source/programs/gdal_raster_resize.rst @@ -88,6 +88,8 @@ Standard Options Examples -------- +.. _gdal_raster_resize_example_resize: + .. example:: :title: Resize a dataset to 1000 columns and 500 lines using cubic resampling diff --git a/doc/source/programs/gdal_vector_buffer.rst b/doc/source/programs/gdal_vector_buffer.rst index 62dcd848d979..a2a535f22a44 100644 --- a/doc/source/programs/gdal_vector_buffer.rst +++ b/doc/source/programs/gdal_vector_buffer.rst @@ -175,6 +175,8 @@ Standard Options .. include:: gdal_options/upsert.rst +.. _gdal_vector_buffer_examples: + Examples -------- diff --git a/doc/source/programs/gdal_vector_rasterize.rst b/doc/source/programs/gdal_vector_rasterize.rst index 4b8cf76d85a6..234c890787d0 100644 --- a/doc/source/programs/gdal_vector_rasterize.rst +++ b/doc/source/programs/gdal_vector_rasterize.rst @@ -181,6 +181,8 @@ Standard Options Examples -------- +.. _gdal_vector_rasterize_example_burn: + .. example:: :title: Burn a shapefile into a raster diff --git a/doc/source/user/cookbook.rst b/doc/source/user/cookbook.rst new file mode 100644 index 000000000000..b53c3c0a79bf --- /dev/null +++ b/doc/source/user/cookbook.rst @@ -0,0 +1,134 @@ +.. _cookbook: + +================================================================================ +GDAL Command-line Cookbook +================================================================================ + + +.. contents:: + :depth: 3 + +Introduction +------------ + +Welcome to the GDAL Users Cookbook. This guide provides practical examples for working with raster and vector data using the GDAL command-line tools. +It demonstrates common tasks such as raster analysis, vector geometry operations, and combining raster and vector workflows. +Examples includes code snippets in both Bash and PowerShell, or links to relevant examples elsewhere in the GDAL documentation. + +General +------- + +Get the GDAL version +++++++++++++++++++++ + +.. tabs:: + + .. code-tab:: bash + + ogr2ogr --version + gdalinfo --version + + .. code-tab:: bash gdal CLI + + gdal --version + +Raster +------ + +Resize a Raster ++++++++++++++++ + +See :ref:`gdal_raster_resize_example_resize`. + +Vector +------ + +Get the geometry field name for a dataset ++++++++++++++++++++++++++++++++++++++++++ + +After running the commands below look for ``Geometry Column = `` in the output. +For example, if you see ``Geometry Column = geom``, then the geometry field name is ``geom``. + +.. tabs:: + + .. code-tab:: bash + + # list layers + ogrinfo -so edges.gpkg + # list details for a specific layer + ogrinfo -so edges.gpkg Edges + + .. code-tab:: bash gdal CLI + + gdal vector info edges.gpkg + +Buffer geometries ++++++++++++++++++ + +You can use the :ref:`gdal_vector_buffer` command; see :ref:`gdal_vector_buffer_examples` for usage examples. +Alternatively, the SQLite dialect can be used, as shown below. + +Buffer geometries using an attribute +++++++++++++++++++++++++++++++++++++ + +This example uses a ``lines.gpkg`` dataset containing a single layer named ``lines``, +with a geometry field named ``geom`` and an integer attribute named ``width``. The value +of this attribute is used as the buffer distance for each feature. + +.. note:: + + When creating derived geometries using SQL, avoid using ``SELECT *``. + Including the original geometry field will result in multiple geometry + columns in the output. Instead, explicitly list the required attributes + and return a single geometry column. + +.. tabs:: + + .. code-tab:: bash + + ogr2ogr buffered-lines.gpkg lines.gpkg \ + -dialect SQLITE \ + -sql "SELECT fid, ST_Buffer(geom, width) AS geom FROM lines" \ + -overwrite \ + -nlt POLYGON -nln BufferedLines + + .. code-tab:: bash gdal CLI + + gdal vector pipeline \ + ! read lines.gpkg \ + ! sql "SELECT fid, ST_Buffer(geom, width) AS geom FROM lines" \ + ! set-geom-type --geometry-type Polygon \ + ! write buffered-lines.gpkg --output-layer=BufferedLines --overwrite --overwrite-layer + +Combined Raster and Vector Workflows +------------------------------------ + +Burn a vector dataset into a raster ++++++++++++++++++++++++++++++++++++ + +See :ref:`gdal_vector_rasterize_example_burn`. + +Extract pixel values from a raster and apply them to a point dataset +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Example dataset: ``points.gpkg`` contains a single layer called ``points`` with a geometry column named ``geometry``. + +.. tabs:: + + .. code-tab:: bash + + export OGR_SQLITE_ALLOW_EXTERNAL_ACCESS="YES" + gdal vector sql points.gpkg \ + points-dem.gpkg \ + --sql "SELECT *, gdal_get_pixel_value('./dem.tif', 1, 'georef', ST_X(geometry), ST_Y(geometry)) as pixel FROM points" \ + --dialect SQLITE \ + --overwrite + + .. code-tab:: ps1 + + $env:OGR_SQLITE_ALLOW_EXTERNAL_ACCESS="YES" + gdal vector sql points.gpkg ` + points-dem.gpkg ` + --sql "SELECT *, gdal_get_pixel_value('./dem.tif', 1, 'georef', ST_X(geometry), ST_Y(geometry)) as pixel FROM points" ` + --dialect SQLITE ` + --overwrite diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index cb858c03621f..dbbcefbd682c 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -7,6 +7,7 @@ User oriented documentation .. toctree:: :maxdepth: 1 + cookbook raster_data_model band_algebra multidim_raster_data_model