diff --git a/.github/workflows/pdf.yml b/.github/workflows/pdf.yml new file mode 100644 index 0000000..2801154 --- /dev/null +++ b/.github/workflows/pdf.yml @@ -0,0 +1,47 @@ +name: Docs + +on: + push: + branches: '*' + +jobs: + docs: + name: Docs + + runs-on: ubuntu-latest + strategy: + fail-fast: true + container: ghcr.io/osgeo/proj-docs + + steps: + - uses: actions/checkout@v3 + - name: Print versions + run: | + python3 --version + sphinx-build --version + DEBIAN_FRONTEND=noninteractive apt-get update -y + DEBIAN_FRONTEND=noninteractive apt-get install texlive-fonts-recommended -y + - name: Lint .rst files + run: | + if find . -name '*.rst' | xargs grep -P '\t'; then echo 'Tabs are bad, please use four spaces in .rst files.'; false; fi + - name: PDF + run: | + make latexpdf + - name: Spelling + run: | + make spelling + - uses: actions/upload-artifact@v4 + with: + name: PDF + path: build/latex/LAS.pdf + if-no-files-found: error + - uses: actions/upload-artifact@v4 + with: + name: TEX + path: build/latex/LAS.tex + if-no-files-found: error + - uses: actions/upload-artifact@v4 + with: + name: Misspelled + path: build/spelling/output.txt + if-no-files-found: ignore diff --git a/.gitignore b/.gitignore index 567609b..f785746 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ build/ +.vscode diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..a1a2d62 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,27 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +build: + os: "ubuntu-lts-latest" + tools: + python: "mambaforge-latest" + +sphinx: + builder: html + configuration: source/conf.py + fail_on_warning: false + +python: + install: + - requirements: source/requirements.txt + +conda: + environment: source/environment.yml + +formats: + - pdf + - epub diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 4ee1dec..0000000 --- a/.travis.yml +++ /dev/null @@ -1,18 +0,0 @@ -language: c -services: docker -sudo: required -os: -- linux -before_install: "./scripts/before_install.sh" -script: -- echo "no compile needed. We just build the docs in after_success" -after_success: -- echo "$TRAVIS_SECURE_ENV_VARS" -- sh -c "./scripts/build_docs.sh" -- sh -c 'if test "$TRAVIS_SECURE_ENV_VARS" = "true"; then echo "publish "; ./scripts/stage.sh; fi' -- echo "PDF at https://s3.amazonaws.com/asprs-las/LAS-specification-$TRAVIS_COMMIT.pdf" - -env: - global: - - secure: wJwGbbWxTl/mKS+qtgzlSOPydZNC2uJ/lAh35W3Tw5pufrLflFondwuxTMu8vnYR1kk2c5uxu5TFf6bjNDhEv5M/L4wYvt5rISYuqeU7C7iisl02VfbdXzZGBqLFRsB6z2Oho6nYB+nszFEMerd5m9r3qPSPILDlYuxmyjE0oZeptBOGLF9URhL4DrCRw00e7qjuOR09D9s5roZgK81FmOAtohQEfx0T8u5bqMFHcViWQGHsIGrowmObQd+4vnogV6WdydR87ezMtJn+L1Nc7EfXnmDme7NiGQRiBoVNQGxdDE07YAM4ev7sKgt+VeZSWidfHVKbUGyCxs1rhZfjsMF1f2efeSbfnN4nCI3+qrr7WNVU+da93U3PSVzk005/bMDz7KGXNZbh7yQyOmTitCxT557KWxz6twO87DxyoWDi+eZceC+ArrpycA1qR7QwMzjECHwVqITuSzXtMFfS3dps7kxUTcO8CyTXd01DeGt+5AUaoFWBLBFtq6BFgnFG/2rjuzK5DCz590hdDZV7jb4SVcWmOz9+Ig172CfwfIatLboyfm5RlFSXI5bXFPED7z83ZEqf5LWrWZaGr5l5mcIL/4OJaqsagvEPiY9rrvBRJ2LnoumMK1Glk6Iror4m4ovDcFA16CVnHZe3f45UJ4EJ+sCE+0vZYkkr6PvHEoE= - - secure: DZ1aTWsXRQMapAogRcReYHhOxAvxBksm8X9C8VeE1WNJ3vxrfMSjz7ESih3GC/gN2bCEhVIYDr2LF3rd2Y5KJOLg/heWxzvyLFEBMlYnQaIMA7lxKevPid5yOgX79M63Czh4k3paooJ6K4lJvNzLKJG2Fme1yWwr/y9RSZ0VKPVm/d0APJcQWwGT0bFYe7fYLSHVf3baZZm9WaS/XAr4pEGwamW3mua7RbdWkT72KBynuX2VPO8b0M6z+G44tSV9KM7uQVGZ/lAEnD3iU33JGGNW52LxVE67Sv2Flvv0nnNg23/y4iFMSNoGR0wigBgoIOWIA5ypUSNs1mJm1kk3Sxz3EDqt6cvDVjp5rn5gF3yR6XXuJQSssi/ZdL18v2ISqTkVMj1yKvrCIB74yzWI8kfiuW+QydK0Cb+7Ci0bkDjM9N9rgZcZNQZf6MCoaqIH9M+XamROUYWbqrTUuysiE+1VPZ0ihpY1a68f4Zw0xpK803o2xLtaZJdJpSD4Xxjf3/OHWW+LsIq8Kn/m7Zyh6Hu9DX40rVJnRj5cpeFgInrsyARVdOWEOu8q64C9s9Av+dlJ9qdNB0Hj/yW4p1Iz1v4PFudMkismjeDrJTvQeyKskdHMIhBYeuUJxLJsZZ90HgvjWU0VH+zfWCmuhZh0mGeUS0Eu4HoZ7J/6Y9VCx3s= diff --git a/Makefile b/Makefile index 18d5339..e1f68b7 100644 --- a/Makefile +++ b/Makefile @@ -17,4 +17,6 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + diff --git a/scripts/before_install.sh b/scripts/before_install.sh deleted file mode 100755 index 5d44a57..0000000 --- a/scripts/before_install.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/bin/bash - -./scripts/docker.sh - diff --git a/scripts/build_docs.sh b/scripts/build_docs.sh deleted file mode 100755 index 2a886b9..0000000 --- a/scripts/build_docs.sh +++ /dev/null @@ -1,6 +0,0 @@ -#!/bin/bash - -echo "building docs for $TRAVIS_BUILD_DIR" -docker run -v $TRAVIS_BUILD_DIR:/data -w /data asprsorg/las make latexpdf - - diff --git a/scripts/docker.sh b/scripts/docker.sh deleted file mode 100755 index 5d9d70f..0000000 --- a/scripts/docker.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/bin/bash - -# asprsorg/las image has all of the Sphinx -# dependencies need to build the LAS specification - -docker pull asprsorg/las - - diff --git a/scripts/docker/Dockerfile b/scripts/docker/Dockerfile deleted file mode 100644 index 34cee88..0000000 --- a/scripts/docker/Dockerfile +++ /dev/null @@ -1,30 +0,0 @@ -## -# ASPRSorg/LAS - -FROM ubuntu:xenial - -MAINTAINER Howard Butler - -RUN apt-key adv --recv-keys --keyserver hkp://keyserver.ubuntu.com:80 16126D3A3E5C1192 \ - && apt-get update \ - && apt-get install -y --fix-missing --no-install-recommends \ - software-properties-common build-essential ca-certificates \ - git make cmake wget unzip libtool automake python-pip \ - libpython-dev libjpeg-dev zlib1g-dev \ - python-dev python-pip g++ doxygen dvipng \ - cmake libjpeg8-dev zlib1g-dev texlive-latex-base \ - texlive-latex-extra git texlive-fonts-recommended texlive-latex-recommended \ - graphviz python-matplotlib \ - python-setuptools imagemagick latexmk \ - && apt-get remove --purge -y $BUILD_PACKAGES && rm -rf /var/lib/apt/lists/* - - - -RUN pip install breathe \ - sphinx_bootstrap_theme awscli sphinxcontrib-bibtex \ - sphinx_rtd_theme gitpython - -RUN git clone https://github.com/sphinx-doc/sphinx.git && cd sphinx \ - && git checkout stable \ - && python setup.py install - diff --git a/scripts/stage.sh b/scripts/stage.sh deleted file mode 100755 index 49592a2..0000000 --- a/scripts/stage.sh +++ /dev/null @@ -1,19 +0,0 @@ -#!/bin/bash - -sha=$(git rev-parse HEAD) - -basetex="LAS-specification-$sha.tex" -basepdf="LAS-specification-$sha.pdf" - -filename="build/latex/$basepdf" - - - -docker run -e "AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY" -e "AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID" -v $TRAVIS_BUILD_DIR:/data -w /data asprsorg/las aws s3 cp /data/build/latex/LAS.tex s3://asprs-las/$basetex --acl public-read --region us-east-1 - -echo "Raw TEX uploaded to https://s3.amazonaws.com/asprs-las/$basetex" - -docker run -e "AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY" -e "AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID" -v $TRAVIS_BUILD_DIR:/data -w /data asprsorg/las aws s3 cp /data/build/latex/LAS.pdf s3://asprs-las/$basepdf --acl public-read --region us-east-1 - -echo "Compiled PDF uploaded to https://s3.amazonaws.com/asprs-las/$basepdf" - diff --git a/source/01_intro.txt b/source/01_intro.txt index 3c5be49..8a99a40 100644 --- a/source/01_intro.txt +++ b/source/01_intro.txt @@ -12,136 +12,46 @@ produce points with X, Y, and Z coordinates. The purpose of LAS is to provide an open format that allows different hardware and software tools to exchange point cloud data in a common format. -This document reflects the fourth revision of the LAS format specification +This document reflects the fifth version of the LAS file specification since its initial version 1.0 release. -LAS 1.4 Revision History +LAS 1.5 Revision History ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Summary of LAS 1.4 revisions (GitHub Issue numbers included when applicable): - -* 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 (March 2019): - - * Aesthetic changes from migration to GitHub. - * Multiple capitalization & typo corrections. - * Updated ASPRS contact info. - (`I-30 `_) - * Additional standard classifications 19-22 for PDRFs 6-10: - (`I-11 `_, - `I-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 `_) - * Added minimum PDRF sizes to attribute tables. - (`I-47 `_) - * Section reorganization: - (`I-57 `_) - - * Addition of Table of Contents with section numbers. (c.f. - `I-27 `_, - `I-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 `_) - - * Added explanation and example of implicit arrays from descriptor names. - - * Clarified that ExtraByte min/max should be an untransformed value. - (`I-4 `_) - * Clarified that Legacy Point Counts should be set to zero if using non-legacy - PDRFs. (`I-12 `_) - * Clarified Full Waveform descriptions and added wiki link. - (`I-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 `_) - * Clarified origin date/time for Adjusted Standard GPS Time. - (`I-40 `_) - * Clarified null-termination of fixed-length ``char`` arrays, especially VLR - Description. (`I-46 `_) - * Clarified relationship between FileSourceID and PointSourceID. - (`I-59 `_) - * Added language to support technologies other than conventional linear-mode - lidar scanners. (`I-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 `_) - -* R15 - Errata and typo corrections for R14 (July 2019): - - * Minor editorial punctuation corrections. - (`I-78 `_) - * Fixed unintended reordering of Min/Max XYZ in R14 LAS header. - (`I-79 `_) - * Added missing Scanner Channel field in note about PDRF6-10 bit field. - (`I-80 `_) - -For detailed information on changes in revisions R14 and newer, review the -inline differencing provided on the `GitHub page `_. - - -Comparison of LAS 1.4 to Previous Versions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The additions of LAS 1.4 include: +Summary of LAS 1.5 revisions (topic links included when applicable): -* Backward compatibility with LAS 1.1 – LAS 1.3 when payloads consist of only - legacy content. -* LAS 1.4 mode which supports: +* R00 - Approved Version (August 2025). - * Extension of offsets and field sizes to support full 64 bit. - * Support for up to 15 returns per outgoing pulse. - * Extension of the Point Class field to support 256 classes. - * Definition of several new ASPRS standard classes. - * Extension of the Scan Angle field to 2 bytes to support finer angle resolution. - * Addition of a Sensor Channel bit field to support mobile mapping systems. - * Addition of Well Known Text (WKT) definitions for Coordinate Reference - Systems. - * Addition of an Overlap bit to indicate points in the overlap - region while maintaining the class definition. - * Addition of an (optional) :ref:`extrabytes_vlr_label` Variable Length Record to describe - "extra bytes" stored with each point. -* Other minor changes: +Comparison of LAS 1.5 to Previous Versions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - * Added definitions for "LAS Domain Profile" and "LAS Domain Profile - Description". - * Added links to official LAS wiki: https://github.com/ASPRSorg/LAS/wiki +The additions of LAS 1.5 include (topic links included when applicable): + + * Backward compatibility with 64-bit LAS 1.4 files. + * Header compatibility with LAS 1.1 - 1.4 files. + * Removed support for legacy Point Data Record Formats 0-5. + (`I-128 `_) + * Added Max/Min GPS Time fields to header block. + (`I-118 `_) + * Added Offset GPS Time definition. + (`I-6 `_) + * CRS support expanded to all published WKT versions, removing support for GeoTIFF CRS encoding. + (`I-95 `_, + `I-104 `_, + `I-129 `_) + * Clarify requirement that the Extra Bytes VLR must be unique. + (`I-150 `_) + * Deprecated Classification Lookup VLR. + (`I-82 `_) 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"). +ANSI C Language Specification (ANSI/ISO/IEC 9899:1999 ("C99")). Authority @@ -156,24 +66,29 @@ organization as directed by the ASPRS Board of Directors. Questions related to this standard can be directed to ASPRS: * Online at https://github.com/ASPRSorg/LAS -* By phone at 301-493-0290 +* By phone at 225-408-4747 * By email at las@asprs.org or asprs@asprs.org -* By mail at 425 Barlow Place, Suite 210, Bethesda, Maryland 20814-2160 +* By mail at 8550 United Plaza Blvd, Suite 1001, Baton Rouge, LA 70809 OGC ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -LAS has been recognized by the Open Geospatial Consortium (`OGC`_) in 2018 as an +LAS has been recognized by the Open Geospatial Consortium (`OGC`_) since 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. +be found at https://www.ogc.org/publications/standard/las/. Future recognition and activity on OGC referencing activities of LAS can be -followed at http://www.opengeospatial.org/standards/community. +followed at https://www.ogc.org/publications/. -.. _`OGC`: http://www.opengeospatial.org +.. _`OGC`: https://www.ogc.org -.. raw:: latex - \newpage +.. _laswiki_link: + +Official LAS Wiki +................................................................................ +The official LAS wiki hosts supplemental guidance pages, links to external +resources, public registries, and more LAS-related resources. +The wiki can be found at https://github.com/ASPRSorg/LAS/wiki. diff --git a/source/02.00_definition.txt b/source/02.00_definition.txt index 6e80c14..bdd34ed 100644 --- a/source/02.00_definition.txt +++ b/source/02.00_definition.txt @@ -1,3 +1,7 @@ +.. raw:: latex + + \newpage + LAS Format Definition -------------------------------------------------------------------------------- @@ -18,7 +22,7 @@ allows, for example, adding projection information to a LAS file without having to rewrite the entire file. -.. table:: LAS 1.4 Format Definition +.. table:: LAS 1.5 Format Definition +--------------------------------------------+ | :ref:`headerblock_label` | @@ -31,7 +35,7 @@ to rewrite the entire file. +--------------------------------------------+ -A LAS file that contains point record types 4, 5, 9, or 10 could potentially +A LAS file that contains point record types 9 or 10 could potentially contain one block of waveform data packets that is stored as the payload of any Extended Variable Length Record (EVLR). Unlike other EVLRs, the Waveform Data Packets (if stored internally to the file) have the offset to the storage @@ -39,11 +43,10 @@ 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 +.. include:: ./02.02_datatypes.sub +.. include:: ./02.03_header.sub +.. include:: ./02.04_vlr.sub +.. include:: ./02.05_point.sub +.. include:: ./02.06_evlr.sub diff --git a/source/02.01_legacy.sub b/source/02.01_legacy.sub index 2bb011a..ea00f85 100644 --- a/source/02.01_legacy.sub +++ b/source/02.01_legacy.sub @@ -1,17 +1,15 @@ 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 is necessary to duplicate some of -the fields within the LAS 1.4 file structure. These duplicate fields are named +LAS 1.4 moved the file specification from a 32 bit file structure to a +64 bit file structure. +To maintain the ability to place a LAS 1.1 through LAS 1.3 payload +in a LAS 1.4 or LAS 1.5 file header, optional support for the 32 bit field +variants is retained alongside the required 64 bit fields. +These duplicate 32 bit 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 +A LAS 1.5 file writer who wishes to maintain backward compatibility must maintain both the legacy fields and the equivalent non-legacy fields in 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 @@ -19,12 +17,12 @@ file writer is not maintaining backward compatibility, the legacy fields must always be set to zero. If there is a discrepancy between a non-zero legacy field and the equivalent -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 +LAS 1.5 field, the LAS reader should use the legacy value to maintain the +same behavior as prior versions of LAS. 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 +Extended Variable Length Records (EVLRs) instead. A LAS file writer wishing to maintain backward compatibility must use only VLRs. See the :ref:`evlr_legacy_label` section for more information. diff --git a/source/02.02_crs.sub b/source/02.02_crs.sub deleted file mode 100644 index 9b0cdb6..0000000 --- a/source/02.02_crs.sub +++ /dev/null @@ -1,40 +0,0 @@ -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 -by LAS 1.4. - -GeoTIFF is maintained for legacy reasons for point types 0-5. - -A "WKT" bit has been added to the Global Encoding flag in the Public Header -Block. If this bit is set, the CRS for the file will be located in the WKT -(Extended) Variable Length Records (EVLR, VLR). - -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 below: - -.. table:: Coordinate Reference System Representation - - +-----------------------+----------------------------+-----------------------+ - | Point Type | WKT bit == False | WKT bit == True | - +=======================+============================+=======================+ - | 0-5 | GeoTIFF | WKT | - +-----------------------+----------------------------+-----------------------+ - | 6-10 | Error | WKT | - +-----------------------+----------------------------+-----------------------+ - -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 ":ref:`superseded_vlr_label`", a new LASF_Spec defined in this -release. - - -.. raw:: latex - - \newpage - diff --git a/source/02.02_datatypes.sub b/source/02.02_datatypes.sub new file mode 100644 index 0000000..594da39 --- /dev/null +++ b/source/02.02_datatypes.sub @@ -0,0 +1,38 @@ +.. raw:: latex + + \newpage + +Data Types +................................................................................ + +The following data types are used in the LAS format definition. Note that these +data types are conformant to the 1999 ANSI C Language Specification +(ANSI/ISO/IEC 9899:1999 ("C99")), as defined in the standard header +````. + +* int8_t (1 byte) +* uint8_t (1 byte) +* int16_t (2 bytes) +* uint16_t (2 bytes) +* int32_t (4 bytes) +* uint32_t (4 bytes) +* int64_t (8 bytes) +* uint64_t (8 bytes) +* float (4-byte ``binary32`` IEEE floating point format) +* double (8-byte ``binary64`` IEEE floating point format) +* string (a variable-length array of 1-byte characters, ASCII-encoded, + null-terminated, contained in a fixed-length ``char`` array, where ``char`` + must be equivalent to either ``int8_t`` or ``uint8_t``) + +.. 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 + diff --git a/source/02.03_datatypes.sub b/source/02.03_datatypes.sub deleted file mode 100644 index 2d63e8c..0000000 --- a/source/02.03_datatypes.sub +++ /dev/null @@ -1,31 +0,0 @@ -Data Types -................................................................................ - -The following data types are used in the LAS format definition. Note that these -data types are conformant to the 1999 ANSI C Language Specification -(ANSI/ISO/IEC 9899:1999 ("C99")). - -* char (1 byte) -* unsigned char (1 byte) -* short (2 bytes) -* unsigned short (2 bytes) -* long (4 bytes) -* unsigned long (4 bytes) -* long long (8 bytes) -* 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) - -.. 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 - diff --git a/source/02.04_header.sub b/source/02.03_header.sub similarity index 56% rename from source/02.04_header.sub rename to source/02.03_header.sub index 8de5105..2af3060 100644 --- a/source/02.04_header.sub +++ b/source/02.03_header.sub @@ -1,92 +1,104 @@ +.. raw:: latex + + \newpage + .. _headerblock_label: Public Header Block ................................................................................ -.. tabularcolumns:: |p{6.5cm}|p{4.0cm}|p{2.0cm}|p{1.5cm}| +.. tabularcolumns:: |p{6.5cm}|p{2.0cm}|p{1.2cm}|p{1.8cm}|p{1.8cm}| .. table:: Public Header Block - +----------------------------------+-------------------------+-----------+--------------+ - | **Item** | **Format** | **Size** | **Required** | - +----------------------------------+-------------------------+-----------+--------------+ - | File Signature ("LASF") | char[4] | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | File Source ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Global Encoding | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Project ID - GUID Data 1 | unsigned long | 4 bytes | | - +----------------------------------+-------------------------+-----------+--------------+ - | Project ID - GUID Data 2 | unsigned short | 2 bytes | | - +----------------------------------+-------------------------+-----------+--------------+ - | Project ID - GUID Data 3 | unsigned short | 2 bytes | | - +----------------------------------+-------------------------+-----------+--------------+ - | Project ID - GUID Data 4 | unsigned char[8] | 8 bytes | | - +----------------------------------+-------------------------+-----------+--------------+ - | Version Major | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Version Minor | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | System Identifier | char[32] | 32 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Generating Software | char[32] | 32 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | File Creation Day of Year | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | File Creation Year | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Header Size | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Offset to Point Data | unsigned long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Number of Variable Length Records| unsigned long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Point Data Record Format | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Point Data Record Length | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Legacy Number of Point Records | unsigned long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Legacy Number of Point by Return | unsigned long[5] | 20 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | X Scale Factor | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Y Scale Factor | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Z Scale Factor | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | X Offset | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Y Offset | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Z Offset | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Max X | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Min X | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Max Y | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Min Y | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Max Z | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Min Z | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Start of Waveform Data Packet | unsigned long long | 8 bytes | yes | - | Record | | | | - +----------------------------------+-------------------------+-----------+--------------+ - | Start of First Extended Variable | unsigned long long | 8 bytes | yes | - | Length Record | | | | - +----------------------------------+-------------------------+-----------+--------------+ - | Number of Extended Variable | unsigned long | 4 bytes | yes | - | Length Records | | | | - +----------------------------------+-------------------------+-----------+--------------+ - | Number of Point Records | unsigned long long | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ - | Number of Points by Return | unsigned long long[15] | 120 bytes | yes | - +----------------------------------+-------------------------+-----------+--------------+ + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Item | Format | Byte Offset | Size | Required | + +==================================+=========================+=================+===========+==============+ + | File Signature ("LASF") | char[4] | 0 | 4 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | File Source ID | uint16_t | 4 | 2 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Global Encoding | uint16_t | 6 | 2 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Project ID - GUID Data 1 | uint32_t | 8 | 4 bytes | | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Project ID - GUID Data 2 | uint16_t | 12 | 2 bytes | | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Project ID - GUID Data 3 | uint16_t | 14 | 2 bytes | | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Project ID - GUID Data 4 | uint8_t[8] | 16 | 8 bytes | | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Version Major | uint8_t | 24 | 1 byte | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Version Minor | uint8_t | 25 | 1 byte | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | System Identifier | char[32] | 26 | 32 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Generating Software | char[32] | 58 | 32 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | File Creation Day of Year | uint16_t | 90 | 2 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | File Creation Year | uint16_t | 92 | 2 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Header Size | uint16_t | 94 | 2 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Offset to Point Data | uint32_t | 96 | 4 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Number of Variable Length Records| uint32_t | 100 | 4 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Point Data Record Format | uint8_t | 104 | 1 byte | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Point Data Record Length | uint16_t | 105 | 2 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Legacy Number of Point Records | uint32_t | 107 | 4 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Legacy Number of Point by Return | uint32_t[5] | 111 | 20 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | X Scale Factor | double | 131 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Y Scale Factor | double | 139 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Z Scale Factor | double | 147 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | X Offset | double | 155 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Y Offset | double | 163 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Z Offset | double | 171 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Max X | double | 179 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Min X | double | 187 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Max Y | double | 195 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Min Y | double | 203 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Max Z | double | 211 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Min Z | double | 219 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Start of Waveform Data Packet | uint64_t | 227 | 8 bytes | yes | + | Record | | | | | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Start of First Extended Variable | uint64_t | 235 | 8 bytes | yes | + | Length Record | | | | | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Number of Extended Variable | uint32_t | 243 | 4 bytes | yes | + | Length Records | | | | | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Number of Point Records | uint64_t | 247 | 8 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Number of Points by Return | uint64_t[15] | 255 | 120 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Max GPS Time | double | 375 | 8 bytes | | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Min GPS Time | double | 383 | 8 bytes | | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | Time Offset | uint16_t | 391 | 2 bytes | yes | + +----------------------------------+-------------------------+-----------------+-----------+--------------+ + | *LAS 1.5 Header Size* | *393 bytes* | + +------------------------------------------------------------+--------------------------------------------+ .. note:: @@ -117,10 +129,8 @@ systems. **Global Encoding** -This is a bit field used to indicate certain global properties about the file. -In LAS 1.2 (the version in which this field was introduced), only the low bit -is defined (this is the bit, that if set, would have the unsigned integer yield -a value of 1). This bit field is defined as: +This is a bit field used to indicate certain global properties about the file, +defined as follows: .. tabularcolumns:: |p{2.0cm}|p{3.0cm}|p{11.0cm}| @@ -130,11 +140,17 @@ a value of 1). This bit field is defined as: +-------+-----------------------+------------------------------------------+ | Bits | Field Name | Description | +=======+=======================+==========================================+ - | 0 | GPS Time Type | The meaning of GPS Time in the point | - | | | records. If this bit is not set, the GPS | - | | | time in the point record fields is GPS | + | 0 | GPS Time Type | Used in combination with Time Offset | + | | | Flag to indicate the meaning of | + | | | :ref:`GPS Time ` in the | + | | | point records. | + | | | | + | | | If neither bit is set, the GPS | + | | | Time in the point record fields is GPS | | | | Week Time (the same as versions 1.0 | - | | | through 1.2 of LAS). Otherwise, if this | + | | | through 1.2 of LAS). | + | | | | + | | | Otherwise, if this | | | | bit is set, the GPS Time is standard GPS | | | | Time (satellite GPS Time) minus | | | | 1 x :math:`10^9` (Adjusted Standard GPS | @@ -167,14 +183,39 @@ a value of 1). This bit field is defined as: | | | for a system not directly supporting | | | | multiple returns. | +-------+-----------------------+------------------------------------------+ - | 4 | WKT | If set, the Coordinate Reference System | - | | | (CRS) is WKT. If not set, the CRS is | - | | | GeoTIFF. It should not be set if the | - | | | file writer wishes to ensure legacy | - | | | compatibility (which means the CRS must | - | | | be GeoTIFF). | + | 4 | Well Known Text (WKT) | If set, the Coordinate Reference System | + | | | (CRS) is formatted as OGC WKT. This bit | + | | | must be set in LAS 1.5; GeoTIFF CRS | + | | | definitions from prior versions of LAS | + | | | are no longer supported in LAS 1.5. | + | | | The CRS definition will be located in | + | | | the WKT VLR(s) or EVLR(s) as defined in | + | | | the :ref:`crs_label` section. | + +-------+-----------------------+------------------------------------------+ + | 5 | Reserved | Must be set to zero. | + +-------+-----------------------+------------------------------------------+ + | 6 | Time Offset Flag | Used in combination with GPS Time Type | + | | | to indicate the meaning of | + | | | :ref:`GPS Time ` in the | + | | | point records. | + | | | | + | | | If both bits are set, the GPS Time | + | | | is defined as Offset GPS Time. The | + | | | Offset GPS Time is standard GPS Time | + | | | (satellite GPS Time) minus | + | | | 1 x :math:`10^6` x Time Offset. The | + | | | :ref:`Time Offset ` | + | | | is specified in the LAS header. | + | | | The offset moves time to near zero to | + | | | improve floating-point resolution for a | + | | | given time period. | + | | | The origin of standard GPS | + | | | Time is defined as midnight of the | + | | | morning of January 6, 1980. | + | | | The GPS Time Type flag must be set if | + | | | the Time Offset Flag is set. | +-------+-----------------------+------------------------------------------+ - | 5:15 | Reserved | Must be set to zero (0). | + | 7:15 | Reserved | Must be set to zero. | +-------+-----------------------+------------------------------------------+ @@ -191,14 +232,14 @@ file can be uniquely identified, globally. .. note:: Example implementations of representing the Project ID fields as a GUID can - be found on the official LAS wiki: https://github.com/ASPRSorg/LAS/wiki + be found on the :ref:`Official LAS Wiki `. **Version Number** The version number consists of a major and minor field. The major and minor fields combine to form the number that indicates the format number of the -current specification itself. For example, specification number 1.4 would -contain 1 in the major field and 4 in the minor field. It should be noted that +current specification itself. For example, specification number 1.5 would +contain 1 in the major field and 5 in the minor field. It should be noted that the LAS Working Group does not associate any particular meaning to major or minor version number. @@ -234,6 +275,8 @@ files. Thus, System ID becomes: | | identifying the operation | +-----------------------------+---------------------------------------------+ +If the character data is less than 32 characters, the remaining +data must be null. **Generating Software** @@ -246,7 +289,7 @@ data must be null. **File Creation Day of Year** -Day, expressed as an unsigned short, on which this file was created. Day is +Day, expressed as a uint16_t, on which this file was created. Day is computed as the Greenwich Mean Time (GMT) day. January 1 is considered day 1. **File Creation Year** @@ -255,8 +298,8 @@ The year, expressed as a four digit number, in which the file was created. **Header Size** -The size, in bytes, of the Public Header Block itself. For LAS 1.4 this size is -375 bytes. In the event that the header is extended by a new revision of the +The size, in bytes, of the Public Header Block itself. For LAS 1.5 this size is +393 bytes. In the event that the header is extended by a new revision of the LAS specification through the addition of data at the end of the header, the Header Size field will be updated with the new header size. The Public Header Block may not be extended by users. @@ -273,18 +316,22 @@ This field contains the current number of VLRs that are stored in the file preceding the Point Data Records. If the number of VLRs changes, then this number must be updated. +This field is unrelated to the number of EVLRs appended to the file. + **Point Data Record Format** -The point data record indicates the type of point data records contained in the -file. LAS 1.4 defines types 0 through 10. These types are defined in the +The point data record format (PDRF) value indicates the type of point data records contained in the +file. LAS 1.5 defines types 6 through 10. These types are defined in the :ref:`ptrecords_label` section of this specification. +PDRFs 0-5 as defined in previous versions of LAS are no longer valid +for LAS 1.5. **Point Data Record Length** The size, in bytes, of the Point Data Record. All Point Data Records within a -single LAS file must be the same type and hence the same length. If the -specified size is larger than implied by the point format type (e.g., 32 bytes -instead of 28 bytes for type 1) the remaining bytes are user-specific "extra +single LAS file must be the same PDRF and hence the same length. If the +specified size is larger than implied by the PDRF type (e.g., 32 bytes +instead of 30 bytes for PDRF 6) the remaining bytes are user-specific "extra bytes". The format and meaning of such "extra bytes" can (optionally) be described with an :ref:`extrabytes_vlr_label` VLR. @@ -309,7 +356,7 @@ five returns. **X, Y, and Z Scale Factors** The scale factor fields contain a double floating-point value that is used to -scale the corresponding X, Y, and Z long values within the point records. The +scale the corresponding X, Y, and Z int32_t values within the point records. The corresponding X, Y, and Z scale factor must be multiplied by the X, Y, or Z point record value to get the actual X, Y, or Z coordinate. For example, if the X, Y, and Z coordinates are intended to have two decimal digits, then each @@ -337,15 +384,16 @@ record X is multiplied by the X scale factor and then added to the X offset. **Max and Min X, Y, and Z** The max and min data fields are the actual unscaled extents of the LAS point -file data, specified in the coordinate system of the LAS data. +file data, specified in the coordinate system of the LAS data. If there are no +point records in the file, these values must be set to zero. **Start of Waveform Data Packet Record** This value provides the offset, in bytes, from the beginning of the LAS file to the first byte of the Waveform Data Package Record. Note that this will be the first byte of the Waveform Data Packet header. If no waveform records are -contained within the file or they are stored externally, this value must be zero. It should be noted that LAS -1.4 allows multiple Extended Variable Length Records (EVLRs) and that the +contained within the file or they are stored externally, this value must be zero. It should be noted that +LAS 1.5 allows multiple Extended Variable Length Records (EVLRs) and that the Waveform Data Packet Record is not necessarily the first EVLR in the file. **Start of First Extended Variable Length Record** @@ -354,12 +402,15 @@ This value provides the offset, in bytes, from the beginning of the LAS file to the first byte of the first EVLR. If any software adds/removes data to/from the Variable Length Records or Point Records, then this offset value must be updated. +If there are no EVLRs, this value must be zero. + **Number of Extended Variable Length Records** This field contains the current number of EVLRs (including, if present, the Waveform Data Packet Record) that are stored in the file after the Point Data -Records. If the number of EVLRs changes, then this number must be updated. If there -are no EVLRs this value is zero. +Records. If the number of EVLRs changes, then this number must be updated. + +If there are no EVLRs, this value must be zero. **Number of Point Records** @@ -367,6 +418,11 @@ This field contains the total number of point records in the file. Note that this field must always be correctly populated, regardless of legacy mode intent. +.. note:: + + Any changes to the number of points or their attributes must also be reflected + in the Public Header Block. + **Number of Points by Return** These fields contain an array of the total point records per return. The first @@ -375,3 +431,32 @@ contains the total number for return two, and so on up to fifteen returns. Note that these fields must always be correctly populated, regardless of legacy mode intent. +**Max and Min GPS Time** + +The max and min GPS Time fields reflect the highest and lowest non-zero +GPS Time values stored with the point records in this LAS file. The +GPS Time in this field will be in the same encoding described in the file's +:ref:`Global Encoding ` field. + +These values must be set to zero if there are no point records in the file or if +all point records within the file have GPS Time values set to zero, +such as for certain :ref:`Aggregate Model Systems `. + +.. _timeoffset_link: + +**Time Offset** + +The Time Offset field can be used to optimize :ref:`GPS Time ` precision for a desired time period. +Offset GPS Time for a point record is equal to standard GPS Time, minus :math:`10^6` * Time Offset. + +For example, Adjusted Standard GPS Time uses a total offset of 1 billion (:math:`10^9`) seconds, which would be specified by a Time Offset of 1000. +This achieves 100 nanosecond precision for the years 2007-2015. The +:ref:`Official LAS Wiki ` provides recommended values +and year ranges that users are encouraged to use to maximize compatibility between datasets. + +This value must be set to zero if there are no point records in the file, +if the file is derived from a source not utilizing GPS Time +(such as for certain :ref:`Aggregate Model Systems `), +or if the Time Offset Flag is unset. + +It is invalid for the GPS Time Type bit to be unset if the Offset Time Flag bit is set. diff --git a/source/02.05_vlr.sub b/source/02.04_vlr.sub similarity index 76% rename from source/02.05_vlr.sub rename to source/02.04_vlr.sub index c007a09..e4951bf 100644 --- a/source/02.05_vlr.sub +++ b/source/02.04_vlr.sub @@ -5,7 +5,7 @@ Variable Length Records (VLRs) The Public Header Block can be followed by any number of Variable Length Records (VLRs) so long as the total size does not make the start of the Point -Record data inaccessible by an unsigned long ("Offset to Point Data" in the +Record data inaccessible by a uint32_t ("Offset to Point Data" in the Public Header Block). The number of VLRs is specified in the "Number of Variable Length Records" field in the Public Header Block. The Variable Length Records must be accessed sequentially since the size of each variable length @@ -13,23 +13,23 @@ record is contained in the Variable Length Record Header. Each Variable Length Record Header is 54 bytes in length. -.. tabularcolumns:: |p{6.5cm}|p{4.0cm}|p{2.0cm}|p{1.5cm}| +.. tabularcolumns:: |p{5.0cm}|p{3.0cm}|p{2.2cm}|p{1.6cm}|p{1.5cm}| .. table:: Variable Length Record Header - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | Reserved | unsigned short | 2 bytes | | - +----------------------------------+-------------------------+-----------+----------+ - | User ID | char[16] | 16 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Record ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Record Length After Header | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Description | char[32] | 32 bytes | | - +----------------------------------+-------------------------+-----------+----------+ + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Item | Format | Byte Offset | Size | Required | + +==================================+=========================+=============+===========+==========+ + | Reserved | uint16_t | 0 | 2 bytes | | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | User ID | char[16] | 2 | 16 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Record ID | uint16_t | 18 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Record Length After Header | uint16_t | 20 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Description | char[32] | 22 | 32 bytes | | + +----------------------------------+-------------------------+-------------+-----------+----------+ **Reserved** diff --git a/source/02.05_point.sub b/source/02.05_point.sub new file mode 100644 index 0000000..6196347 --- /dev/null +++ b/source/02.05_point.sub @@ -0,0 +1,748 @@ +.. _ptrecords_label: + +Point Data Records +................................................................................ + +Software must use the "Offset to Point Data" field in the Public +Header Block to locate the starting position of the first Point Data Record. +Note that all Point Data Records must be the same type (i.e., Point Data Record +Format). + +Point Data Record Formats (PDRFs) 0-5 as defined in previous versions of LAS are no longer valid for LAS 1.5. +PDRFs 6-10 have improved several aspects of the core +information in the point data records, particularly support for 256 classes, +the definition of a specific "Overlap" bit, support for multiple sensor channels, etc. + +**Required Point Attributes** + +Point attributes that are "Required" must be populated with relevant values +whenever possible. If unused, point attributes that are not "Required" must be +set to the equivalent of zero for the data type (i.e., 0.0 for floating types, +null for ASCII, 0 for integers). + +If a "Required" point attribute cannot apply to a particular technology (e.g., +Scan Direction for a passive sensor) then the attribute must be set to a default +value as directed. This default value is zero if unspecified in the attribute +description. + +.. _aggregate_link: + +**Aggregate Model Systems** + +Points derived from multiple observations in an aggregate model rather than +a direct measurement system should be assigned valid values using a consistent +scheme for a given dataset. For example, in the case of a photogrammetrically +derived point cloud, the Point Source ID, GPS Time, and Scan Angle could be +assigned to a point based on the value associated with the most recent +photograph from which the point was derived. Example systems to which this +recommendation applies include photogrammetrically derived point clouds and +Geiger-mode lidar processed with a consensus model. These systems are hereafter +collectively denoted as "Aggregate Model Systems." + + + +.. raw:: latex + + \newpage + +Point Data Record Format 6 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Point Data Record Format 6 contains the core 30 bytes that are shared by Point +Data Record Formats 6 to 10. + +.. tabularcolumns:: |p{6.0cm}|p{3.5cm}|p{1.2cm}|p{1.5cm}|p{1.5cm}| + +.. table:: Point Data Record Format 6 + + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Item | Format | Byte Offset | Size | Required | + +==================================+=========================+=============+===========+==========+ + | X | int32_t | 0 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Y | int32_t | 4 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Z | int32_t | 8 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Intensity | uint16_t | 12 | 2 bytes | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Return Number | 4 bits (bits 0-3) | 14:0 | 4 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Number of Returns (Given Pulse) | 4 bits (bits 4-7) | 14:4 | 4 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Classification Flags | 4 bits (bits 0-3) | 15:0 | 4 bits | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scanner Channel | 2 bits (bits 4-5) | 15:4 | 2 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scan Direction Flag | 1 bit (bit 6) | 15:6 | 1 bit | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Edge of Flight Line | 1 bit (bit 7) | 15:7 | 1 bit | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Classification | uint8_t | 16 | 1 byte | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | User Data | uint8_t | 17 | 1 byte | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scan Angle | int16_t | 18 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Point Source ID | uint16_t | 20 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | GPS Time | double | 22 | 8 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | *Minimum PDRF Length* [1]_ | *30 bytes* | + +------------------------------------------------------------+------------------------------------+ + +.. [1] Recall that the Point Data Record Length can be greater than the minimum + required for a PDRF. These "extra bytes" follow the standard Point Record + fields and are described in the :ref:`extrabytes_vlr_label` VLR section. + +.. note:: + + A note on Bit Fields – The LAS storage format is "Little Endian." This + means that multi-byte data fields are stored in memory from least + significant byte at the low address to most significant byte at the high + address. Bit fields are always interpreted as bit 0 set to 1 equals 1, bit + 1 set to 1 equals 2, bit 2 set to 1 equals 4 and so forth. + +**X, Y, and Z** + +The X, Y, and Z values are stored as int32_t integers. The X, Y, and Z values are +used in conjunction with the scale values and the offset values to determine +the coordinate for each point as described in the :ref:`headerblock_label` section. + +**Intensity** + +The Intensity value is the integer representation of the pulse return +magnitude. This value is optional and system specific. However, it should +always be included if available. If Intensity is not included, this value must +be set to zero. + +Intensity, when included, is always normalized +to a 16 bit, unsigned value by multiplying the value by 65,536/(intensity +dynamic range of the sensor). For example, if the dynamic range of the sensor +is 10 bits, the scaling value would be (65,536/1,024). This normalization is required to +ensure that data from different sensors can be correctly merged. + +For systems based on technology other than pulsed lasers, Intensity values may +represent estimated relative reflectivity, rather than a direct measurement of +pulse return magnitude, and may be derived from multiple sources. + +.. note:: + + The following two fields (Return Number and Number of Returns) are bit fields, encoded + into one byte. + +**Return Number** + +The Return Number is the pulse return number for a given output pulse. A given +output laser pulse can have many returns, and they must be marked in sequence +of return. The first return will have a Return Number of 1, the second a +Return Number of 2, and so on up to 15 returns. The Return Number must +be between 1 and the Number of Returns, inclusive. + +For systems unable to record multiple returns, the Return Number should be +set to 1, unless it is synthetically derived and the Synthetic Return Number +:ref:`Global Encoding ` bit is set. + +**Number of Returns (Given Pulse)** + +The Number of Returns is the total number of returns for a given pulse. For +example, a laser data point may be return 2 (Return Number) within a total +number of up to 15 returns. + +For systems unable to record multiple returns, the Number of Returns should be +set to 1, unless it is synthetically derived and the Synthetic Return Number +:ref:`Global Encoding ` bit is set. + +.. note:: + + The following four fields (Classification Flags, Scanner Channel, Scan Direction Flag, + and Edge of Flight Line) are bit fields, encoded + into one byte. + +**Classification Flags** + +Classification flags are used to indicate special characteristics associated +with the point. The bit definitions are: + +.. tabularcolumns:: |p{2.0cm}|p{3.0cm}|p{8.5cm}| + +.. table:: Classification Bit Field Encoding (Point Data Record Formats 6-10) + + +-------+-------------------------+------------------------------------------+ + | Bit | Field Name | Description | + +=======+=========================+==========================================+ + | 0 | Synthetic | If set, this point was created by a | + | | | technique other than direct observation | + | | | such as digitized from a photogrammetric | + | | | stereo model or by traversing a | + | | | waveform. Point attribute interpretation | + | | | might differ from non-Synthetic points. | + | | | Unused attributes must be set to the | + | | | appropriate default value. | + +-------+-------------------------+------------------------------------------+ + | 1 | Key-Point | If set, this point is considered to be a | + | | | model key-point and therefore generally | + | | | should not be withheld in a thinning | + | | | algorithm. | + +-------+-------------------------+------------------------------------------+ + | 2 | Withheld | If set, this point should not be | + | | | included in processing (synonymous with | + | | | Deleted). | + +-------+-------------------------+------------------------------------------+ + | 3 | Overlap | If set, this point is within the | + | | | overlap region of two or more swaths or | + | | | takes. Setting this bit is not mandatory | + | | | (unless required by a specification | + | | | other than this document) but | + | | | allows Classification of overlap points | + | | | to be preserved. For example, this may | + | | | be useful for designating Ground points | + | | | that are valid but are not needed to | + | | | meet coverage or density requirements. | + +-------+-------------------------+------------------------------------------+ + +.. note:: + These bits are treated as flags and can be set or cleared in any + combination. For example, a point with bits 0 and 1 both set to one and the + *Classification* field set to 2 would be a *Ground* point that had been + *Synthetically* collected and marked as a model *Key-Point*. + + +**Scanner Channel** + +Scanner Channel is used to indicate the channel (scanner head) of a multi- +channel system. Channel 0 is used for single scanner systems. Up to four +channels are supported (0-3). + +For :ref:`Aggregate Model Systems `, the Channel should be set +to zero unless assigned from a component measurement. + +**Scan Direction Flag** + +The Scan Direction Flag denotes the direction in which the scanner mirror was +traveling at the time of the output pulse. A bit value of 1 is a positive scan +direction, and a bit value of 0 is a negative scan direction (where positive +scan direction is a scan moving from the left side of the in-track direction to +the right side and negative the opposite). + +For :ref:`Aggregate Model Systems ` or if the measurement system +does not include a rotational component, the Scan Direction Flag should be set +to zero. + +**Edge of Flight Line Flag** + +The Edge of Flight Line Flag has a value of 1 only when the point is at the +end of a scan. It is the last point on a given scan line before it changes +direction or the mirror facet changes. + +Note that this field has no meaning for :ref:`Aggregate Model Systems ` +or 360 degree Field of View scanners (e.g., terrestrial lidar scanners). In +these cases, the Edge of Flight Line Flag should be set to zero. + +**Classification** + +This field represents the "class" attributes of a point. Classifications 0-63 are +reserved for ASPRS-standard definitions, as defined in this specification and +approved :ref:`LAS Domain Profiles `. Classifications 64 and +above may be assigned meaning at the user's discretion. + + +Classification must adhere to the following standard: + + +.. tabularcolumns:: |p{3.0cm}|p{5.0cm}|p{7.0cm}| + +.. table:: ASPRS Standard Point Classes (Point Data Record Formats 6-10) + + +------------------+-----------------------------+--------------------------------+ + | Value | Meaning | Notes | + +==================+=============================+================================+ + | 0 | Created, Never Classified | See note [2]_ | + +------------------+-----------------------------+--------------------------------+ + | 1 | Unclassified | See note [2]_ | + +------------------+-----------------------------+--------------------------------+ + | 2 | Ground | | + +------------------+-----------------------------+--------------------------------+ + | 3 | Low Vegetation | | + +------------------+-----------------------------+--------------------------------+ + | 4 | Medium Vegetation | | + +------------------+-----------------------------+--------------------------------+ + | 5 | High Vegetation | | + +------------------+-----------------------------+--------------------------------+ + | 6 | Building | | + +------------------+-----------------------------+--------------------------------+ + | 7 | Low Point (Noise) | | + +------------------+-----------------------------+--------------------------------+ + | 8 | *Reserved* | | + +------------------+-----------------------------+--------------------------------+ + | 9 | Water | | + +------------------+-----------------------------+--------------------------------+ + | 10 | Rail | | + +------------------+-----------------------------+--------------------------------+ + | 11 | Road Surface | | + +------------------+-----------------------------+--------------------------------+ + | 12 | *Reserved* | | + +------------------+-----------------------------+--------------------------------+ + | 13 | Wire -- Guard (Shield) | | + +------------------+-----------------------------+--------------------------------+ + | 14 | Wire -- Conductor (Phase) | | + +------------------+-----------------------------+--------------------------------+ + | 15 | Transmission Tower | | + +------------------+-----------------------------+--------------------------------+ + | 16 | Wire-Structure Connector | e.g., insulators | + +------------------+-----------------------------+--------------------------------+ + | 17 | Bridge Deck | | + +------------------+-----------------------------+--------------------------------+ + | 18 | High Noise | | + +------------------+-----------------------------+--------------------------------+ + | 19 | Overhead Structure | e.g., conveyors, mining | + | | | equipment, traffic lights | + +------------------+-----------------------------+--------------------------------+ + | 20 | Ignored Ground | e.g., breakline proximity | + +------------------+-----------------------------+--------------------------------+ + | 21 | Snow | | + +------------------+-----------------------------+--------------------------------+ + | 22 | Temporal Exclusion | Features excluded due to | + | | | changes over time between data | + | | | sources -- e.g., water levels, | + | | | landslides, permafrost | + +------------------+-----------------------------+--------------------------------+ + | 23-63 | *Reserved* | | + +------------------+-----------------------------+--------------------------------+ + | 64-255 | User Definable | | + +------------------+-----------------------------+--------------------------------+ + + +.. [2] We are using both 0 and 1 as Unclassified to maintain compatibility + with current popular classification software such as TerraScan. We extend the + idea of classification value 1 to include cases in which data have been + subjected to a classification algorithm but emerged in an undefined state. For + example, data with class 0 is sent through an algorithm to detect man-made + structures – points that emerge without having been assigned as belonging to + structures could be remapped from class 0 to class 1. + + +**User Data** + +This field may be used at the user's discretion. + +**Scan Angle** + +The Scan Angle is an int16_t that represents the rotational position of the +emitted laser pulse with respect to the vertical dimension of the coordinate system of +the data. Down in the data coordinate system is the 0.0 position. Each +increment represents 0.006 degrees. Counter-clockwise rotation, as viewed from +the rear of the sensor, facing in the along-track (positive trajectory) +direction, is positive. The maximum value in the positive sense is 30,000 (180 +degrees which is up in the coordinate system of the data). The maximum value in +the negative direction is -30,000 which is also directly up. + +For :ref:`Aggregate Model Systems `, the Scan Angle should be +set to zero unless assigned from a component measurement. + +**Point Source ID** + +This value indicates the source from which this point originated. A source is +typically defined as a grouping of temporally consistent data, such as a +flight line or sortie number for airborne systems, a route number for mobile +systems, or a setup identifier for static systems. Valid values for this field +are 1 to 65,535 inclusive. Zero is reserved as a convenience to system +implementers. + +For :ref:`Aggregate Model Systems `, the Point Source ID should +be set to one (1) unless assigned from a component measurement. + +.. _gpstime_link: + +**GPS Time** + +The GPS Time is the double floating point time tag value at which the point was +observed. GPS Time encoding is specified by the :ref:`Global Encoding ` +bit field. The time value encoding is defined as GPS Week Time if the GPS Time Type bit is unset, +Adjusted Standard GPS Time if the GPS Time Type bit is set, +and Offset GPS Time if the Time Offset Flag bit is set. + +.. table:: GPS Time Encoding + + +---------------------+------------------------+------------------------------+ + | GPS Time Type bit | Time Offset Flag bit | Timestamp Encoding | + +=====================+========================+==============================+ + | Unset | Unset | GPS Week Time | + +---------------------+------------------------+------------------------------+ + | Set | Unset | Adjusted Standard GPS Time | + +---------------------+------------------------+------------------------------+ + | Unset | Set | *INVALID* | + +---------------------+------------------------+------------------------------+ + | Set | Set | Offset GPS Time | + +---------------------+------------------------+------------------------------+ + +It is intended that each return of a given pulse would have an identical GPS +Time. In the example of pulsed LiDAR systems, the GPS Time would be the time at +which the originating pulse was emitted, not the time at which each return was +recorded. + +For :ref:`Aggregate Model Systems `, the GPS Time should be set +to zero unless assigned from a component measurement. + + +.. raw:: latex + + \newpage + +Point Data Record Format 7 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Point Data Record Format 7 is the same as Point Data Record Format 6 with the +addition of three RGB color channels. These fields are used when "colorizing" a +point using ancillary data, typically from a camera. + +.. tabularcolumns:: |p{6.0cm}|p{3.5cm}|p{1.2cm}|p{1.5cm}|p{1.5cm}| + +.. table:: Point Data Record Format 7 + + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Item | Format | Byte Offset | Size | Required | + +==================================+=========================+=============+===========+==========+ + | X | int32_t | 0 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Y | int32_t | 4 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Z | int32_t | 8 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Intensity | uint16_t | 12 | 2 bytes | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Return Number | 4 bits (bits 0-3) | 14:0 | 4 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Number of Returns (Given Pulse) | 4 bits (bits 4-7) | 14:4 | 4 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Classification Flags | 4 bits (bits 0-3) | 15:0 | 4 bits | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scanner Channel | 2 bits (bits 4-5) | 15:4 | 2 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scan Direction Flag | 1 bit (bit 6) | 15:6 | 1 bit | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Edge of Flight Line | 1 bit (bit 7) | 15:7 | 1 bit | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Classification | uint8_t | 16 | 1 byte | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | User Data | uint8_t | 17 | 1 byte | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scan Angle | int16_t | 18 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Point Source ID | uint16_t | 20 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | GPS Time | double | 22 | 8 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Red | uint16_t | 30 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Green | uint16_t | 32 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Blue | uint16_t | 34 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | *Minimum PDRF Length* | *36 bytes* | + +------------------------------------------------------------+------------------------------------+ + +**Red, Green, and Blue** + +The Red, Green, and Blue image channel values associated with this point. + +.. note:: + + The Red, Green, and Blue values should always be normalized to 16 bit values. + For example, when encoding an 8 bit per channel pixel, multiply each + channel value by 256 prior to storage in these fields. This normalization + allows color values from different camera bit depths to be accurately + merged. + +.. raw:: latex + + \newpage + +Point Data Record Format 8 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Point Data Record Format 8 is the same as Point Data Record Format 7 with the +addition of a NIR (near infrared) channel. + +.. tabularcolumns:: |p{6.0cm}|p{3.5cm}|p{1.2cm}|p{1.5cm}|p{1.5cm}| + +.. table:: Point Data Record Format 8 + + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Item | Format | Byte Offset | Size | Required | + +==================================+=========================+=============+===========+==========+ + | X | int32_t | 0 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Y | int32_t | 4 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Z | int32_t | 8 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Intensity | uint16_t | 12 | 2 bytes | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Return Number | 4 bits (bits 0-3) | 14:0 | 4 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Number of Returns (Given Pulse) | 4 bits (bits 4-7) | 14:4 | 4 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Classification Flags | 4 bits (bits 0-3) | 15:0 | 4 bits | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scanner Channel | 2 bits (bits 4-5) | 15:4 | 2 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scan Direction Flag | 1 bit (bit 6) | 15:6 | 1 bit | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Edge of Flight Line | 1 bit (bit 7) | 15:7 | 1 bit | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Classification | uint8_t | 16 | 1 byte | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | User Data | uint8_t | 17 | 1 byte | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scan Angle | int16_t | 18 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Point Source ID | uint16_t | 20 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | GPS Time | double | 22 | 8 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Red | uint16_t | 30 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Green | uint16_t | 32 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Blue | uint16_t | 34 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | NIR | uint16_t | 36 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | *Minimum PDRF Length* | *38 bytes* | + +------------------------------------------------------------+------------------------------------+ + +**NIR** + +The NIR (near infrared) channel value associated with this point. + +.. note:: + + Note that Red, Green, Blue, and NIR values should always be normalized to 16 + bit values. For example, when encoding an 8 bit per channel pixel, multiply + each channel value by 256 prior to storage in these fields. This + normalization allows color values from different camera bit depths to be + accurately merged. + +.. raw:: latex + + \newpage + +Point Data Record Format 9 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Point Data Record Format 9 adds Wave Packets to Point Data Record Format 6. + +.. tabularcolumns:: |p{6.0cm}|p{3.5cm}|p{1.2cm}|p{1.5cm}|p{1.5cm}| + +.. table:: Point Data Record Format 9 + + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Item | Format | Byte Offset | Size | Required | + +==================================+=========================+=============+===========+==========+ + | X | int32_t | 0 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Y | int32_t | 4 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Z | int32_t | 8 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Intensity | uint16_t | 12 | 2 bytes | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Return Number | 4 bits (bits 0-3) | 14:0 | 4 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Number of Returns (Given Pulse) | 4 bits (bits 4-7) | 14:4 | 4 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Classification Flags | 4 bits (bits 0-3) | 15:0 | 4 bits | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scanner Channel | 2 bits (bits 4-5) | 15:4 | 2 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scan Direction Flag | 1 bit (bit 6) | 15:6 | 1 bit | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Edge of Flight Line | 1 bit (bit 7) | 15:7 | 1 bit | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Classification | uint8_t | 16 | 1 byte | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | User Data | uint8_t | 17 | 1 byte | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scan Angle | int16_t | 18 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Point Source ID | uint16_t | 20 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | GPS Time | double | 22 | 8 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Wave Packet Descriptor Index | uint8_t | 30 | 1 byte | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Byte Offset to Waveform Data | uint64_t | 31 | 8 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Waveform Packet Size in Bytes | uint32_t | 39 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Return Point Waveform Location | float | 43 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Parametric dx | float | 47 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Parametric dy | float | 51 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Parametric dz | float | 55 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | *Minimum PDRF Length* | *59 bytes* | + +------------------------------------------------------------+------------------------------------+ + +**Wave Packet Descriptor Index** + +This value plus **99** is the Record ID of the :ref:`fwf_descriptor_label` and +indicates the User Defined Record that describes the waveform packet associated +with this Point Record. Up to 255 different User Defined Records which describe +the waveform packet are supported. A value of zero indicates that there is no +waveform data associated with this Point Record. + +**Byte Offset to Waveform Data** + +The waveform packet data are stored in the LAS file in an Extended Variable +Length Record or in an auxiliary \*.wdp file. The Byte Offset represents the +location of the start of this Point Record’s waveform packet within the waveform +data variable length record (or external file) relative to the beginning of the +:ref:`fwf_packets_label` header. The absolute location of the beginning of this +waveform packet relative to the beginning of the file is given by: + + **Start of Waveform Data Packet Record** + **Byte Offset to Waveform Data** + + for waveform packets stored within the LAS file and + + **Byte Offset to Waveform Data** + + for data stored in an auxiliary \*.wdp file. + +**Waveform Packet Size in Bytes** + +The size, in bytes, of the waveform packet associated with this return. Note +that each waveform can be of a different size (even those with the same +Waveform Packet Descriptor index) due to packet compression. Also note that +waveform packets can be located only via the Byte Offset to Waveform Packet +Data value since there is no requirement that records be stored sequentially. + + +**Return Point Waveform Location** + +The temporal offset in picoseconds (:math:`10^{-12}`) from the arbitrary "anchor +point" to the location within the waveform packet for this Point Record. + + +**Parametric dx, dy, dz** + +These parameters define a parametric line equation for extrapolating points +along the associated waveform. The position along the wave is given by: + +.. math:: + :nowrap: + + \begin {eqnarray} + X &= X_0 + t * dx \\ + Y &= Y_0 + t * dy \\ + Z &= Z_0 + t * dz + \end {eqnarray} + +where :math:`(X, Y, Z)` is the spatial position of a derived point, +:math:`(X_0, Y_0, Z_0)` is the position of the "anchor" point, and :math:`t` is +the time, in picoseconds, relative to the anchor point. + +The anchor point is an arbitrary location at the origin of the associated +waveform -- i.e. :math:`t = 0` at the anchor point -- with coordinates defined +by: + +.. math:: + :nowrap: + + \begin {eqnarray} + X_0 &= X_P + L * dx \\ + Y_0 &= Y_P + L * dy \\ + Z_0 &= Z_P + L * dz + \end {eqnarray} + +where :math:`(X_P, Y_P, Z_P)` is this Point Record's transformed position (as a +double) and :math:`L` is this Point Record's Return Point Waveform Location. + +The units of X, Y and Z are the units of the coordinate systems of the LAS data. +If the coordinate system is geographic, the horizontal units are decimal degrees +and the vertical units are meters. + +.. note:: + + Users seeking further clarity regarding LAS waveform encoding are encouraged + to learn more on the :ref:`Official LAS Wiki `. + + +.. raw:: latex + + \newpage + +Point Data Record Format 10 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Point Data Record Format 10 is the same as Point Data Record Format 9 with RGB and NIR values. + +.. tabularcolumns:: |p{6.0cm}|p{3.5cm}|p{1.2cm}|p{1.5cm}|p{1.5cm}| + +.. table:: Point Data Record Format 10 + + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Item | Format | Byte Offset | Size | Required | + +==================================+=========================+=============+===========+==========+ + | X | int32_t | 0 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Y | int32_t | 4 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Z | int32_t | 8 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Intensity | uint16_t | 12 | 2 bytes | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Return Number | 4 bits (bits 0-3) | 14:0 | 4 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Number of Returns (Given Pulse) | 4 bits (bits 4-7) | 14:4 | 4 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Classification Flags | 4 bits (bits 0-3) | 15:0 | 4 bits | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scanner Channel | 2 bits (bits 4-5) | 15:4 | 2 bits | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scan Direction Flag | 1 bit (bit 6) | 15:6 | 1 bit | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Edge of Flight Line | 1 bit (bit 7) | 15:7 | 1 bit | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Classification | uint8_t | 16 | 1 byte | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | User Data | uint8_t | 17 | 1 byte | no | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Scan Angle | int16_t | 18 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Point Source ID | uint16_t | 20 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | GPS Time | double | 22 | 8 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Red | uint16_t | 30 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Green | uint16_t | 32 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Blue | uint16_t | 34 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | NIR | uint16_t | 36 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Wave Packet Descriptor Index | uint8_t | 38 | 1 byte | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Byte Offset to Waveform Data | uint64_t | 39 | 8 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Waveform Packet Size in Bytes | uint32_t | 47 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Return Point Waveform Location | float | 51 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Parametric dx | float | 55 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Parametric dy | float | 59 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Parametric dz | float | 63 | 4 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | *Minimum PDRF Length* | *67 bytes* | + +------------------------------------------------------------+------------------------------------+ + +.. raw:: latex + + \newpage + diff --git a/source/02.07_evlr.sub b/source/02.06_evlr.sub similarity index 76% rename from source/02.07_evlr.sub rename to source/02.06_evlr.sub index baebd96..ebcf73b 100644 --- a/source/02.07_evlr.sub +++ b/source/02.06_evlr.sub @@ -19,23 +19,23 @@ be accessed sequentially since the size of each variable length record is contained in the Extended Variable Length Record Header. Each Extended Variable Length Record Header is 60 bytes in length. -.. tabularcolumns:: |p{6.5cm}|p{4.0cm}|p{2.0cm}|p{1.5cm}| +.. tabularcolumns:: |p{5.0cm}|p{3.2cm}|p{2.2cm}|p{1.6cm}|p{1.5cm}| .. table:: Extended Variable Length Record Header - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | Reserved | unsigned short | 2 bytes | | - +----------------------------------+-------------------------+-----------+----------+ - | User ID | char[16] | 16 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Record ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Record Length After Header | unsigned long long | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Description | char[32] | 32 bytes | | - +----------------------------------+-------------------------+-----------+----------+ + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Item | Format | Byte Offset | Size | Required | + +==================================+=========================+=============+===========+==========+ + | Reserved | uint16_t | 0 | 2 bytes | | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | User ID | char[16] | 2 | 16 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Record ID | uint16_t | 18 | 2 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Record Length After Header | uint64_t | 20 | 8 bytes | yes | + +----------------------------------+-------------------------+-------------+-----------+----------+ + | Description | char[32] | 28 | 32 bytes | | + +----------------------------------+-------------------------+-------------+-----------+----------+ .. note:: diff --git a/source/02.06_point.sub b/source/02.06_point.sub deleted file mode 100644 index 9827219..0000000 --- a/source/02.06_point.sub +++ /dev/null @@ -1,1202 +0,0 @@ -.. _ptrecords_label: - -Point Data Records -................................................................................ - -Software must use the "Offset to Point Data" field in the Public -Header Block to locate the starting position of the first Point Data Record. -Note that all Point Data Records must be the same type (i.e., Point Data Record -Format). - -Point Data Record Formats (PDRFs) 6-10 have improved several aspects of the core -information in the point data records, particularly support for 256 classes and -the definition of a specific "Overlap" bit. While all PDRFs (0-10) are supported -in LAS 1.4, the preferred formats are 6-10. PDRFs 0-5 are therefore designated -as the "legacy" point formats. - -**Required Point Attributes** - -Point attributes that are "Required" must be populated with relevant values -whenever possible. If unused, point attributes that are not "Required" must be -set to the equivalent of zero for the data type (i.e., 0.0 for floating types, -null for ASCII, 0 for integers). - -If a "Required" point attribute cannot apply to a particular technology (e.g., -Scan Direction for a passive sensor) then the attribute must be set to a default -value as directed. This default value is zero if unspecified in the attribute -description. - -.. _aggregate_link: - -**Aggregate Model Systems** - -Points derived from multiple observations in an aggregate model rather than -a direct measurement system should be assigned valid values using a consistent -scheme for a given dataset. For example, in the case of a photogrammetrically -derived point cloud, the Point Source ID, GPS Time, and Scan Angle could be -assigned to a point based on the value associated with the most recent -photograph from which the point was derived. Example systems to which this -recommendation applies include photogrammetrically derived point clouds and -Geiger-mode lidar processed with a consensus model. These systems are hereafter -collectively denoted as "Aggregate Model Systems." - - -Point Data Record Format 0 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Point Data Record Format 0 contains the core 20 bytes that are shared by Point -Data Record Formats 0 to 5. - -.. tabularcolumns:: |p{7.5cm}|p{3.5cm}|p{1.5cm}|p{1.5cm}| - -.. table:: Point Data Record Format 0 - - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | X | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Y | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Z | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Intensity | unsigned short | 2 bytes | no | - +----------------------------------+-------------------------+-----------+----------+ - | Return Number | 3 bits (bits 0-2) | 3 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Number of Returns (Given Pulse) | 3 bits (bits 3-5) | 3 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Direction Flag | 1 bit (bit 6) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Edge of Flight Line | 1 bit (bit 7) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Angle Rank (-90 to +90) -- | signed char | 1 byte | yes | - | Left Side | | | | - +----------------------------------+-------------------------+-----------+----------+ - | User Data | unsigned char | 1 byte | no | - +----------------------------------+-------------------------+-----------+----------+ - | Point Source ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | *Minimum PDRF Size* [1]_ | *20 bytes* | - +------------------------------------------------------------+----------------------+ - -.. [1] Recall that the Point Data Record Size can be greater than the minimum - required for a PDRF. These "extra bytes" follow the standard Point Record - fields and are described in the :ref:`extrabytes_vlr_label` VLR section. - -**X, Y, and Z** - -The X, Y, and Z values are stored as long integers. The X, Y, and Z values are -used in conjunction with the scale values and the offset values to determine -the coordinate for each point as described in the :ref:`headerblock_label` section. - -**Intensity** - -The Intensity value is the integer representation of the pulse return -magnitude. This value is optional and system specific. However, it should -always be included if available. If Intensity is not included, this value must -be set to zero. - -Intensity, when included, is always normalized -to a 16 bit, unsigned value by multiplying the value by 65,536/(intensity -dynamic range of the sensor). For example, if the dynamic range of the sensor -is 10 bits, the scaling value would be (65,536/1,024). This normalization is required to -ensure that data from different sensors can be correctly merged. - -For systems based on technology other than pulsed lasers, Intensity values may -represent estimated relative reflectivity, rather than a direct measurement of -pulse return magnitude, and may be derived from multiple sources. - -.. note:: - - Please note that the following four fields (Return Number, Number of Returns, - Scan Direction Flag, and Edge of Flight Line) are bit fields within a single - byte. - -**Return Number** - -The Return Number is the pulse return number for a given output pulse. A given -output laser pulse can have many returns, and they must be marked in sequence -of return. The first return will have a Return Number of one, the second a -Return Number of two, and so on up to five returns. The Return Number must -be between 1 and the Number of Returns, inclusive. - -For systems unable to record multiple returns, the Return Number should be -set to one, unless it is synthetically derived and the Synthetic Return Number -Global Encoding bit is set. - -**Number of Returns (Given Pulse)** - -The Number of Returns is the total number of returns for a given pulse. For -example, a laser data point may be return two (Return Number) within a total -number of up to five returns. - -For systems unable to record multiple returns, the Number of Returns should be -set to one, unless it is synthetically derived and the Synthetic Return Number -Global Encoding bit is set. - -**Scan Direction Flag** - -The Scan Direction Flag denotes the direction in which the scanner mirror was -traveling at the time of the output pulse. A bit value of 1 is a positive scan -direction, and a bit value of 0 is a negative scan direction (where positive -scan direction is a scan moving from the left side of the in-track direction to -the right side and negative the opposite). - -For :ref:`Aggregate Model Systems ` or if the measurement system -does not include a rotational component, the Scan Direction Flag should be set -to zero. - -**Edge of Flight Line Flag** - -The Edge of Flight Line Flag has a value of 1 only when the point is at the -end of a scan. It is the last point on a given scan line before it changes -direction or the mirror facet changes. - -Note that this field has no meaning for :ref:`Aggregate Model Systems ` -or 360 degree Field of View scanners (e.g., terrestrial lidar scanners). In -these cases, the Edge of Flight Line Flag should be set to zero. - -**Classification** - -This field represents the "class" attributes of a point. If a point has never -been classified, this byte must be set to zero. The format for classification -is a bit encoded field with the lower five bits used for the class and the -three high bits used for flags. The bit definitions are listed in Table 8 and -the classification values in Table 9. - - -.. tabularcolumns:: |p{2.0cm}|p{3.0cm}|p{8.5cm}| - -.. table:: Classification Bit Field Encoding (Point Data Record Formats 0-5) - - +-------+-------------------------+------------------------------------------+ - | Bit | Field Name | Description | - +=======+=========================+==========================================+ - | 0:4 | Classification | Standard ASPRS classification from | - | | | 0 to 31 as defined in the classification | - | | | table for legacy point formats (see | - | | | :ref:`Reserved Point Classes | - | | | `). | - +-------+-------------------------+------------------------------------------+ - | 5 | Synthetic | If set, this point was created by a | - | | | technique other than direct observation | - | | | such as digitized from a photogrammetric | - | | | stereo model or by traversing a | - | | | waveform. Point attribute interpretation | - | | | might differ from non-Synthetic points. | - | | | Unused attributes must be set to the | - | | | appropriate default value. | - +-------+-------------------------+------------------------------------------+ - | 6 | Key-Point | If set, this point is considered to be a | - | | | model key-point and therefore generally | - | | | should not be withheld in a thinning | - | | | algorithm. | - +-------+-------------------------+------------------------------------------+ - | 7 | Withheld | If set, this point should not be | - | | | included in processing (synonymous with | - | | | Deleted). | - +-------+-------------------------+------------------------------------------+ - -.. note:: - - Note that bits 5, 6, and 7 are treated as flags and can be set or clear in - any combination. For example, a point with bits 5 and 6 both set to one and - the lower five bits set to 2 would be a *Ground* point that had been - *Synthetically* collected and marked as a model *Key-Point*. - -.. _legacy_pt_class_link: - -**Reserved Point Classes** - -Classification must adhere to the following standard: - -.. tabularcolumns:: |p{6.0cm}|p{8.0cm}| - -.. table:: ASPRS Standard Point Classes (Point Data Record Formats 0-5) - - +-----------------------------------+-----------------------------------------------+ - | Classification Value (Bits 0:4) | Meaning | - +===================================+===============================================+ - | 0 | Created, Never Classified | - +-----------------------------------+-----------------------------------------------+ - | 1 | Unclassified [2]_ | - +-----------------------------------+-----------------------------------------------+ - | 2 | Ground | - +-----------------------------------+-----------------------------------------------+ - | 3 | Low Vegetation | - +-----------------------------------+-----------------------------------------------+ - | 4 | Medium Vegetation | - +-----------------------------------+-----------------------------------------------+ - | 5 | High Vegetation | - +-----------------------------------+-----------------------------------------------+ - | 6 | Building | - +-----------------------------------+-----------------------------------------------+ - | 7 | Low Point (Noise) | - +-----------------------------------+-----------------------------------------------+ - | 8 | Model Key-Point (Mass Point) | - +-----------------------------------+-----------------------------------------------+ - | 9 | Water | - +-----------------------------------+-----------------------------------------------+ - | 10 | *Reserved for ASPRS Definition* | - +-----------------------------------+-----------------------------------------------+ - | 11 | *Reserved for ASPRS Definition* | - +-----------------------------------+-----------------------------------------------+ - | 12 | Overlap Points [3]_ | - +-----------------------------------+-----------------------------------------------+ - | 13-31 | *Reserved for ASPRS Definition* | - +-----------------------------------+-----------------------------------------------+ - -.. note:: - - A note on Bit Fields – The LAS storage format is "Little Endian." This - means that multi-byte data fields are stored in memory from least - significant byte at the low address to most significant byte at the high - address. Bit fields are always interpreted as bit 0 set to 1 equals 1, bit - 1 set to 1 equals 2, bit 2 set to 1 equals 4 and so forth. - - -.. [2] We are using both 0 and 1 as *Unclassified* to maintain compatibility with - current popular classification software such as TerraScan. We extend the idea - of classification value 1 to include cases in which data have been subjected to - a classification algorithm but emerged in an undefined state. For example, data - with class 0 is sent through an algorithm to detect man-made structures – - points that emerge without having been assigned as belonging to structures - could be remapped from class 0 to class 1. - -.. [3] Overlap Points are those points that were immediately culled during the - merging of overlapping flight lines. In general, the *Withheld* bit should be set - since these points are not subsequently classified. - -**Scan Angle Rank** - -The Scan Angle Rank is a signed one-byte integer with a valid range from -90 to -+90. The Scan Angle Rank is the angle (rounded to the nearest integer in the -absolute value sense) at which the laser point was output from the laser system -including the roll of the aircraft. The scan angle is within 1 degree of -accuracy from +90 to -90 degrees. The scan angle is an angle based on 0 degrees -being nadir, and -90 degrees to the left side of the aircraft in the direction -of flight. - -For :ref:`Aggregate Model Systems `, the Scan Angle Rank should -be set to zero unless assigned from a component measurement. - -**User Data** - -This field may be used at the user's discretion. - -**Point Source ID** - -This value indicates the source from which this point originated. A source is -typically defined as a grouping of temporally consistent data, such as a -flight line or sortie number for airborne systems, a route number for mobile -systems, or a setup identifier for static systems. Valid values for this field -are 1 to 65,535 inclusive. Zero is reserved as a convenience to system -implementers. - -For :ref:`Aggregate Model Systems `, the Point Source ID should -be set to one (1) unless assigned from a component measurement. - -.. raw:: latex - - \newpage - -Point Data Record Format 1 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Point Data Record Format 1 is the same as Point Data Record Format 0 with the -addition of GPS Time. - - -.. tabularcolumns:: |p{7.5cm}|p{3.5cm}|p{1.5cm}|p{1.5cm}| - -.. table:: Point Data Record Format 1 - - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | X | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Y | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Z | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Intensity | unsigned short | 2 bytes | no | - +----------------------------------+-------------------------+-----------+----------+ - | Return Number | 3 bits (bits 0-2) | 3 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Number of Returns (Given Pulse) | 3 bits (bits 3-5) | 3 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Direction Flag | 1 bit (bit 6) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Edge of Flight Line | 1 bit (bit 7) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Angle Rank (-90 to +90) -- | signed char | 1 byte | yes | - | Left Side | | | | - +----------------------------------+-------------------------+-----------+----------+ - | User Data | unsigned char | 1 byte | no | - +----------------------------------+-------------------------+-----------+----------+ - | Point Source ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | GPS Time | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | *Minimum PDRF Size* | *28 bytes* | - +------------------------------------------------------------+----------------------+ - -**GPS Time** - -The GPS Time is the double floating point time tag value at which the point was -observed. It is GPS Week Time if the :ref:`Global Encoding ` -low bit is clear and Adjusted Standard GPS Time if the bit is set. - -For :ref:`Aggregate Model Systems `, the GPS Time should be set -to zero unless assigned from a component measurement. - - -.. raw:: latex - - \newpage - -Point Data Record Format 2 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Point Data Record Format 2 is the same as Point Data Record Format 0 with the -addition of three color channels. These fields are used when "colorizing" a -point using ancillary data, typically from a camera. - -.. tabularcolumns:: |p{7.5cm}|p{3.5cm}|p{1.5cm}|p{1.5cm}| - -.. table:: Point Data Record Format 2 - - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | X | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Y | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Z | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Intensity | unsigned short | 2 bytes | no | - +----------------------------------+-------------------------+-----------+----------+ - | Return Number | 3 bits (bits 0-2) | 3 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Number of Returns (Given Pulse) | 3 bits (bits 3-5) | 3 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Direction Flag | 1 bit (bit 6) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Edge of Flight Line | 1 bit (bit 7) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Angle Rank (-90 to +90) -- | signed char | 1 byte | yes | - | Left Side | | | | - +----------------------------------+-------------------------+-----------+----------+ - | User Data | unsigned char | 1 byte | no | - +----------------------------------+-------------------------+-----------+----------+ - | Point Source ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Red | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Green | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Blue | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | *Minimum PDRF Size* | *26 bytes* | - +------------------------------------------------------------+----------------------+ - -**Red, Green, and Blue** - -The Red, Green, and Blue image channel values associated with this point. - -.. note:: - - The Red, Green, and Blue values should always be normalized to 16 bit values. - For example, when encoding an 8 bit per channel pixel, multiply each - channel value by 256 prior to storage in these fields. This normalization - allows color values from different camera bit depths to be accurately - merged. - -.. raw:: latex - - \newpage - -Point Data Record Format 3 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Point Data Record Format 3 is the same as Point Data Record Format 2 with the -addition of GPS Time. - -.. tabularcolumns:: |p{7.5cm}|p{3.5cm}|p{1.5cm}|p{1.5cm}| - -.. table:: Point Data Record Format 3 - - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | X | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Y | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Z | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Intensity | unsigned short | 2 bytes | no | - +----------------------------------+-------------------------+-----------+----------+ - | Return Number | 3 bits (bits 0-2) | 3 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Number of Returns (Given Pulse) | 3 bits (bits 3-5) | 3 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Direction Flag | 1 bit (bit 6) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Edge of Flight Line | 1 bit (bit 7) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Angle Rank (-90 to +90) -- | signed char | 1 byte | yes | - | Left Side | | | | - +----------------------------------+-------------------------+-----------+----------+ - | User Data | unsigned char | 1 byte | no | - +----------------------------------+-------------------------+-----------+----------+ - | Point Source ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | GPS Time | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Red | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Green | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Blue | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | *Minimum PDRF Size* | *34 bytes* | - +------------------------------------------------------------+----------------------+ - -.. raw:: latex - - \newpage - -Point Data Record Format 4 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Point Data Record Format 4 adds Wave Packets to Point Data Record Format 1. - -.. tabularcolumns:: |p{7.5cm}|p{3.5cm}|p{1.5cm}|p{1.5cm}| - -.. table:: Point Data Record Format 4 - - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | X | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Y | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Z | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Intensity | unsigned short | 2 bytes | no | - +----------------------------------+-------------------------+-----------+----------+ - | Return Number | 3 bits (bits 0-2) | 3 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Number of Returns (Given Pulse) | 3 bits (bits 3-5) | 3 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Direction Flag | 1 bit (bit 6) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Edge of Flight Line | 1 bit (bit 7) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Angle Rank (-90 to +90) -- | signed char | 1 byte | yes | - | Left Side | | | | - +----------------------------------+-------------------------+-----------+----------+ - | User Data | unsigned char | 1 byte | no | - +----------------------------------+-------------------------+-----------+----------+ - | Point Source ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | GPS Time | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Wave Packet Descriptor Index | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Byte Offset to Waveform Data | unsigned long long | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Waveform Packet Size in Bytes | unsigned long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Return Point Waveform Location | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Parametric dx | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Parametric dy | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Parametric dz | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | *Minimum PDRF Size* | *57 bytes* | - +------------------------------------------------------------+----------------------+ - -**Wave Packet Descriptor Index** - -This value plus **99** is the Record ID of the :ref:`fwf_descriptor_label` and -indicates the User Defined Record that describes the waveform packet associated -with this Point Record. Up to 255 different User Defined Records which describe -the waveform packet are supported. A value of zero indicates that there is no -waveform data associated with this Point Record. - -**Byte Offset to Waveform Data** - -The waveform packet data are stored in the LAS file in an Extended Variable -Length Record or in an auxiliary *.wdp file. The Byte Offset represents the -location of the start of this Point Record’s waveform packet within the waveform -data variable length record (or external file) relative to the beginning of the -:ref:`fwf_packets_label` header. The absolute location of the beginning of this -waveform packet relative to the beginning of the file is given by: - - **Start of Waveform Data Packet Record** + **Byte Offset to Waveform Data** - - for waveform packets stored within the LAS file and - - **Byte Offset to Waveform Data** - - for data stored in an auxiliary *.wdp file. - -**Waveform Packet Size in Bytes** - -The size, in bytes, of the waveform packet associated with this return. Note -that each waveform can be of a different size (even those with the same -Waveform Packet Descriptor index) due to packet compression. Also note that -waveform packets can be located only via the Byte Offset to Waveform Packet -Data value since there is no requirement that records be stored sequentially. - - -**Return Point Waveform Location** - -The temporal offset in picoseconds (:math:`10^{-12}`) from the arbitrary "anchor -point" to the location within the waveform packet for this Point Record. - - -**Parametric dx, dy, dz** - -These parameters define a parametric line equation for extrapolating points -along the associated waveform. The position along the wave is given by: - -.. math:: - :nowrap: - - \begin {eqnarray} - X &= X_0 + t * dx \\ - Y &= Y_0 + t * dy \\ - Z &= Z_0 + t * dz - \end {eqnarray} - -where :math:`(X, Y, Z)` is the spatial position of a derived point, -:math:`(X_0, Y_0, Z_0)` is the position of the "anchor" point, and :math:`t` is -the time, in picoseconds, relative to the anchor point. - -The anchor point is an arbitrary location at the origin of the associated -waveform -- i.e. :math:`t = 0` at the anchor point -- with coordinates defined -by: - -.. math:: - :nowrap: - - \begin {eqnarray} - X_0 &= X_P + L * dx \\ - Y_0 &= Y_P + L * dy \\ - Z_0 &= Z_P + L * dz - \end {eqnarray} - -where :math:`(X_P, Y_P, Z_P)` is this Point Record's transformed position (as a -double) and :math:`L` is this Point Record's Return Point Waveform Location. - -The units of X, Y and Z are the units of the coordinate systems of the LAS data. -If the coordinate system is geographic, the horizontal units are decimal degrees -and the vertical units are meters. - -.. note:: - - Users seeking further clarity regarding LAS waveform encoding are encouraged - to learn more on the official LAS wiki: https://github.com/ASPRSorg/LAS/wiki - - -.. raw:: latex - - \newpage - -Point Data Record Format 5 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Point Data Record Format 5 adds Wave Packets to Point Data Record Format 3. - -.. tabularcolumns:: |p{7.0cm}|p{3.5cm}|p{1.5cm}|p{1.5cm}| - -.. table:: Point Data Record Format 5 - - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | X | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Y | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Z | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Intensity | unsigned short | 2 bytes | no | - +----------------------------------+-------------------------+-----------+----------+ - | Return Number | 3 bits (bits 0-2) | 3 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Number of Returns (Given Pulse) | 3 bits (bits 3-5) | 3 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Direction Flag | 1 bit (bit 6) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Edge of Flight Line | 1 bit (bit 7) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Angle Rank (-90 to +90) -- | signed char | 1 byte | yes | - | Left Side | | | | - +----------------------------------+-------------------------+-----------+----------+ - | User Data | unsigned char | 1 byte | no | - +----------------------------------+-------------------------+-----------+----------+ - | Point Source ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | GPS Time | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Red | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Green | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Blue | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Wave Packet Descriptor Index | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Byte Offset to Waveform Data | unsigned long long | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Waveform Packet Size in Bytes | unsigned long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Return Point Waveform Location | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Parametric dx | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Parametric dy | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Parametric dz | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | *Minimum PDRF Size* | *63 bytes* | - +------------------------------------------------------------+----------------------+ - -.. raw:: latex - - \newpage - -Point Data Record Format 6 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Point Data Record Format 6 contains the core 30 bytes that are shared by Point -Data Record Formats 6 to 10. The difference to the core 20 bytes of Point Data -Record Formats 0 to 5 is that there are more bits for return numbers in order -to support up to 15 returns, there are more bits for point classifications to -support up to 256 classes, there is a higher precision scan angle (16 bits -instead of 8), and the GPS time is mandatory. - -.. tabularcolumns:: |p{7.5cm}|p{3.5cm}|p{1.5cm}|p{1.5cm}| - -.. table:: Point Data Record Format 6 - - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | X | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Y | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Z | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Intensity | unsigned short | 2 bytes | no | - +----------------------------------+-------------------------+-----------+----------+ - | Return Number | 4 bits (bits 0-3) | 4 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Number of Returns (Given Pulse) | 4 bits (bits 4-7) | 4 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification Flags | 4 bits (bits 0-3) | 4 bits | no | - +----------------------------------+-------------------------+-----------+----------+ - | Scanner Channel | 2 bits (bits 4-5) | 2 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Direction Flag | 1 bit (bit 6) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Edge of Flight Line | 1 bit (bit 7) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | User Data | unsigned char | 1 byte | no | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Angle | short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Point Source ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | GPS Time | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | *Minimum PDRF Size* | *30 bytes* | - +------------------------------------------------------------+----------------------+ - -.. note:: - - The following six fields (Return Number, Number of Returns, Classification - Flags, Scanner Channel, Scan Direction Flag, and Edge of Flight Line) are bit fields, encoded - into two bytes. - -**Return Number** - -The Return Number is the pulse return number for a given output pulse. A given -output laser pulse can have many returns, and they must be marked in sequence -of return. The first return will have a Return Number of one, the second a -Return Number of two, and so on up to fifteen returns. The Return Number must -be between 1 and the Number of Returns, inclusive. - -For systems unable to record multiple returns, the Return Number should be -set to one, unless it is synthetically derived and the Synthetic Return Number -Global Encoding bit is set. - -**Number of Returns (Given Pulse)** - -The Number of Returns is the total number of returns for a given pulse. For -example, a laser data point may be return two (Return Number) within a total -number of up to fifteen returns. - -For systems unable to record multiple returns, the Number of Returns should be -set to one, unless it is synthetically derived and the Synthetic Return Number -Global Encoding bit is set. - -**Classification Flags** - -Classification flags are used to indicate special characteristics associated -with the point. The bit definitions are: - -.. tabularcolumns:: |p{2.0cm}|p{3.0cm}|p{8.5cm}| - -.. table:: Classification Bit Field Encoding (Point Data Record Formats 6-10) - - +-------+-------------------------+------------------------------------------+ - | Bit | Field Name | Description | - +=======+=========================+==========================================+ - | 0 | Synthetic | If set, this point was created by a | - | | | technique other than direct observation | - | | | such as digitized from a photogrammetric | - | | | stereo model or by traversing a | - | | | waveform. Point attribute interpretation | - | | | might differ from non-Synthetic points. | - | | | Unused attributes must be set to the | - | | | appropriate default value. | - +-------+-------------------------+------------------------------------------+ - | 1 | Key-Point | If set, this point is considered to be a | - | | | model key-point and therefore generally | - | | | should not be withheld in a thinning | - | | | algorithm. | - +-------+-------------------------+------------------------------------------+ - | 2 | Withheld | If set, this point should not be | - | | | included in processing (synonymous with | - | | | Deleted). | - +-------+-------------------------+------------------------------------------+ - | 3 | Overlap | If set, this point is within the | - | | | overlap region of two or more swaths or | - | | | takes. Setting this bit is not mandatory | - | | | (unless required by a specification | - | | | other than this document) but | - | | | allows Classification of overlap points | - | | | to be preserved. | - +-------+-------------------------+------------------------------------------+ - -.. note:: - These bits are treated as flags and can be set or cleared in any - combination. For example, a point with bits 0 and 1 both set to one and the - *Classification* field set to 2 would be a *Ground* point that had been - *Synthetically* collected and marked as a model *Key-Point*. - - -**Scanner Channel** - -Scanner Channel is used to indicate the channel (scanner head) of a multi- -channel system. Channel 0 is used for single scanner systems. Up to four -channels are supported (0-3). - -For :ref:`Aggregate Model Systems `, the Channel should be set -to zero unless assigned from a component measurement. - -**Scan Direction Flag** - -The Scan Direction Flag denotes the direction in which the scanner mirror was -traveling at the time of the output pulse. A bit value of 1 is a positive scan -direction, and a bit value of 0 is a negative scan direction (where positive -scan direction is a scan moving from the left side of the in-track direction to -the right side and negative the opposite). - -For :ref:`Aggregate Model Systems ` or if the measurement system -does not include a rotational component, the Scan Direction Flag should be set -to zero. - -**Edge of Flight Line Flag** - -The Edge of Flight Line Flag has a value of 1 only when the point is at the -end of a scan. It is the last point on a given scan line before it changes -direction or the mirror facet changes. - -Note that this field has no meaning for :ref:`Aggregate Model Systems ` -or 360 degree Field of View scanners (e.g., terrestrial lidar scanners). In -these cases, the Edge of Flight Line Flag should be set to zero. - -**Classification** - -Classification must adhere to the following standard: - - -.. tabularcolumns:: |p{3.0cm}|p{5.0cm}|p{7.0cm}| - -.. table:: ASPRS Standard Point Classes (Point Data Record Formats 6-10) - - +------------------+-----------------------------+--------------------------------+ - | Value (Bits 0:4) | Meaning | Notes | - +==================+=============================+================================+ - | 0 | Created, Never Classified | See note [4]_ | - +------------------+-----------------------------+ + - | 1 | Unclassified | | - +------------------+-----------------------------+--------------------------------+ - | 2 | Ground | | - +------------------+-----------------------------+--------------------------------+ - | 3 | Low Vegetation | | - +------------------+-----------------------------+--------------------------------+ - | 4 | Medium Vegetation | | - +------------------+-----------------------------+--------------------------------+ - | 5 | High Vegetation | | - +------------------+-----------------------------+--------------------------------+ - | 6 | Building | | - +------------------+-----------------------------+--------------------------------+ - | 7 | Low Point (Noise) | | - +------------------+-----------------------------+--------------------------------+ - | 8 | *Reserved* | | - +------------------+-----------------------------+--------------------------------+ - | 9 | Water | | - +------------------+-----------------------------+--------------------------------+ - | 10 | Rail | | - +------------------+-----------------------------+--------------------------------+ - | 11 | Road Surface | | - +------------------+-----------------------------+--------------------------------+ - | 12 | *Reserved* | | - +------------------+-----------------------------+--------------------------------+ - | 13 | Wire -- Guard (Shield) | | - +------------------+-----------------------------+--------------------------------+ - | 14 | Wire -- Conductor (Phase) | | - +------------------+-----------------------------+--------------------------------+ - | 15 | Transmission Tower | | - +------------------+-----------------------------+--------------------------------+ - | 16 | Wire-Structure Connector | e.g., insulators | - +------------------+-----------------------------+--------------------------------+ - | 17 | Bridge Deck | | - +------------------+-----------------------------+--------------------------------+ - | 18 | High Noise | | - +------------------+-----------------------------+--------------------------------+ - | 19 | Overhead Structure | e.g., conveyors, mining | - | | | equipment, traffic lights | - +------------------+-----------------------------+--------------------------------+ - | 20 | Ignored Ground | e.g., breakline proximity | - +------------------+-----------------------------+--------------------------------+ - | 21 | Snow | | - +------------------+-----------------------------+--------------------------------+ - | 22 | Temporal Exclusion | Features excluded due to | - | | | changes over time between data | - | | | sources -- e.g., water levels, | - | | | landslides, permafrost | - +------------------+-----------------------------+--------------------------------+ - | 23-63 | *Reserved* | | - +------------------+-----------------------------+--------------------------------+ - | 64-255 | User Definable | | - +------------------+-----------------------------+--------------------------------+ - - -.. [4] We are using both 0 and 1 as Unclassified to maintain compatibility - with current popular classification software such as TerraScan. We extend the - idea of classification value 1 to include cases in which data have been - subjected to a classification algorithm but emerged in an undefined state. For - example, data with class 0 is sent through an algorithm to detect man-made - structures – points that emerge without having been assigned as belonging to - structures could be remapped from class 0 to class 1. - - -**Scan Angle** - -The Scan Angle is a signed short that represents the rotational position of the -emitted laser pulse with respect to the vertical dimension of the coordinate system of -the data. Down in the data coordinate system is the 0.0 position. Each -increment represents 0.006 degrees. Counter-clockwise rotation, as viewed from -the rear of the sensor, facing in the along-track (positive trajectory) -direction, is positive. The maximum value in the positive sense is 30,000 (180 -degrees which is up in the coordinate system of the data). The maximum value in -the negative direction is -30,000 which is also directly up. - -For :ref:`Aggregate Model Systems `, the Scan Angle should be -set to zero unless assigned from a component measurement. - - -.. raw:: latex - - \newpage - -Point Data Record Format 7 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Point Data Record Format 7 is the same as Point Data Record Format 6 with the -addition of three RGB color channels. These fields are used when "colorizing" a -point using ancillary data, typically from a camera. - -.. tabularcolumns:: |p{7.5cm}|p{3.5cm}|p{1.5cm}|p{1.5cm}| - -.. table:: Point Data Record Format 7 - - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | X | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Y | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Z | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Intensity | unsigned short | 2 bytes | no | - +----------------------------------+-------------------------+-----------+----------+ - | Return Number | 4 bits (bits 0-3) | 4 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Number of Returns (Given Pulse) | 4 bits (bits 4-7) | 4 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification Flags | 4 bits (bits 0-3) | 4 bits | no | - +----------------------------------+-------------------------+-----------+----------+ - | Scanner Channel | 2 bits (bits 4-5) | 2 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Direction Flag | 1 bit (bit 6) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Edge of Flight Line | 1 bit (bit 7) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | User Data | unsigned char | 1 byte | no | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Angle | short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Point Source ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | GPS Time | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Red | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Green | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Blue | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | *Minimum PDRF Size* | *36 bytes* | - +------------------------------------------------------------+----------------------+ - -.. raw:: latex - - \newpage - -Point Data Record Format 8 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Point Data Record Format 8 is the same as Point Data Record Format 7 with the -addition of a NIR (near infrared) channel. - -.. tabularcolumns:: |p{7.5cm}|p{3.5cm}|p{1.5cm}|p{1.5cm}| - -.. table:: Point Data Record Format 8 - - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | X | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Y | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Z | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Intensity | unsigned short | 2 bytes | no | - +----------------------------------+-------------------------+-----------+----------+ - | Return Number | 4 bits (bits 0-3) | 4 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Number of Returns (Given Pulse) | 4 bits (bits 4-7) | 4 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification Flags | 4 bits (bits 0-3) | 4 bits | no | - +----------------------------------+-------------------------+-----------+----------+ - | Scanner Channel | 2 bits (bits 4-5) | 2 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Direction Flag | 1 bit (bit 6) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Edge of Flight Line | 1 bit (bit 7) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | User Data | unsigned char | 1 byte | no | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Angle | short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Point Source ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | GPS Time | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Red | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Green | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Blue | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | NIR | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | *Minimum PDRF Size* | *38 bytes* | - +------------------------------------------------------------+----------------------+ - -**NIR** - -The NIR (near infrared) channel value associated with this point. - -.. note:: - - Note that Red, Green, Blue, and NIR values should always be normalized to 16 - bit values. For example, when encoding an 8 bit per channel pixel, multiply - each channel value by 256 prior to storage in these fields. This - normalization allows color values from different camera bit depths to be - accurately merged. - -.. raw:: latex - - \newpage - -Point Data Record Format 9 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Point Data Record Format 9 adds Wave Packets to Point Data Record Format 6. - -.. tabularcolumns:: |p{7.5cm}|p{3.5cm}|p{1.5cm}|p{1.5cm}| - -.. table:: Point Data Record Format 9 - - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | X | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Y | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Z | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Intensity | unsigned short | 2 bytes | no | - +----------------------------------+-------------------------+-----------+----------+ - | Return Number | 4 bits (bits 0-3) | 4 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Number of Returns (Given Pulse) | 4 bits (bits 4-7) | 4 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification Flags | 4 bits (bits 0-3) | 4 bits | no | - +----------------------------------+-------------------------+-----------+----------+ - | Scanner Channel | 2 bits (bits 4-5) | 2 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Direction Flag | 1 bit (bit 6) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Edge of Flight Line | 1 bit (bit 7) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | User Data | unsigned char | 1 byte | no | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Angle | short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Point Source ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | GPS Time | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Wave Packet Descriptor Index | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Byte Offset to Waveform Data | unsigned long long | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Waveform Packet Size in Bytes | unsigned long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Return Point Waveform Location | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Parametric dx | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Parametric dy | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Parametric dz | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | *Minimum PDRF Size* | *59 bytes* | - +------------------------------------------------------------+----------------------+ - -.. raw:: latex - - \newpage - -Point Data Record Format 10 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Point Data Record Format 10 is the same as Point Data Record Format 9 with RGB and NIR values. - -.. tabularcolumns:: |p{7.5cm}|p{3.5cm}|p{1.5cm}|p{1.5cm}| - -.. table:: Point Data Record Format 10 - - +----------------------------------+-------------------------+-----------+----------+ - | Item | Format | Size | Required | - +==================================+=========================+===========+==========+ - | X | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Y | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Z | long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Intensity | unsigned short | 2 bytes | no | - +----------------------------------+-------------------------+-----------+----------+ - | Return Number | 4 bits (bits 0-3) | 4 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Number of Returns (Given Pulse) | 4 bits (bits 4-7) | 4 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification Flags | 4 bits (bits 0-3) | 4 bits | no | - +----------------------------------+-------------------------+-----------+----------+ - | Scanner Channel | 2 bits (bits 4-5) | 2 bits | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Direction Flag | 1 bit (bit 6) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Edge of Flight Line | 1 bit (bit 7) | 1 bit | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Classification | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | User Data | unsigned char | 1 byte | no | - +----------------------------------+-------------------------+-----------+----------+ - | Scan Angle | short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Point Source ID | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | GPS Time | double | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Red | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Green | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Blue | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | NIR | unsigned short | 2 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Wave Packet Descriptor Index | unsigned char | 1 byte | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Byte Offset to Waveform Data | unsigned long long | 8 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Waveform Packet Size in Bytes | unsigned long | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Return Point Waveform Location | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Parametric dx | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Parametric dy | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | Parametric dz | float | 4 bytes | yes | - +----------------------------------+-------------------------+-----------+----------+ - | *Minimum PDRF Size* | *67 bytes* | - +------------------------------------------------------------+----------------------+ - -.. raw:: latex - - \newpage - diff --git a/source/03_crs.txt b/source/03_crs.txt new file mode 100644 index 0000000..47a870c --- /dev/null +++ b/source/03_crs.txt @@ -0,0 +1,85 @@ +.. raw:: latex + + \newpage + +.. _crs_label: + +Coordinate Reference System +-------------------------------------------------------------------------------- + +Coordinate Reference System (CRS) information is required for a LAS 1.5 file +and must be placed in :ref:`vlrdef_label` or :ref:`evlrdef_label`. +LAS 1.5 CRS information shall be represented as `OGC Well +Known Text `__ (WKT), as indicated by +the :ref:`Global Encoding ` bit. + +GeoTIFF CRS representations from prior versions of LAS are not supported in LAS 1.5. + +It is considered a file error to have more than one WKT VLR or EVLR in the file. +A writer can efficiently revise a CRS definition without rewriting the entire LAS file by +"superseding" the existing CRS VLR or EVLR and appending a new CRS definition in an EVLR. +Superseding is performed by changing the +Record ID of the VLR or EVLR to match the :ref:`superseded_vlr_label` VLR definition. + +.. _crs_wkt: + +OGC Coordinate System WKT Record (Required) +................................................................................ + +The WKT record is **required** and can be specified as either a VLR or an +EVLR. If an EVLR is to override an already existing CRS VLR, writers +should also write a :ref:`Superseded VLR ` to label it. + ++-----------------+-----------------------------+ +| User ID | LASF_Projection | ++-----------------+-----------------------------+ +| Record ID | 2112 | ++-----------------+-----------------------------+ + +This record must contain the textual data representing a WKT as defined by any +published OGC Well Known Text standard with the following considerations: + +* The OGC Coordinate System WKT VLR data shall be a null-terminated string. +* The OGC Coordinate System WKT VLR data shall be considered UTF-8. +* The OGC Coordinate System WKT VLR data shall be considered C locale-based with + no localization of the numeric strings within the WKT being performed. + + +.. note:: + + Any published version of an OGC WKT standard is a valid definition for LAS 1.5. + OGC has published multiple versions of WKT, including the following noteworthy versions: + + * `18-010r11 `__ - Commonly called "WKT2" + or "WKTv2" and is the most current version of WKT as of this publication. + * `18-010r7 `__ - This variant of "WKT2" + added support for the definition of ``EPOCH`` for defining the date against which + coordinates in the LAS file are referenced in a dynamic coordinate reference system. + * `12-063r5 `__ - + Commonly called "WKT1" and the formally ratified variant of WKT that was used + for LAS 1.4. + + If OGC were to publish a new WKT standard, it would also be a + valid definition for LAS 1.5. + +.. _math_wkt: + +OGC Math Transform WKT Record (Optional) +................................................................................ + +Writers may include an optional OGC Math Transform WKT Record to provide a +supplemental parameterized math transform definition. + ++-----------------+-----------------------------+ +| User ID | LASF_Projection | ++-----------------+-----------------------------+ +| Record ID | 2111 | ++-----------------+-----------------------------+ + +This record must contain a Math Transform WKT Record consistent with the same WKT +specification being used by the :ref:`Coordinate System WKT Record `, with the following considerations: + +* The OGC Math Transform WKT VLR data shall be a null-terminated string. +* The OGC Math Transform WKT VLR data shall be considered UTF-8. +* The OGC Math Transform WKT VLR data shall be considered C locale-based, and + no localization of the numeric strings within the WKT should be performed. diff --git a/source/03_required_vlrs.txt b/source/03_required_vlrs.txt deleted file mode 100644 index c1241e4..0000000 --- a/source/03_required_vlrs.txt +++ /dev/null @@ -1,190 +0,0 @@ -.. raw:: latex - - \newpage - -Coordinate Reference System VLRs (Required) --------------------------------------------------------------------------------- -LAS 1.4 defines Variable Length Records (VLRs) and Extended Variable Length -Records (EVLRs). Coordinate Reference System (CRS) VLRs are defined in this -section, while other VLRs and EVLRs are defined in the following two sections. - -Coordinate Reference System Information -................................................................................ - -The Coordinate Reference System (CRS) information for the point data is -required for all data. The CRS information will be placed in Variable Length -Records or Extended Variable Length Records (note that if the writer wishes to -maintain legacy compatibility, then GeoTIFF in VLRs must be used). The CRS is -represented by either GeoTIFF or Well Known Text (WKT) as indicated by the WKT -:ref:`Global Encoding ` bit. Point Record Formats 0-5 can -use either GeoTIFF or WKT, but not both simultaneously. Point Data Record -Formats 6-10 must use WKT. - -Georeferencing Information Using WKT -................................................................................ - -For definition of WKT, we refer to Open Geospatial Consortium (OGC) -specification "OpenGIS coordinate transformation service implementation -specification" revision 1.00 released 12 January 2001, section 7 (`"Coordinate -Transformation Service Spec" `_). -As there are a few dialects of WKT, please note that LAS is not using the "ESRI -WKT" dialect, which does not include TOWGS84 and Authority nodes. - -WKT georeferencing information can be specified in two optional variable length -records, the OGC math transform WKT record and the OGC coordinate system WKT -record, as follows. Note that the math transform WKT record is added for -completeness, and a coordinate system WKT *may* or *may not* require a math -transform WKT record (a parameterized math transform definition). - -OGC Math Transform WKT Record -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+-----------------+-----------------------------+ -| User ID | LASF_Projection | -+-----------------+-----------------------------+ -| Record ID | 2111 | -+-----------------+-----------------------------+ - -This record contains the textual data representing a Math Transform WKT as -defined in section 7 of the Coordinate Transformation Service Spec, with the -following notes: - -* The OGC Math Transform WKT VLR data shall be a null-terminated string. -* The OGC Math Transform WKT VLR data shall be considered UTF-8. -* The OGC Math Transform WKT VLR data shall be considered C locale-based, and - no localization of the numeric strings within the WKT should be performed. - -OGC Coordinate System WKT Record -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+-----------------+-----------------------------+ -| User ID | LASF_Projection | -+-----------------+-----------------------------+ -| Record ID | 2112 | -+-----------------+-----------------------------+ - -This record contains the textual data representing a Coordinate System WKT as -defined in section 7 of the Coordinate Transformation Service Spec, with the -following notes: - -* The OGC Coordinate System WKT VLR data shall be a null-terminated string. -* The OGC Coordinate System WKT VLR data shall be considered UTF-8. -* The OGC Coordinate System WKT VLR data shall be considered C locale-based, and - no localization of the numeric strings within the WKT should be performed. - -Georeferencing Information Using GeoTIFF -................................................................................ - -The GeoTIFF specification is defined by http://geotiff.osgeo.org/. - -GeoTIFF georeferencing for the LAS formats uses the same mechanism that was -developed for the GeoTIFF standard. The variable length header records section -may contain the same data that would be contained in the GeoTIFF key tags of a -TIFF file. Since LAS is not a raster format and each point contains its own -absolute location information, only 3 of the 6 GeoTIFF tags are necessary when -using GeoTIFF records instead of WKT records. The ModelTiePointTag (33922), -ModelPixelScaleTag (33550), and ModelTransformationTag (34264) records can be -excluded. The GeoKeyDirectoryTag (34735), GeoDoubleParamsTag (34736), and -GeoAsciiParamsTag (34737) records are used. - -Only the GeoKeyDirectoryTag record is required when using GeoTIFF records -instead of WKT records. The GeoDoubleParamsTag and GeoAsciiParamsTag records -may or may not be present, depending on the content of the GeoKeyDirectoryTag -record. - -GeoKeyDirectoryTag Record -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+-----------------+-----------------------------+ -| User ID | LASF_Projection | -+-----------------+-----------------------------+ -| Record ID | 34735 | -+-----------------+-----------------------------+ - -This record contains the key values that define the coordinate system. A -complete description can be found in the GeoTIFF format specification. Here is -a summary from a programmatic point of view for someone interested in -implementation. - -The GeoKeyDirectoryTag is defined as an array of unsigned short values. -Programmatically, the data can be structured as follows: - -:: - - struct sGeoKeys { - unsigned short wKeyDirectoryVersion; - unsigned short wKeyRevision; - unsigned short wMinorRevision; - unsigned short wNumberOfKeys; - - struct sKeyEntry { - unsigned short wKeyID; - unsigned short wTIFFTagLocation; - unsigned short wCount; - unsigned short wValue_Offset; - } pKey[1]; - }; - -...where... - -:: - - wKeyDirectoryVersion = 1; // Always - wKeyRevision = 1; // Always - wMinorRevision = 0; // Always - wNumberOfKeys // Number of sets of 4 unsigned shorts to follow - -.. tabularcolumns:: |p{4.5cm}|p{12.0cm}| - -.. table:: GeoKey Four Unsigned Shorts - - +---------------------------------+----------------------------------------------------------+ - | Name | Definition | - +=================================+==========================================================+ - | ``wKeyID`` | Defined key ID for each piece of GeoTIFF data. IDs | - | | contained in the GeoTIFF specification. | - +---------------------------------+----------------------------------------------------------+ - | ``wTIFFTagLocation`` | Indicates where the data for this key is located: | - | | | - | | * 0 means data is in the ``wValue_Offset`` field as an | - | | unsigned short. | - | | * 34736 means the data is located at index | - | | ``wValue_Offset`` of the GeoDoubleParamsTag record. | - | | * 34737 means the data is located at index | - | | ``wValue_Offset`` of the GeoAsciiParamsTag record. | - +---------------------------------+----------------------------------------------------------+ - | ``wCount`` | Number of characters in string for values of | - | | GeoAsciiParamsTag, otherwise is 1. | - +---------------------------------+----------------------------------------------------------+ - | ``wValue_Offset`` | Contents vary depending on value for wTIFFTagLocation | - | | above. | - +---------------------------------+----------------------------------------------------------+ - - - -GeoDoubleParamsTag Record (Optional) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+-----------------+-----------------------------+ -| User ID | LASF_Projection | -+-----------------+-----------------------------+ -| Record ID | 34736 | -+-----------------+-----------------------------+ - -This record is simply an array of doubles that contain values referenced by tag -sets in the GeoKeyDirectoryTag record. - -GeoAsciiParamsTag Record (Optional) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+-----------------+-----------------------------+ -| User ID | LASF_Projection | -+-----------------+-----------------------------+ -| Record ID | 34737 | -+-----------------+-----------------------------+ - -This record is simply an array of ASCII data. It contains many strings separated -by null terminator characters, which are referenced by position from data in the -GeoKeyDirectoryTag record. - - diff --git a/source/04_optional_vlrs.txt b/source/04_optional_vlrs.txt index 0a23a1f..e5e261a 100644 --- a/source/04_optional_vlrs.txt +++ b/source/04_optional_vlrs.txt @@ -2,10 +2,17 @@ \newpage -Other Specification Defined VLRs (Optional) +.. _optional_vlrs: + +Optional VLR Definitions -------------------------------------------------------------------------------- -Classification Lookup +Definitions for official :ref:`vlrdef_label` and :ref:`evlrdef_label` +are provided in this section as a means to extend the LAS file format. +Additional VLR and EVLR definitions contributed by the LAS Working Group and the +LAS community can be found on the :ref:`Official LAS Wiki `. + +Classification Lookup (Deprecated) ................................................................................ +----------------------------+-----------------------------------+ @@ -19,10 +26,15 @@ Classification Lookup :: struct CLASSIFICATION { - unsigned char ClassNumber; + uint8_t ClassNumber; char Description[15]; }; //total of 16 bytes +The legacy Classification Lookup VLR (Record ID 0) has been a feature of the LAS specification +since LAS 1.0. This VLR is deprecated in LAS 1.5 due to the limitation of +15 characters being insufficient for a detailed description. An updated +version of the VLR may be found on the :ref:`Official LAS Wiki `. + Text Area Description ................................................................................ @@ -33,7 +45,7 @@ Text Area Description | Record ID | 3 | +-----------------+-----------------------------+ -This VLR/EVLR is used for providing a textual description of the content of the +This VLR is used for providing a textual description of the content of the LAS file. It is a null-terminated, free-form ASCII string. .. _extrabytes_vlr_label: @@ -50,15 +62,16 @@ Extra Bytes +----------------------------+-----------------------------+ The Extra Bytes VLR provides a mechanism whereby additional information can be -added to the end of a standard Point Record. This VLR has been added to LAS 1.4 -to formalize a process that has been used in prior versions of LAS. It is +added to the end of a standard Point Record. This VLR was added to LAS 1.4 +to formalize a process that had been used in prior versions of LAS, and is +a core feature of the LAS 1.5 specification. It is envisioned that software that is not cognizant of the meaning of the extra bytes will simply copy these bytes when manipulating files. This VLR is only required for LAS files where points contain user-defined -"extra bytes". This happens when the point record size is set to a larger value +"extra bytes". This happens when the point record length is set to a larger value than required by the point type. For example, if a LAS file that contains -point type 1 has a point record size of 32 instead of 28, there are 4 "extra +point type 6 has a point record length of 34 instead of 30, there are 4 "extra bytes". The Extra Bytes VLR contains a simple description of the type and the meaning of these "extra bytes" so they can be accessed in a consistent manner across applications. The extra bytes descriptor is defined as follows: @@ -66,22 +79,22 @@ across applications. The extra bytes descriptor is defined as follows: :: struct EXTRA_BYTES { - unsigned char reserved[2]; // 2 bytes - unsigned char data_type; // 1 byte - unsigned char options; // 1 byte - char name[32]; // 32 bytes - unsigned char unused[4]; // 4 bytes - anytype no_data; // 8 bytes - unsigned char deprecated1[16]; // 16 bytes - anytype min; // 8 bytes - unsigned char deprecated2[16]; // 16 bytes - anytype max; // 8 bytes - unsigned char deprecated3[16]; // 16 bytes - double scale; // 8 bytes - unsigned char deprecated4[16]; // 16 bytes - double offset; // 8 bytes - unsigned char deprecated5[16]; // 16 bytes - char description[32]; // 32 bytes + uint8_t reserved[2]; // 2 bytes + uint8_t data_type; // 1 byte + uint8_t options; // 1 byte + char name[32]; // 32 bytes + uint8_t unused[4]; // 4 bytes + anytype no_data; // 8 bytes + uint8_t deprecated1[16]; // 16 bytes + anytype min; // 8 bytes + uint8_t deprecated2[16]; // 16 bytes + anytype max; // 8 bytes + uint8_t deprecated3[16]; // 16 bytes + double scale; // 8 bytes + uint8_t deprecated4[16]; // 16 bytes + double offset; // 8 bytes + uint8_t deprecated5[16]; // 16 bytes + char description[32]; // 32 bytes }; // total of 192 bytes The 4 "extra bytes" could, for example, be of data_type 9 - a 4-byte floating @@ -93,10 +106,10 @@ each point record: #) "laser pulse direction [0]" - data_type = 9 (float) #) "laser pulse direction [1]" - data_type = 9 (float) #) "laser pulse direction [2]" - data_type = 9 (float) -#) "pulse width" - data_type = 3 (ushort) +#) "pulse width" - data_type = 3 (uint16_t) In this example, an array of three individual floats collectively specify a -"laser pulse direction" for that point, and one unsigned short integer specifies +"laser pulse direction" for that point, and one uint16_t integer specifies a "pulse width" for that point. The "extra bytes" are made accessible via a unique name. The "name" field @@ -106,14 +119,22 @@ by another software. Descriptive names such as "normalized reflectivity", "echo width", or "shading normal" are encouraged. The use of generic names such as "variable1" or "temp1" is discouraged. +Only one Extra Bytes VLR may exist in a given LAS file. If an Extra Bytes VLR +already exists in a LAS file, then new Extra Byte definitions must be added to +the existing Extra Bytes VLR. + Multiple sequential "extra byte" records can compose an array of associated values. It is recommended that each member's name be consistent with other members, only varying by an index number wrapped in square brackets, as in -the above example. Zero-indexed arrays are encouraged. Previous revisions -of the LAS 1.4 specification utilized data_types 11-30 to define standard -two- and three-member arrays, but this feature was never widely implemented -and was `deprecated in R14 `_ to -simplify implementation. +the above example. Zero-indexed arrays are encouraged. + +.. note:: + + Previous versions of the LAS specification utilized data_type values 11-30 to define + two- and three-member arrays, but this feature was never widely implemented + and was `deprecated in LAS 1.4 R14 `_ to + simplify implementation. + Any unused characters in the "name" or "description" fields must be set to zero. @@ -127,21 +148,21 @@ Any unused characters in the "name" or "description" fields must be set to zero. | 0 | undocumented extra bytes | specify value in | | | | ``options`` field | +------------+-------------------------------+-------------------+ - | 1 | unsigned char | 1 byte | + | 1 | uint8_t | 1 byte | +------------+-------------------------------+-------------------+ - | 2 | char | 1 byte | + | 2 | int8_t | 1 byte | +------------+-------------------------------+-------------------+ - | 3 | unsigned short | 2 bytes | + | 3 | uint16_t | 2 bytes | +------------+-------------------------------+-------------------+ - | 4 | short | 2 bytes | + | 4 | int16_t | 2 bytes | +------------+-------------------------------+-------------------+ - | 5 | unsigned long | 4 bytes | + | 5 | uint32_t | 4 bytes | +------------+-------------------------------+-------------------+ - | 6 | long | 4 bytes | + | 6 | int32_t | 4 bytes | +------------+-------------------------------+-------------------+ - | 7 | unsigned long long | 8 bytes | + | 7 | uint64_t | 8 bytes | +------------+-------------------------------+-------------------+ - | 8 | long long | 8 bytes | + | 8 | int64_t | 8 bytes | +------------+-------------------------------+-------------------+ | 9 | float | 4 bytes | +------------+-------------------------------+-------------------+ @@ -186,9 +207,9 @@ values in the corresponding fields are to be disregarded. Any unused If the selected data_type is less than 8 bytes, the no_data, min, and max fields should be upcast into 8-byte storage. For any float these 8 bytes would be -upcast to a double, for any unsigned char, unsigned short, or unsigned long -they would be upcast to an unsigned long long and for any char, short, or long, -they would be upcast to a long long. +upcast to a double, for any uint8_t, uint16_t, or uint32_t +they would be upcast to a uint64_t and for any int8_t, int16_t, or int32_t, +they would be upcast to a int64_t. If used, the min and max fields reflect the actual minimum and maximum values of the attribute in the LAS file, in its raw form, without any scale @@ -220,8 +241,8 @@ Superseded | Record ID | 7 | +-----------------+-----------------------------+ -This LASF Record ID is used to negate an existing VLR/EVLR when rewriting the -file (to remove the undesired VLR/EVLR). It is used, for example, when +This LASF Record ID is used to negate an existing VLR or EVLR when rewriting the +file (to remove the undesired VLR or EVLR). It is used, for example, when updating a record such as projection information where a new EVLR is appended to the end of the LAS file. The existing VLR which has been superseded must be marked with the SUPERSEDED Record ID. @@ -253,13 +274,13 @@ dataset, the LAS file supports up to 255 Waveform Packet Descriptors. +------------------------------+-------------------------+-----------+--------------+ | Item | Format | Size | Required | +==============================+=========================+===========+==============+ - | Bits per Sample | unsigned char | 1 byte | yes | + | Bits per Sample | uint8_t | 1 byte | yes | +------------------------------+-------------------------+-----------+--------------+ - | Waveform Compression Type | unsigned char | 1 byte | yes | + | Waveform Compression Type | uint8_t | 1 byte | yes | +------------------------------+-------------------------+-----------+--------------+ - | Number of Samples | unsigned long | 4 bytes | yes | + | Number of Samples | uint32_t | 4 bytes | yes | +------------------------------+-------------------------+-----------+--------------+ - | Temporal Sample Spacing | unsigned long | 4 bytes | yes | + | Temporal Sample Spacing | uint32_t | 4 bytes | yes | +------------------------------+-------------------------+-----------+--------------+ | Digitizer Gain | double | 8 bytes | yes | +------------------------------+-------------------------+-----------+--------------+ @@ -300,6 +321,6 @@ absolute digitizer voltage using the formula: .. note:: Users seeking further clarity regarding LAS waveform encoding are encouraged - to learn more on the official LAS wiki: https://github.com/ASPRSorg/LAS/wiki + to learn more on the :ref:`Official LAS Wiki `. diff --git a/source/05_defined_evlrs.txt b/source/05_defined_evlrs.txt index cb964c2..901f9dc 100644 --- a/source/05_defined_evlrs.txt +++ b/source/05_defined_evlrs.txt @@ -13,7 +13,7 @@ Waveform Data Packets .. warning:: This EVLR is REQUIRED internally or externally when using Point Data Record - Formats 4, 5, 9, or 10. + Formats 9 or 10. +-----------------+-----------------------------+ | User ID | LASF_Spec | diff --git a/source/06_profiles.txt b/source/06_profiles.txt index 0d06159..4dca982 100644 --- a/source/06_profiles.txt +++ b/source/06_profiles.txt @@ -2,6 +2,8 @@ \newpage +.. _domainprofile_label: + LAS Domain Profiles -------------------------------------------------------------------------------- diff --git a/source/_static/ASPRS_Logo_Blue.png b/source/_static/ASPRS_Logo_Blue.png new file mode 100644 index 0000000..d392414 Binary files /dev/null and b/source/_static/ASPRS_Logo_Blue.png differ diff --git a/source/_static/asprslogo45.png b/source/_static/asprslogo45.png deleted file mode 100644 index 79fff8d..0000000 Binary files a/source/_static/asprslogo45.png and /dev/null differ diff --git a/source/conf.py b/source/conf.py index 5426292..45d6937 100644 --- a/source/conf.py +++ b/source/conf.py @@ -30,8 +30,17 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. + +HAVE_SPELLING = True +try: + import sphinxcontrib.spelling +except ImportError: + HAVE_SPELLING=False extensions = ['sphinx.ext.mathjax'] +if HAVE_SPELLING: + extensions.append('sphinxcontrib.spelling') + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -42,11 +51,11 @@ source_suffix = '.txt' # The master toctree document. -master_doc = '00_index' +master_doc = 'index' # General information about the project. project = u'LAS' -copyright = u'2019, ASPRS' +copyright = u'2025, ASPRS' author = u'ASPRS' # The version info for the project you're documenting, acts as replacement for @@ -56,21 +65,25 @@ # The short X.Y version. #version = u'1.4' # Custom non-keyword version tag for header -myversion = u'1.4 - R15' +myversion = u'1.5 - R00' # The full version, including alpha/beta/rc tags. release = u'VERSION ' + myversion releasename = release version='' # Publication info (approval date, release date, and GitHub SHA) -today='09 July 2019' -releasedate='09 July 2019' -approvaldate = 'November 2011' +releasedate='27 August 2025' +approvaldate = 'August 2025' import subprocess def get_git_revision_short_hash(): - return subprocess.check_output(['git', 'rev-parse', 'HEAD']) + import os + if 'GITHUB_SHA' in os.environ: + return os.environ['GITHUB_SHA'] + elif 'READTHEDOCS_GIT_COMMIT_HASH' in os.environ: + return os.environ['READTHEDOCS_GIT_COMMIT_HASH'] + return '' gitsha = get_git_revision_short_hash() # The language for content autogenerated by Sphinx. Refer to documentation @@ -78,12 +91,12 @@ def get_git_revision_short_hash(): # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] +exclude_patterns = ['spelling_wordlist.txt'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -103,6 +116,11 @@ def get_git_revision_short_hash(): # further. For a list of options available for each theme, see the # documentation. # +# HTML theme options in Alabaster here: +# https://alabaster.readthedocs.io/en/latest/customization.html +# Alabaster default CSS is here: +# https://github.com/sphinx-doc/alabaster/blob/master/alabaster/static/alabaster.css_t + # html_theme_options = {} # Add any paths that contain custom static files (such as style sheets) here, @@ -130,6 +148,8 @@ def get_git_revision_short_hash(): \usepackage{titling} \usepackage{fancyhdr} +\usepackage{times} +\usepackage{courier} \makeatletter \fancypagestyle{normal}{ \fancyhf{} @@ -143,9 +163,11 @@ def get_git_revision_short_hash(): } % Override Sphinx defaults for table heading (bold instead of sans serif) -% note: won't work in newer versions of Sphinx 1.7+ -\protected\def\sphinxstylethead{\textbf} +% https://stackoverflow.com/a/42988749/1666676 +% https://github.com/sphinx-doc/sphinx/blob/a6d7ae16739bf92a032a7c4df0297db7cf120ec9/sphinx/texinputs/sphinxlatexstyletext.sty#L46 +\protected\def\sphinxstyletheadfamily{\bfseries} +% leave this here... https://tex.stackexchange.com/a/8353/143333 \makeatother % Override Sphinx defaults for list item spacing and bolding. More info: @@ -202,10 +224,9 @@ def get_git_revision_short_hash(): \noindent Published by:\\ } The American Society for Photogrammetry \& Remote Sensing\\ -425 Barlow Place, Suite 210\\ -Bethesda, Maryland 20814-2160\\ -Voice: 301-493-0290\\ -Fax: 225-408-4422\\ +8550 United Plaza Blvd. Suite 1001\\ +Baton Rouge, LA 70809\\ +Voice: 225-408-4747\\ Web: \underline{www.asprs.org}\\ @@ -241,7 +262,7 @@ def get_git_revision_short_hash(): # The font size ('10pt', '11pt' or '12pt'). # - 'pointsize': '12pt', + 'pointsize': '11pt', # Other document class options - ensure uniform header/footer 'classoptions': ',oneside,openany', @@ -257,12 +278,26 @@ def get_git_revision_short_hash(): 'maketitle': title, # Don't use atendofbody. Use fancyhdr calls in preamble instead (above). -# 'atendofbody': """American Society for Photogrammetry \& Remote Sensing \\ LAS SPECIFICATION \\""" + releasename + # 'atendofbody': """American Society for Photogrammetry \& Remote Sensing \\ LAS SPECIFICATION \\""" + releasename + + # Customize sphinx setup parameters + # https://www.sphinx-doc.org/en/master/latex.html#latexsphinxsetup + # 'sphinxsetup': "TableRowColorOdd={rgb}{0,0,255},TableRowColorEven={rgb}{0,255,0}", + # 'sphinxsetup': "TableRowColorHeader={rgb}{235,235,235}", } +# Customize latex table styles: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_table_style +# Defaults are latex_table_style = ['booktabs', 'colorrows'] +# You can override for specific tables using rst-class directive +# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rstclass + +# Override default table styles back to plain tables because of aliasing issues with booktabs +# latex_table_style = ['booktabs', 'colorrows'] +latex_table_style = ['standard'] + latex_toplevel_sectioning='section' latex_show_urls='footnote' -latex_logo = './_static/asprslogo45.png' +latex_logo = './_static/ASPRS_Logo_Blue.png' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, diff --git a/source/environment.yml b/source/environment.yml new file mode 100644 index 0000000..9d1f5a0 --- /dev/null +++ b/source/environment.yml @@ -0,0 +1,10 @@ +name: asprsorg +channels: + - conda-forge +dependencies: + - pip + - pip: + - pybtex + - sphinxcontrib-bibtex + - sphinxcontrib-spelling + diff --git a/source/00_index.txt b/source/index.txt similarity index 91% rename from source/00_index.txt rename to source/index.txt index ffcfc7e..50815e8 100644 --- a/source/00_index.txt +++ b/source/index.txt @@ -9,7 +9,7 @@ Welcome to LAS's documentation! 01_intro 02.00_definition - 03_required_vlrs + 03_crs 04_optional_vlrs 05_defined_evlrs 06_profiles diff --git a/source/spelling_wordlist.txt b/source/spelling_wordlist.txt new file mode 100644 index 0000000..d98547c --- /dev/null +++ b/source/spelling_wordlist.txt @@ -0,0 +1,41 @@ +LAS +LiDAR +lidar +upcast +structs +georeferencing +Georeferencing +ushort +dataset +Digitizer +digitizer +picoseconds +wTIFFTagLocation +Programmatically +dx +dy +dz +photogrammetric +Endian +endian +Reprojection +rescaling +unscaled +wdp +breakline +WKT +wkt +untransformed +differencing +conformant +Photogrammetry +bathymetric +powerline +LMS +implementers +reflectivity +photogrammetrically +Geospatial +TerraScan +OpenGIS +uint diff --git a/wiki/LAS_FWF_illustration_constant.png b/wiki/LAS_FWF_illustration_constant.png deleted file mode 100644 index 951cf1c..0000000 Binary files a/wiki/LAS_FWF_illustration_constant.png and /dev/null differ diff --git a/wiki/LAS_FWF_illustration_refracted.png b/wiki/LAS_FWF_illustration_refracted.png deleted file mode 100644 index 65757de..0000000 Binary files a/wiki/LAS_FWF_illustration_refracted.png and /dev/null differ