Merge pull request #1322 from PDAL/filters-colorinterpolate

Implement filters.colorinterp

doc/stages/filters.colorinterp.rst

@@ -0,0 +1,148 @@
+.. _filters.colorinterp:
+
+filters.colorinterp
+====================
+
+The color interpolation filter assigns scaled RGB values from an image based on
+a given dimension.  It provides three possible approaches:
+
+1. You provide a ``minimum`` and ``maximum``, and the data are scaled for the
+   given ``dimension`` accordingly.
+
+2. You provide a ``k`` and a ``mad`` setting, and the scaling is set based on
+   Median Absolute Deviation.
+
+3. You provide a ``k`` setting and the scaling is set based on the
+   ``k``-number of standard deviations from the median.
+
+You can provide your own `GDAL`_-readable image for the scale color factors,
+but a number of pre-defined ramps are embedded in PDAL.  The default ramps
+provided by PDAL are 256x1 RGB images, and might be a good starting point for
+creating your own scale factors. See `Default Ramps`_ for more information.
+
+.. note::
+
+    :ref:`filters.colorinterp` will use the entire band to scale the colors.
+
+.. code-block:: json
+
+  {
+    "pipeline":[
+      "uncolored.las",
+      {
+        "type":"filters.colorinterp",
+        "ramp":"pestel_shades",
+        "mad":true,
+        "k":1.8,
+        "dimension":"Z"
+      },
+      "colorized.las"
+    ]
+  }
+
+.. figure:: ../images/pestel_scaled_plasio.png
+    :scale: 80%
+
+    Image data with interpolated colors based on ``Z`` dimension and ``pestel_shades``
+    ramp.
+
+Default Ramps
+--------------------------------------------------------------------------------
+
+PDAL provides a number of default color ramps you can use in addition to
+providing your own. Give the ramp name as the ``ramp`` option to the filter
+and it will be used. Otherwise, provide a `GDAL`_-readable raster filename.
+
+``awesome_green``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ../images/awesome-green.png
+    :scale: 400%
+    :alt: awesome-green color ramp
+
+``black_orange``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ../images/black-orange.png
+    :scale: 400%
+    :alt: black-orange color ramp
+
+``blue_orange``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ../images/blue-orange.png
+    :scale: 400%
+    :alt: blue-orange color ramp
+
+``blue_hue``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ../images/blue-hue.png
+    :scale: 400%
+    :alt: blue-hue color ramp
+
+``blue_orange``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ../images/blue-orange.png
+    :scale: 400%
+    :alt: blue-orange color ramp
+
+``blue_red``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ../images/blue-red.png
+    :scale: 400%
+    :alt: blue-red color ramp
+
+``heat_map``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ../images/heat-map.png
+    :scale: 400%
+    :alt: heat-map color ramp
+
+``pestel_shades``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ../images/pestel-shades.png
+    :scale: 400%
+    :alt: pestel-shades color ramp
+
+Options
+-------
+
+ramp
+  The raster file to use for the color ramp. Any format supported by `GDAL`_ may be read.
+  Alternatively, one of the default color ramp names can be used. [Default: ``pestel_shades``]
+
+dimension
+  A dimension name to use for the values to interpolate colors. [Default: ``Z``]
+
+minimum
+  The minimum value to use to scale the data. If none is specified, one is
+  computed from the data. If one is specified but a ``k`` value is also
+  provided, the ``k`` value will be used.
+
+maximum
+  The maximum value to use to scale the data. If none is specified, one is
+  computed from the data. If one is specified but a ``k`` value is also
+  provided, the ``k`` value will be used.
+
+invert
+  Invert the direction of the ramp? [Default: false]
+
+k
+  Color based on the given number of standard deviations from the median. If
+  set, ``minimum`` and ``maximum`` will be computed from the median and setting
+  them will have no effect.
+
+mad
+  If true, ``minimum`` and ``maximum`` will be computed by the median absolute
+  deviation. See :ref:`filters.mad` for discussion. [Default: false]
+
+mad_multiplier
+  MAD threshold multiplier. Used in conjunction with ``k`` to threshold the
+  diferencing. [Default: 1.4862]
+
+.. _`GDAL`: http://www.gdal.org

filters/CMakeLists.txt

@@ -1,6 +1,7 @@
 add_subdirectory(approximatecoplanar)
 add_subdirectory(attribute)
 add_subdirectory(chipper)
+add_subdirectory(colorinterp)
 add_subdirectory(colorization)
 add_subdirectory(crop)
 add_subdirectory(decimation)

filters/colorinterp/CMakeLists.txt

@@ -0,0 +1,18 @@
+#
+# Colorinterp filter CMake configuration
+#
+
+#
+# Colorinterp Filter
+#
+set(srcs
+    ColorinterpFilter.cpp
+)
+
+set(incs
+    ColorinterpFilter.hpp
+    color-ramps.hpp
+)
+
+PDAL_ADD_DRIVER(filter colorinterp "${srcs}" "${incs}" objects)
+set(PDAL_TARGET_OBJECTS ${PDAL_TARGET_OBJECTS} ${objects} PARENT_SCOPE)