.. _filters.attribute:

filters.attribute
===================

The attribute filter allows you to set the values of a
selected dimension. Two scenarios are supported:

* Set the value of a dimension of all points to single value
  (use option 'value')

* Set points inside an OGR-readable Polygon or MultiPolygon
  (use option 'datasource')

OGR SQL support
----------------

You can limit your queries based on OGR's SQL support. If the
filter has both a `datasource` and a `query` option, those will
be used instead of the entire OGR data source. At this time it is
not possible to further filter the OGR query based on a geometry
but that may be added in the future.

.. note::

    The OGR SQL support follows the rules specified in `ExecuteSQL`_
    documentation, and it will pass SQL down to the underlying
    datasource if it can do so.

.. _`ExecuteSQL`: http://www.gdal.org/ogr__api_8h.html#a9892ecb0bf61add295bd9decdb13797a

Example 1
---------

In this scenario, we are altering the attributes of the dimension
'Classification'.  Points from autzen-dd.las that lie within a feature will
have their classification to match the 'CLS' field associated with that
feature.

.. code-block:: xml

    <?xml version="2.0" encoding="utf-8"?>
    <Pipeline version="1.0">
        <Writer type="writers.las">
            <Option name="filename">
                attributed.las
            </Option>
            <Option name="forward">
                all
            </Option>
            <Filter type="filters.attribute">
                <Option name="dimension">
                    Classification
                </Option>
                <Option name="datasource">
                    ./test/data/autzen/attributes.shp
                </Option>
                <Option name="layer">
                    attributes
                </Option>
                <Option name="column">
                    CLS
                </Option>
                <Reader type="readers.las">
                    <Option name="filename">
                        ../autzen/autzen-dd.las
                    </Option>
                </Reader>
            </Filter>
        </Writer>
    </Pipeline>

Example 2
---------

This pipeline sets the PointSourceId of all points from 'autzen-dd.las'
to the value '26'.

.. code-block:: xml

    <?xml version="2.0" encoding="utf-8"?>
    <Pipeline version="1.0">
        <Writer type="writers.las">
            <Option name="filename">
                attributed.las
            </Option>
            <Option name="forward">
                all
            </Option>
            <Filter type="filters.attribute">
                <Option name="dimension">
                    PointSourceId
                </Option>
                <Option name="value">
                    26
                </Option>
                <Option name="datasource">
                    ./test/data/autzen/attributes.shp
                </Option>
                <Reader type="readers.las">
                    <Option name="filename">
                        ../autzen/autzen-dd.las
                    </Option>
                </Reader>
            </Filter>
        </Writer>
    </Pipeline>

Example 3
--------------------------------------------------------------------------------

This example sets the Intensity attribute to ``CLS`` values read from the
`OGR SQL`_ query.

.. _`OGR SQL`: http://www.gdal.org/ogr_sql_sqlite.html

.. code-block:: xml

    <?xml version="2.0" encoding="utf-8"?>
    <Pipeline version="1.0">
        <Writer type="writers.las">
            <Option name="filename">
                attributed.las
            </Option>
            <Option name="forward">
                all
            </Option>
            <Filter type="filters.attribute">
                <Option name="dimension">
                    Intensity
                </Option>
                <Option name="datasource">
                    ./test/data/autzen/attributes.shp
                </Option>
                <Option name="query">
                    SELECT CLS FROM attributes where cls != 6
                </Option>
                <Option name="column">
                    CLS
                </Option>
                <Reader type="readers.las">
                    <Option name="filename">
                        ../autzen/autzen-dd.las
                    </Option>
                </Reader>
            </Filter>
        </Writer>
    </Pipeline>

Options
-------

dimension
  Name of the dimension whose value should be altered.  [Default: none]

value
  Value to apply to the dimension.  [Default: none]

datasource
  OGR-readable datasource for Polygon or MultiPolygon data.  [Default: none]

column
  The OGR datasource column from which to read the attribute.
  [Default: first column]

query
  OGR SQL query to execute on the datasource to fetch geometry and attributes.
  [Default: none]

layer
  The data source's layer to use. [Defalt: first layer]

