.. _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.

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

.. include:: return_code.rst

Caveats
-------

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