Merge pull request #76 from ASPRSorg/draft-R14

Merging LAS 1.4 R14 changes for final draft

source/00_index.txt

@@ -3,18 +3,14 @@ Welcome to LAS's documentation!
 ===============================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 5
    :caption: Contents:
+   :numbered:
 
    01_intro
-   04_definition
-   05_legacy
-   06_crs
-   07_datatypes
-   08_header
-   09_vlr
-   10_point
-   11_evlr
-   12_defined_vlrs
-   15_profiles
+   02.00_definition
+   03_required_vlrs
+   04_optional_vlrs
+   05_defined_evlrs
+   06_profiles
 

source/01_intro.txt

@@ -1,24 +1,111 @@
-Purpose, Scope, and Applicability
+Introduction
 --------------------------------------------------------------------------------
 
-The LAS file is intended to contain LIDAR (or other) point cloud data records.
-The data will generally be put into this format from software (e.g. provided by
-LIDAR hardware vendors) which combines GPS, IMU, and laser pulse range data to
+Purpose, Scope, and Applicability
+................................................................................
+
+The LAS file is intended to contain lidar (or other) point cloud data records.
+The data will generally be put into this format from software (e.g., provided by
+hardware vendors), which combines GPS, IMU, and laser pulse range data to
 produce X, Y, and Z point data. The intention of the data format is to provide
-an open format that allows different LIDAR hardware and software tools to
+an open format that allows different hardware and software tools to
 output data in a common format.
 
 This document reflects the fourth revision of the LAS format specification
 since its initial version 1.0 release.
 
-LAS 1.4 Additions
-................................................................................
+
+LAS 1.4 Revision History
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Summary of LAS 1.4 revisions:
+
+* R11 - Approved Version (Nov 2011).
+* R12 - Errata (June 2012) - Typographical corrections:
+
+  * Corrected Public Header Size in descriptive paragraph to 375 bytes.
+  * Corrected two instances of Scan Angle Rank from "Unsigned Char" to "Char".
+
+* R13 - Added Domain Profile Section (July 2013).
+* R14 - Multiple updates (GitHub Issue numbers):
+
+  * Aesthetic changes from migration to GitHub
+  * Multiple capitalization & typo corrections.
+  * Updated ASPRS contact info.
+    (`I-30 <https://github.com/ASPRSorg/LAS/issues/30>`_)
+  * Additional standard classifications 19-22 for PDRFs 6-10:
+    (`I-11 <https://github.com/ASPRSorg/LAS/issues/11>`_,
+    `I-26 <https://github.com/ASPRSorg/LAS/issues/26>`_)
+
+    * Class 19 -- Overhead Structure in PDRFs 6-10.
+    * Class 20 -- Ignored Ground.
+    * Class 21 -- Snow.
+    * Class 22 -- Temporal Exclusion.
+
+  * Added OGC endorsement.
+    (`I-31 <https://github.com/ASPRSorg/LAS/issues/31>`_)
+  * Added minimum PDRF sizes to attribute tables.
+    (`I-47 <https://github.com/ASPRSorg/LAS/issues/47>`_)
+  * Section reorganization:
+    (`I-57 <https://github.com/ASPRSorg/LAS/issues/57>`_)
+
+    * Addition of Table of Contents with section numbers. (c.f. 
+      `I-27 <https://github.com/ASPRSorg/LAS/issues/27>`_,
+      `I-49 <https://github.com/ASPRSorg/LAS/issues/49>`_)
+    * Divided Defined Variable Length Records section into Coordinate
+      Reference System VLRs section (s3) and Other Specification Defined
+      VLRs (s4).
+    * Expanded EVLR discussion in Legacy Compatibility section (s2.1) and moved
+      Legacy Compatibility section to EVLR definition (now s2.7.1).
+    * Swapped order of LAS 1.4 Revision History (now s1.1.1) and
+      LAS 1.4 Additions (now s1.1.2).
+    * Rearranged paragraphs in Extra Bytes VLR description.
+
+  * Deprecated "tuple" and "triple" extra byte data types.
+    (`I-1 <https://github.com/ASPRSorg/LAS/issues/1>`_)
+
+    * Added explanation and example of implicit arrays from descriptor names.
+
+  * Clarified that ExtraByte min/max should be an untransformed value.
+    (`I-4 <https://github.com/ASPRSorg/LAS/issues/4>`_)
+  * Clarified that Legacy Point Counts should be set to zero if using non-legacy
+    PDRFs. (`I-12 <https://github.com/ASPRSorg/LAS/issues/12>`_)
+  * Clarified Full Waveform descriptions and added wiki link.
+    (`I-9 <https://github.com/ASPRSorg/LAS/issues/9>`_)
+  * Renamed X(t), Y(t), and Z(t) from waveform packets to Parametric dx/dy/dz.
+  * PDRF9 now correctly requires Scanner Channel like other PDRFs.
+    (`I-29 <https://github.com/ASPRSorg/LAS/issues/29>`_)
+  * Clarified origin date/time for Adjusted Standard GPS Time.
+    (`I-40 <https://github.com/ASPRSorg/LAS/issues/40>`_)
+  * Clarified null-termination of fixed-length ``char`` arrays, especially VLR
+    Description. (`I-46 <https://github.com/ASPRSorg/LAS/issues/46>`_)
+  * Clarified relationship between FileSourceID and PointSourceID.
+    (`I-59 <https://github.com/ASPRSorg/LAS/issues/59>`_)
+  * Added language to support technologies other than conventional linear-mode
+    lidar scanners. (`I-35 <https://github.com/ASPRSorg/LAS/issues/35>`_)
+
+    * Clarified and renamed Synthetic Return Numbers Global Encoding bit.
+    * Clarified Synthetic point classification flag.
+    * Clarified validity of zero-value PointSourceID.
+    * Unified Return Number and Number of Returns descriptions between
+      legacy and non-legacy PDRFs.
+    * Clarified Scan Direction and Edge of Flight Line Flags for non-rotational systems.
+
+  * Added wiki link for Project ID examples.
+    (`I-38 <https://github.com/ASPRSorg/LAS/issues/38>`_)
+
+For detailed information on changes in revisions R14 and newer, review the
+inline differencing provided on the `GitHub page <https://github.com/ASPRSorg/LAS>`_.
+
+
+Comparison of LAS 1.4 to Previous Versions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The additions of LAS 1.4 include:
 
 * Backward compatibility with LAS 1.1 – LAS 1.3 when payloads consist of only
   legacy content
-* LAS 1.4 Mode which supports
+* LAS 1.4 mode which supports:
 
   * Extension of offsets and field sizes to support full 64 bit
   * Support for up to 15 returns per outgoing pulse
@@ -33,43 +120,48 @@ The additions of LAS 1.4 include:
   * Addition of an (optional) Extra Byte Variable Length Record to describe
     "extra bytes" stored with each point
 
-* Other minor changes
+* Other minor changes:
 
   * Added definitions for "LAS Domain Profile" and "LAS Domain Profile
     Description"
+  * Added links to official LAS wiki: https://github.com/ASPRSorg/LAS/wiki
 
-LAS 1.4 Revision History
-................................................................................
-
-Summary of LAS 1.4 revisions:
-
-* R11 - Approved Version (Nov 2011)
-* R12 - Errata (June 2012) - Typographical corrections:
-
-  * Corrected Public Header size in descriptive paragraph to 375 bytes
-  * Corrected two instances of Scan Angle Rank from "Unsigned Char" to "Char"
-
-* R13 - Added Domain Profile Section (July 2013)
-* R14 - Aesthetic changes from migration to GitHub
-
-For detailed information on changes in revisions R14 and newer, review the
-inline differencing provided on the GitHub page: https://github.com/ASPRSorg/LAS
 
 Conformance
---------------------------------------------------------------------------------
+................................................................................
 
 The data types used in the LAS format definition are conformant to the 1999
 ANSI C Language Specification (ANSI/ISO/IEC 9899:1999 ("C99").
 
+
 Authority
---------------------------------------------------------------------------------
+................................................................................
+
+ASPRS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The American Society for Photogrammetry & Remote Sensing (ASPRS) is the owner
 of the LAS Specification. The standard is maintained by committees within the
 organization as directed by the ASPRS Board of Directors. Questions related to
-this standard can be directed to ASPRS at 301-493-0290, by email at
-[email protected], or by mail at 5410 Grosvenor Lane, Suite 210, Bethesda,
-Maryland 20814-2160.
+this standard can be directed to ASPRS:
+
+* Online at https://github.com/ASPRSorg/LAS
+* By phone at 301-493-0290
+* By email at [email protected] or [email protected]
+* By mail at 425 Barlow Place, Suite 210, Bethesda, Maryland 20814-2160.
+
+OGC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+LAS has been recognized by the Open Geospatial Consortium (`OGC`_) in 2018 as an
+OGC Community Standard. The OGC version of the document with forward material
+about standards that LAS references and its status within the standard body can
+be found at https://portal.opengeospatial.org/files/17-030r1.
+
+Future recognition and activity on OGC referencing activities of LAS can be
+followed at http://www.opengeospatial.org/standards/community.
+
+.. _`OGC`: http://www.opengeospatial.org
 
 .. raw:: latex
 

source/04_definition.txt → source/02.00_definition.txt

@@ -12,22 +12,22 @@ The Variable Length Records (VLRs) contain variable types of data including
 projection information, metadata, waveform packet information, and user
 application data. They are limited to a data payload of 65,535 bytes.
 
-The Extended Variable Length Records (EVRLs) allow a higher payload than VLRs
+The Extended Variable Length Records (EVLRs) allow a higher payload than VLRs
 and have the advantage that they can be appended to the end of a LAS file. This
-allows adding, for example, projection information to a LAS file without having
+allows, for example, adding projection information to a LAS file without having
 to rewrite the entire file.
 
 
 .. table:: LAS 1.4 Format Definition
 
     +--------------------------------------------+
-    | PUBLIC HEADER BLOCK                        |
+    | :ref:`headerblock_label`                   |
     +--------------------------------------------+
-    | VARIABLE LENGTH RECORDS (VLR)              |
+    | :ref:`vlrdef_label`                        |
     +--------------------------------------------+
-    | POINT DATA RECORDS                         |
+    | :ref:`ptrecords_label`                     |
     +--------------------------------------------+
-    | EXTENDED VARIABLE LENGTH RECORDS (EVLR)    |
+    | :ref:`evlrdef_label`                       |
     +--------------------------------------------+
 
 
@@ -38,4 +38,12 @@ Packets (if stored internally to the file) have the offset to the storage
 header contained within the Public Header Block ("Start of Waveform Data Packet
 Record").
 
+.. include:: ./02.01_legacy.sub
+.. include:: ./02.02_crs.sub
+.. include:: ./02.03_datatypes.sub
+.. include:: ./02.04_header.sub
+.. include:: ./02.05_vlr.sub
+.. include:: ./02.06_point.sub
+.. include:: ./02.07_evlr.sub
+
 

source/05_legacy.txt → source/02.01_legacy.sub

@@ -1,19 +1,19 @@
-Legacy Compatibility (LAS 1.1 – LAS 1.3)
---------------------------------------------------------------------------------
+Legacy Compatibility (LAS 1.1 - LAS 1.3)
+................................................................................
 
 LAS 1.4 moves the file specification from a 32 bit file structure (maximum
 value of :math:`2^{32}-1 \equiv 4,294,967,295 \equiv \mbox{UINT32\_MAX}`) to a
 64 bit file structure (:math:`2^{64} - 1`).
 
 To maintain the ability to place a LAS 1.1 through LAS 1.3 payload (point
 record types 0-5, GeoTIFF coordinate reference system, referred to as "Legacy"
-payloads) in a LAS 1.4 file structure, it was necessary to duplicate some of
+payloads) in a LAS 1.4 file structure, it is necessary to duplicate some of
 the fields within the LAS 1.4 file structure. These duplicate fields are named
 "Legacy xxx" where "xxx" denotes the meaning of the field.
 
 A LAS 1.4 file writer who wishes to maintain backward compatibility must
 maintain both the legacy fields and the equivalent non-legacy fields in
-synchronization. Of course, this is not possible if the number of points
+synchronization. However, this is not possible if the number of points
 exceeds UINT32_MAX, in which case the legacy fields must be set to zero. If a
 file writer is not maintaining backward compatibility, the legacy fields must
 always be set to zero.
@@ -23,4 +23,8 @@ LAS 1.4 field, the LAS 1.4 reader should use the legacy value to maintain the
 same behavior as a LAS 1.1 through LAS 1.3 reader. Best practice is to also
 throw an informative error so that the file can be repaired.
 
+LAS 1.4 introduced the option to define Variable Length Records (VLRs) as
+Extended Variable Length Records (EVLRs) instead. A LAS 1.4 file writer wishing
+to maintain backward compatibility must use only VLRs. See the
+:ref:`evlr_legacy_label` section for more information.
 

source/06_crs.txt → source/02.02_crs.sub

@@ -1,5 +1,5 @@
 Coordinate Reference System (CRS) Representation
---------------------------------------------------------------------------------
+................................................................................
 
 GeoTIFF is being replaced by Well Known Text (WKT) as the required Coordinate
 Reference System (CRS) representation for the new point types (6-10) introduced
@@ -15,7 +15,7 @@ A file writer who desires to maintain backward compatibility with legacy LAS
 for point types 0-5 must add a GeoTIFF VLR to represent the CRS for the file
 and ensure that the WKT bit is false.
 
-The CRS representation is summarized in Table 2
+The CRS representation is summarized below:
 
 .. table:: Coordinate Reference System Representation
 
@@ -30,11 +30,10 @@ The CRS representation is summarized in Table 2
 It is considered a file error to have more than one GeoTIFF (E)VLR or more than
 one WKT (E)VLR in the file. A writer can append a new CRS EVLR to a file by
 "superseding" the existing CRS (E)VLR. Superseding is performed by changing the
-LAS_Spec ID of the record to "Superseded", a new LASF_Spec defined in this
+LAS_Spec ID of the record to ":ref:`superseded_vlr_label`", a new LASF_Spec defined in this
 release.
 
 
-
 .. raw:: latex
 
     \newpage

source/07_datatypes.txt → source/02.03_datatypes.sub

@@ -15,6 +15,17 @@ data types are conformant to the 1999 ANSI C Language Specification
 * unsigned long long (8 bytes)
 * float (4 byte IEEE floating point format)
 * double (8 byte IEEE floating point format)
-* string (a variable series of 1 byte characters, ASCII encoded, null terminated)
+* string (a variable series of 1 byte characters, ASCII encoded, null-terminated)
 
+.. warning::
+
+    Fixed-length ``char`` arrays will not be null-terminated if all bytes are
+    utilized. Examples include the System Identifier and Generating Software in
+    the LAS Header, the User ID or Description in the Variable Length Record,
+    and the Name of an Extra Byte Descriptor.
+
+
+.. raw:: latex
+
+    \newpage