python docs

doc/index.rst

@@ -88,6 +88,7 @@ Drivers
    stages/writers
    stages/filters
    dimensions
+   python
 
 Tutorials
 --------------------------------------------------------------------------------

doc/python.rst

@@ -0,0 +1,118 @@
+.. _python:
+
+********************************************************************
+Python
+********************************************************************
+
+PDAL provides Python support in two significant ways. First it `embeds`_ Python
+to allow you to write Python programs that interact with data using
+:ref:`filters.programmable` and :ref:`filters.predicate` filters. Second,
+it `extends`_ Python by providing an extension that Python programmers
+can use to leverage PDAL capabilities in their own applications.
+
+.. _`embeds`: https://docs.python.org/3/extending/embedding.html
+.. _`extends`: https://docs.python.org/3/extending/extending.html
+
+.. note::
+
+    PDAL's Python story always revolves around `Numpy`_ support. PDAL's
+    data is provided to both the filters ands the extension as
+    Numpy arrays.
+
+.. _Python: http://python.org/
+.. _NumPy: http://www.numpy.org/
+
+Versions
+--------------------------------------------------------------------------------
+
+PDAL supports both Python 2.7 and Python 3.4+. :ref:`integration` tests Python
+2.7 on both Linux and Windows. Python 3 is used by a number of developers
+for adhoc development and testing.
+
+Embed
+--------------------------------------------------------------------------------
+
+PDAL allows users to embed Python functions inline with other :ref:`pipeline`
+processing operations. The purpose of this capability is to allow users to
+write small programs that implement interesting actions without requiring a
+full C++ development activity of building a PDAL stage to implement it. A
+Python filter is an opportunity to interactively and iteratively prototype a
+data operation without strong considerations of performance or generality.  If
+something works well enough, maybe one takes on the effort to formalize it, but
+that isn't necessary. PDAL's embed of Python allows you to be as grimy as you
+need to get the job done.
+
+.. figure:: ./images/python-pdal-pipeline.png
+
+    Embedding a Python function to take Z values read from a
+    :ref:`readers.las` and then output them to a :ref:`writers.bpf`.
+
+Extend
+--------------------------------------------------------------------------------
+
+PDAL provides a Python extension that gives users access to executing
+:ref:`pipeline` instantiations and capturing the results as `Numpy`_ arrays.
+This mode of operation is useful if you are looking to have PDAL simply act as
+your data format and processing handler.
+
+Python extension users are expected to construct their own JSON :ref:`pipeline`
+using Python's ``json`` library, or whatever other libraries they wish to
+manipulate JSON. They then feed it into the extension and get back the
+results as `Numpy`_ arrays:
+
+.. code-block:: python
+
+
+    json = """
+    {
+      "pipeline": [
+        "1.2-with-color.las",
+        {
+            "type": "filters.sort",
+            "dimension": "X"
+        }
+      ]
+    }"""
+
+    import pdal
+    pipeline = pdal.Pipeline(json)
+    pipeline.validate() # check if our JSON and options were good
+    pipeline.loglevel = 8 #really noisy
+    count = pipeline.execute()
+    arrays = pipeline.arrays
+    metadata = pipeline.metadata
+    log = pipeline.log
+
+Installation
+................................................................................
+
+To install it need to compile and install :ref:`PDAL <building>` and
+then install the PDAL Python extension. The extension lives on `PyPI`_ at
+https://pypi.python.org/pypi/PDAL and you should use that version as
+your canonical Python extension install.
+
+.. _`PyPI`: https://pypi.python.org/pypi/PDAL
+
+Install from local
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In the source code of PDAL there is a ``python`` folder, you have to enter
+there and run ::
+
+    python setup.py build
+    # this should be run as administrator/super user
+    python setup.py install
+
+Install from repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The second method to install the PDAL Python extension is to use `pip`_
+or `easy_install`_, you have to run the command as administrator. ::
+
+    pip install PDAL
+
+.. note::
+
+    To install pip please read
+    `here <https://pip.pypa.io/en/stable/installing/>`_
+
+.. _`pip`: https://pip.pypa.io/en/stable/
+.. _`easy_install`: https://pypi.python.org/pypi/setuptools