Update documentation with new graphics and proper refs

doc/stages/filters.hag_delaunay.rst

@@ -3,7 +3,7 @@
 filters.hag_delaunay
 ===============================================================================
 
-The **Height Above Ground Delaunay `filter** takes as input a point cloud with
+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.
 
@@ -13,35 +13,35 @@ The **Height Above Ground Delaunay `filter** takes as input a point cloud with
    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.
+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.
+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.
+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)
+Using the autzen dataset (here shown colored by elevation), which already has
+points classified as ground
 
 .. image:: ./images/autzen-elevation.png
    :height: 400px
@@ -56,32 +56,25 @@ we execute the following pipeline
           "type":"filters.hag_delaunay"
       },
       {
-          "type":"writers.bpf",
-          "filename":"autzen-height.bpf",
-          "output_dims":"X,Y,Z,HeightAboveGround"
+          "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-height.bpf hag_delaunay \
-        --writers.bpf.output_dims="X,Y,Z,HeightAboveGround"
+    $ 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-height.png
+.. image:: ./images/autzen-hag-delaunay.png
    :height: 400px
 
-::
-
-    $ pdal translate autzen.laz autzen-height-as-Z-smrf.bpf \
-        smrf hag_delaunay ferry \
-        --filters.ferry.dimensions="HeightAboveGround=Z" \
-        --filters.hag_delaunay.count=15
-
 Options
 -------------------------------------------------------------------------------
 

doc/stages/filters.hag_dem.rst

@@ -26,42 +26,45 @@ Using the autzen dataset (here shown colored by elevation)
 .. image:: ./images/autzen-elevation.png
    :height: 400px
 
-and a DEM generated from it
+we generate a DEM based on the points already classified as ground
 
 ::
   
-  # pdal translate autzen.laz autzen-dem.tiff filters.smrf \
-      --writers.gdal.resolution=1
+    $ 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
 
-we execute the following pipeline
+and execute the following pipeline
 
 .. code-block:: json
 
   [
       "autzen.laz",
       {
           "type":"filters.hag_dem",
-          "raster": "autzen-dem.tiff"
+          "raster": "autzen_dem.tif"
       },
       {
-          "type":"writers.bpf",
-          "filename":"autzen-height.bpf",
-          "output_dims":"X,Y,Z,HeightAboveGround"
+          "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-height.bpf hag_dem \
-        --filters.hag_dem.raster=autzen-dem.tiff \
-        --writers.bpf.output_dims="X,Y,Z,HeightAboveGround"
+    $ 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-height.png
+.. image:: ./images/autzen-hag-dem.png
    :height: 400px
 
 Options

doc/stages/filters.hag_nn.rst

@@ -3,38 +3,38 @@
 filters.hag_nn
 ===============================================================================
 
-The **Height Above Ground Nearest Neighbor 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.
+The **Height Above Ground Nearest Neighbor 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.
+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.
+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 finds the `count`_ ground points nearest the
-non-ground point under consideration.  It calculates an average ground
-height weighted by the distance of each ground point from the non-ground
-point.  The ``HeightAboveGround`` is the difference between the ``Z`` value
-of the non-ground point and the interpolated ground height.
+The filter finds the `count`_ ground points nearest the non-ground point under
+consideration.  It calculates an average ground height weighted by the distance
+of each ground point from the non-ground point.  The ``HeightAboveGround`` is
+the difference between the ``Z`` value of the non-ground point and the
+interpolated ground height.
 
 .. embed::
 
 Example #1
 ----------
 
-Using the autzen dataset (here shown colored by elevation)
+Using the autzen dataset (here shown colored by elevation), which already has
+points classified as ground
 
 .. image:: ./images/autzen-elevation.png
    :height: 400px
@@ -49,40 +49,38 @@ we execute the following pipeline
           "type":"filters.hag_nn"
       },
       {
-          "type":"writers.bpf",
-          "filename":"autzen-height.bpf",
-          "output_dims":"X,Y,Z,HeightAboveGround"
+          "type":"writers.laz",
+          "filename":"autzen_hag_nn.laz",
+          "extra_dims":"HeightAboveGround=float32"
       }
   ]
 
 which is equivalent to the ``pdal translate`` command
 
 ::
 
-    $ pdal translate autzen.laz autzen-height.bpf hag \
-        --writers.bpf.output_dims="X,Y,Z,HeightAboveGround"
+    $ pdal translate autzen.laz autzen_hag_nn.laz hag_nn \
+        --writers.las.extra_dims="HeightAboveGround=float32"
 
 In either case, the result, when colored by the normalized height instead of
 elevation is
 
-.. image:: ./images/autzen-height.png
+.. image:: ./images/autzen-hag-nn.png
    :height: 400px
 
 Example #2
 -------------------------------------------------------------------------------
 
-In the previous example, we chose a :ref:`writer <writers.bpf>` that could
-output custom dimensions. If you'd instead like to overwrite your Z values,
-then follow the height filter with :ref:`filters.ferry` as shown
+In the previous example, we chose to write ``HeightAboveGround`` using the
+``extra_dims`` option of :ref:`writers.las`. If you'd instead like to overwrite
+your Z values, then follow the height filter with :ref:`filters.ferry` as shown
 
 .. code-block:: json
 
   [
       "autzen.laz",
       {
-          "type":"filters.hag_nn",
-          "count": 10,
-          "delaunay": true
+          "type":"filters.hag_nn"
       },
       {
           "type":"filters.ferry",
@@ -106,8 +104,7 @@ or :ref:`filters.smrf` to label ground returns, as shown
           "type":"filters.smrf"
       },
       {
-          "type":"filters.hag_nn",
-          "count":4
+          "type":"filters.hag_nn"
       },
       {
           "type":"filters.ferry",
@@ -116,14 +113,6 @@ or :ref:`filters.smrf` to label ground returns, as shown
       "autzen-height-as-Z-smrf.laz"
   ]
 
-which is equivalent to the command:
-
-::
-
-    $ pdal translate autzen.laz autzen-height-as-Z-smrf.bpf smrf hag_nn ferry \
-        --filters.ferry.dimensions="HeightAboveGround=Z" \
-        --filters.hag_nn.count=4
-
 Options
 -------------------------------------------------------------------------------
 
@@ -136,8 +125,7 @@ max_distance
     performing neighbor interpolation.  [Default: None]
 
 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, extrapolation is used to assign the ``HeightAboveGround``
-    value.
-    [Default: false]
+    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,
+    extrapolation is used to assign the ``HeightAboveGround`` value.  [Default:
+    false]

doc/stages/filters.rst

@@ -42,8 +42,9 @@ invalidate an existing KD-tree.
    filters.estimaterank
    filters.elm
    filters.ferry
-   filters.hag
+   filters.hag_delaunay
    filters.hag_dem
+   filters.hag_nn
    filters.info
    filters.lof
    filters.miniball