Update README with the new Pipeline/Stage API

Author: gsakkis

README.rst

@@ -62,6 +62,60 @@ sorts it by the ``X`` dimension:
     metadata = pipeline.metadata
     log = pipeline.log
 
+Programmatic Pipeline Construction
+................................................................................
+
+The previous example specified the pipeline as a JSON string. Alternatively, a
+pipeline can be constructed by creating ``Stage`` instances and piping them
+together. For example, the previous pipeline can be specified as:
+
+.. code-block:: python
+
+    pipeline = pdal.Reader("1.2-with-color.las") | pdal.Filter.sort(dimension="X")
+
+Stage Objects
+=============
+
+- A stage is an instance of ``pdal.Reader``, ``pdal.Filter`` or ``pdal.Writer``.
+- A stage can be instantiated by passing as keyword arguments the options
+  applicable to the respective PDAL stage. For more on PDAL stages and their
+  options, check the PDAL documentation on `Stage Objects <https://pdal.io/pipeline.html#stage-objects>`__.
+- The ``filename`` option of ``Readers`` and ``Writers`` as well as the ``type``
+  option of ``Filters`` can be passed positionally as the first argument.
+- The ``inputs`` option specifies a sequence of stages to be set as input to the
+  current stage. Each input can be either the string tag of another stage, or
+  the ``Stage`` instance itself.
+- The ``Reader``, ``Filter`` and ``Writer`` classes come with classmethods for
+  all the respective PDAL drivers. For example, ``pdal.Filter.head()`` is a
+  shortcut for ``pdal.Filter(type="filters.head")``.
+
+Pipeline Objects
+================
+
+A ``pdal.Pipeline`` instance can be created from:
+
+- a JSON string: ``Pipeline(json_string)``
+- a sequence of ``Stage`` instances: ``Pipeline([stage1, stage2])``
+- a single ``Stage`` with the ``Stage.pipeline`` method: ``stage.pipeline()``
+- nothing: ``Pipeline()`` creates a pipeline with no stages.
+- joining ``Stage`` and/or other ``Pipeline`` instances together with the pipe
+  operator (``|``):
+
+  - ``stage1 | stage2``
+  - ``stage1 | pipeline1``
+  - ``pipeline1 | stage1``
+  - ``pipeline1 | pipeline2``
+
+Every application of the pipe operator creates a new ``Pipeline`` instance. To
+update an existing ``Pipeline`` use the respective in-place pipe operator (``|=``):
+
+.. code-block:: python
+
+    # update pipeline in-place
+    pipeline = pdal.Pipeline()
+    pipeline |= stage
+    pipeline |= pipeline2
+
 Reading using Numpy Arrays
 ................................................................................
 
@@ -75,77 +129,44 @@ PDAL and Python:
 
 .. code-block:: python
 
-    data = "https://github.com/PDAL/PDAL/blob/master/test/data/las/1.2-with-color.las?raw=true"
-
-
-    json = """
-        {
-          "pipeline": [
-            {
-                "type": "readers.las",
-                "filename": "%s"
-            }
-          ]
-        }"""
-
     import pdal
     import numpy as np
-    pipeline = pdal.Pipeline(json % data)
-    count = pipeline.execute()
 
-    # get the data from the first array
+    data = "https://github.com/PDAL/PDAL/blob/master/test/data/las/1.2-with-color.las?raw=true"
+
+    pipeline = pdal.Reader.las(filename=data).pipeline()
+    print(pipeline.execute())  # 1065 points
+
+    # Get the data from the first array
     # [array([(637012.24, 849028.31, 431.66, 143, 1,
     # 1, 1, 0, 1,  -9., 132, 7326, 245380.78254963,  68,  77,  88),
     # dtype=[('X', '<f8'), ('Y', '<f8'), ('Z', '<f8'), ('Intensity', '<u2'),
     # ('ReturnNumber', 'u1'), ('NumberOfReturns', 'u1'), ('ScanDirectionFlag', 'u1'),
     # ('EdgeOfFlightLine', 'u1'), ('Classification', 'u1'), ('ScanAngleRank', '<f4'),
     # ('UserData', 'u1'), ('PointSourceId', '<u2'),
     # ('GpsTime', '<f8'), ('Red', '<u2'), ('Green', '<u2'), ('Blue', '<u2')])
-
     arr = pipeline.arrays[0]
-    print (len(arr)) # 1065 points
-
 
     # Filter out entries that have intensity < 50
-    intensity = arr[arr['Intensity'] > 30]
-    print (len(intensity)) # 704 points
+    intensity = arr[arr["Intensity"] > 30]
+    print(len(intensity))  # 704 points
 
-
-    # Now use pdal to clamp points that have intensity
-    # 100 <= v < 300, and there are 387
-    clamp =u"""{
-      "pipeline":[
-        {
-          "type":"filters.range",
-          "limits":"Intensity[100:300)"
-        }
-      ]
-    }"""
-
-    p = pdal.Pipeline(clamp, [intensity])
-    count = p.execute()
-    clamped = p.arrays[0]
-    print (count)
+    # Now use pdal to clamp points that have intensity 100 <= v < 300
+    pipeline = pdal.Filter.range(limits="Intensity[100:300)").pipeline(intensity)
+    print(pipeline.execute())  # 387 points
+    clamped = pipeline.arrays[0]
 
     # Write our intensity data to an LAS file
-    output =u"""{
-      "pipeline":[
-        {
-          "type":"writers.las",
-          "filename":"clamped.las",
-          "offset_x":"auto",
-          "offset_y":"auto",
-          "offset_z":"auto",
-          "scale_x":0.01,
-          "scale_y":0.01,
-          "scale_z":0.01
-        }
-      ]
-    }"""
-
-    p = pdal.Pipeline(output, [clamped])
-    count = p.execute()
-    print (count)
+    pipeline = pdal.Writer.las(
+        filename="clamped2.las",
+        offset_x="auto",
+        offset_y="auto",
+        offset_z="auto",
+        scale_x=0.01,
+        scale_y=0.01,
+        scale_z=0.01,
+    ).pipeline(clamped)
+    print(pipeline.execute())  # 387 points
 
 
 Accessing Mesh Data