diff --git a/CHANGELOG.md b/CHANGELOG.md
index aa6ce71..7da648f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -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`
diff --git a/README.md b/README.md
index 45fafc1..ef154f8 100644
--- a/README.md
+++ b/README.md
@@ -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
@@ -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
@@ -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
@@ -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
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 6114759..02ad521 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -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
diff --git a/docs/public-api.md b/docs/public-api.md
index 71c0249..cfbcd61 100644
--- a/docs/public-api.md
+++ b/docs/public-api.md
@@ -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). |
@@ -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
@@ -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
@@ -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.
diff --git a/src/PclIO.Cli/Program.cs b/src/PclIO.Cli/Program.cs
index 5bb0f86..60f91ce 100644
--- a/src/PclIO.Cli/Program.cs
+++ b/src/PclIO.Cli/Program.cs
@@ -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)
diff --git a/src/PclIO/Formats/Pcd/PcdDocument.cs b/src/PclIO/Formats/Pcd/PcdDocument.cs
new file mode 100644
index 0000000..b4b6183
--- /dev/null
+++ b/src/PclIO/Formats/Pcd/PcdDocument.cs
@@ -0,0 +1,755 @@
+using PclIO.Internal;
+
+namespace PclIO.Formats.Pcd;
+
+/// Represents a Point Cloud Library point cloud file (.pcd).
+///
+///
+/// Supported: the 0.7 header (entries in the documented order, with or without a COUNT line), ASCII, binary and
+/// binary compressed (LZF) point data, the declared fields, organised and unorganised clouds, and the viewpoint
+/// (kept as metadata). Positions come from the x, y and z fields; colour from a packed rgb or rgba field;
+/// intensity from an intensity field; normals from normal_x, normal_y and normal_z. Points whose coordinates are
+/// not finite are not returned, like points the file marks as not-a-number.
+///
+///
+/// Not read (reported with when the file is opened): files without x, y and z
+/// fields, and x, y or z fields of an uninterpretable size and type combination. Colour, intensity and normals of
+/// an uninterpretable shape stay unread instead: the points come without that channel.
+///
+///
+public sealed class PcdDocument : PclDocument
+{
+ // Bounds for data taken from an untrusted file.
+ private const int MaxHeaderLines = 4096;
+ internal const int MaxLineLength = 1 << 20;
+ private const int MaxFields = 1024;
+ private const int MaxFieldCount = 65536;
+ private const long MaxDecompressedBytes = 1L << 30;
+
+ ///
+ public override PclFileKind Kind => PclFileKind.Pcd;
+
+ /// Version string from the header.
+ public string Version { get; }
+
+ /// Viewpoint string from the header (translation plus quaternion).
+ public string Viewpoint { get; }
+
+ ///
+ public override IReadOnlyList Scans => _scans;
+ private readonly List _scans = [];
+
+ private PcdDocument(string path, long fileSize, string version, string viewpoint)
+ : base(path, fileSize)
+ {
+ Version = version;
+ Viewpoint = viewpoint;
+ _metadata["Format"] = "Point Cloud Library PCD";
+ _metadata["Version"] = version;
+ _metadata["Viewpoint"] = viewpoint;
+ }
+
+ /// Opens a PCD file and reads its header.
+ /// Path of the .pcd file.
+ /// Currently unused; accepted for symmetry with the other readers.
+ /// The file does not exist.
+ /// The header is damaged or truncated, or declares sizes outside the file.
+ /// The file has no usable positions.
+ public static PcdDocument Open(string path, PclReadOptions? options = null)
+ {
+ var fi = new FileInfo(path);
+ if (!fi.Exists) throw new FileNotFoundException("PCD file not found.", path);
+
+ using var fs = File.OpenRead(path);
+ var header = ReadHeader(fs);
+
+ // An organised cloud holds WIDTH * HEIGHT points; an unorganised one holds WIDTH points with HEIGHT 1.
+ // Either way the product must be the declared point count.
+ long gridPoints;
+ try
+ {
+ checked
+ {
+ gridPoints = header.Width * header.Height;
+ }
+ }
+ catch (OverflowException)
+ {
+ throw FormatError.Corrupted("PCD WIDTH and HEIGHT declare more points than can be counted.");
+ }
+
+ if (gridPoints != header.Points)
+ throw FormatError.Corrupted("PCD WIDTH and HEIGHT do not hold the declared number of points.");
+
+ int x = Find(header, "x");
+ int y = Find(header, "y");
+ int z = Find(header, "z");
+ if (x < 0 || y < 0 || z < 0)
+ throw FormatError.Unsupported("PCD file has no x, y and z fields.");
+
+ foreach (int axis in new[] { x, y, z })
+ {
+ var field = header.Fields[axis];
+ if (!IsInterpretable(field))
+ throw FormatError.Unsupported($"PCD position field '{field.Name}' has size {field.Size} and type '{field.Type}'.");
+ }
+
+ var document = new PcdDocument(path, fs.Length, header.Version, header.Viewpoint);
+ document._metadata["Data"] = header.Data switch
+ {
+ PcdData.Ascii => "ascii",
+ PcdData.Binary => "binary",
+ _ => "binary_compressed",
+ };
+
+ // The binary layouts state their sizes up front, so a short file is rejected here and not mid-read.
+ if (header.Data == PcdData.Binary)
+ {
+ long need = CheckedPointBytes(header.Points, header.RecordSize);
+ if (need > fs.Length - header.DataStart) throw FormatError.Truncated("point data");
+ }
+ else if (header.Data == PcdData.Compressed)
+ {
+ if (header.DataStart + 8 > fs.Length) throw FormatError.Truncated("compressed point data");
+ fs.Position = header.DataStart;
+ byte[] sizes = new byte[8];
+ fs.ReadExactly(sizes);
+ uint compressedSize = Bytes.ReadUInt32LE(sizes.AsSpan(0, 4));
+ uint uncompressedSize = Bytes.ReadUInt32LE(sizes.AsSpan(4, 4));
+ if (uncompressedSize != CheckedPointBytes(header.Points, header.RecordSize))
+ throw FormatError.Corrupted("PCD compressed data does not hold the declared points.");
+ if (uncompressedSize > MaxDecompressedBytes)
+ throw FormatError.Corrupted("PCD compressed data is larger than the accepted size.");
+ if (compressedSize > fs.Length - header.DataStart - 8) throw FormatError.Truncated("compressed point data");
+ }
+
+ string name = Path.GetFileNameWithoutExtension(path);
+ document._scans.Add(new PcdScan("0", name, header.Points, path, header));
+ return document;
+ }
+
+ private static int Find(PcdHeader header, string name)
+ {
+ for (int i = 0; i < header.Fields.Length; i++)
+ if (header.Fields[i].Name.Equals(name, StringComparison.Ordinal)) return i;
+ return -1;
+ }
+
+ // A field size and type pair the reader converts; anything else stays unread.
+ internal static bool IsInterpretable(PcdField field) =>
+ (field.Type, field.Size) is ('I', 1 or 2 or 4) or ('U', 1 or 2 or 4) or ('F', 4 or 8);
+
+ // The product of the declared point count and the record size, checked: a crafted header can wrap it past
+ // zero and slip a short file past the size check, so the overflow is rejected rather than read.
+ internal static long CheckedPointBytes(long points, int recordSize)
+ {
+ try
+ {
+ checked { return points * recordSize; }
+ }
+ catch (OverflowException)
+ {
+ throw FormatError.Corrupted("PCD point count and record size declare more bytes than can be counted.");
+ }
+ }
+
+ /// How the points are stored after the header.
+ internal enum PcdData
+ {
+ Ascii,
+ Binary,
+ Compressed,
+ }
+
+ /// One declared field: its name, size, type, element count and byte offset in a record.
+ internal sealed record PcdField(string Name, int Size, char Type, int Count, int Offset)
+ {
+ public int Bytes => Size * Count;
+ }
+
+ /// The parsed header: everything a read needs.
+ internal sealed record PcdHeader(
+ string Version, PcdField[] Fields, PcdData Data, long Width, long Height, long Points,
+ string Viewpoint, long DataStart, int RecordSize);
+
+ // Reads the ASCII header: the documented entries in order, with or without a COUNT line, skipping
+ // comment and empty lines. Returns the header and the offset where the point data starts.
+ private static PcdHeader ReadHeader(FileStream fs)
+ {
+ string? version = null;
+ string[]? names = null;
+ int[]? sizes = null;
+ char[]? types = null;
+ int[]? counts = null;
+ long width = -1, height = -1, points = -1;
+ string? viewpoint = null;
+ PcdData? data = null;
+
+ // The header entries are dispatched by keyword: VERSION, WIDTH, HEIGHT and VIEWPOINT may appear anywhere,
+ // while FIELDS, SIZE, TYPE, COUNT and POINTS keep their relative order (COUNT optional) and DATA ends the
+ // header. Each entry appears once.
+ string[] ordered = ["FIELDS", "SIZE", "TYPE", "COUNT", "POINTS"];
+ int lastOrdered = -1;
+ var seen = new HashSet(StringComparer.Ordinal);
+ int lines = 0;
+
+ while (data == null)
+ {
+ if (++lines > MaxHeaderLines) throw FormatError.Corrupted("PCD header has too many lines.");
+ string line = ReadHeaderLine(fs);
+ if (line.StartsWith('#') || line.Length == 0) continue;
+
+ int space = line.IndexOfAny([' ', '\t']);
+ if (space < 0) throw FormatError.Corrupted($"PCD header line '{line}' has no value.");
+ string keyword = line[..space];
+ string[] values = line[(space + 1)..].Split([' ', '\t'], StringSplitOptions.RemoveEmptyEntries);
+
+ if (!seen.Add(keyword)) throw FormatError.Corrupted($"PCD header entry '{keyword}' appears twice.");
+ int orderIndex = Array.IndexOf(ordered, keyword);
+ if (orderIndex >= 0)
+ {
+ if (orderIndex <= lastOrdered) throw FormatError.Corrupted($"PCD header entry '{keyword}' is out of order.");
+ lastOrdered = orderIndex;
+ }
+
+ switch (keyword)
+ {
+ case "VERSION":
+ if (values.Length != 1) throw FormatError.Corrupted("PCD VERSION needs one value.");
+ version = values[0];
+ break;
+ case "FIELDS":
+ if (values.Length == 0 || values.Length > MaxFields)
+ throw FormatError.Corrupted("PCD FIELDS declares no fields or too many fields.");
+ // "_" is the padding placeholder and may repeat; the real field names must be unique.
+ var realNames = values.Where(v => !v.Equals("_", StringComparison.Ordinal)).ToArray();
+ if (realNames.Distinct(StringComparer.Ordinal).Count() != realNames.Length)
+ throw FormatError.Corrupted("PCD FIELDS names a field twice.");
+ names = values;
+ break;
+ case "SIZE":
+ sizes = ParseCounts(values, "SIZE");
+ foreach (int size in sizes)
+ if (size is not (1 or 2 or 4 or 8)) throw FormatError.Corrupted($"PCD field size {size} is not 1, 2, 4 or 8.");
+ break;
+ case "TYPE":
+ if (values.Any(v => v.Length != 1 || v[0] is not ('I' or 'U' or 'F')))
+ throw FormatError.Corrupted("PCD field type is not I, U or F.");
+ types = values.Select(v => v[0]).ToArray();
+ break;
+ case "COUNT":
+ counts = ParseCounts(values, "COUNT");
+ foreach (int count in counts)
+ if (count < 1 || count > MaxFieldCount) throw FormatError.Corrupted("PCD field count is out of range.");
+ break;
+ case "WIDTH":
+ width = ParseCount(values, "WIDTH");
+ break;
+ case "HEIGHT":
+ height = ParseCount(values, "HEIGHT");
+ break;
+ case "VIEWPOINT":
+ if (values.Length != 7) throw FormatError.Corrupted("PCD VIEWPOINT needs seven values.");
+ foreach (string value in values)
+ if (!double.TryParse(value, System.Globalization.NumberStyles.Float,
+ System.Globalization.CultureInfo.InvariantCulture, out double d) || !double.IsFinite(d))
+ throw FormatError.Corrupted("PCD VIEWPOINT is not usable.");
+ viewpoint = string.Join(' ', values);
+ break;
+ case "POINTS":
+ points = ParseCount(values, "POINTS");
+ break;
+ case "DATA":
+ if (values.Length != 1) throw FormatError.Corrupted("PCD DATA needs one value.");
+ data = values[0] switch
+ {
+ "ascii" => PcdData.Ascii,
+ "binary" => PcdData.Binary,
+ "binary_compressed" => PcdData.Compressed,
+ _ => throw FormatError.Corrupted($"PCD data type '{values[0]}' is not ascii, binary or binary_compressed."),
+ };
+ break;
+ }
+ }
+
+ if (version == null || names == null || sizes == null || types == null || viewpoint == null ||
+ width < 0 || height < 0 || points < 0)
+ throw FormatError.Corrupted("PCD header misses an entry.");
+ if (names.Length != sizes.Length || names.Length != types.Length)
+ throw FormatError.Corrupted("PCD FIELDS, SIZE and TYPE declare different field counts.");
+ counts ??= Enumerable.Repeat(1, names.Length).ToArray();
+ if (counts.Length != names.Length)
+ throw FormatError.Corrupted("PCD COUNT declares a different field count.");
+
+ var fields = new PcdField[names.Length];
+ int offset = 0;
+ for (int i = 0; i < names.Length; i++)
+ {
+ fields[i] = new PcdField(names[i], sizes[i], types[i], counts[i], offset);
+ offset += sizes[i] * counts[i];
+ if (offset < 0) throw FormatError.Corrupted("PCD fields declare more bytes than can be counted.");
+ }
+
+ return new PcdHeader(version, fields, data.Value, width, height, points, viewpoint, fs.Position, offset);
+ }
+
+ private static int[] ParseCounts(string[] values, string what)
+ {
+ if (values.Length == 0 || values.Length > MaxFields)
+ throw FormatError.Corrupted($"PCD {what} declares no fields or too many fields.");
+ var result = new int[values.Length];
+ for (int i = 0; i < values.Length; i++)
+ if (!int.TryParse(values[i], System.Globalization.NumberStyles.None,
+ System.Globalization.CultureInfo.InvariantCulture, out result[i]))
+ throw FormatError.Corrupted($"PCD {what} value '{values[i]}' is not a count.");
+ return result;
+ }
+
+ private static long ParseCount(string[] values, string what)
+ {
+ if (values.Length != 1 ||
+ !long.TryParse(values[0], System.Globalization.NumberStyles.None,
+ System.Globalization.CultureInfo.InvariantCulture, out long result) || result < 0)
+ throw FormatError.Corrupted($"PCD {what} is not a count.");
+ return result;
+ }
+
+ // One ASCII header line without its line break; the file position ends after the break.
+ private static string ReadHeaderLine(FileStream fs)
+ {
+ var bytes = new List(128);
+ while (true)
+ {
+ int b = fs.ReadByte();
+ if (b < 0) throw FormatError.Truncated("PCD header");
+ if (b == '\n') break;
+ if (b != '\r')
+ {
+ if (b > 127) throw FormatError.Corrupted("PCD header is not ASCII.");
+ bytes.Add((byte)b);
+ if (bytes.Count > MaxLineLength) throw FormatError.Corrupted("PCD header line is too long.");
+ }
+ }
+
+ return System.Text.Encoding.ASCII.GetString(bytes.ToArray());
+ }
+}
+
+/// The single scan of a PCD file.
+public sealed class PcdScan : PclScan
+{
+ // Binary records stream in chunks of at most this many bytes; memory use does not depend on the point count.
+ private const int MaxChunkBytes = 64 * 1024;
+
+ ///
+ public override string Id { get; }
+
+ ///
+ public override string Name { get; }
+
+ /// Number of points the header declares (WIDTH times HEIGHT).
+ public override long PointCount { get; }
+
+ /// Path of the PCD file.
+ public string FilePath { get; }
+
+ ///
+ public override bool HasColors { get; }
+
+ ///
+ public override bool HasIntensities { get; }
+
+ ///
+ public override bool HasNormals { get; }
+
+ private readonly PcdDocument.PcdHeader _header;
+ private readonly int _x;
+ private readonly int _y;
+ private readonly int _z;
+ private readonly int _rgb;
+ private readonly int _intensity;
+ private readonly int _normalX;
+ private readonly int _normalY;
+ private readonly int _normalZ;
+ private readonly int[] _starts;
+
+ internal PcdScan(string id, string name, long pointCount, string filePath, PcdDocument.PcdHeader header)
+ {
+ Id = id;
+ Name = name;
+ PointCount = pointCount;
+ FilePath = filePath;
+ _header = header;
+ _x = Find("x");
+ _y = Find("y");
+ _z = Find("z");
+ _rgb = FindColor();
+ _intensity = InterpretableIndex("intensity");
+ _normalX = InterpretableIndex("normal_x");
+ _normalY = InterpretableIndex("normal_y");
+ _normalZ = InterpretableIndex("normal_z");
+ HasColors = _rgb >= 0;
+ HasIntensities = _intensity >= 0;
+ HasNormals = _normalX >= 0 && _normalY >= 0 && _normalZ >= 0;
+
+ _starts = new int[header.Fields.Length];
+ int total = 0;
+ for (int i = 0; i < _starts.Length; i++)
+ {
+ _starts[i] = total;
+ total += header.Fields[i].Count;
+ }
+ }
+
+ private int Find(string name)
+ {
+ for (int i = 0; i < _header.Fields.Length; i++)
+ if (_header.Fields[i].Name.Equals(name, StringComparison.Ordinal)) return i;
+ return -1;
+ }
+
+ // A channel is read only when its field has a shape the reader converts; any other shape stays unread, so the
+ // points come without that channel rather than failing or misreading it.
+ private int InterpretableIndex(string name)
+ {
+ int i = Find(name);
+ return i >= 0 && PcdDocument.IsInterpretable(_header.Fields[i]) ? i : -1;
+ }
+
+ // A packed rgb or rgba field holds its colour in a single four-byte float or unsigned integer; anything else
+ // stays unread.
+ private int FindColor()
+ {
+ foreach (string name in new[] { "rgb", "rgba" })
+ {
+ int i = Find(name);
+ if (i < 0) continue;
+ var field = _header.Fields[i];
+ if (field.Count == 1 && ((field.Type == 'F' && field.Size == 4) || (field.Type == 'U' && field.Size == 4)))
+ return i;
+ }
+
+ return -1;
+ }
+
+ /// Streams the points of the file.
+ ///
+ /// Points whose coordinates are not finite are not returned. Organised clouds stream row after row.
+ /// and are ignored:
+ /// the point stream has no independent blocks to select or decode in parallel.
+ ///
+ /// The point data is truncated or malformed.
+ public override IEnumerable ReadPoints(PclReadOptions? options = null)
+ {
+ options ??= PclReadOptions.Default;
+ long targetCount = options.MaxPoints ?? PointCount;
+ if (targetCount <= 0) yield break;
+ targetCount = Math.Min(targetCount, PointCount);
+ int step = Math.Max(1, options.SubsampleStep);
+
+ using var fs = File.OpenRead(FilePath);
+ long yielded = 0;
+
+ if (_header.Data == PcdDocument.PcdData.Ascii)
+ {
+ fs.Position = _header.DataStart;
+ using var reader = new StreamReader(fs, System.Text.Encoding.ASCII, detectEncodingFromByteOrderMarks: false,
+ bufferSize: 65536, leaveOpen: true);
+ for (long i = 0; i < targetCount; i++)
+ {
+ string? line = ReadDataLine(reader);
+ if (line == null) throw FormatError.Truncated("point data");
+ if ((i % step) != 0) continue;
+
+ var point = ParseAsciiPoint(line, out bool valid);
+ if (!valid) continue;
+ point = point with { Index = (ulong)yielded };
+ if (options.ApplyTransform)
+ point = point with { Position = Transform.TransformPoint(point.Position) };
+
+ yield return point;
+ yielded++;
+ if (yielded >= targetCount) yield break;
+ }
+
+ yield break;
+ }
+
+ if (_header.Data == PcdDocument.PcdData.Binary)
+ {
+ foreach (var pt in ReadBinaryStreaming(fs, targetCount, step, options.ApplyTransform)) yield return pt;
+ yield break;
+ }
+
+ byte[] records = ReadDecompressedRecords(fs);
+ int recordSize = _header.RecordSize;
+ for (long i = 0; i < targetCount; i++)
+ {
+ if ((i % step) != 0) continue;
+ var point = ParseBinaryPoint(records.AsSpan((int)(i * recordSize), recordSize), out bool valid);
+ if (!valid) continue;
+ point = point with { Index = (ulong)yielded };
+ if (options.ApplyTransform)
+ point = point with { Position = Transform.TransformPoint(point.Position) };
+
+ yield return point;
+ yielded++;
+ if (yielded >= targetCount) yield break;
+ }
+ }
+
+ // Streams the binary point data in bounded chunks, carrying a record that straddles a chunk boundary, so
+ // memory use does not depend on the point count. The open path checked that the declared records fit the file.
+ private IEnumerable ReadBinaryStreaming(FileStream fs, long targetCount, int step, bool applyTransform)
+ {
+ int recordSize = _header.RecordSize;
+ fs.Position = _header.DataStart;
+ byte[] chunk = new byte[MaxChunkBytes];
+ byte[] carry = new byte[recordSize];
+ int carryLen = 0;
+ long parsed = 0;
+ long yielded = 0;
+
+ while (parsed < targetCount)
+ {
+ int read = fs.Read(chunk, 0, chunk.Length);
+ if (read == 0) throw FormatError.Truncated("point data");
+ int pos = 0;
+
+ // Complete a record carried over from the previous chunk.
+ if (carryLen > 0)
+ {
+ int take = Math.Min(recordSize - carryLen, read);
+ chunk.AsSpan(0, take).CopyTo(carry.AsSpan(carryLen));
+ carryLen += take;
+ pos = take;
+ if (carryLen == recordSize)
+ {
+ carryLen = 0;
+ if (parsed % step == 0)
+ {
+ var point = ParseBinaryPoint(carry, out bool valid);
+ if (valid)
+ {
+ point = point with { Index = (ulong)yielded };
+ if (applyTransform) point = point with { Position = Transform.TransformPoint(point.Position) };
+ yield return point;
+ yielded++;
+ if (yielded >= targetCount) yield break;
+ }
+ }
+ parsed++;
+ }
+ }
+
+ // Parse the whole records of this chunk.
+ while (pos + recordSize <= read && parsed < targetCount)
+ {
+ if (parsed % step == 0)
+ {
+ var point = ParseBinaryPoint(chunk.AsSpan(pos, recordSize), out bool valid);
+ if (valid)
+ {
+ point = point with { Index = (ulong)yielded };
+ if (applyTransform) point = point with { Position = Transform.TransformPoint(point.Position) };
+ yield return point;
+ yielded++;
+ if (yielded >= targetCount) yield break;
+ }
+ }
+ pos += recordSize;
+ parsed++;
+ }
+
+ // Carry the partial record into the next chunk.
+ if (pos < read && parsed < targetCount)
+ {
+ chunk.AsSpan(pos, read - pos).CopyTo(carry);
+ carryLen = read - pos;
+ }
+ }
+ }
+
+ // Decompresses the whole LZF payload: its structure-of-arrays layout needs every field to read any point.
+ private byte[] ReadDecompressedRecords(FileStream fs)
+ {
+ fs.Position = _header.DataStart;
+ byte[] sizes = new byte[8];
+ fs.ReadExactly(sizes);
+ uint compressedSize = Bytes.ReadUInt32LE(sizes.AsSpan(0, 4));
+ uint uncompressedSize = Bytes.ReadUInt32LE(sizes.AsSpan(4, 4));
+
+ long expect = PcdDocument.CheckedPointBytes(PointCount, _header.RecordSize);
+ if (uncompressedSize != expect)
+ throw FormatError.Corrupted("PCD compressed data does not hold the declared points.");
+ if (compressedSize > fs.Length - _header.DataStart - 8) throw FormatError.Truncated("compressed point data");
+
+ byte[] compressed = new byte[compressedSize];
+ fs.ReadExactly(compressed);
+ byte[] flat = LzfDecoder.Decompress(compressed, (int)uncompressedSize);
+
+ // The payload holds one block per field with every point: gather point after point. A field with
+ // several elements keeps them together per point.
+ byte[] records = new byte[uncompressedSize];
+ int recordSize = _header.RecordSize;
+ long fieldBase = 0;
+ foreach (var field in _header.Fields)
+ {
+ for (long i = 0; i < PointCount; i++)
+ flat.AsSpan((int)(fieldBase + (i * field.Bytes)), field.Bytes)
+ .CopyTo(records.AsSpan((int)(i * recordSize) + field.Offset, field.Bytes));
+ fieldBase += PointCount * (long)field.Bytes;
+ }
+
+ return records;
+ }
+
+ // Reads one data line with a bounded length, so a crafted multi-gigabyte line fails instead of exhausting
+ // memory. Returns null at the end of the stream.
+ private static string? ReadDataLine(StreamReader reader)
+ {
+ var sb = new System.Text.StringBuilder();
+ int c;
+ while ((c = reader.Read()) >= 0)
+ {
+ if (c == '\n') break;
+ if (c == '\r')
+ {
+ if (reader.Peek() == '\n') reader.Read();
+ break;
+ }
+ sb.Append((char)c);
+ if (sb.Length > PcdDocument.MaxLineLength) throw FormatError.Corrupted("PCD point line is too long.");
+ }
+ return c < 0 && sb.Length == 0 ? null : sb.ToString();
+ }
+
+ // Parses one ASCII line with exactly one value per field element.
+ private PclPoint ParseAsciiPoint(string line, out bool valid)
+ {
+ string[] tokens = line.Split([' ', '\t'], StringSplitOptions.RemoveEmptyEntries);
+ double[] numbers = new double[tokens.Length];
+ int t = 0;
+ foreach (var field in _header.Fields)
+ {
+ for (int c = 0; c < field.Count; c++)
+ {
+ if (t >= tokens.Length) throw FormatError.Corrupted("PCD point line holds the wrong number of values.");
+ numbers[t] = ParseNumber(tokens[t], field);
+ t++;
+ }
+ }
+
+ if (t != tokens.Length) throw FormatError.Corrupted("PCD point line holds the wrong number of values.");
+ return AssemblePoint(numbers, out valid);
+ }
+
+ private static double ParseNumber(string token, PcdDocument.PcdField field)
+ {
+ if (field.Type == 'F')
+ {
+ if (token.Equals("inf", StringComparison.OrdinalIgnoreCase)) return double.PositiveInfinity;
+ if (token.Equals("+inf", StringComparison.OrdinalIgnoreCase)) return double.PositiveInfinity;
+ if (token.Equals("-inf", StringComparison.OrdinalIgnoreCase)) return double.NegativeInfinity;
+ if (!double.TryParse(token, System.Globalization.NumberStyles.Float,
+ System.Globalization.CultureInfo.InvariantCulture, out double value))
+ throw FormatError.Corrupted($"PCD value '{token}' is not a number.");
+ if (field.Size == 4 && double.IsFinite(value) &&
+ (value > float.MaxValue || value < float.MinValue))
+ throw FormatError.Corrupted($"PCD value '{token}' does not fit a float.");
+ return value;
+ }
+
+ if (field.Type == 'I')
+ {
+ if (!long.TryParse(token, System.Globalization.NumberStyles.Integer,
+ System.Globalization.CultureInfo.InvariantCulture, out long value))
+ throw FormatError.Corrupted($"PCD value '{token}' is not an integer.");
+ long min = field.Size == 1 ? sbyte.MinValue : field.Size == 2 ? short.MinValue : field.Size == 4 ? int.MinValue : long.MinValue;
+ long max = field.Size == 1 ? sbyte.MaxValue : field.Size == 2 ? short.MaxValue : field.Size == 4 ? int.MaxValue : long.MaxValue;
+ if (value < min || value > max) throw FormatError.Corrupted($"PCD value '{token}' does not fit its field.");
+ return value;
+ }
+
+ if (!ulong.TryParse(token, System.Globalization.NumberStyles.Integer,
+ System.Globalization.CultureInfo.InvariantCulture, out ulong unsigned))
+ throw FormatError.Corrupted($"PCD value '{token}' is not an integer.");
+ ulong umax = field.Size == 1 ? byte.MaxValue : field.Size == 2 ? ushort.MaxValue : field.Size == 4 ? uint.MaxValue : ulong.MaxValue;
+ if (unsigned > umax) throw FormatError.Corrupted($"PCD value '{token}' does not fit its field.");
+ return unsigned;
+ }
+
+ // Reads one binary record: the fields in declared order, COUNT elements each.
+ private PclPoint ParseBinaryPoint(ReadOnlySpan record, out bool valid)
+ {
+ double[] numbers = new double[_starts[^1] + _header.Fields[^1].Count];
+ for (int f = 0; f < _header.Fields.Length; f++)
+ {
+ var field = _header.Fields[f];
+ var bytes = record.Slice(field.Offset, field.Bytes);
+ for (int c = 0; c < field.Count; c++)
+ numbers[_starts[f] + c] = ReadValue(bytes.Slice(c * field.Size, field.Size), field);
+ }
+
+ return AssemblePoint(numbers, out valid);
+ }
+
+ private static double ReadValue(ReadOnlySpan bytes, PcdDocument.PcdField field) =>
+ (field.Type, field.Size) switch
+ {
+ ('I', 1) => (sbyte)bytes[0],
+ ('I', 2) => Bytes.ReadInt16LE(bytes),
+ ('I', 4) => Bytes.ReadInt32LE(bytes),
+ ('I', 8) => Bytes.ReadInt64LE(bytes),
+ ('U', 1) => bytes[0],
+ ('U', 2) => Bytes.ReadUInt16LE(bytes),
+ ('U', 4) => Bytes.ReadUInt32LE(bytes),
+ ('U', 8) => Bytes.ReadUInt64LE(bytes),
+ ('F', 4) => Bytes.ReadSingleLE(bytes),
+ ('F', 8) => Bytes.ReadDoubleLE(bytes),
+ // A one- or two-byte float has no representation; such a field is gated out of every channel and its
+ // value is never used, so it reads as zero rather than running past the span.
+ _ => 0,
+ };
+
+ // Builds a point from the flat values: x, y and z decide validity, the rest fills the channels.
+ private PclPoint AssemblePoint(double[] numbers, out bool valid)
+ {
+ valid = true;
+ double x = numbers[_starts[_x]];
+ double y = numbers[_starts[_y]];
+ double z = numbers[_starts[_z]];
+ if (!double.IsFinite(x) || !double.IsFinite(y) || !double.IsFinite(z))
+ {
+ valid = false;
+ return default;
+ }
+
+ PclColor? color = null;
+ if (_rgb >= 0)
+ {
+ uint bits = ColorBits(numbers[_starts[_rgb]], _header.Fields[_rgb]);
+ color = new PclColor((byte)((bits >> 16) & 0xFF), (byte)((bits >> 8) & 0xFF), (byte)(bits & 0xFF));
+ }
+
+ float? intensity = _intensity >= 0 ? (float)numbers[_starts[_intensity]] : null;
+
+ PclVector3? normal = null;
+ if (HasNormals)
+ {
+ var n = new PclVector3(numbers[_starts[_normalX]], numbers[_starts[_normalY]], numbers[_starts[_normalZ]]);
+ if (double.IsFinite(n.X) && double.IsFinite(n.Y) && double.IsFinite(n.Z)) normal = n;
+ }
+
+ return new PclPoint(new PclVector3(x, y, z), Color: color, Intensity: intensity, Normal: normal);
+ }
+
+ // The first four bytes of a colour field as an unsigned integer: the float bits for a float field,
+ // the stored value otherwise.
+ private static uint ColorBits(double value, PcdDocument.PcdField field)
+ {
+ if (field.Type == 'F' && field.Size == 4) return BitConverter.SingleToUInt32Bits((float)value);
+ if (value < 0 || value > uint.MaxValue) return 0;
+ return (uint)(ulong)value;
+ }
+}
diff --git a/src/PclIO/Internal/KindDetector.cs b/src/PclIO/Internal/KindDetector.cs
index cad536a..1185afc 100644
--- a/src/PclIO/Internal/KindDetector.cs
+++ b/src/PclIO/Internal/KindDetector.cs
@@ -97,6 +97,84 @@ public static PclFileKind Detect(Stream stream, string? extension = null)
if (head.StartsWith(LasMagic))
return extension == ".laz" ? PclFileKind.Unknown : PclFileKind.Las;
+ // PCD files have no signature; a strict header structure in any extension decides.
+ if (IsPcdHeader(stream, origin))
+ return PclFileKind.Pcd;
+
return PclFileKind.Unknown;
}
+
+ // True when the stream starts with a PCD header: the documented entries in order, with or without COUNT.
+ // At most the first 256 KiB are inspected; the position is restored.
+ private static bool IsPcdHeader(Stream stream, long origin)
+ {
+ const int maxProbeBytes = 256 * 1024;
+ const int maxLineLength = 1 << 20;
+ string[] ordered = ["FIELDS", "SIZE", "TYPE", "COUNT", "POINTS"];
+
+ long length = stream.CanSeek ? stream.Length : long.MaxValue;
+ int toRead = (int)Math.Min(maxProbeBytes, Math.Max(0, length - origin));
+ if (toRead < 7) return false;
+
+ byte[] buffer = new byte[toRead];
+ stream.Position = origin;
+ try
+ {
+ int got = 0;
+ while (got < toRead)
+ {
+ int n = stream.Read(buffer, got, toRead - got);
+ if (n == 0) break;
+ got += n;
+ }
+
+ int lastOrdered = -1;
+ var seen = new HashSet(StringComparer.Ordinal);
+ int position = 0;
+ int lines = 0;
+ while (position < got)
+ {
+ int end = Array.IndexOf(buffer, (byte)'\n', position, got - position);
+ if (end < 0) return false;
+ int lineLength = end - position;
+ if (lineLength > 0 && buffer[end - 1] == (byte)'\r') lineLength--;
+ if (lineLength > maxLineLength) return false;
+
+ bool comment = lineLength > 0 && buffer[position] == (byte)'#';
+ if (!comment && lineLength > 0)
+ {
+ int space = -1;
+ for (int i = position; i < position + lineLength; i++)
+ {
+ if (buffer[i] is (byte)' ' or (byte)'\t')
+ {
+ space = i;
+ break;
+ }
+ }
+
+ if (space < 0) return false;
+ string keyword = System.Text.Encoding.ASCII.GetString(buffer, position, space - position);
+
+ if (!seen.Add(keyword)) return false;
+ int orderIndex = Array.IndexOf(ordered, keyword);
+ if (orderIndex >= 0)
+ {
+ if (orderIndex <= lastOrdered) return false;
+ lastOrdered = orderIndex;
+ }
+ if (keyword == "DATA") return true;
+ }
+
+ position = end + 1;
+ if (++lines > 4096) return false;
+ }
+
+ return false;
+ }
+ finally
+ {
+ stream.Position = origin;
+ }
+ }
}
diff --git a/src/PclIO/Internal/LzfDecoder.cs b/src/PclIO/Internal/LzfDecoder.cs
new file mode 100644
index 0000000..2922e35
--- /dev/null
+++ b/src/PclIO/Internal/LzfDecoder.cs
@@ -0,0 +1,65 @@
+namespace PclIO.Internal;
+
+/// Decompresses an LZF stream: Marc Lehmann's byte-oriented LZ77 format with literal runs and matches.
+///
+/// The stream is a sequence of tokens read from input: a control byte below 32 starts a literal run of
+/// control + 1 bytes that follow, and any other control byte starts a match. A match copies
+/// (control >> 5) + 2 bytes, or, when control >> 5 is 7, 7 + 2 plus one extra length byte more,
+/// from (control & 0x1F) * 256 plus the next byte plus one bytes back; a match may overlap its own output.
+/// Matches reach at most 8192 bytes back and copy at most 264 bytes. Anything else is malformed.
+///
+internal static class LzfDecoder
+{
+ /// Decompresses into exactly bytes.
+ /// The stream ends early, overruns the output or holds trailing bytes.
+ public static byte[] Decompress(ReadOnlySpan input, int expectedLength)
+ {
+ ArgumentOutOfRangeException.ThrowIfNegative(expectedLength);
+ byte[] output = new byte[expectedLength];
+ int ip = 0;
+ int op = 0;
+
+ while (op < expectedLength)
+ {
+ if (ip >= input.Length) throw FormatError.Corrupted("LZF stream ends before the output is complete.");
+ int ctrl = input[ip++];
+
+ if (ctrl < 32)
+ {
+ // A literal run: the next ctrl + 1 bytes are copied as they are.
+ int length = ctrl + 1;
+ if (length > input.Length - ip) throw FormatError.Corrupted("LZF literal run reaches past the input.");
+ if (length > expectedLength - op) throw FormatError.Corrupted("LZF literal run reaches past the output.");
+ input.Slice(ip, length).CopyTo(output.AsSpan(op, length));
+ ip += length;
+ op += length;
+ }
+ else
+ {
+ // A match: its length follows from the control byte (plus one extra byte at the longest code),
+ // and its offset from the low bits of the control byte and the next input byte.
+ int length = ctrl >> 5;
+ int offset = (ctrl & 0x1F) << 8;
+ if (length == 7)
+ {
+ if (ip >= input.Length) throw FormatError.Corrupted("LZF match length reaches past the input.");
+ length += input[ip++];
+ }
+
+ if (ip >= input.Length) throw FormatError.Corrupted("LZF match offset reaches past the input.");
+ offset += input[ip++] + 1;
+ if (offset > op) throw FormatError.Corrupted("LZF match reaches before the start of the output.");
+
+ length += 2;
+ if (length > expectedLength - op) throw FormatError.Corrupted("LZF match reaches past the output.");
+
+ // A match may overlap its own output, so it proceeds byte by byte.
+ int from = op - offset;
+ for (int i = 0; i < length; i++) output[op++] = output[from++];
+ }
+ }
+
+ if (ip != input.Length) throw FormatError.Corrupted("LZF stream holds bytes past the output.");
+ return output;
+ }
+}
diff --git a/src/PclIO/PclFile.cs b/src/PclIO/PclFile.cs
index 0f2caa6..7db4065 100644
--- a/src/PclIO/PclFile.cs
+++ b/src/PclIO/PclFile.cs
@@ -3,6 +3,7 @@
using PclIO.Formats.Faro;
using PclIO.Formats.Las;
using PclIO.Formats.Leica;
+using PclIO.Formats.Pcd;
using PclIO.Formats.PinPoint;
using PclIO.Formats.Recap;
using PclIO.Internal;
@@ -50,6 +51,7 @@ public static PclDocument Open(string path, PclReadOptions? options = null)
PclFileKind.PinPoint => PinPointDocument.Open(path, options),
PclFileKind.EdgeWise => EdgeWiseDocument.Open(path, options),
PclFileKind.Las => LasDocument.Open(path, options),
+ PclFileKind.Pcd => PcdDocument.Open(path, options),
_ => throw new NotSupportedException($"Unsupported or unrecognized point cloud file: '{path}'"),
};
}
diff --git a/src/PclIO/PclFileKind.cs b/src/PclIO/PclFileKind.cs
index 5e1d745..3b8f2ce 100644
--- a/src/PclIO/PclFileKind.cs
+++ b/src/PclIO/PclFileKind.cs
@@ -32,4 +32,7 @@ public enum PclFileKind
/// ASPRS LAS point cloud file (.las).
Las = 9,
+
+ /// Point Cloud Library point cloud file (.pcd).
+ Pcd = 10,
}
diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs
index 26faa70..ca41f76 100644
--- a/tests/PclIO.Tests/FormatTests.cs
+++ b/tests/PclIO.Tests/FormatTests.cs
@@ -4,6 +4,7 @@
using PclIO.Formats.Faro;
using PclIO.Formats.Las;
using PclIO.Formats.Leica;
+using PclIO.Formats.Pcd;
using PclIO.Formats.PinPoint;
using PclIO.Formats.Recap;
using Xunit;
@@ -2534,4 +2535,365 @@ public void Las_Extra_Bytes_Per_Record_Are_Skipped()
AssertNear(new PclVector3(1, 2, 3), points[0].Position);
Assert.Equal(new PclColor(10, 20, 30), points[0].Color);
}
+
+ // ---- PCD ----------------------------------------------------------------------------------------------------
+
+ [Fact]
+ public void PclFile_Opens_Pcd_With_Count_Channels_Viewpoint_And_Metadata()
+ {
+ using var dir = new TempDirectory();
+ using var doc = PclFile.Open(dir.Write("sample.pcd", SyntheticFixtures.CreateSyntheticPcd()));
+
+ Assert.Equal(PclFileKind.Pcd, doc.Kind);
+ var scan = Assert.Single(doc.Scans);
+ Assert.Equal("0", scan.Id);
+ Assert.Equal("sample", scan.Name);
+ Assert.Equal(3, scan.PointCount);
+ Assert.Equal(3, doc.TotalPointCount);
+ Assert.True(scan.HasColors);
+ Assert.True(scan.HasIntensities);
+ Assert.True(scan.HasNormals);
+ Assert.True(scan.Bounds.IsEmpty);
+ Assert.Equal("0.7", ((PcdDocument)doc).Version);
+ Assert.Equal("0 0 0 1 0 0 0", ((PcdDocument)doc).Viewpoint);
+ Assert.Equal("Point Cloud Library PCD", doc.Metadata["Format"]);
+ Assert.Null(doc.CoordinateSystem);
+ Assert.Empty(doc.Warnings);
+ }
+
+ [Theory]
+ [InlineData("ascii")]
+ [InlineData("binary")]
+ [InlineData("binary_compressed")]
+ public void Pcd_Round_Trip_Positions_Intensity_Colour_And_Normals(string data)
+ {
+ using var dir = new TempDirectory();
+ using var doc = PcdDocument.Open(dir.Write("sample.pcd", SyntheticFixtures.CreateSyntheticPcd(data: data)));
+
+ var points = doc.Scans[0].ReadPoints(NoTransform).ToList();
+
+ Assert.Equal(3, points.Count);
+ Assert.Equal([0UL, 1UL, 2UL], points.Select(p => p.Index));
+ AssertNear(new PclVector3(1, 2, 3), points[0].Position);
+ AssertNear(new PclVector3(-4.5, 5.25, 6.125), points[1].Position);
+ AssertNear(new PclVector3(7, 8, 9), points[2].Position);
+ Assert.Equal(0.25f, points[0].Intensity);
+ Assert.Equal(0.5f, points[1].Intensity);
+ Assert.Equal(0f, points[2].Intensity);
+ Assert.Equal(new PclColor(10, 20, 30), points[0].Color);
+ Assert.Equal(new PclColor(255, 255, 255), points[1].Color);
+ Assert.Equal(new PclColor(255, 255, 255), points[2].Color);
+ Assert.Equal(new PclVector3(0, 0, 1), points[0].Normal);
+ // Stored zeros read back as-is: PCD marks nothing as missing.
+ Assert.Equal(new PclVector3(0, 0, 0), points[1].Normal);
+ Assert.Equal(new PclVector3(0, 0, 0), points[2].Normal);
+ Assert.All(points, p => Assert.Null(p.Classification));
+ }
+
+ [Fact]
+ public void Pcd_Organised_Cloud_Streams_Row_After_Row()
+ {
+ var points = new[]
+ {
+ new PcdSamplePoint(1, 0, 0), new PcdSamplePoint(2, 0, 0),
+ new PcdSamplePoint(3, 0, 0), new PcdSamplePoint(4, 0, 0),
+ };
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticPcd(points,
+ fields: [("x", 4, 'F', 1), ("y", 4, 'F', 1), ("z", 4, 'F', 1)],
+ heightOverride: 2, widthOverride: 2);
+ using var doc = PcdDocument.Open(dir.Write("grid.pcd", bytes));
+
+ var scan = Assert.Single(doc.Scans);
+ Assert.Equal(4, scan.PointCount);
+ Assert.False(scan.HasColors);
+ Assert.False(scan.HasIntensities);
+
+ var read = scan.ReadPoints(NoTransform).ToList();
+ Assert.Equal([1.0, 2.0, 3.0, 4.0], read.Select(p => p.X));
+ Assert.All(read, p => Assert.Null(p.Intensity));
+ }
+
+ [Fact]
+ public void Pcd_Points_Without_Finite_Coordinates_Are_Not_Returned()
+ {
+ var points = new[]
+ {
+ new PcdSamplePoint(1, 2, 3),
+ new PcdSamplePoint(double.NaN, 0, 0),
+ new PcdSamplePoint(4, 5, 6),
+ };
+ foreach (string data in new[] { "ascii", "binary", "binary_compressed" })
+ {
+ using var dir = new TempDirectory();
+ using var doc = PcdDocument.Open(dir.Write("sample.pcd",
+ SyntheticFixtures.CreateSyntheticPcd(points, data: data)));
+
+ var read = doc.Scans[0].ReadPoints(NoTransform).ToList();
+ Assert.Equal(2, read.Count);
+ Assert.Equal([0UL, 1UL], read.Select(p => p.Index));
+ }
+ }
+
+ [Fact]
+ public void Pcd_Honours_Limit_And_Step_And_Ignores_Blocks_And_Parallelism()
+ {
+ var points = Enumerable.Range(0, 8).Select(i => new PcdSamplePoint(i, 0, 0)).ToList();
+ using var dir = new TempDirectory();
+ using var doc = PcdDocument.Open(dir.Write("sample.pcd", SyntheticFixtures.CreateSyntheticPcd(points)));
+ var scan = doc.Scans[0];
+
+ Assert.Equal(3, scan.ReadPoints(new PclReadOptions { MaxPoints = 3 }).Count());
+ Assert.Equal(4, scan.ReadPoints(new PclReadOptions { SubsampleStep = 2 }).Count());
+ Assert.Empty(scan.ReadPoints(new PclReadOptions { MaxPoints = 0 }));
+
+ var ranged = scan.ReadPoints(new PclReadOptions
+ {
+ Blocks = new BlockRange { StartBlock = 1, BlockCount = 1 },
+ MaxDegreeOfParallelism = 4,
+ }).ToList();
+ Assert.Equal(8, ranged.Count);
+ }
+
+ [Fact]
+ public void Pcd_Without_X_Y_Or_Z_Is_Not_Read()
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticPcd(
+ fields: [("y", 4, 'F', 1), ("z", 4, 'F', 1), ("rgb", 4, 'F', 1)]);
+
+ Assert.Throws(() => PcdDocument.Open(dir.Write("sample.pcd", bytes)));
+ }
+
+ [Fact]
+ public void Pcd_Unusable_Colour_Leaves_Points_Without_Colour()
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticPcd(
+ fields: [("x", 4, 'F', 1), ("y", 4, 'F', 1), ("z", 4, 'F', 1), ("rgb", 1, 'U', 1)]);
+ using var doc = PcdDocument.Open(dir.Write("sample.pcd", bytes));
+
+ var scan = Assert.Single(doc.Scans);
+ Assert.False(scan.HasColors);
+ Assert.Equal(3, scan.ReadPoints(NoTransform).Count());
+ Assert.All(scan.ReadPoints(NoTransform), p => Assert.Null(p.Color));
+ }
+
+ [Fact]
+ public void Pcd_Unknown_Data_Type_Is_Rejected()
+ {
+ using var dir = new TempDirectory();
+ var header = new[]
+ {
+ "VERSION 0.7", "FIELDS x y z", "SIZE 4 4 4", "TYPE F F F", "COUNT 1 1 1",
+ "WIDTH 1", "HEIGHT 1", "VIEWPOINT 0 0 0 1 0 0 0", "POINTS 1", "DATA base64",
+ };
+
+ Assert.Throws(() =>
+ PcdDocument.Open(dir.Write("sample.pcd", SyntheticFixtures.CreatePcdFile(header, [0]))));
+ }
+
+ [Fact]
+ public void Pcd_Header_Out_Of_Order_Is_Rejected()
+ {
+ using var dir = new TempDirectory();
+ var header = new[]
+ {
+ "VERSION 0.7", "SIZE 4 4 4", "FIELDS x y z", "TYPE F F F", "COUNT 1 1 1",
+ "WIDTH 1", "HEIGHT 1", "VIEWPOINT 0 0 0 1 0 0 0", "POINTS 1", "DATA ascii",
+ };
+
+ Assert.Throws(() =>
+ PcdDocument.Open(dir.Write("sample.pcd", SyntheticFixtures.CreatePcdFile(header, "1 2 3"u8.ToArray()))));
+ }
+
+ [Fact]
+ public void Pcd_Grid_That_Does_Not_Hold_The_Point_Count_Is_Rejected()
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticPcd(widthOverride: 2, heightOverride: 2);
+
+ Assert.Throws(() => PcdDocument.Open(dir.Write("sample.pcd", bytes)));
+ }
+
+ [Fact]
+ public void Pcd_Truncated_Ascii_Point_Data_Is_Rejected_When_Read()
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticPcd(data: "ascii");
+ byte[] cut = bytes[..(bytes.Length - 5)];
+ using var doc = PcdDocument.Open(dir.Write("cut.pcd", cut));
+
+ Assert.Equal(3, doc.Scans[0].PointCount);
+ Assert.Throws(() => doc.Scans[0].ReadPoints().ToList());
+ }
+
+ [Theory]
+ [InlineData("binary")]
+ [InlineData("binary_compressed")]
+ public void Pcd_Truncated_Binary_Point_Data_Is_Rejected_At_Open(string data)
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticPcd(data: data);
+ byte[] cut = bytes[..(bytes.Length - 5)];
+
+ Assert.Throws(() => PcdDocument.Open(dir.Write("cut.pcd", cut)));
+ }
+
+ [Fact]
+ public void Pcd_Corrupt_Lzf_Is_Rejected_When_Read()
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticPcd(data: "binary_compressed");
+
+ // The header ends at the first DATA line; the first compressed byte follows the two sizes.
+ int dataAt = System.Text.Encoding.ASCII.GetString(bytes).IndexOf("DATA binary_compressed", StringComparison.Ordinal);
+ int bodyAt = System.Text.Encoding.ASCII.GetString(bytes).IndexOf('\n', dataAt) + 1;
+ bytes[bodyAt + 8] = 0xFF; // a match reaching before the start of the output
+ using var doc = PcdDocument.Open(dir.Write("sample.pcd", bytes));
+
+ Assert.Throws(() => doc.Scans[0].ReadPoints().ToList());
+ }
+
+ [Fact]
+ public void Pcd_Compressed_Size_Mismatch_Is_Rejected()
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticPcd(data: "binary_compressed");
+
+ // The header ends at the first DATA line; the sizes start 8 bytes after it.
+ int dataAt = System.Text.Encoding.ASCII.GetString(bytes).IndexOf("DATA binary_compressed", StringComparison.Ordinal);
+ int bodyAt = System.Text.Encoding.ASCII.GetString(bytes).IndexOf('\n', dataAt) + 1;
+ System.Buffers.Binary.BinaryPrimitives.WriteUInt32LittleEndian(bytes.AsSpan(bodyAt + 4, 4), 1);
+
+ Assert.Throws(() => PcdDocument.Open(dir.Write("sample.pcd", bytes)));
+ }
+
+ [Fact]
+ public void Pcd_Huge_Point_Count_With_No_Data_Is_Rejected_At_Open()
+ {
+ // POINTS * record size wraps past zero unchecked; the checked product rejects the file instead of
+ // opening it and crashing mid-read.
+ using var dir = new TempDirectory();
+ var header = new[]
+ {
+ "# .PCD v.7", "VERSION 0.7", "FIELDS x y z", "SIZE 4 4 4", "TYPE F F F", "COUNT 1 1 1",
+ "WIDTH 4611686018427387904", "HEIGHT 1", "VIEWPOINT 0 0 0 1 0 0 0",
+ "POINTS 4611686018427387904", "DATA binary",
+ };
+ byte[] bytes = SyntheticFixtures.CreatePcdFile(header, []);
+
+ Assert.Throws(() => PcdDocument.Open(dir.Write("sample.pcd", bytes)));
+ }
+
+ [Fact]
+ public void Pcd_Intensity_Of_Uninterpretable_Shape_Stays_Unread()
+ {
+ // A one-byte float intensity has no representation; the points come without intensity rather than
+ // crashing on the short span.
+ using var dir = new TempDirectory();
+ var header = new[]
+ {
+ "# .PCD v.7", "VERSION 0.7", "FIELDS x y z intensity", "SIZE 4 4 4 1", "TYPE F F F F",
+ "COUNT 1 1 1 1", "WIDTH 1", "HEIGHT 1", "VIEWPOINT 0 0 0 1 0 0 0", "POINTS 1", "DATA binary",
+ };
+ byte[] body = new byte[13];
+ System.Buffers.Binary.BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(0, 4), 1f);
+ System.Buffers.Binary.BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(4, 4), 2f);
+ System.Buffers.Binary.BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(8, 4), 3f);
+ body[12] = 200;
+ using var doc = PcdDocument.Open(dir.Write("sample.pcd", SyntheticFixtures.CreatePcdFile(header, body)));
+
+ var scan = Assert.Single(doc.Scans);
+ Assert.False(scan.HasIntensities);
+ var point = Assert.Single(scan.ReadPoints(NoTransform));
+ AssertNear(new PclVector3(1, 2, 3), point.Position);
+ Assert.Null(point.Intensity);
+ }
+
+ [Fact]
+ public void Pcd_Repeated_Padding_Field_Names_Are_Accepted()
+ {
+ // "_" is the padding placeholder and may repeat; the format allows repeated padding names.
+ using var dir = new TempDirectory();
+ var header = new[]
+ {
+ "# .PCD v.7", "VERSION 0.7", "FIELDS x y z _ rgb", "SIZE 4 4 4 4 4", "TYPE F F F F U",
+ "COUNT 1 1 1 1 1", "WIDTH 1", "HEIGHT 1", "VIEWPOINT 0 0 0 1 0 0 0", "POINTS 1", "DATA binary",
+ };
+ byte[] body = new byte[20];
+ System.Buffers.Binary.BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(0, 4), 1f);
+ System.Buffers.Binary.BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(4, 4), 2f);
+ System.Buffers.Binary.BinaryPrimitives.WriteSingleLittleEndian(body.AsSpan(8, 4), 3f);
+ System.Buffers.Binary.BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(16, 4), (10u << 16) | (20u << 8) | 30u);
+ using var doc = PcdDocument.Open(dir.Write("sample.pcd", SyntheticFixtures.CreatePcdFile(header, body)));
+
+ var scan = Assert.Single(doc.Scans);
+ Assert.True(scan.HasColors);
+ var point = Assert.Single(scan.ReadPoints(NoTransform));
+ AssertNear(new PclVector3(1, 2, 3), point.Position);
+ Assert.Equal(new PclColor(10, 20, 30), point.Color);
+ }
+
+ [Fact]
+ public void Pcd_Viewpoint_May_Precede_Width_And_Height()
+ {
+ // The format lets VERSION, WIDTH, HEIGHT and VIEWPOINT float; only the field entries keep order.
+ using var dir = new TempDirectory();
+ var header = new[]
+ {
+ "# .PCD v.7", "VERSION 0.7", "VIEWPOINT 0 0 0 1 0 0 0", "FIELDS x y z", "SIZE 4 4 4",
+ "TYPE F F F", "HEIGHT 1", "WIDTH 1", "POINTS 1", "DATA ascii",
+ };
+ using var doc = PcdDocument.Open(dir.Write("sample.pcd", SyntheticFixtures.CreatePcdFile(header, "1 2 3"u8.ToArray())));
+
+ AssertNear(new PclVector3(1, 2, 3), Assert.Single(doc.Scans[0].ReadPoints(NoTransform)).Position);
+ Assert.Equal(PclFileKind.Pcd, PclFile.DetectKind(dir.Write("detect.pcd", SyntheticFixtures.CreatePcdFile(header, "1 2 3"u8.ToArray()))));
+ }
+
+ [Fact]
+ public void Pcd_Binary_Read_Streams_Records_Across_Chunk_Boundaries()
+ {
+ // A twelve-byte record does not divide the 64 KiB chunk; records that straddle a boundary must stay aligned.
+ var points = Enumerable.Range(0, 7000).Select(i => new PcdSamplePoint(i % 1000, i / 1000, 0)).ToList();
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticPcd(points,
+ fields: [("x", 4, 'F', 1), ("y", 4, 'F', 1), ("z", 4, 'F', 1)], data: "binary");
+ using var doc = PcdDocument.Open(dir.Write("sample.pcd", bytes));
+
+ var all = doc.Scans[0].ReadPoints(NoTransform).ToList();
+ Assert.Equal(7000, all.Count);
+ AssertNear(new PclVector3(553, 6, 0), all[6553].Position);
+ AssertNear(new PclVector3(999, 6, 0), all[6999].Position);
+ }
+
+ [Fact]
+ public void Pcd_Overlong_Ascii_Line_Is_Rejected()
+ {
+ using var dir = new TempDirectory();
+ var header = new[]
+ {
+ "# .PCD v.7", "VERSION 0.7", "FIELDS x y z", "SIZE 4 4 4", "TYPE F F F", "COUNT 1 1 1",
+ "WIDTH 1", "HEIGHT 1", "VIEWPOINT 0 0 0 1 0 0 0", "POINTS 1", "DATA ascii",
+ };
+ byte[] body = System.Text.Encoding.ASCII.GetBytes(new string('1', (1 << 20) + 1) + "\n");
+ using var doc = PcdDocument.Open(dir.Write("sample.pcd", SyntheticFixtures.CreatePcdFile(header, body)));
+
+ Assert.Throws(() => doc.Scans[0].ReadPoints().ToList());
+ }
+
+ [Fact]
+ public void Pcd_Detection_Accepts_A_Long_Comment_Line()
+ {
+ // The probe's line bound matches the reader's, so a long comment does not hide the format.
+ using var dir = new TempDirectory();
+ var header = new[]
+ {
+ "# " + new string('c', 5000), "# .PCD v.7", "VERSION 0.7", "FIELDS x y z", "SIZE 4 4 4",
+ "TYPE F F F", "COUNT 1 1 1", "WIDTH 1", "HEIGHT 1", "VIEWPOINT 0 0 0 1 0 0 0", "POINTS 1", "DATA ascii",
+ };
+ byte[] bytes = SyntheticFixtures.CreatePcdFile(header, "1 2 3"u8.ToArray());
+
+ Assert.Equal(PclFileKind.Pcd, PclFile.DetectKind(dir.Write("sample.pcd", bytes)));
+ }
}
diff --git a/tests/PclIO.Tests/KindDetectionTests.cs b/tests/PclIO.Tests/KindDetectionTests.cs
index dcbb70c..163d537 100644
--- a/tests/PclIO.Tests/KindDetectionTests.cs
+++ b/tests/PclIO.Tests/KindDetectionTests.cs
@@ -58,7 +58,18 @@ public void Las_Needs_The_Signature_Not_Just_The_Extension() =>
[Fact]
public void A_Laz_File_Is_Not_Detected_As_Las() =>
- Assert.Equal(PclFileKind.Unknown, Detect(SyntheticFixtures.CreateSyntheticLas(), "sample.laz")); [Fact]
+ Assert.Equal(PclFileKind.Unknown, Detect(SyntheticFixtures.CreateSyntheticLas(), "sample.laz"));
+
+ [Theory]
+ [InlineData("sample.pcd")]
+ [InlineData("SAMPLE.PCD")]
+ [InlineData("sample.dat")]
+ public void Detects_Pcd_By_Header_Structure(string name) =>
+ Assert.Equal(PclFileKind.Pcd, Detect(SyntheticFixtures.CreateSyntheticPcd(), name));
+
+ [Fact]
+ public void Pcd_Needs_The_Header_Structure_Not_Just_The_Extension() =>
+ Assert.Equal(PclFileKind.Unknown, Detect("just some text"u8.ToArray(), "sample.pcd")); [Fact]
public void Faro_Needs_The_Container_Signature_Not_Just_The_Extension() =>
Assert.Equal(PclFileKind.Unknown, Detect(new byte[100], "scanner.fls"));
diff --git a/tests/PclIO.Tests/LzfDecoderTests.cs b/tests/PclIO.Tests/LzfDecoderTests.cs
new file mode 100644
index 0000000..0e83b47
--- /dev/null
+++ b/tests/PclIO.Tests/LzfDecoderTests.cs
@@ -0,0 +1,97 @@
+using PclIO.Internal;
+using Xunit;
+
+namespace PclIO.Tests;
+
+/// Hand-built LZF streams: every vector is computed from the token rules, not by the test encoder.
+public sealed class LzfDecoderTests
+{
+ private static byte[] Decode(byte[] stream, int expected) => LzfDecoder.Decompress(stream, expected);
+
+ [Fact]
+ public void Empty_Stream_Decodes_To_Empty() =>
+ Assert.Empty(Decode([], 0));
+
+ [Fact]
+ public void A_Literal_Run_Copies_Its_Bytes() =>
+ Assert.Equal("abc"u8.ToArray(), Decode([0x02, (byte)'a', (byte)'b', (byte)'c'], 3));
+
+ [Fact]
+ public void A_Literal_Run_Holds_At_Most_32_Bytes()
+ {
+ byte[] payload = Enumerable.Range(0, 32).Select(i => (byte)i).ToArray();
+ Assert.Equal(payload, Decode([0x1F, .. payload], 32));
+ }
+
+ [Fact]
+ public void A_Match_Copies_From_The_Output()
+ {
+ // 'a', then a match of offset 1 and 9 bytes: control (7 << 5) | 0, extra 0, low 0.
+ Assert.Equal("aaaaaaaaaa"u8.ToArray(), Decode([0x00, (byte)'a', 0xE0, 0x00, 0x00], 10));
+ }
+
+ [Fact]
+ public void A_Match_May_Overlap_Its_Own_Output()
+ {
+ // "ab", then a match of offset 2 and 18 bytes: control (7 << 5) | 0, extra 9, low 1.
+ byte[] expected = "abababababababababab"u8.ToArray();
+ Assert.Equal(expected, Decode([0x01, (byte)'a', (byte)'b', 0xE0, 0x09, 0x01], 20));
+ }
+
+ [Fact]
+ public void A_Match_Without_Extra_Length_Copies_Up_To_Nine_Bytes()
+ {
+ // "abcdef", then a match of offset 6 and 5 bytes: control (3 << 5) | 0, low 5.
+ byte[] expected = "abcdefabcde"u8.ToArray();
+ Assert.Equal(expected, Decode([0x05, .. "abcdef"u8.ToArray(), 0x60, 0x05], 11));
+ }
+
+ [Fact]
+ public void A_Match_Can_Reach_8192_Bytes_Back()
+ {
+ byte[] prefix = Enumerable.Range(0, 8192).Select(i => (byte)(i & 0xFF)).ToArray();
+ var stream = new List();
+ for (int at = 0; at < prefix.Length; at += 32)
+ {
+ stream.Add(0x1F);
+ stream.AddRange(prefix.AsSpan(at, 32).ToArray());
+ }
+
+ // Offset 8192 is (31 << 8) + 255 + 1: control (1 << 5) | 31, low 255; copies 3 bytes.
+ stream.Add(0x3F);
+ stream.Add(0xFF);
+ byte[] expected = [.. prefix, prefix[0], prefix[1], prefix[2]];
+ Assert.Equal(expected, Decode([.. stream], expected.Length));
+ }
+
+ [Fact]
+ public void A_Round_Trip_Through_The_Test_Encoder_Restores_Random_Data()
+ {
+ var random = new Random(42);
+ foreach (int length in new[] { 0, 1, 31, 32, 33, 300, 9000 })
+ {
+ byte[] data = new byte[length];
+ random.NextBytes(data);
+ // Repetitions make matches likely at every size.
+ for (int i = 100; i + 10 < length; i += 100) Array.Copy(data, 0, data, i, 10);
+
+ byte[] compressed = SyntheticFixtures.LzfCompress(data);
+ Assert.Equal(data, Decode(compressed, data.Length));
+ }
+ }
+
+ [Theory]
+ [InlineData(new byte[] { 0x05, (byte)'a' })] // literal run ends early
+ [InlineData(new byte[] { 0x00, (byte)'a', 0x20, 0x05 })] // match of offset 6 with one byte out
+ [InlineData(new byte[] { 0x00, (byte)'a' })] // literal ends early with output missing
+ public void A_Truncated_Stream_Is_Rejected(byte[] stream) =>
+ Assert.Throws(() => Decode(stream, 4));
+
+ [Fact]
+ public void A_Output_Overrun_Is_Rejected() =>
+ Assert.Throws(() => Decode([0x1F, .. new byte[32]], 10));
+
+ [Fact]
+ public void Trailing_Bytes_Are_Rejected() =>
+ Assert.Throws(() => Decode([0x00, (byte)'a', 0x00, (byte)'b'], 1));
+}
diff --git a/tests/PclIO.Tests/RealFileTests.cs b/tests/PclIO.Tests/RealFileTests.cs
index 85afbd4..09cc8e5 100644
--- a/tests/PclIO.Tests/RealFileTests.cs
+++ b/tests/PclIO.Tests/RealFileTests.cs
@@ -75,6 +75,9 @@ private static void AssertReadsPoints(string extension, PclFileKind kind)
[SkippableFact]
public void Read_Real_Las_Points() => AssertReadsPoints(".las", PclFileKind.Las);
+ [SkippableFact]
+ public void Read_Real_Pcd_Points() => AssertReadsPoints(".pcd", PclFileKind.Pcd);
+
[SkippableFact]
public void Export_Real_File_To_Las_Matches_The_Requested_Count()
{
diff --git a/tests/PclIO.Tests/SyntheticFixtures.cs b/tests/PclIO.Tests/SyntheticFixtures.cs
index f58a0c8..50f2c21 100644
--- a/tests/PclIO.Tests/SyntheticFixtures.cs
+++ b/tests/PclIO.Tests/SyntheticFixtures.cs
@@ -17,6 +17,9 @@ namespace PclIO.Tests;
/// One point of a synthetic LAS file: position, normalised intensity, colour and class code.
public readonly record struct LasSamplePoint(double X, double Y, double Z, float Intensity = 1.0f, PclColor? Color = null, byte Classification = 0);
+/// One point of a synthetic PCD file: position, intensity, colour and normal.
+public readonly record struct PcdSamplePoint(double X, double Y, double Z, float? Intensity = null, PclColor? Color = null, PclVector3? Normal = null);
+
/// Generates small synthetic scan files for the tests. Every layout is written from what the readers implement;
/// no byte of any of them comes from a real scan.
internal static class SyntheticFixtures
@@ -611,7 +614,6 @@ public static byte[] CreateSyntheticFlsContainer(string? parameters = null, usho
}
// ---- LAS (.las) ---------------------------------------------------------------------------------------------------
-
/// Base record size of a LAS point format; waveform tails are not interpreted.
public static int LasBaseRecordSize(int pointFormat) => pointFormat switch
{
@@ -781,4 +783,249 @@ public static byte[] CreateSyntheticLas(IReadOnlyList? points =
return ms.ToArray();
}
+
+ // ---- PCD (.pcd) ---------------------------------------------------------------------------------------------------
+
+ /// Default PCD fields: positions, packed colour, intensity and normals, all 4-byte floats.
+ public static IReadOnlyList<(string Name, int Size, char Type, int Count)> DefaultPcdFields =>
+ [
+ ("x", 4, 'F', 1), ("y", 4, 'F', 1), ("z", 4, 'F', 1),
+ ("rgb", 4, 'F', 1), ("intensity", 4, 'F', 1),
+ ("normal_x", 4, 'F', 1), ("normal_y", 4, 'F', 1), ("normal_z", 4, 'F', 1),
+ ];
+
+ /// Default PCD points: three points with mixed channels.
+ public static IReadOnlyList DefaultPcdPoints =>
+ [
+ new(1, 2, 3, 0.25f, new PclColor(10, 20, 30), new PclVector3(0, 0, 1)),
+ new(-4.5, 5.25, 6.125, 0.5f),
+ new(7, 8, 9, null, new PclColor(255, 255, 255)),
+ ];
+
+ /// A synthetic PCD file with one scan.
+ /// Points to store.
+ /// Field declarations; null uses .
+ /// Point storage: ascii, binary or binary_compressed.
+ /// VIEWPOINT value; null uses the default.
+ /// WIDTH to declare instead of the point count.
+ /// HEIGHT to declare instead of 1.
+ /// POINTS to declare instead of the point count.
+ /// False leaves the COUNT line out.
+ public static byte[] CreateSyntheticPcd(IReadOnlyList? points = null,
+ IReadOnlyList<(string Name, int Size, char Type, int Count)>? fields = null, string data = "ascii",
+ string? viewpoint = null, long? widthOverride = null, long? heightOverride = null, long? pointsOverride = null,
+ bool withCountLine = true)
+ {
+ points ??= DefaultPcdPoints;
+ fields ??= DefaultPcdFields;
+
+ var header = new List
+ {
+ "# .PCD v.7 - Point Cloud Data file format",
+ "VERSION 0.7",
+ "FIELDS " + string.Join(' ', fields.Select(f => f.Name)),
+ "SIZE " + string.Join(' ', fields.Select(f => f.Size)),
+ "TYPE " + string.Join(' ', fields.Select(f => f.Type)),
+ };
+ if (withCountLine) header.Add("COUNT " + string.Join(' ', fields.Select(f => f.Count)));
+ header.AddRange([
+ $"WIDTH {widthOverride ?? points.Count}",
+ $"HEIGHT {heightOverride ?? 1}",
+ $"VIEWPOINT {viewpoint ?? "0 0 0 1 0 0 0"}",
+ $"POINTS {pointsOverride ?? points.Count}",
+ $"DATA {data}",
+ ]);
+
+ byte[] body = data switch
+ {
+ "ascii" => PcdAsciiBody(points, fields),
+ "binary" => PcdBinaryBody(points, fields),
+ "binary_compressed" => PcdCompressedBody(points, fields),
+ _ => throw new ArgumentException($"Unknown PCD data '{data}'.", nameof(data)),
+ };
+
+ byte[] headerBytes = System.Text.Encoding.ASCII.GetBytes(string.Join('\n', header) + "\n");
+ return [.. headerBytes, .. body];
+ }
+
+ /// A PCD file from raw header lines and a body.
+ public static byte[] CreatePcdFile(IEnumerable headerLines, byte[] body)
+ {
+ byte[] headerBytes = System.Text.Encoding.ASCII.GetBytes(string.Join('\n', headerLines) + "\n");
+ return [.. headerBytes, .. body];
+ }
+
+ private static byte[] PcdAsciiBody(IReadOnlyList points,
+ IReadOnlyList<(string Name, int Size, char Type, int Count)> fields)
+ {
+ var sb = new StringBuilder();
+ foreach (var p in points)
+ {
+ var tokens = new List();
+ foreach (var field in fields)
+ for (int c = 0; c < field.Count; c++)
+ tokens.Add(PcdAsciiValue(p, field, c));
+ sb.Append(string.Join(' ', tokens));
+ sb.Append('\n');
+ }
+
+ return System.Text.Encoding.ASCII.GetBytes(sb.ToString());
+ }
+
+ private static string PcdAsciiValue(PcdSamplePoint p, (string Name, int Size, char Type, int Count) field, int index)
+ {
+ if (index > 0) return "0";
+ // Packed colour travels as the float holding its bits; other shapes hold no colour.
+ if (field.Name is "rgb" or "rgba")
+ {
+ if (field is not { Size: 4, Type: 'F' }) return "0";
+ uint bits = p.Color is { } c ? (uint)((c.R << 16) | (c.G << 8) | c.B) : 0xFFFFFF;
+ return BitConverter.UInt32BitsToSingle(bits).ToString("R", System.Globalization.CultureInfo.InvariantCulture);
+ }
+
+ double value = PcdFieldValue(p, field);
+ if (field.Type == 'F') return double.IsNaN(value) ? "nan" : value.ToString("R", System.Globalization.CultureInfo.InvariantCulture);
+ return ((long)value).ToString(System.Globalization.CultureInfo.InvariantCulture);
+ }
+
+ private static byte[] PcdBinaryBody(IReadOnlyList points,
+ IReadOnlyList<(string Name, int Size, char Type, int Count)> fields)
+ {
+ using var ms = new MemoryStream();
+ foreach (var p in points)
+ foreach (var field in fields)
+ for (int c = 0; c < field.Count; c++)
+ ms.Write(PcdFieldBytes(p, field, c));
+ return ms.ToArray();
+ }
+
+ private static byte[] PcdCompressedBody(IReadOnlyList points,
+ IReadOnlyList<(string Name, int Size, char Type, int Count)> fields)
+ {
+ // The payload is one block per field holding every point.
+ using var flat = new MemoryStream();
+ foreach (var field in fields)
+ foreach (var p in points)
+ for (int c = 0; c < field.Count; c++)
+ flat.Write(PcdFieldBytes(p, field, c));
+
+ byte[] uncompressed = flat.ToArray();
+ byte[] compressed = LzfCompress(uncompressed);
+
+ using var ms = new MemoryStream();
+ byte[] sizes = new byte[8];
+ BinaryPrimitives.WriteUInt32LittleEndian(sizes.AsSpan(0, 4), (uint)compressed.Length);
+ BinaryPrimitives.WriteUInt32LittleEndian(sizes.AsSpan(4, 4), (uint)uncompressed.Length);
+ ms.Write(sizes);
+ ms.Write(compressed);
+ return ms.ToArray();
+ }
+
+ private static double PcdFieldValue(PcdSamplePoint p, (string Name, int Size, char Type, int Count) field) => field.Name switch
+ {
+ "x" => p.X,
+ "y" => p.Y,
+ "z" => p.Z,
+ "intensity" => p.Intensity ?? 0,
+ "normal_x" => p.Normal?.X ?? 0,
+ "normal_y" => p.Normal?.Y ?? 0,
+ "normal_z" => p.Normal?.Z ?? 0,
+ _ => 0,
+ };
+
+ private static byte[] PcdFieldBytes(PcdSamplePoint p, (string Name, int Size, char Type, int Count) field, int index)
+ {
+ // Packed colour travels as its four bytes; other shapes hold no colour.
+ if (field.Name is "rgb" or "rgba")
+ {
+ uint bits = p.Color is { } c ? (uint)((c.R << 16) | (c.G << 8) | c.B) : 0xFFFFFF;
+ byte[] colour = new byte[field.Size];
+ if (field.Size >= 4) BinaryPrimitives.WriteUInt32LittleEndian(colour, bits);
+ return colour;
+ }
+
+ double value = index == 0 ? PcdFieldValue(p, field) : 0;
+ byte[] bytes = new byte[field.Size];
+ switch (field.Type)
+ {
+ case 'I':
+ long signed = (long)value;
+ for (int i = 0; i < field.Size; i++) bytes[i] = (byte)(signed >> (8 * i));
+ break;
+ case 'U':
+ ulong unsigned = (ulong)(long)value;
+ for (int i = 0; i < field.Size; i++) bytes[i] = (byte)(unsigned >> (8 * i));
+ break;
+ default:
+ if (field.Size == 4)
+ BinaryPrimitives.WriteSingleLittleEndian(bytes, (float)value);
+ else
+ BinaryPrimitives.WriteDoubleLittleEndian(bytes, value);
+ break;
+ }
+
+ return bytes;
+ }
+
+ /// Test-only LZF compressor for fixtures: greedy matches of at least 3 bytes in an 8 KiB window.
+ public static byte[] LzfCompress(byte[] input)
+ {
+ var output = new List(input.Length);
+ int i = 0;
+ int literals = 0;
+
+ void FlushLiterals(int from, int count)
+ {
+ while (count > 0)
+ {
+ int run = Math.Min(32, count);
+ output.Add((byte)(run - 1));
+ output.AddRange(input.AsSpan(from, run).ToArray());
+ from += run;
+ count -= run;
+ }
+ }
+
+ while (i < input.Length)
+ {
+ int bestLength = 0;
+ int bestOffset = 0;
+ int start = Math.Max(0, i - 8192);
+ for (int j = start; j < i; j++)
+ {
+ int length = 0;
+ while (length < 264 && i + length < input.Length && input[j + length] == input[i + length]) length++;
+ if (length >= 3 && length > bestLength)
+ {
+ bestLength = length;
+ bestOffset = i - j;
+ if (length == 264) break;
+ }
+ }
+
+ if (bestLength >= 3)
+ {
+ FlushLiterals(i - literals, literals);
+ literals = 0;
+ int coded = bestLength - 2;
+ output.Add((byte)((Math.Min(7, coded) << 5) | ((bestOffset - 1) >> 8)));
+ if (coded >= 7) output.Add((byte)(coded - 7));
+ output.Add((byte)((bestOffset - 1) & 0xFF));
+ i += bestLength;
+ }
+ else
+ {
+ literals++;
+ i++;
+ if (literals == 32)
+ {
+ FlushLiterals(i - literals, literals);
+ literals = 0;
+ }
+ }
+ }
+
+ FlushLiterals(i - literals, literals);
+ return [.. output];
+ }
}