Public API
The PclIO package exposes the types listed here. Format detection, container helpers, byte helpers and path handling are
internal; they can change in any release and are visible only to the test project through InternalsVisibleTo.
The format readers (see Format documents) are public, but each describes one format, so their
format-specific members can change when the support for that format changes.
Opening a file
| 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 and EdgeWise. |
PclReadOptions |
MaxPoints (limit of one read call, null for all, 0 for none), SubsampleStep (1 keeps every point, N keeps about one in N) and ApplyTransform (default true). Negative MaxPoints and a step below 1 throw ArgumentOutOfRangeException. PclReadOptions.Default has no limit. |
Open throws FileNotFoundException for a missing path, DirectoryNotFoundException when a directory the reader needs is
missing or disappears while reading, NotSupportedException for an unrecognised format or an unsupported feature, and
InvalidDataException for a malformed or truncated file. DetectKind(path) throws FileNotFoundException when the path is
neither a file nor a directory. DetectKind(stream, extension) needs a seekable stream, restores its position, and throws
NotSupportedException otherwise.
Format detection
Detection finds the kind from the content of the file, its extension or the layout of a folder, and returns
PclFileKind.Unknown for anything else. Extensions are compared without regard to case; for the stream overload the extension
is the argument, which may also be a file name.
E57,RecapScanand the Leica kinds are recognised by content and accepted with any extension;LeicaLgsis chosen for the extension.lgsandLeicaLgsxfor any other.EdgeWiseis also recognised by content in a file with another extension.FaroFlsneeds an OLE2 compound file with the extension.fls,RecapProjecta ZIP archive with the extension.rcp, andPinPointa JSON text file with the extension.smfor.srf.- The extensions
.c3dband.c3ptxselectEdgeWisewithout a content check, so a damaged file with one of these extensions is detected asEdgeWiseand fails withInvalidDataExceptionwhen it is opened. - A folder is
FaroFlsfor a FARO scan folder, andPinPointwhen it holdsScanProject.json, or a.smfor.srffile directly inside it.
Open throws NotSupportedException for Unknown. For EdgeWise, the extension .c3ptx selects the single cluster file reader
and any other extension the point database reader.
Reading
| Type | Use |
|---|---|
PclDocument |
An opened file (IDisposable). Kind, FilePath, FileSize, Scans, TotalPointCount, OverallBounds, CoordinateSystem, Metadata, Warnings and ReadAllPoints(options), which streams the points of all scans in order and applies MaxPoints across all scans. TotalPointCount is the sum of the scans' PointCount; it saturates at long.MaxValue and ignores negative counts. |
PclScan |
One scan or setup. Id, Name, PointCount (see below for what each reader reports), Bounds, Transform, HasColors, HasNormals, HasIntensities, Properties and ReadPoints(options). |
PclPoint |
One point: Position (X, Y, Z), Color, Intensity (scale is format specific), Normal, Classification and Index, a running number within one scan's read call (it starts again at 0 for each scan of ReadAllPoints). Missing channels are null. |
PclColor, PclVector3, PclBounds, PclTransform |
Value types. PclBounds.Empty means unknown bounds. PclTransform has Translation, Rotation (stored for information, never applied), Scale and an optional Matrix4x4 of 16 values; TransformPoint applies scale and translation, or the matrix when there is one. |
PclDocument.Warnings lists non-fatal problems found while reading. The library never writes to the console.
What PointCount means
PclScan.PointCount is a number the reader reports, not a count of the points that ReadPoints will return. Some readers
drop points that fail a plausibility rule (see the README), so a scan can yield fewer points than it reports.
| Reader | PointCount |
|---|---|
| E57 | Declared by the file. It is not checked against the point data until the points are read. |
| ReCap scan | Declared in the header. It is not checked against the node table. |
| ReCap project | Declared by the project manifest; 0 when the manifest states none. |
| Leica | Computed. The container does not store it, so the first access decodes all of the point data and caches the result, which can be slow on large files; the access throws InvalidDataException for corrupt data. The container is one scan with the id unified-cloud. |
| FARO | Approximate: the size of the scan grid (rows times columns), not the number of valid returns. For a folder scan it is limited by the size of the data stream. |
| 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: always 0 (not known), so TotalPointCount is 0 for such a project. |
| EdgeWise | A .c3db database node: the count the database declares. A .c3ptx file: computed by walking the cluster headers when the file is opened. |
HasColors, HasIntensities and HasNormals follow what the file contains, except for ReCap scan, where they are constants of the
supported layout and always true (a single point can still have no normal), and 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.
Format documents
E57Document/E57Scan, RcsScanDocument/RcsScan, RcpProjectDocument/RcpScan, LgsxDocument/LgsxScan/LgsxEntry,
FaroFlsDocument/FaroScan, PinPointDocument/PinPointScan and EdgeWiseDocument/EdgeWiseScan 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.
Limits and filters
Readers check the sizes and counts a file declares against fixed limits and reject a file that exceeds one with
InvalidDataException. A few readers also drop points without an error or a warning. The numbers and rules are listed under
Limits and Data filters in the README. A few cases differ from
InvalidDataException; the README lists them.
Paths stored in files
File names read from ReCap, PinPoint and EdgeWise project files are resolved only inside the project's own folder. The check is lexical: symbolic links and junctions are not resolved, so a link inside the project folder counts as part of it. A name that is empty, rooted, contains invalid characters or resolves outside the folder is rejected.
Export
| Type | Use |
|---|---|
PclLasExporter |
Export(doc, stream, options) writes ASPRS LAS 1.2, point format 2, with a 1 mm scale. Returns the number of points written. |
PclXyzExporter |
Export(doc, writer, options) writes X Y Z R G B, or X Y Z I, or X Y Z per point. |
PclPtsExporter |
Export(doc, writer, options) writes the point count, then X Y Z Intensity R G B per point. |
PclJsonExporter |
Export(doc, writer, indented, maxPoints) writes metadata, scans and, when maxPoints is above zero, sample points. |
Each exporter has an overload with out long skippedPoints, the number of points skipped because a coordinate was NaN or infinite.
Output is culture independent; XYZ and PTS end lines with \n, and JSON uses the line ends of the platform. LAS and PTS read the source twice; the others stream it once. Normals are not exported.
Command line
PclIO.Cli installs the tool pclio. The Program class exposes Run(args, stdout, stderr) and the exit-code constants
ExitOk, ExitUsage, ExitFileNotFound, ExitFormatError and ExitUnexpected; see Getting started for the commands.