rasterization doc

doc/workshop/exercises/analysis/rasterize/classification.json

@@ -1,18 +1,16 @@
 {
   "pipeline":[
-      {
-          "type":"readers.greyhound",
-          "url":"http://na.greyhound.io/resource/dk-z/read?depthBegin=1&depthEnd=29&bounds=[11045777.34375,-11852109.375,223441.40625,11055492.1875,-11842394.53125,233156.25]&compress=true&scale=0.01&offset=[1295630,7596240,-2280]"
-      },
+    {
+        "type":"readers.greyhound",
+        "url":"http://na.greyhound.io/resource/dk-z/read?depthBegin=1&depthEnd=29&bounds=[11045777.34375,-11852109.375,223441.40625,11055492.1875,-11842394.53125,233156.25]&compress=true&scale=0.01&offset=[1295630,7596240,-2280]"
+    },
     {
       "type":"writers.gdal",
-      "filename":"denmark-elevation.tif",
-      "dimension":"Z",
-      "data_type":"float",
+      "filename":"denmark-classification.tif",
+      "dimension":"Classification",
+      "data_type":"uint16_t",
       "output_type":"mean",
-      "window_size":"20",
-      "resolution":5.0
-
+      "resolution":30.0
     }
   ]
 }

doc/workshop/exercises/analysis/rasterize/classify-command.txt

@@ -1,4 +1 @@
-gdaldem hillshade ^
-    C:/Users/hobu/pdal/exercises/analysis/dtm/dtm.tif ^
-    C:/Users/hobu/pdal/exercises/analysis/dtm/hillshade.tif ^
-    -z 1.0 -s 1.0 -az 315.0 -alt 45.0 -of GTiff
+pdal pipeline classification.json

doc/workshop/exercises/analysis/rasterize/intensity-run-command.txt

@@ -1,2 +1,6 @@
-pdal pipeline ^
-   c:/Users/hobu/PDAL/exercises/analysis/rasterize/classification.json
+pdal pipeline classification.json ^
+    --writers.gdal.dimension="Intensity" ^
+    --writers.gdal.data_type="float" ^
+    --writers.gdal.filename="intensity.tif"
+
+gdal_translate intensity.tif intensity.png -of PNG

doc/workshop/exercises/analysis/rasterize/rasterize.rst

@@ -5,22 +5,21 @@ Rasterizing Attributes
 
 .. include:: ../../../includes/substitutions.rst
 
-.. index:: elevation model, DTM, DSM, classifications,
+.. index:: classification, intensity, rasterization
 
 This exercise uses PDAL to generate a raster surface using a fully classified
-point cloud with PDAL's :ref:`writers.gdal` operation.
+point cloud with PDAL's :ref:`writers.gdal`.
 
 
 Exercise
 --------------------------------------------------------------------------------
 
 
 .. note::
+    The exercise fetches its data from a `Greyhound`_ service that organizes the
+    point cloud collection for the entire country of Denmark. You can view the
+    data online at http://potree.entwine.io/data/denmark.html
 
-    The primary input for `Digital Terrain Model`_ generation is a point cloud
-    with ground classifications. We created this file, called
-    ``denoised-ground-only.laz``, in the :ref:`ground` exercise. Please produce that
-    file by following that exercise before starting this one.
 
 .. _`Digital Terrain Model`: https://en.wikipedia.org/wiki/Digital_elevation_model
 
@@ -33,16 +32,17 @@ Command
 
 Invoke the following command, substituting accordingly, in your `OSGeo4W Shell`:
 
-PDAL capability to generate rasterized output is provided by the :ref:`writers.gdal`
-stage. There is no :ref:`application <apps>` to drive this stage, and we
-must use a pipeline.
+PDAL capability to generate rasterized output is provided by the :ref:`writers.gdal` stage.
+There is no :ref:`application <apps>` to drive this stage, and we must use a pipeline.
+
+
 
 Pipeline breakdown
 ................................................................................
 
 
-.. include:: ./gdal.json
-    :literal:
+.. literalinclude:: ./classification.json
+    :highlight-lines: 3-7
 
 .. note::
 
@@ -54,87 +54,102 @@ Pipeline breakdown
 1. Reader
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``denoised-ground-only`` is the |LASzip| file we will clip. You should have
-created this output as part of the :ref:`ground` exercise.
+.. literalinclude:: ./classification.json
+    :lines: 3-7
+
+The data is read from a readers.greyhound server that hosts the Denmark data.
+We’re going to download a small patch of data by the Copenhagen airport that is
+the “full depth” of the tree.
 
 
 2. :ref:`writers.gdal`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :ref:`writers.gdal` writer that bins the point cloud data into an elevation
-surface.
+The :ref:`writers.gdal` writer that bins the point cloud data with classification
+values.
+
+.. literalinclude:: ./classification.json
+    :lines: 7-14
 
 Execution
 ................................................................................
 
-.. literalinclude:: ./dtm-run-command.txt
-    :linenos:
+Issue the :ref:`pipeline <pipeline>` operation to execute the interpolation:
+
+.. literalinclude:: ./classify-command.txt
 
-.. image:: ../../../images/dtm-run-command.png
-    :target: ../../../../_images/dtm-run-command.png
+.. literalinclude:: ./classification.json
+
+.. image:: ../../../images/rasterization-classification-run-command.png
+    :target: ../../../../_images/rasterization-classification-run-command.png
 
 Visualization
 ................................................................................
 
-Something happened, and some files were written, but we cannot really
-see what was produced. Let us use :ref:`qgis` to visualize the output.
-
-1. Open :ref:`qgis` and `Add Raster Layer`:
+.. figure:: ../../../images/rasterization-denmark-no-ramp.png
+    :target: ../../../../_images/rasterization-denmark-no-ramp.png
+    :scale: 200%
 
-   .. image:: ../../../images/dtm-add-raster-layer.png
-        :target: ../../../../_images/dtm-add-raster-layer.png
+    Basic interpolation of data with :ref:`writers.gdal` will output raw
+    classification values into the resulting raster file. We will need to add a
+    color ramp to the data for a satisfactory preview.
 
-2. Add the `dtm.tif` file from your ``./PDAL/exercises/analysis/dtm``
-   directory.
 
-   .. image:: ../../../images/dtm-add-raster-mean.png
-        :target: ../../../../_images/dtm-add-raster-mean.png
+Unfortunately, this doesn’t give us a very satisfactory image to view. The
+reason is there is no color ramp associated with the file, and we’re looking at
+pixel values with values from 0-31 according to the ASPRS LAS specification.
 
-   .. image:: ../../../images/dtm-qgis-added.png
-        :target: ../../../../_images/dtm-qgis-added.png
+We want colors that correspond to the classification values a bit more
+directly. We can use a color ramp to assign explicit values. :ref:`qgis` allows us to
+create a text file color ramp that gdaldem can consume to apply colors to the
+data.
 
-3. Classify the DTM by right-clicking on the `dtm.tif` and choosing
-   `Properties`. Pick the pseudocolor rendering type, and then
-   choose a color ramp and click `Classify`.
+.. literalinclude:: ./ramp.txt
+   :linenos:
 
-   .. image:: ../../../images/dtm-qgis-classify.png
-        :target: ../../../../_images/dtm-qgis-classify.png
+With the ramp, we can use `gdaldem`_ to apply it to a new image:
 
-   .. image:: ../../../images/dtm-qgis-colorize-dtm.png
-        :target: ../../../../_images/dtm-qgis-colorize-dtm.png
+.. literalinclude:: ./gdaldem-run-command.txt
+   :linenos:
 
 
-4. :ref:`qgis` provides access to |GDAL| processing tools, and we
-   are going to use that to create a hillshade of our surface.
-   Choose `Raster-->Analysis-->Dem`:
+.. figure:: ../../../images/rasterization-colored-classification.png
+    :target: ../../../../_images/rasterization-colored-classification.png
+    :scale: 200%
 
-   .. image:: ../../../images/dtm-qgis-select-hillshade.png
-        :target: ../../../../_images/dtm-qgis-select-hillshade.png
+    The use of ``-exact_color_entry`` for gdaldem ensures that specific
+    classification values are given the requested color. For categorical
+    data such as a classification surface, interpolated output would look
+    poor.
 
-5. Click the window for the `Output file` and select a location
-   to save the ``hillshade.tif`` file.
+Intensity
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   .. image:: ../../../images/dtm-qgis-gdaldem.png
-        :target: ../../../../_images/dtm-qgis-gdaldem.png
+With PDAL’s ability to override pipeline via commands, we can generate a
+relative intensity image:
 
+.. literalinclude:: ./intensity-run-command.txt
+   :linenos:
 
-   .. literalinclude:: ./dtm-hillshade-command.txt
-       :linenos:
+.. figure:: ../../../images/rasterization-colored-intensity.png
+    :target: ../../../../_images/rasterization-colored-intensity.png
+    :scale: 200%
 
+    The same pipeline can be used to generate a preview image of the Intensity
+    channel of the data by overriding pipeline arguments at the command line.
 
-6. Click `OK` and the hillshade of your DTM is now available
 
-   .. image:: ../../../images/dtm-qgis-hillshade-done.png
-        :target: ../../../../_images/dtm-qgis-hillshade-done.png
 
 Notes
 --------------------------------------------------------------------------------
 
-1. `gdaldem`_, which powers the :ref:`qgis` DEM tools, is a very powerful
-   command line utility you can use for processing data.
+1. :ref:`writers.gdal`  can output any dimension PDAL can provide, but it is is
+   up to the user to interpolate the values. For categorical data, neighborhood
+   smoothing might produce undesirable results, for example.
+
+2. :ref:`pipeline` contains more information about overrides and organizing complex pipelines.
 
-2. :ref:`writers.gdal` can be used for large data, but it does not interpolate a
-   typical `TIN`_ surface model.
 
 .. _`TIN`: https://en.wikipedia.org/wiki/Triangulated_irregular_network
 .. _`gdaldem`: http://www.gdal.org/gdaldem.html
+.. _`Greyhound`: https://greyhound.io