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

    {
      "pipeline":[
        "autzen-dd.las",
        {
          "type":"filters.attribute",
          "dimension":"Classification",
          "datasource":"attributes.shp",
          "layer":"attributes",
          "column":"CLS"
        },
        {
          "filename":"attributed.las",
          "scale_x":0.0000001,
          "scale_y":0.0000001
        }
      ]
    }

Example 2
---------

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

.. code-block:: json

    {
      "pipeline":[
        "autzen-dd.las",
        {
          "type":"filters.attribute",
          "dimension":"PointSourceId",
          "value":26
        },
        {
          "filename":"attributed.las",
          "scale_x":0.0000001,
          "scale_y":0.0000001
        }
      ]
    }



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:: json

    {
      "pipeline":[
        "autzen-dd.las",
        {
          "type":"filters.attribute",
          "dimension":"Intensity",
          "datasource":"attributes.shp",
          "query":"SELECT CLS FROM attributes where cls!=6",
          "column":"CLS"
        },
        {
          "filename":"attributed.las",
        }
      ]
    }

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]

