Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- LAS files are read (`PclFileKind.Las`): versions 1.0 to 1.4 with point formats 0 to 10, the legacy and the extended
1.4 point counts, scale and offset, and the coordinate system records when present. GPS time, return numbers, scan
angles, point source ids, near infrared and waveform packet descriptors are not interpreted.
- PCD files are read (`PclFileKind.Pcd`): ASCII, binary and binary compressed (LZF, decoded by a decoder of its own)
point data with the declared fields, organised and unorganised clouds, and the viewpoint as metadata. Points with
non-finite coordinates are not returned.
- Leica scans read a block range with opt-in parallel decoding: the new `PclReadOptions.Blocks` selects the blocks of the
scan in file order (per scan) and the new `PclReadOptions.MaxDegreeOfParallelism` (default 1, sequential streaming)
decodes the selected blocks in parallel, keeping file order, consecutive `Index` values and `MaxPoints`/`SubsampleStep`
Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ The library targets .NET 8 and .NET 10. It is managed code with no dependencies
| PinPoint project | `.srf`, `.smf`, or a folder with `ScanProject.json` or `.smf`/`.srf` files | Experimental. The manifest (scan names, ids, poses, counts) is read. Points come from the referenced `.bin` files, in either of two layouts: a table of named channels, or numbered sections with a property table and Snappy-compressed channels, which PclIO decodes itself. Colour, intensity and normals are reported only when the file has that channel; in the second layout positions, colours, intensities, normals (`Normals`, three float32 components per point) and the per-point flags (`FilterBits`, one byte per point) are read, while the grid indices stored beside them are not interpreted, so by default every stored point that passes the plausibility rule below is returned. With `PclReadOptions.ExcludeFilteredPoints` the points with a non-zero flag are not returned. A manifest with a scan position list takes the point count from the manifest, else from the data file; a manifest with a data object list takes it from the data file the object refers to, and every location that shares one file reports its full count, because the shares are not recorded. |
| EdgeWise | `.c3db`, `.c3ptx` | Experimental. A `.c3db` point database lists the scan clusters and a `.c3ptx` is one cluster file; the cluster files give positions only, as three 16-bit offsets from the cluster centre per point. The scale of the offsets is not stored in the files, so the reader assumes 32768 units = 0.128 m unless the caller states it with `PclReadOptions.EdgeWiseCoordinateScale`. |
| LAS | `.las` | Points decoded from versions 1.0 to 1.4 with point formats 0 to 10: XYZ with scale and offset, intensity, classification and RGB for the colour formats (2, 3, 5, 7, 8, 10). GPS time, return numbers, scan angles, point source ids, near infrared and waveform packet descriptors are not interpreted; extra bytes past a format's base size are skipped. The extended point counts of 1.4 are used when stated. Coordinate system records name an `EPSG:` code from a GeoTIFF key directory when it holds one, else the OGC WKT when one is stored. |
| PCD | `.pcd` | Points decoded from the 0.7 header in ASCII, binary and binary compressed (LZF) form: XYZ from x, y and z, colour from packed rgb or rgba, intensity, and normals from normal_x, normal_y and normal_z. Points with non-finite coordinates are not returned. The viewpoint is kept as metadata and not applied. |

### Format detection

Expand All @@ -52,7 +53,7 @@ regard to case.

- E57, ReCap scan and Leica files are recognised by their content and accepted with any extension; for Leica, `.lgs` selects the
older container and any other extension `.lgsx`. EdgeWise files are also recognised by content when the extension is none of its own.
A LAS file is recognised by the `LASF` signature with any extension except `.laz`, which shares the signature and stays unknown.
A LAS file is recognised by the `LASF` signature with any extension except `.laz`, which shares the signature and stays unknown. A PCD file is recognised by its header structure with any extension.
- A FARO file must be an OLE2 compound file with the extension `.fls`. A ReCap project must be a ZIP archive with the extension
`.rcp`. A PinPoint file must be a JSON text file with the extension `.smf` or `.srf`.
- The extensions `.c3db` and `.c3ptx` select EdgeWise without a content check. A `.c3ptx` file is read as one cluster file and any
Expand Down Expand Up @@ -100,7 +101,7 @@ These readers drop data without an error or a warning, so a scan can yield fewer
skipped, and a block that is not recognised ends the scan. The reader counts what it dropped or skipped and reports it in the
warnings of the document, so that an incomplete result is visible. With `PclReadOptions.Strict` the read fails instead.
- EdgeWise: a database node whose point count is 0 is skipped.

- PCD: a point with a NaN or infinite coordinate is not returned.
### Limits

A file that exceeds one of these limits, or whose declared sizes and counts do not fit the file, is rejected with
Expand All @@ -123,6 +124,7 @@ outside the file is fetched.
| PinPoint | Manifest 64 MiB and the default nesting depth of `System.Text.Json` (64); 100,000 scans. The parsed manifest needs memory of about 15 times its size, so a manifest at the limit needs about 1 GB. Sectioned data file: at most 16 sections, a property table of at most 1 MiB nested at most 8 levels, copies in a compressed stream at most 8 MiB back with a decoder window of at most 8 MiB per stream; the sections must be contiguous and fill the file, and the `Points`, `RGB8`, `Intensities8`, `Normals` and `FilterBits` streams must decode to exactly 12, 3, 1, 12 and 1 bytes per stored point. |
| EdgeWise | 1,048,576 characters per database line; 1,000,000 nodes. Patterns that parse a line have a time limit. |
| LAS | Header of at least 227 bytes (375 for 1.4); at most 4096 variable length records of at most 1 MiB each; point records at most 1 MiB. |
| PCD | 4096 header lines of at most 1 MiB each; at most 1024 fields with an element count of at most 65536; decompressed binary data at most 1 GiB. |

## Exporters

Expand Down
3 changes: 2 additions & 1 deletion docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,11 +88,12 @@ reading), `NotSupportedException` (unrecognised format or unsupported feature) o
| PinPoint project | `.srf`, `.smf`, or a folder with `ScanProject.json` or `.smf`/`.srf` files | Experimental; manifest plus point data files in one of two layouts (named channels, or sections with Snappy-compressed channels); a data file in neither layout is not read. |
| EdgeWise | `.c3db`, `.c3ptx` | Experimental; positions only, with a coordinate scale that is an assumption of the reader. |
| LAS | `.las` | Versions 1.0 to 1.4 with point formats 0 to 10; positions, intensity, classification and RGB for the colour formats. |
| PCD | `.pcd` | ASCII, binary and binary compressed (LZF) data; positions, colour, intensity and normals from the declared fields. |

A file is detected from its content, its extension or, for a folder, its layout. E57, ReCap scan and Leica files are recognised
by content, `.fls` needs an OLE2 compound file, `.rcp` a ZIP archive, `.srf` and `.smf` a JSON text file, `.las` the `LASF`
signature (a `.laz` file shares it and stays unknown), and `.c3db` and `.c3ptx`
are decided by extension alone, without a content check. Anything else is `PclFileKind.Unknown`. The rules are in
are decided by extension alone, without a content check. A `.pcd` file is recognised by its header structure. Anything else is `PclFileKind.Unknown`. The rules are in
[Public API](public-api.md#format-detection).
Anything a decoder does not support fails instead of being guessed, apart from the assumptions named in the README (the FARO folder
record layout, the EdgeWise position scale and the ReCap scan channel flags). The sizes and counts a reader accepts are limited; a
Expand Down
6 changes: 4 additions & 2 deletions docs/public-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ format-specific members can change when the support for that format changes.
| Type | Use |
|---|---|
| `PclFile` | Static entry point. `DetectKind(path)` and `DetectKind(stream, extension)` return a `PclFileKind`; `Open(path, options)` detects the format and returns a `PclDocument`. |
| `PclFileKind` | `Unknown`, `E57`, `RecapProject`, `RecapScan`, `LeicaLgsx`, `LeicaLgs`, `FaroFls`, `PinPoint`, `EdgeWise` and `Las`. |
| `PclFileKind` | `Unknown`, `E57`, `RecapProject`, `RecapScan`, `LeicaLgsx`, `LeicaLgs`, `FaroFls`, `PinPoint`, `EdgeWise`, `Las` and `Pcd`. |
| `PclReadOptions` | `MaxPoints` (limit of one read call, null for all, 0 for none), `MaxCoordinateMagnitude` (default 5000, null for no limit; NaN and infinite coordinates are never returned; currently only PinPoint applies it), `EdgeWiseCoordinateScale` (default 0.128 / 32768 metres per unit; the files do not declare it), `SubsampleStep` (1 keeps every point, N keeps about one in N), `Blocks` (range of the scan's blocks in file order, null for all; currently only Leica honours it), `MaxDegreeOfParallelism` (default 1: sequential; above 1 decodes the selected Leica blocks in parallel, keeping file order), `ApplyTransform` (default true), `Strict` (default false: a reader that finds incomplete data fails with `InvalidDataException` instead of adding a warning) and `ExcludeFilteredPoints` (default false: points the file marks as filtered are excluded; currently the `FilterBits` channel of the PinPoint sectioned layout). Negative `MaxPoints`, a negative magnitude limit, a negative block start or count, a non-positive or non-finite EdgeWise scale and a step or parallelism below 1 throw `ArgumentOutOfRangeException`. `PclReadOptions.Default` has no limit. |
| `BlockRange` | `StartBlock` (zero-based index of the first block to read) and `BlockCount` (how many blocks at most, null for all from the start on; a range past the last block yields no points, 0 yields none). |

Expand All @@ -33,6 +33,7 @@ is the argument, which may also be a file name.
- `E57`, `RecapScan` and the Leica kinds are recognised by content and accepted with any extension; `LeicaLgs` is chosen for the
extension `.lgs` and `LeicaLgsx` for any other. `EdgeWise` is also recognised by content in a file with another extension.
`Las` is recognised by the `LASF` signature with any extension except `.laz`, which shares the signature and stays unknown.
`Pcd` is recognised by its header structure (the documented entries in order) with any extension.
- `FaroFls` needs an OLE2 compound file with the extension `.fls`, `RecapProject` a ZIP archive with the extension `.rcp`, and
`PinPoint` a JSON text file with the extension `.smf` or `.srf`.
- The extensions `.c3db` and `.c3ptx` select `EdgeWise` without a content check, so a damaged file with one of these extensions is
Expand Down Expand Up @@ -69,6 +70,7 @@ drop points that fail a plausibility rule (see the README), so a scan can yield
| PinPoint | A manifest with a scan position list: declared by the manifest, else derived from the data file, else 0 (not known). A manifest with a data object list: derived from the data file the object refers to, else 0 (not known); locations that share one file each report its full count. |
| EdgeWise | A `.c3db` database node: the count the database declares. A `.c3ptx` file: computed by walking the cluster headers when the file is opened. |
| LAS | The header count (the extended 1.4 count when it states one). It is not checked against the point data until the points are read; a truncated read fails then. |
| PCD | WIDTH times HEIGHT, validated against POINTS when the file is opened. Points with non-finite coordinates are skipped, so a read can yield fewer points. |

`HasColors`, `HasIntensities` and `HasNormals` follow what the file contains, except for the scans of a ReCap project, where all three
are true when the `.rcs` file was found and false otherwise, without the file being opened. A ReCap scan reads the channels
Expand All @@ -78,7 +80,7 @@ no colour.
## Format documents

`E57Document`/`E57Scan`, `RcsScanDocument`/`RcsScan`, `RcpProjectDocument`/`RcpScan`, `LgsxDocument`/`LgsxScan`/`LgsxEntry`/`LgsxSetup`,
`FaroFlsDocument`/`FaroScan`, `PinPointDocument`/`PinPointScan`, `EdgeWiseDocument`/`EdgeWiseScan` and `LasDocument`/`LasScan` are the readers behind
`FaroFlsDocument`/`FaroScan`, `PinPointDocument`/`PinPointScan`, `EdgeWiseDocument`/`EdgeWiseScan`, `LasDocument`/`LasScan` and `PcdDocument`/`PcdScan` are the readers behind
`PclFile.Open`. Each has a static `Open` method and format-specific properties (for example the E57 version or the FARO scanner model).
Their XML documentation states what each reader supports. Prefer `PclFile.Open`, which detects the format and chooses the reader.

Expand Down
1 change: 1 addition & 0 deletions src/PclIO.Cli/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ ReCap project a ZIP archive with the extension .rcp
ScanProject.json, a .smf file or a .srf file
EdgeWise the extension .c3db or .c3ptx, or a text or tree signature in another file
LAS by signature (.las)
PCD by header structure (.pcd)

Output formats (--format, or the output extension; any other extension needs --format):
las ASPRS LAS 1.2, point data record format 2 (XYZ, intensity, RGB)
Expand Down
Loading
Loading