.. _gdal2xyz:

================================================================================
gdal2xyz
================================================================================

.. only:: html

    Translates a raster file into `xyz` format.

.. Index:: gdal2xyz

Synopsis
--------

.. code-block::

    gdal2xyz [--help] [--help-general]
        [-skip <factor>]
        [-srcwin <xoff> <yoff> <xsize> <ysize>]
        [-b <band>]... [-allbands]
        [-skipnodata]
        [-csv]
        [-srcnodata <value>] [-dstnodata <value>]
        <src_dataset> <dst_dataset>

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

The :program:`gdal2xyz` utility can be used to translate a raster file into xyz format.
`gdal2xyz` can be used as an alternative to `gdal_translate of=xyz`. Features include:

    * Select more then one band
    * Skip or replace nodata value
    * Return the output as numpy arrays.

.. note::

    gdal2xyz is a Python utility, and is only available if GDAL Python bindings are available.

.. tip:: Equivalent in new "gdal" command line interface:

    See :ref:`gdal_raster_convert` with ``--of XYZ``.

.. program:: gdal2xyz

.. include:: options/help_and_help_general.rst

.. option:: -skip

    How many rows/cols to skip in each iteration.

.. option:: -srcwin <xoff> <yoff> <xsize> <ysize>

    Selects a subwindow from the source image for copying based on pixel/line location.

.. option:: -b, -band <band>

    Select band *band* from the input spectral bands for output.
    Bands are numbered from 1 in the order spectral bands are specified.
    Multiple **-b** switches may be used.
    When no -b switch is used, the first band will be used.
    In order to use all input bands set `-allbands` or `-b 0`.

.. option:: -allbands

    Select all input bands.

.. option:: -csv

    Use comma instead of space as a delimiter.

.. option:: -skipnodata

    Exclude the output lines with nodata value (as determined by srcnodata)

.. option:: -srcnodata

    The nodata value of the dataset (for skipping or replacing)
    Default (`None`) - Use the dataset nodata value;
    `Sequence`/`Number` - Use the given nodata value (per band or per dataset).

.. option:: -dstnodata

    Replace source nodata with a given nodata. Has an effect only if not setting `-skipnodata`.
    Default(`None`) - Use `srcnodata`, no replacement;
    `Sequence`/`Number` - Replace the `srcnodata` with the given nodata value (per band or per dataset).

.. option:: -h, --help

    Show help message and exit.

.. option:: <src_dataset>

    The source dataset name. It can be either file name, URL of data source or
    subdataset name for multi-dataset files.

.. option:: <dst_dataset>

    The destination file name.


Examples
--------

.. example::

   .. code-block:: bash

       gdal2xyz -b 1 -b 2 -dstnodata 0 input.tif output.txt


   To create a text file in `xyz` format from the input file `input.tif`.
   The first columns, x and y, are the coordinates of the centers of each cell.
   The remaining columns represent the first and second bands.
   We also replace the dataset nodata values with zeros.


Caveats
-------

gdal2xyz output values with a limited precision. Use ``gdal_translate -of XYZ`` if more precision is desired.
