Merge remote-tracking branch 'origin/master' into issue-2262

doc/java.rst

@@ -33,9 +33,9 @@ that gives users access to executing
 :ref:`pipeline <pipeline>` instantiations and capturing the results
 in `Java`_ interfaces.
 This mode of operation is useful if you are looking to have PDAL simply act as
-your data format and processing handler. 
+your data format and processing handler.
 
-Users are expected to construct their own PDAL :ref:`pipeline <pipeline>`, 
+Users are expected to construct their own PDAL :ref:`pipeline <pipeline>`,
 execute it, and retrieve points into Java memory:
 
 .. code-block:: scala
@@ -70,7 +70,7 @@ execute it, and retrieve points into Java memory:
     val pv: PointView          = pvs.next() // let's take the first PointView
 
     // load all points into JVM memory
-    // PointCloud provides operations on PDAL points that 
+    // PointCloud provides operations on PDAL points that
     // are loaded in this case into JVM memory as a single Array[Byte]
     val pointCloud: PointCloud = pv.getPointCloud()
     val x: Double = pointCloud.getDouble(0, DimType.X) // get a point with PointId = 0 and only a single dimensions
@@ -112,7 +112,7 @@ PDAL Scala project introduces a DSL to simplify PDAL Pipeline construction (this
     val pv: PointView          = pvs.next() // let's take the first PointView
 
     // load all points into JVM memory
-    // PointCloud provides operations on PDAL points that 
+    // PointCloud provides operations on PDAL points that
     // are loaded in this case into JVM memory as a single Array[Byte]
     val pointCloud: PointCloud = pv.getPointCloud()
     val x: Double = pointCloud.getDouble(0, DimType.X) // get a point with PointId = 0 and only a single dimensions
@@ -130,7 +130,7 @@ PDAL Scala project introduces a DSL to simplify PDAL Pipeline construction (this
     pv.close()
     pipeline.close()
 
-It covers PDAL 2.0.x, but to use any custom DSL that is not covered by the 
+It covers PDAL 2.0.x, but to use any custom DSL that is not covered by the
 current Scala API you can use `RawExpr`_ type to build `Pipeline Expression`_:
 
 .. code-block:: scala
@@ -139,9 +139,9 @@ current Scala API you can use `RawExpr`_ type to build `Pipeline Expression`_:
     import io.pdal.pipeline._
     import io.circe.syntax._
 
-    val pipelineWithRawExpr = 
-      ReadLas("1.2-with-color.las") ~ 
-      RawExpr(Map("type" -> "filters.crop").asJson) ~ 
+    val pipelineWithRawExpr =
+      ReadLas("1.2-with-color.las") ~
+      RawExpr(Map("type" -> "filters.crop").asJson) ~
       WriteLas("1.2-with-color-out.las")
 
 Installation
@@ -150,7 +150,7 @@ Installation
 .. index:: Install, Java, Scala
 
 PDAL Java artifacts are cross published for `Scala 2.13`_, `2.12`_ and `2.11`_.
-However, if it is not required, a separate artifact that has no Scala specific 
+However, if it is not required, a separate artifact that has no Scala specific
 artifact postfix is published as well.
 
 .. code-block:: scala
@@ -169,10 +169,10 @@ artifact postfix is published as well.
 
 The latest version is: |Maven Central|
 
-.. |Maven Central| image:: https://maven-badges.herokuapp.com/maven-central/io.pdal/pdal/badge.svg
+.. |Maven Central| image:: https://maven-badges.herokuapp.com/maven-central/io.pdal/pdal/badge.png
    :target: https://search.maven.org/search?q=g:io.pdal
 
-There is also an `example SBT PDAL Demo project <https://github.com/PDAL/java/tree/master/examples/pdal-jni>`_ in the 
+There is also an `example SBT PDAL Demo project <https://github.com/PDAL/java/tree/master/examples/pdal-jni>`_ in the
 bindings repository, that can be used for a quick start.
 
 Compilation
@@ -181,7 +181,7 @@ Compilation
 .. index:: Compile, Java, Scala
 
 Development purposes (including binaries) compilation:
-  1. Install PDAL (using brew / package managers (unix) / build from sources / etc)     
+  1. Install PDAL (using brew / package managers (unix) / build from sources / etc)
   2. Build native libs `./sbt native/nativeCompile`_ (optionally, binaries would be built during tests run)
   3. Run `./sbt core/test`_ to run PDAL tests
 
@@ -195,7 +195,7 @@ Only Java development purposes compilation:
 If you would like to use your own bindings binary, it is necessary to set `java.library.path`:
 
 .. code-block:: scala
-    
+
     // Mac OS X example with manual JNI installation
     // cp -f native/target/resource_managed/main/native/x86_64-darwin/libpdaljni.2.1.dylib /usr/local/lib/libpdaljni.2.1.dylib
     // place built binary into /usr/local/lib, and pass java.library.path to your JVM

doc/stages/filters.hag.rst

@@ -3,18 +3,22 @@
 filters.hag
 ===============================================================================
 
-The **Height Above Ground (HAG) filter** takes as input a point cloud with
-``Classification`` set to 2 for ground points.  It creates a new dimension,
-``HeightAboveGround``, that contains the normalized height values.
-
 .. note::
 
-   We expect ground returns to have the classification value of 2 in keeping
-   with the `ASPRS Standard LIDAR Point Classes <http://www.asprs.org/a/society/committees/standards/LAS_1_4_r13.pdf>`_.
+    The HAG filter is deprecated and has been replaced by :ref:`filters.hag_nn`,
+    :ref:`filters.hag_dem` and :ref:`filters.hag_delaunay`.  Please use
+    the new filter
+    that matches your needs as this filter will be removed in a future release.
 
-Ground points may be generated by :ref:`filters.pmf` or
-:ref:`filters.smrf`, but you can use any method
-you choose, as long as the ground returns are marked.
+The **Height Above Ground (HAG) filter** takes as input a point cloud with
+``Classification`` set to 2 for ground points (see
+`ASPRS Standard LIDAR Point Classes
+<http://www.asprs.org/a/society/committees/standards/LAS_1_4_r13.pdf>`_).
+It creates a new dimension,
+``HeightAboveGround``, that contains the normalized height values.  Ground
+points may be generated by :ref:`filters.pmf` or :ref:`filters.smrf`,
+but you can use any method you choose, as long as the ground returns are
+marked with the classification value of 2.
 
 Normalized heights are a commonly used attribute of point cloud data. This can
 also be referred to as *height above ground* (HAG) or *above ground level* (AGL)

doc/stages/filters.hag_delaunay.rst

@@ -0,0 +1,90 @@
+.. _filters.hag_delaunay:
+
+filters.hag_delaunay
+===============================================================================
+
+The **Height Above Ground Delaunay filter** takes as input a point cloud with
+``Classification`` set to 2 for ground points.  It creates a new dimension,
+``HeightAboveGround``, that contains the normalized height values.
+
+.. note::
+
+   We expect ground returns to have the classification value of 2 in keeping
+   with the `ASPRS Standard LIDAR Point Classes
+   <http://www.asprs.org/a/society/committees/standards/LAS_1_4_r13.pdf>`_.
+
+Ground points may be generated by :ref:`filters.pmf` or :ref:`filters.smrf`,
+but you can use any method you choose, as long as the ground returns are
+marked.
+
+Normalized heights are a commonly used attribute of point cloud data. This can
+also be referred to as *height above ground* (HAG) or *above ground level*
+(AGL) heights. In the end, it is simply a measure of a point's relative height
+as opposed to its raw elevation value.
+
+The filter creates a delaunay triangulation of the `count`_ ground points
+closest to the non-ground point in question.  If the non-ground point is within
+the trianulated area, the assigned ``HeightAboveGround`` is the difference
+between its ``Z`` value and a ground height interpolated from the three
+vertices of the containing triangle.  If the non-ground point is outside of the
+triangulated area, its ``HeightAboveGround`` is calculated as the difference
+between its ``Z`` value and the ``Z`` value of the nearest ground point.
+
+Choosing a value for `count`_ is difficult, as placing the non-ground point in
+the triangulated area depends on the layout of the nearby points.  If, for
+example, all the ground points near a non-ground point lay on one side of that
+non-ground point, finding a containing triangle will fail.
+
+.. embed::
+
+Example #1
+----------
+
+Using the autzen dataset (here shown colored by elevation), which already has
+points classified as ground
+
+.. image:: ./images/autzen-elevation.png
+   :height: 400px
+
+we execute the following pipeline
+
+.. code-block:: json
+
+  [
+      "autzen.laz",
+      {
+          "type":"filters.hag_delaunay"
+      },
+      {
+          "type":"writers.laz",
+          "filename":"autzen_hag_delaunay.laz",
+          "extra_dims":"HeightAboveGround=float32"
+      }
+  ]
+
+which is equivalent to the ``pdal translate`` command
+
+::
+
+    $ pdal translate autzen.laz autzen_hag_delaunay.laz hag_delaunay \
+        --writers.las.extra_dims="HeightAboveGround=float32"
+
+In either case, the result, when colored by the normalized height instead of
+elevation is
+
+.. image:: ./images/autzen-hag-delaunay.png
+   :height: 400px
+
+Options
+-------------------------------------------------------------------------------
+
+_`count`
+    The number of ground neighbors to consider when determining the height
+    above ground for a non-ground point.  [Default: 10]
+
+allow_extrapolation
+    If false and a non-ground point lies outside of the bounding box of
+    all ground points, its ``HeightAboveGround`` is set to 0.  If true
+    and ``delaunay`` is set, the ``HeightAboveGround`` is set to the
+    difference between the heights of the non-ground point and nearest
+    ground point.  [Default: false]

doc/stages/filters.hag_dem.rst

@@ -0,0 +1,84 @@
+.. _filters.hag_dem:
+
+filters.hag_dem
+===============================================================================
+
+The **Height Above Ground (HAG) Digital Elevation Model (DEM) filter** loads
+a GDAL-readable raster image specifying the DEM. The ``Z`` value of each point
+in the input is compared against the value at the corresponding X,Y location
+in the DEM raster. It creates a new dimension, ``HeightAboveGround``, that
+contains the normalized height values.
+
+Normalized heights are a commonly used attribute of point cloud data. This can
+also be referred to as *height above ground* (HAG) or *above ground level* (AGL)
+heights. In the end, it is simply a measure of a point's relative height as
+opposed to its raw elevation value.
+
+.. embed::
+
+.. streamable::
+
+Example #1
+----------
+
+Using the autzen dataset (here shown colored by elevation)
+
+.. image:: ./images/autzen-elevation.png
+   :height: 400px
+
+we generate a DEM based on the points already classified as ground
+
+::
+  
+    $ pdal translate autzen.laz autzen_dem.tif range \
+        --filters.range.limits="Classification[2:2]" \
+        --writers.gdal.output_type="idw" \
+        --writers.gdal.resolution=6 \
+        --writers.gdal.window_size=24
+
+and execute the following pipeline
+
+.. code-block:: json
+
+  [
+      "autzen.laz",
+      {
+          "type":"filters.hag_dem",
+          "raster": "autzen_dem.tif"
+      },
+      {
+          "type":"writers.las",
+          "filename":"autzen_hag_dem.laz",
+          "extra_dims":"HeightAboveGround=float32"
+      }
+  ]
+
+which is equivalent to the ``pdal translate`` command
+
+::
+
+    $ pdal translate autzen.laz autzen_hag_dem.laz hag_dem \
+        --filters.hag_dem.raster=autzen_dem.tif \
+        --writers.las.extra_dims="HeightAboveGround=float32"
+
+In either case, the result, when colored by the normalized height instead of
+elevation is
+
+.. image:: ./images/autzen-hag-dem.png
+   :height: 400px
+
+Options
+-------------------------------------------------------------------------------
+
+_`raster`
+    GDAL-readable raster to use for DEM.
+
+band
+    GDAL Band number to read (count from 1).
+    [Default: 1]
+
+zero_ground
+    If true, set HAG of ground-classified points to 0 rather than comparing
+    ``Z`` value to raster DEM.
+    [Default: true]
+