.. _ogrlineref:

================================================================================
ogrlineref
================================================================================

.. only:: html

    Create linear reference and provide some calculations using it

.. Index:: ogrlineref

Synopsis
--------

.. code-block::

    ogrlineref [--help] [--help-general] [-progress] [-quiet]
               [-f <format_name>] [-dsco <NAME>=<VALUE>]... [-lco <NAME>=<VALUE>]...
               [-create]
               [-l <src_line_datasource_name>] [-ln <layer_name>] [-lf <field_name>]
               [-p <src_repers_datasource_name>] [-pn <layer_name>] [-pm <pos_field_name>] [-pf <field_name>]
               [-r <src_parts_datasource_name>] [-rn <layer_name>]
               [-o <dst_datasource_name>] [-on <layer_name>] [-of <field_name>] [-s <step>]
               [-get_pos] [-x <long>] [-y <lat>]
               [-get_coord] [-m <position>]
               [-get_subline] [-mb <position>] [-me <position>]

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

The :program:`ogrlineref` program can be used to:

-  create a linear reference file from input data

-  return the "linear referenced" distance for the projection of the
   input coordinates (point) on the path

-  return the coordinates (point) on the path according to the "linear
   referenced" distance

-  return the portion of the path according to the "linear referenced"
   begin and end distances

The :program:`ogrlineref` utility creates a linear reference - a file containing
segments of a certain length (e.g. 1 km in reference units.) The user can get coordinates,
linear referenced distances or sublines (subpaths) from this file.
The utility does not require the ``M`` or ``Z`` components in the geometry.
The results can be stored in any OGR supported format.
Also some information is written to the stdout.

.. include:: options/help_and_help_general.rst

.. option:: -progress

    Show progress.

.. include:: options/quiet.rst

.. option:: -f <format_name>

    Select an output format name. The default is to create a shapefile.

.. option:: -dsco <NAME>=<VALUE>

    Dataset creation option (format specific)

.. option:: -lco <NAME>=<VALUE>

    Layer creation option (format specific).

.. option:: -create

    Create the linear reference file (linestring of parts).

.. option:: -l <src_line_datasource_name>

    The path to input linestring datasource (e.g. the road)

.. option:: -ln <layer_name>

    The layer name in datasource

.. option:: -lf <field_name>

    The field name of unique values to separate the input lines (e.g.
    the set of roads).

.. option:: -p <src_repers_datasource_name>

    The path to linear references points (e.g. the road mile-stones)

.. option:: -pn <layer_name>

    The layer name in datasource

.. option:: -pm <pos_field_name>

    The field name of distances along path (e.g. mile-stones values)

.. option:: -pf <field_name>

    The field name of unique values to map input reference points to lines.

.. option:: -r <src_parts_datasource_name>

    The path to linear reference file.

.. option:: -rn <layer_name>

    The layer name in datasource

.. option:: -o <dst_datasource_name>

    The path to output linear reference file (linestring datasource)

.. option:: -on <layer_name>

    The layer name in datasource

.. option:: -of <field_name>

    The field name for storing the unique values of input lines

.. option:: -s <step>

    The part size in linear units

.. option:: -get_pos

    Return linear referenced position for input X, Y

.. option:: -x <long>

    Input X coordinate

.. option:: -y <lat>

    Input Y coordinate

.. option:: -get_coord

    Return point on path for input linear distance

.. option:: -m <position>

    The input linear distance

.. option:: -get_subline

    Return the portion of the input path from and to input linear positions.

.. option:: -mb <position>

    The input begin linear distance

.. option:: -me <position>

    The input end linear distance

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

.. include:: return_code.rst

Examples
--------

.. example::

   This example would create a shapefile (:file:`parts.shp`) containing
   a data needed for linear referencing (1 km parts):

   .. code-block:: bash

       ogrlineref -create -l roads.shp -p references.shp -pm dist -o parts.shp -s 1000 -progress
