doc updates (about page, fix links)

doc/about.rst

@@ -8,21 +8,29 @@ About
 What is PDAL?
 --------------------------------------------------------------------------------
 
-|PDAL| is Point Data Abstraction Library, and it is an open source software for
-translating and processing `point cloud data`_. It is not limited to just
-|LiDAR| data, although the focus and impetus for many of the tools in the
-library have their origins in LiDAR.
+|PDAL| is Point Data Abstraction Library, and it is a C/C++ open source library
+and applications for translating and processing `point cloud data`_. It is not
+limited to just |LiDAR| data, although the focus and impetus for many of the
+tools in the library have their origins in LiDAR.
 
 .. _`point cloud data`: https://en.wikipedia.org/wiki/Point_cloud
 
 What is its big idea?
+--------------------------------------------------------------------------------
+
+PDAL allows you to compose :ref:`operations <filters>` on point clouds into :ref:`pipelines
+<pipeline>` of :ref:`stages <stage_index>`. These pipelines can be written in a
+declarative JSON syntax in your favorite language.
+
+Why would you want to do that?
 ................................................................................
 
-Say you wanted to load some `ASPRS LAS`_ (the most common LiDAR binary format)
+A task might be to load some `ASPRS LAS`_ (the most common LiDAR binary format)
 data into a database, but you wanted to transform it into a common coordinate
-system along the way. One option would be to write a specialized program that
-reads LAS data, reprojects it as necessary, and then handles the necessary
-operations to insert the data in the appropriate format in the database.
+system along the way. One option would be to write a specialized monolithic
+program that reads LAS data, reprojects it as necessary, and then handles the
+necessary operations to insert the data in the appropriate format in the
+database.
 
 This approach has a distinct disadvantage. It is a kind of one-off, and it
 could quickly spiral out of control as you look to add new little tweaks and
@@ -40,11 +48,37 @@ have a simple pipeline composed of a :ref:`LAS Reader <readers.las>` stage, a
 specialized program to perform this operation, you can dynamically compose it
 as a sequence of steps or operations.
 
-.. figure:: ./images/las-crop-bpf-pipeline.png
+.. figure:: ./images/las-reproject-pgpointcloud.png
 
     A simple PDAL pipeline composed of a reader, filter, and writer
     stages.
 
+A PDAL JSON :ref:`pipeline` that composes this operation to reproject
+and load the data into PostgreSQL might look something like the following:
+
+.. code-block:: json
+    :linenos:
+    :emphasize-lines: 4, 8, 12
+
+    {
+      "pipeline":[
+        {
+          "type":"readers.las",
+          "filename":"input.las"
+        },
+        {
+          "type":"filters.reprojection",
+          "out_srs":"EPSG:3857"
+        },
+        {
+          "type":"writers.pgpointcloud",
+          "connection":"host='localhost' dbname='lidar' user='hobu'",
+          "table":"output",
+          "srid":"3857"
+        }
+      ]
+    }
+
 PDAL can compose intermediate stages, for operations such as filtering,
 clipping, tiling, transforming into a processing pipeline and reuse as
 necessary. It allows you to define these pipelines as `JSON`_, and it
@@ -61,10 +95,10 @@ provides a command, :ref:`pipeline_command`, to allow you to execute them.
 
 
 How is it different than other tools?
-................................................................................
+--------------------------------------------------------------------------------
 
 LAStools
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+................................................................................
 
 .. index:: LAStools
 
@@ -81,9 +115,14 @@ philosophy in a number of important ways:
    not just `ASPRS LAS`_. `LAStools`_ can read and write formats other than LAS, but
    its view of formats it understands is within the context of the :ref:`dimension <dimensions>`
    types provided by the LAS format.
+4. PDAL is coordinated by users with its declarative :ref:`JSON <pipeline>`
+   syntax. LAStools is coordinated by linking lots of small, specialized
+   command line utilities together with intricate arguments.
+
+.. _about_pcl:
 
 PCL
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+................................................................................
 
 .. index:: PCL
 
@@ -99,7 +138,7 @@ a convenient pipeline mechanism to orchestrate PCL operations.
     PCL capabilities within PDAL operations.
 
 Greyhound and Entwine
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+................................................................................
 
 .. index:: Greyhound, Entwine
 
@@ -116,13 +155,14 @@ via HTTP clients over the internet.
 .. _`Greyhound`: http://greyhound.io
 
 plas.io and Potree
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+................................................................................
 
 `plas.io`_ is a `WebGL`_ HTML5 point cloud renderer that speaks `ASPRS LAS`_ and
-`LASzip`_ compressed LAS.
+`LASzip`_ compressed LAS. You can find the software for it at plasiojs.io and
+https://github.com/hobu/plasio-ui
 
 `Potree`_ is a `WebGL`_ HTML5 point cloud renderer that speaks `ASPRS LAS`_ and
-`LASzip`_ compressed LAS.
+`LASzip`_ compressed LAS. You can find the software at https://github.com/potree/potree/
 
 .. note::
 
@@ -135,7 +175,7 @@ plas.io and Potree
 .. _`LASzip`: http://laszip.org
 
 Others
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+................................................................................
 
 .. index:: OrfeoToolbox, libLAS, CloudCompare, Fusion
 
@@ -171,7 +211,7 @@ might find useful bits of functionality in them. These other tools include:
 .. _`Martin Isenburg`: https://www.cs.unc.edu/~isenburg/
 
 Where did PDAL come from?
-................................................................................
+--------------------------------------------------------------------------------
 
 PDAL takes its cue from another very popular open source project -- |GDAL|.
 GDAL is Geospatial Data Abstraction Library, and it is used throughout the geospatial
@@ -209,7 +249,8 @@ characteristics demand a library oriented toward these approaches and PDAL
 achieves it.
 
 What tasks are PDAL good at?
-................................................................................
+--------------------------------------------------------------------------------
+
 
 PDAL is great at point cloud data translation work flows. It allows users to
 apply algorithms to data by providing an abstract API to the content -- freeing
@@ -227,12 +268,12 @@ features make it attractive to software developers, data managers, and
 scientists.
 
 What are PDAL's weak points?
-................................................................................
+--------------------------------------------------------------------------------
 
 PDAL doesn't provide a friendly GUI interface, it expects that you have the
-confidence to dig into a command-line interface, and it sometimes forgets that
-you don't always want to read source code to figure out what exactly is
-happening.  PDAL is an open source project in active development, and because
+confidence to dig into the options of :ref:`filters`, :ref:`readers`,
+and :ref:`writers`. We sometimes forget that you don't always want to read source code
+to figure out how things work. PDAL is an open source project in active development, and because
 of that, we're always working to improve it. Please visit :ref:`community` to
 find out how you can participate if you are interested. The project is always
 looking for contribution, and the mailing list is the place to ask for help if
@@ -254,7 +295,9 @@ Core C++ Software Library
 
 PDAL provides a :ref:`C++ API <api>` software developers can use to provide
 point cloud processing capabilities in their own software. PDAL is cross-platform
-C++, and it can compile and run on Linux, OS X, and Windows.
+C++, and it can compile and run on Linux, OS X, and Windows. The best place to
+learn how to use PDAL's C API is the :ref:`test suite <pdal_test>` and
+its `source code <https://github.com/PDAL/PDAL/tree/master/test/unit>`__.
 
 .. seealso::
 

doc/api/index.rst

@@ -5,8 +5,7 @@ API
 ******************************************************************************
 
 PDAL is a C++ library, and its primary API is in that language. There is also a
-`Python API <https://pypi.python.org/pypi/PDAL>`__ that allows reading of data
-and interaction with `Numpy`_.
+:ref:`python` API that allows reading of data and interaction with `Numpy`_.
 
 .. toctree::
    :maxdepth: 2

doc/development/docker.rst

@@ -5,7 +5,7 @@ Building Docker Containers for PDAL
 ================================================================================
 
 
-PDAL's :ref:`repository <source>`_ is linked to `DockerHub`_ for automatic building
+PDAL's :ref:`repository <source>` is linked to `DockerHub`_ for automatic building
 of `Docker`_ containers. PDAL keeps three Docker containers current.
 
 * ``pdal/dependencies:latest`` -- PDAL's dependencies
@@ -16,6 +16,7 @@ of `Docker`_ containers. PDAL keeps three Docker containers current.
 
 
 .. _`Docker`: https://www.docker.com/
+.. _`DockerHub`: https://hub.docker.com/r/pdal/pdal/
 
 .. figure:: ../images/docker-master-branch.png
 
@@ -50,7 +51,7 @@ of the SHA you wish to use to have `DockerHub`_ build.
     `Ubuntu Xenial`_. When the next Ubuntu LTS is released,
     the PDAL project will likely move to it.
 
-.. _`Ubuntu Xenial: http://releases.ubuntu.com/16.04/
+.. _`Ubuntu Xenial`: http://releases.ubuntu.com/16.04/
 
 Maintenance
 ================================================================================

doc/faq.rst

@@ -17,6 +17,10 @@ FAQ
   declarative pipeline syntax for orchestrating translation operations.
   PDAL can also use PCL through the :ref:`filters.pclblock` mechanism.
 
+  .. seealso::
+
+        :ref:`about_pcl` describes PDAL and PCL's relationship.
+
 * What is PDAL's relationship to libLAS?
 
   The idea behind libLAS was limited to LIDAR data and basic

doc/index.rst

@@ -10,12 +10,16 @@ PDAL - Point Data Abstraction Library
 
 PDAL is a C++ `BSD`_ library for translating and manipulating `point cloud data`_.
 It is very much like the `GDAL`_ library which handles raster and vector data.
-See :ref:`readers` and :ref:`writers` for data formats PDAL supports, and see
-:ref:`filters` for filtering operations that you can apply with PDAL.
+See :ref:`readers` and :ref:`writers` for data formats PDAL supports, see
+:ref:`filters` for filtering operations that you can apply with PDAL, and
+visit :ref:`about` for a high level over of the library and its philosophy.
 
 In addition to the library code, PDAL provides a suite of command-line
 applications that users can conveniently use to process, filter, translate, and
-query point cloud data.  See :ref:`apps` for more information.
+query point cloud data.  :ref:`apps` provides more information on that topic.
+
+Finally, PDAL speaks Python. Visit :ref:`python` to find out how you can
+use PDAL with Python to process point cloud data.
 
 The entire website is available as a single PDF at http://pdal.io/PDAL.pdf
 

doc/quickstart.rst

@@ -16,28 +16,29 @@ run pre-built software in a way that is isolated from your system. Think of
 it like a binary that doesn't depend on your operating system's configuration
 to be able to run.
 
-While Docker is convenient, it is not for everyone. You can also obtain the
-software by installing a Linux package from :ref:`download` or compiling it
-yourself from :ref:`building`.
-
 This exercise will print the first point of an :ref:`ASPRS LAS <readers.las>` file.
 It will utilize the PDAL :ref:`command line application <apps>` to inspect the
 file.
 
 
 .. note::
 
-    Docker is not required to use PDAL, and there are packages available on
-    Linux (Debian, RPM) and OSX (Homebrew). If you are a developer looking
-    to leverage PDAL, you will need access to the library in your environment,
-    but this quick start document is for those looking to quickly interact
-    with data using PDAL's :ref:`command line applicationds <apps>`.
+    While Docker is convenient, it is not for everyone. You can also obtain the
+    software by installing a Linux package from :ref:`download` or compiling it
+    yourself from :ref:`building`.
 
-.. seealso::
+    Docker is not required to use PDAL, and there are packages available on
+    Linux (Debian, RPM) and OSX (`Homebrew`_). See :ref:`download` to obtain
+    them. If you are a developer looking to leverage PDAL, you will need access
+    to the library in your environment, but this quick start document is for
+    those looking to quickly interact with data using PDAL's :ref:`command line
+    applications <apps>` and :ref:`pipeline`.
 
-    If you need to compile your own copy of PDAL, see :ref:`compilation` for
+    If you need to compile your own copy of PDAL, see :ref:`building` for
     more details.
 
+.. _`Homebrew`: http://brew.sh
+
 .. _docker:
 
 Install Docker
@@ -86,7 +87,8 @@ Obtain PDAL Image
 ................................................................................
 
 A PDAL image based on the latest release, including all recent patches, is
-pushed to `Docker Hub`_ with every code change on the PDAL maintenance branch.
+pushed to `Docker Hub`_ with every code change on the PDAL maintenance branch (find
+out more about that at :ref:`here <development_docker>`).
 We need to pull it locally so we can use it to run PDAL commands. Once it is
 pulled, we don't have to pull it again unless we want to refresh it for
 whatever reason.
@@ -179,6 +181,8 @@ What's next?
 * :ref:`The PDAL workshop <workshop>` contains numerous hands-on examples with screenshots and
   example data of how to use PDAL :ref:`apps` to tackle point cloud data
   processing tasks.
+* :ref:`python` describes how PDAL embeds and extends Python and
+  how you can leverage these capabilities in your own programs.
 
 .. seealso::
 

doc/workshop/exercises/info/metadata.rst

@@ -14,7 +14,7 @@ This exercise uses PDAL to print metadata information. Issue the
 following command in your `Docker Quickstart Terminal`.
 
 
-literalinclude:: ./metadata-command.txt
+.. literalinclude:: ./metadata-command.txt
     :linenos:
 
 
@@ -33,10 +33,12 @@ literalinclude:: ./metadata-command.txt
 
     * `Python JSON library`_
     * `jsawk`_ (like ``awk`` but for JSON data)
+    * `jq`_ (command line processor for JSON)
     * `Ruby JSON library`_
 
 .. _`Python JSON library`: https://docs.python.org/2/library/json.html
 .. _`jsawk`: https://github.com/micha/jsawk
+.. _`jq`: https://stedolan.github.io/jq/
 .. _`Ruby JSON library`: http://ruby-doc.org/stdlib-2.0.0/libdoc/json/rdoc/JSON.html