add a dimensions page. Update the tutorials to match current source code

PDAL · Oct 26, 2016 · 39ea55f · 39ea55f
1 parent 6997b1c
commit 39ea55f
Show file tree

Hide file tree

Showing 15 changed files with 231 additions and 111 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -21,6 +21,27 @@
     year  = datetime.datetime.now().year
 
 
+
+def process_dimensions():
+    import json, csv
+
+    data = open('../src/Dimension.json','rb').read()
+
+    data = json.loads(data)['dimensions']
+
+    output = []
+    for dim in data:
+        output.append([dim['name'], dim['type'], dim['description']])
+
+    output = sorted(output,key=lambda x: x[0])
+
+    with open('dimension-table.csv','wb') as fp:
+        a = csv.writer(fp, delimiter=',', quotechar='"', quoting=csv.QUOTE_ALL)
+        a.writerows(output)
+
+
+process_dimensions()
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.

diff --git a/doc/dimensions.rst b/doc/dimensions.rst
@@ -0,0 +1,15 @@
+.. _dimensions:
+
+===============================================================================
+Dimensions
+===============================================================================
+
+PDAL dimensions describe the combination of data's type, size, and meaning. The
+following table provides a list of known dimension names you can use in
+:ref:`filters`, :ref:`writers`, and :ref:`readers` descriptions.
+
+
+.. csv-table::
+    :file: ./dimension-table.csv
+    :header: "Name", "Type", "Description"
+    :widths: 10, 5, 40
diff --git a/doc/index.rst b/doc/index.rst
@@ -81,6 +81,7 @@ Drivers
    stages/readers
    stages/writers
    stages/filters
+   dimensions
 
 Tutorials
 --------------------------------------------------------------------------------
@@ -110,6 +111,11 @@ Development
    faq
    copyright
 
+.. toctree::
+   :includehidden:
+
+   references
+
 
 
 

diff --git a/doc/references.rst b/doc/references.rst
@@ -0,0 +1,20 @@
+.. _references:
+
+******************************************************************************
+References
+******************************************************************************
+
+.. index:: References
+
+
+.. [Cook1986] Cook, Robert L. "Stochastic sampling in computer graphics." *ACM Transactions on Graphics (TOG)* 5.1 (1986): 51-72.
+
+.. [Dippe1985] Dippé, Mark AZ, and Erling Henry Wold. "Antialiasing through stochastic sampling." *ACM Siggraph Computer Graphics* 19.3 (1985): 69-78.
+
+.. [Mesh2009] ALoopingIcon. "Meshing Point Clouds." *MESHLAB STUFF*. n.p., 7 Sept. 2009. Web. 13 Nov. 2015.
+
+.. [Rusu2008] Rusu, Radu Bogdan, et al. "Towards 3D point cloud based object maps for household environments." Robotics and Autonomous Systems 56.11 (2008): 927-941.
+
+.. [Zhang2003] Zhang, Keqi, et al. "A progressive morphological filter for removing nonground measurements from airborne LIDAR data." Geoscience and Remote Sensing, IEEE Transactions on 41.4 (2003): 872-882.
+
+
diff --git a/doc/stages/filters.dartsample.rst b/doc/stages/filters.dartsample.rst
@@ -17,11 +17,6 @@ is kept in tact (the same cannot be said for :ref:`filters.voxelgrid`).
     :ref:`filters.decimation` and :ref:`filters.voxelgrid` also perform
     decimation.
 
-.. [Cook1986] Cook, Robert L. "Stochastic sampling in computer graphics." *ACM Transactions on Graphics (TOG)* 5.1 (1986): 51-72.
-
-.. [Dippe1985] Dippé, Mark AZ, and Erling Henry Wold. "Antialiasing through stochastic sampling." *ACM Siggraph Computer Graphics* 19.3 (1985): 69-78.
-
-.. [Mesh2009] ALoopingIcon. "Meshing Point Clouds." *MESHLAB STUFF*. n.p., 7 Sept. 2009. Web. 13 Nov. 2015.
 
 Options
 -------------------------------------------------------------------------------

diff --git a/doc/stages/filters.ground.rst b/doc/stages/filters.ground.rst
@@ -9,8 +9,6 @@ ProgressiveMorphologicalFilter algorithm.
 ProgressiveMorphologicalFilter is an implementation of the method described in
 [Zhang2003]_.
 
-.. [Zhang2003] Zhang, Keqi, et al. "A progressive morphological filter for removing nonground measurements from airborne LIDAR data." Geoscience and Remote Sensing, IEEE Transactions on 41.4 (2003): 872-882.
-
 .. _`PCL`: http://www.pointclouds.org
 
 

diff --git a/doc/stages/filters.outlier.rst b/doc/stages/filters.outlier.rst
@@ -15,30 +15,30 @@ The default method for identifying outlier points is the statistical outlier met
 In the first pass, for each point :math:`p_i` in the input ``PointView``, compute the mean distance :math:`\mu_i` to each of the :math:`k` nearest neighbors (where :math:`k` is configurable and specified by ``mean_k``). Then,
 
 .. math::
-  
+
   \overline{\mu} = \frac{1}{N} \sum_{i=1}^N \mu_i
-  
+
 .. math::
-  
+
   \sigma = \sqrt{\frac{1}{N-1} \sum_{i=1}^N (\mu_i - \overline{\mu})^2}
 
 A global mean :math:`\overline{\mu}` of these mean distances is then computed along with the standard deviation :math:`\sigma`. From this, the threshold is computed as
 
 .. math::
-  
+
   t = \mu + m\sigma
-  
+
 where :math:`m` is a user-defined multiplier specified by ``multiplier``.
 
 We now interate over the pre-computed mean distances :math:`\mu_i` and compare to computed threshold value. If :math:`\mu_i` is greater than the threshold, it is marked as an outlier.
 
 .. math::
-  
+
   outlier_i = \begin{cases}
       \text{true,} \phantom{false,} \text{if } \mu_i >= t \\
       \text{false,} \phantom{true,} \text{otherwise} \\
   \end{cases}
-  
+
 The ``classify`` and ``extract`` options are used to control whether outlier
 points are labeled as noise, or removed from the output ``PointView``
 completely.
@@ -59,7 +59,6 @@ After outlier removal, the noise points are removed.
 
 See [Rusu2008]_ for more information.
 
-.. [Rusu2008] Rusu, Radu Bogdan, et al. "Towards 3D point cloud based object maps for household environments." Robotics and Autonomous Systems 56.11 (2008): 927-941.
 
 Example
 ................................................................................
@@ -81,7 +80,7 @@ of the 12 nearest neighbors is below the computed threshold.
         "output.las"
       ]
     }
-        
+
 Radius Method
 -------------------------------------------------------------------------------
 
@@ -91,12 +90,12 @@ number of neighboring points :math:`k_i` within radius :math:`r` (specified by
 of neighbors specified by ``min_k``, it is marked as an outlier.
 
 .. math::
-  
+
   outlier_i = \begin{cases}
       \text{true,} \phantom{false,} \text{if } k_i < k_{min} \\
       \text{false,} \phantom{true,} \text{otherwise} \\
   \end{cases}
-  
+
 The ``classify`` and ``extract`` options are used to control whether outlier
 points are labeled as noise, or removed from the output ``PointView``
 completely.
@@ -121,7 +120,7 @@ four neighbors within a radius of 1.0.
         "output.las"
       ]
     }
-    
+
 Options
 -------------------------------------------------------------------------------
 
@@ -139,7 +138,7 @@ mean_k
 
 multiplier
   Standard deviation threshold (statistical method only). [Default: **2.0**]
-  
+
 classify
   Apply classification value of 18 (LAS high noise)? [Default: **true**]
 

diff --git a/doc/stages/filters.pmf.rst b/doc/stages/filters.pmf.rst
@@ -7,8 +7,6 @@ The Progressive Morphological Filter (PMF) is a method of segmenting ground and
 non-ground returns. This filter is an implementation of the method described in
 [Zhang2003]_.
 
-.. [Zhang2003] Zhang, Keqi, et al. "A progressive morphological filter for removing nonground measurements from airborne LIDAR data." Geoscience and Remote Sensing, IEEE Transactions on 41.4 (2003): 872-882.
-
 
 Example
 -------

diff --git a/doc/stages/filters.sample.rst b/doc/stages/filters.sample.rst
@@ -21,11 +21,6 @@ is kept in tact (the same cannot be said for :ref:`filters.voxelgrid`).
     :ref:`filters.decimation` and :ref:`filters.voxelgrid` also perform
     decimation.
 
-.. [Cook1986] Cook, Robert L. "Stochastic sampling in computer graphics." *ACM Transactions on Graphics (TOG)* 5.1 (1986): 51-72.
-
-.. [Dippe1985] Dippé, Mark AZ, and Erling Henry Wold. "Antialiasing through stochastic sampling." *ACM Siggraph Computer Graphics* 19.3 (1985): 69-78.
-
-.. [Mesh2009] ALoopingIcon. "Meshing Point Clouds." *MESHLAB STUFF*. n.p., 7 Sept. 2009. Web. 13 Nov. 2015.
 
 Options
 -------------------------------------------------------------------------------

diff --git a/doc/stages/filters.statisticaloutlier.rst b/doc/stages/filters.statisticaloutlier.rst
@@ -31,7 +31,7 @@ but a value other than 2 can be chosen using :math:`\tt  multiplier`.
 
 See [Rusu2008]_ for more information.
 
-.. [Rusu2008] Rusu, Radu Bogdan, et al. "Towards 3D point cloud based object maps for household environments." Robotics and Autonomous Systems 56.11 (2008): 927-941.
+
 
 .. _`PCL`: http://www.pointclouds.org
 

diff --git a/doc/stages/readers.rst b/doc/stages/readers.rst
@@ -9,7 +9,7 @@ a network service like :ref:`readers.greyhound`.
 
 .. note::
 
-    Readers provide :cpp:class:`pdal::Dimension` to :ref:`pipeline`. PDAL attempts
+    Readers provide :ref:`dimensions` to :ref:`pipeline`. PDAL attempts
     to normalize common dimension types, like X, Y, Z, or Intensity, which are
     often found in LiDAR point clouds. Not all dimension types need to be fixed, however.
     Database drivers typically return unstructured lists of dimensions.