Add EPT writer docs for creating EPT addon dimensions, and update EPT…

… reader doc for using the 'addon' option.

doc/stages/readers.ept.rst

@@ -16,16 +16,14 @@ This example downloads a small area around the the Statue of Liberty from the Ne
 
 .. code-block:: json
 
-    {
-      "pipeline": [
-        {
-          "type": "readers.ept",
-          "filename": "http://na.entwine.io/nyc",
-          "bounds": "([-8242669, -8242529], [4966549, 4966674])"
-        },
-        "statue-of-liberty.las"
-      ]
-    }
+   [
+      {
+         "type": "readers.ept",
+         "filename": "http://na.entwine.io/nyc/ept.json",
+         "bounds": "([-8242669, -8242529], [4966549, 4966674])"
+      },
+      "statue-of-liberty.las"
+   ]
 
 
 Options
@@ -44,6 +42,11 @@ resolution
 
     The resulting resolution may not be exactly this value: the minimum possible resolution that is at *least* as precise as the requested resolution will be selected.  Therefore the result may be a bit more precise than requested.
 
+addons
+    A mapping of assignments of the form ``DimensionName: AddonPath``, which assigns dimensions from the specified paths to the named dimensions.  These addon dimensions are created by the `EPT writer`_.  If the dimension names already exist in the EPT `Schema`_ for the given resource, then their values will be overwritten with those from the appropriate addon.
+
+    Addons may used to override well-known dimensions (see `Dimensions`_).  For example, an addon assignment of ``"Classification": "~/addons/autzen/MyGroundDimension/"`` will override an existing EPT ``Classification`` dimension with the custom dimension.
+
 origin
     EPT datasets are lossless aggregations of potentially multiple source files.  The *origin* options can be used to select all points from a single source file.  This option may be specified as a string or an integral ID.
 
@@ -58,4 +61,7 @@ threads
 .. _Entwine: https://entwine.io/
 .. _Potree: http://potree.entwine.io/data/nyc.html
 .. _Plasio: http://speck.ly/?s=http%3A%2F%2Fc%5B0-7%5D.greyhound.io&r=ept%3A%2F%2Fna.entwine.io%2Fnyc&ca=-0&ce=49.06&ct=-8239196%2C4958509.308%2C337&cd=42640.943&cmd=125978.13&ps=2&pa=0.1&ze=1&c0s=remote%3A%2F%2Fimagery%3Furl%3Dhttp%3A%2F%2Fserver.arcgisonline.com%2FArcGIS%2Frest%2Fservices%2FWorld_Imagery%2FMapServer%2Ftile%2F%7B%7Bz%7D%7D%2F%7B%7By%7D%7D%2F%7B%7Bx%7D%7D.jpg
+.. _Dimensions: https://pdal.io/dimensions.html
+.. _Schema: https://entwine.io/entwine-point-tile.html#schema
+.. _EPT writer: https://pdal.io/stages/writers.ept.html
 

doc/stages/writers.ept.rst

@@ -0,0 +1,66 @@
+.. _writers.ept:
+
+writers.ept
+===========
+
+The **EPT writer** supports writing additional dimensions to `Entwine Point Tile`_ datasets.  Thus the EPT Writer is unique among most other PDAL writers due to its limitation that it may only be used along with an `EPT reader`_.
+
+The addon dimensions created by this writer may be stored independently from the corresponding EPT dataset, therefore write-access to the EPT resource itself is not required to create and use addon dimensions.
+
+.. embed::
+
+Example
+--------------------------------------------------------------------------------
+
+This example downloads the Autzen dataset (10M points) and runs the `SMRF filter`_, which populates the ``Classification`` dimension with ground values, and writes the resulting attribute to an EPT addon dataset on the local filesystem.
+
+.. code-block:: json
+
+   [{
+      "type": "readers.ept",
+      "filename": "http://na.entwine.io/autzen/ept.json",
+      "threads": 12
+   }, {
+      "type": "filters.assign",
+      "assignment": "Classification[:]=0"
+   }, {
+      "type": "filters.smrf"
+   }, {
+      "type": "writers.ept",
+      "addons": { "~/entwine/addons/autzen/smrf": "Classification" },
+      "threads": 12
+   }]
+
+And here is a follow-up example of reading this dataset with the `EPT reader`_ - with the created addon overwriting the ``Classification`` value - and then writing the output to a single file with the `LAS writer`_.
+
+.. code-block:: json
+
+   [{
+      "type": "readers.ept",
+      "filename": "http://na.entwine.io/autzen/ept.json",
+      "addons": { "Classification": "~/entwine/addons/autzen/smrf" },
+      "threads": 12
+   }, {
+      "type": "writers.las",
+      "filename": "autzen-ept-smrf.las"
+   }]
+
+
+Options
+--------------------------------------------------------------------------------
+
+addons
+   A JSON object whose keys represent output paths for each addon dimension, and whose corresponding values represent the attributes to be written to these addon dimensions.
+
+.. note::
+
+   The ``addons`` option is reversed between the EPT reader and writer: in each case, the right-hand side represents an assignment to the left-hand side.  In the writer, the dimension value is assigned to an addon path.  In the reader, the addon path is assigned to a dimension.
+
+threads
+    Number of worker threads used to write EPT addon data.  A minimum of 4 will be used no matter what value is specified.
+
+.. _Entwine Point Tile: https://github.com/connormanning/entwine/blob/master/doc/entwine-point-tile.md
+.. _EPT reader: https://pdal.io/stages/readers.ept.html
+.. _SMRF filter: https://pdal.io/stages/filters.smrf.html
+.. _LAS writer: https://pdal.io/stages/writers.las.html
+