Merge branch 'next'

tmontaigu · Dec 28, 2020 · 704cbef · 704cbef
2 parents 2b62330 + 6ea8425
commit 704cbef
Show file tree

Hide file tree

Showing 65 changed files with 2,385 additions and 2,697 deletions.
diff --git a/.gitignore b/.gitignore
@@ -10,3 +10,4 @@ pylas.egg-info/
 .pytest_cache/
 .cache/
 .mypy_cache/
+.nox
diff --git a/README.rst b/README.rst
@@ -10,6 +10,7 @@ Another way of reading LAS/LAZ in Python.
 
 .. image:: https://travis-ci.org/tmontaigu/pylas.svg?branch=master
 
+
 Example
 -------
 
@@ -28,19 +29,27 @@ Example
             las = f.read()
     print(las.vlrs)
 
-Some rough documentation is available on ReadTheDocs_ .
+Documentation is hosted on ReadTheDocs_ .
 
 .. _ReadTheDocs: http://pylas.readthedocs.io/en/latest/index.html
 
+
+Installation
+------------
+
+See the Installation_ section of the documentation:
+
+.. _Installation: https://pylas.readthedocs.io/en/latest/installation.html
+
 Dependencies & Requirements
 ---------------------------
 
-Python 3 Only.
-
-lazperf_ is an optional, but recommended dependency that allows pylas to read and write compressed LAZ files.
+Supported CPython versions are: 3.6, 3.7, 3.8, 3.9
 
-.. _lazperf: https://github.com/hobu/laz-perf
+pylas supports LAS natively,to support LAZ it needs one of its supported backend to be installed:
 
+ - lazrs
+ - laszip
 
 
 Installation

diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -2,27 +2,46 @@ pylas package
 =============
 
 .. module:: pylas
+
+Re-exported functions
+---------------------
+
 .. autofunction:: read
 .. autofunction:: open
 .. autofunction:: create
 .. autofunction:: convert
 
 
+Re-exported classes
+-------------------
+
+ - :class:`.LasHeader`
+ - :class:`.LasData`
+ - :class:`.PointFormat`
+ - :class:`.VLR`
+ - :class:`.ExtraBytesParams`
+ - :class:`.LasReader`
+ - :class:`.LasWriter`
+ - :class:`.LasAppender`
+
+
 Submodules
 ----------
 
 .. toctree::
 
    pylas.lib
-   pylas.lasdatas
+   pylas.header
    pylas.lasreader
+   pylas.lasdata
    pylas.vlrs.vlrlist
+   pylas.vlrs.known
+   pylas.vlrs.vlr
    pylas.point.record
-   pylas.evlrs
    pylas.errors
    pylas.compression
-   pylas.headers
    pylas.point.format
-   pylas.vlrs.known
    pylas.lasmmap
+   pylas.lasappender
+   pylas.laswriter
 
diff --git a/docs/api/pylas.compression.rst b/docs/api/pylas.compression.rst
@@ -1,7 +1,10 @@
 pylas.compression module
 ========================
 
-.. automodule:: pylas.compression
+LazBackend
+----------
+
+.. autoclass:: pylas.compression.LazBackend
     :members:
     :undoc-members:
     :show-inheritance:
diff --git a/docs/api/pylas.evlrs.rst b/docs/api/pylas.evlrs.rst
diff --git a/docs/api/pylas.header.rst b/docs/api/pylas.header.rst
@@ -0,0 +1,12 @@
+pylas.header module
+======================
+
+
+LasHeader
+---------
+
+.. autoclass:: pylas.header.LasHeader
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :exclude-members: write_to, read_from, set_compressed, update, partial_reset
diff --git a/docs/api/pylas.headers.rst b/docs/api/pylas.headers.rst
diff --git a/docs/api/pylas.lasappender.rst b/docs/api/pylas.lasappender.rst
@@ -0,0 +1,9 @@
+pylas.lasappender
+=================
+
+
+LasAppender
+-----------
+
+.. autoclass:: pylas.lasappender.LasAppender
+    :members:
diff --git a/docs/api/pylas.lasdata.rst b/docs/api/pylas.lasdata.rst
@@ -0,0 +1,11 @@
+pylas.lasdata module
+======================
+
+
+LasData
+-------
+
+.. autoclass:: pylas.lasdata.LasData
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/pylas.lasdatas.rst b/docs/api/pylas.lasdatas.rst
diff --git a/docs/api/pylas.lasreader.rst b/docs/api/pylas.lasreader.rst
@@ -1,7 +1,10 @@
 pylas.lasreader module
 ======================
 
-.. automodule:: pylas.lasreader
+LasReader
+---------
+
+.. autoclass:: pylas.lasreader.LasReader
     :members:
     :undoc-members:
     :show-inheritance:
diff --git a/docs/api/pylas.laswriter.rst b/docs/api/pylas.laswriter.rst
@@ -0,0 +1,11 @@
+pylas.laswriter module
+======================
+
+
+LasWriter
+---------
+
+.. autoclass:: pylas.laswriter.LasWriter
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/pylas.lib.rst b/docs/api/pylas.lib.rst
@@ -4,4 +4,5 @@ pylas.lib module
 .. automodule:: pylas.lib
     :members:
     :undoc-members:
-    :show-inheritance:
+    :show-inheritance:
+
diff --git a/docs/api/pylas.vlrs.vlr.rst b/docs/api/pylas.vlrs.vlr.rst
@@ -0,0 +1,8 @@
+pylas.vlrs.vlr
+--------------
+
+.. autoclass:: pylas.VLR
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :exclude-members: read_from
diff --git a/docs/basic.rst b/docs/basic.rst
@@ -2,7 +2,6 @@
 Basic Manipulation
 ==================
 
-
 Opening & Reading
 =================
 
@@ -18,7 +17,7 @@ that you can use to access to the data.
     print(np.unique(las.classification))
 
 pylas can also :func:`pylas.open` files reading just the header and vlrs but not the points, this is useful
-if you need metada informations that are contained in the header.
+if you are interested in metadas that are contained in the header and do not need to read the points.
 
 .. code:: python
 
@@ -32,8 +31,8 @@ if you need metada informations that are contained in the header.
 
 
 Sometimes files are big, too big to be read entirely and fit into your RAM.
-The object returned by the :func:`pylas.open` function, :class:`pylas.lasreader.LasReader`
-can also be used to read points chunk by chunk by using :meth:`pylas.lasreader.LasReader.chunk_iterator`, which will allow you to do some
+The object returned by the :func:`pylas.open` function, :class:`.LasReader`
+can also be used to read points chunk by chunk by using :meth:`.LasReader.chunk_iterator`, which will allow you to do some
 processing on large files (splitting, filtering, etc)
 
 .. code:: python
@@ -46,8 +45,6 @@ processing on large files (splitting, filtering, etc)
 
 
 
-
-
 Converting
 ==========
 
@@ -66,12 +63,12 @@ Use :func:`pylas.create`.
 Writing
 =======
 
-To be able to write a las file you will need a :class:`pylas.lasdatas.base.LasBase` (or one if its subclasses).
-You obtain this type of object by using one of the function above,
-use its method :meth:`pylas.lasdatas.base.LasBase.write` to write to a file or a stream.
+To be able to write a las file you will need a :class:`.LasData`.
+You obtain this type of object by using one of the function described in the section above
+use its method :meth:`.LasData.write` to write to a file or a stream.
 
 
-Similar to :class:`pylas.lasreader.LasReader` there exists a way to write a file
+Similar to :class:`.LasReader` there exists a way to write a file
 chunk by chunk.
 
 
@@ -94,7 +91,7 @@ You can access the header of a las file you read or opened by retrieving the 'he
 >>> import pylas
 >>> las = pylas.read('pylastests/simple.las')
 >>> las.header
-<LasHeader(1.2)>
+<LasHeader(1.2, <PointFormat(3, 0 bytes of extra dims)>)>
 >>> las.header.point_count
 1065
 
@@ -105,7 +102,7 @@ You can access the header of a las file you read or opened by retrieving the 'he
 
 
 
-you can see the accessible fields in :class:`pylas.headers.rawheader.RawHeader1_1` and its sub-classes.
+you can see the accessible fields in :class:`.LasHeader`.
 
 
 Accessing Points Records
@@ -179,9 +176,9 @@ To access the VLRs stored in a file, simply access the `vlr` member of the las o
 [<ExtraBytesVlr(extra bytes structs: 5)>]
 
 >>> with pylas.open('pylastests/extrabytes.las') as f:
-...     f.vlrs
+...     f.header.vlrs
 [<ExtraBytesVlr(extra bytes structs: 5)>]
 
 
-To retrieve a particular vlr from the list there are 2 ways: :meth:`pylas.vlrs.vlrlist.VLRList.get` and
-:meth:`pylas.vlrs.vlrlist.VLRList.get_by_id`
+To retrieve a particular vlr from the list there are 2 ways: :meth:`.VLRList.get` and
+:meth:`.VLRList.get_by_id`
diff --git a/docs/conf.py b/docs/conf.py
@@ -20,8 +20,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'pylas'
-copyright = '2018, pylas'
-author = 'pylas'
+copyright = '2018-2020, pylas'
+author = 'Thomas Montaigu'
 
 # Parse the version from setup.py.
 with open('../setup.py') as f:
@@ -53,8 +53,11 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
     'sphinx.ext.doctest',
+    # 'sphinx_autodoc_typehints'
 ]
 
+napoleon_use_param = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -82,6 +85,7 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+autodoc_member_order = 'bysource'
 
 # -- Options for HTML output -------------------------------------------------
 

diff --git a/docs/examples.rst b/docs/examples.rst
@@ -42,3 +42,11 @@ This example shows how you can create a new LAS file from scratch.
     las.write('diagonal.las')
 
 
+Using chunked reading & writing
+-------------------------------
+
+This example shows how to use the 'chunked' reading and writing feature
+to split potentially large LAS/LAZ file into multiple smaller file.
+
+.. literalinclude:: ../examples/recursive-split.py
+    :language: Python
diff --git a/docs/index.rst b/docs/index.rst
@@ -7,7 +7,7 @@
 pylas: Python library for lidar LAS/LAZ IO.
 ===========================================
 
-A popular format for lidar pointcloud and full waveform data is `LAS`_, and it's compressed counterpart LAZ.
+`LAS`_ (and it's compressed counterpart LAZ), is a popular format for lidar pointcloud and full waveform,
 pylas reads and writes these formats and provides a Python API via Numpy Arrays.
 
 .. _LAS: https://www.asprs.org/committee-general/laser-las-file-format-exchange-activities.html
@@ -51,8 +51,8 @@ User Guide
 .. toctree::
     :maxdepth: 2
 
-    intro
     installation
+    intro
     basic
     examples
     lessbasic