From 54c83849c3c1db19b292979989bf049e5eb31da6 Mon Sep 17 00:00:00 2001
From: mahach666 <79989386+mahach666@users.noreply.github.com>
Date: Wed, 18 Nov 2026 16:24:34 +0000
Subject: [PATCH 1/4] Format: CC BIN (*.bin) (#37)
---
CHANGELOG.md | 1 +
README.md | 3 +-
docs/public-api.md | 6 +-
src/PclIO/Formats/CcBin/CcBinDocument.cs | 352 +++++++++++++++++++++++
src/PclIO/Formats/CcBin/CcBinScan.cs | 192 +++++++++++++
src/PclIO/Internal/KindDetector.cs | 13 +
src/PclIO/PclFile.cs | 2 +
src/PclIO/PclFileKind.cs | 3 +
tests/PclIO.Tests/FormatTests.cs | 177 +++++++++++-
tests/PclIO.Tests/KindDetectionTests.cs | 32 +++
tests/PclIO.Tests/RealFileTests.cs | 3 +
tests/PclIO.Tests/SyntheticFixtures.cs | 213 ++++++++++++++
12 files changed, 984 insertions(+), 13 deletions(-)
create mode 100644 src/PclIO/Formats/CcBin/CcBinDocument.cs
create mode 100644 src/PclIO/Formats/CcBin/CcBinScan.cs
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5c1d25b..297dbe4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
+- CC BIN (`*.bin`, `CCB2`) reader supporting single and multi-cloud entity datasets with 32-bit floating point Cartesian XYZ coordinates, global shift and scale vectors, 8-bit RGB colour arrays, 4x4 coordinate transform matrices, and scalar fields (including intensity). Added `CcBinDocument`, `CcBinScan`, and `PclFileKind.CcBin`.
- Leica PTG (`*.ptg`) gridded point cloud reader supporting binary scan files with `PTG\0` signature, magic number `0x928FA3C7`, ASCII metadata header (`NumRows`, `NumCols`, `%%properties`, `%%transform`), column offset array, and column validity bitmasks with single or double precision Cartesian XYZ coordinates, intensity and RGB colour. Top-level ASCII index files (`.ptg`) referencing binary scan files are aggregated into multi-scan documents. Added `PtgDocument`, `PtgScan`, and `PclFileKind.LeicaPtg`.
- Entwine Point Tile (EPT) reader supporting dataset manifests (`ept.json`), octree hierarchy traversal (`ept-hierarchy/`) with sub-hierarchy page resolution and cycle detection, and point data tile streaming (`ept-data/`) across `"laszip"`, `"binary"`, and `"zstandard"` compression formats. Added `EptDocument`, `EptScan`, `EptKey`, `EptNode`, and `EptDimension`, with spatial bounding box queries (`FindNodes`, `ReadPoints`) and schema-driven dimension extraction.
diff --git a/README.md b/README.md
index eac2670..2c61510 100644
--- a/README.md
+++ b/README.md
@@ -55,6 +55,7 @@ The library targets .NET 8 and .NET 10. It is managed code with no dependencies
| COPC | `.copc.laz`, `.laz` | Cloud Optimized Point Cloud (COPC octree in LAS 1.4 / LAZ): reads the octree hierarchy (root and sub-hierarchy pages) and voxel bounding boxes, center, halfsize and spacing metadata, streaming points by octree node, bounding box or across the whole dataset. LAS formats 0 to 3 are fully decompressed via LASzip arithmetic decoding; LAS 1.4 formats 6 to 8 decode uncompressed anchor points with exact positions, intensity, classification and RGB colour per octree node. |
| EPT | `ept.json`, `.laz`, `.bin`, `.zst` | Entwine Point Tile (EPT octree datasets): reads dataset manifest (`ept.json`), octree hierarchy (`ept-hierarchy/`), and point data tiles (`ept-data/`) across `"laszip"`, `"binary"`, and `"zstandard"` storage types. Supports schema dimension extraction (XYZ, intensity, classification, RGB colour, normals), spatial querying by bounding box (`FindNodes`, `ReadPoints`), depth filtering, and single-node streaming. |
| Leica PTG | `.ptg` | Leica Cyclone gridded binary exchange point clouds: binary scan files (`.ptg`) with 8-byte signature and magic (`0x928FA3C7`), ASCII metadata header (`NumRows`, `NumCols`, `%%properties`, `%%transform`), column offset array, and column validity bitmasks with single or double precision Cartesian XYZ coordinates, intensity [0..1] and 8-bit RGB colour. Top-level ASCII index files (`.ptg`) referencing binary scan files are aggregated into multi-scan documents. Coordinate transforms applied unless `ApplyTransform` is false. |
+| CC BIN | `.bin` | CC BIN binary entity files (`*.bin`, signature `CCB2`): single or multi-cloud datasets with 32-bit floating point Cartesian XYZ coordinates, global shift and scale vectors, 8-bit RGB colour arrays, 4x4 coordinate transform matrices, and scalar fields (including intensity). Coordinates are transformed by global shift and scale unless `ApplyTransform` is false. Points with non-finite coordinates are skipped. |
### Format detection
@@ -64,7 +65,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` and `.copc.laz`. A LAZ file is recognised by the `LASF` signature, a valid LASzip VLR and the `.laz` extension. A COPC file is recognised by the LAS 1.4 header and the `copc` info variable length record with `.copc.laz` or any extension. A PCD file is recognised by its header structure with any extension. A PLY file is recognised by its magic word and header structure with any extension. A PTS file is recognised by an integer point count header line followed by coordinate lines with any extension, or coordinate lines with the `.pts` extension. A PTX file is recognised by its 10-line header structure (grid dimensions, scanner pose, 4x4 matrix) with any extension. An XYZ / delimited text file is recognised by an explicit column header containing X, Y, Z in any extension, or by numeric coordinate lines with a recognised extension (`.xyz`, `.asc`, `.txt`, `.csv`). An SBF file is recognised by its companion `[SBF]` header structure with any extension, or by the binary signature `0x2A, 0x2A` (`**`) and record size formula (`.sbf`, `.sbf.data`, `.data`). A 3D Tiles `.pnts` tile is recognised by the `pnts` signature, version 1, and matching byte lengths. A glTF `.glb` point cloud is recognised by the `glTF` signature, version 2, and mesh primitive mode 0 (POINTS). A 3D Tiles tileset is recognised by JSON containing `asset` and `root` objects (`tileset.json`). A Potree dataset is recognised by `cloud.js` (with `octreeDir` and attribute descriptors) or `metadata.json` (version 2.x and point attributes) in `.js` or `.json`, by `.hrc` hierarchy files with 5-byte node records, or by ancestor `cloud.js`/`metadata.json` next to a `.bin` file. An EPT dataset is recognised by `ept.json` manifest structure (bounds, dataType, schema) or by companion `ept.json` next to octree tiles. A Leica PTG binary scan file is recognised by the `PTG\0` tag and magic number `0x928FA3C7` with any extension; a top-level ASCII index file is recognised by the `PTG index` header and the `.ptg` extension.
+ A LAS file is recognised by the `LASF` signature with any extension except `.laz` and `.copc.laz`. A LAZ file is recognised by the `LASF` signature, a valid LASzip VLR and the `.laz` extension. A COPC file is recognised by the LAS 1.4 header and the `copc` info variable length record with `.copc.laz` or any extension. A PCD file is recognised by its header structure with any extension. A PLY file is recognised by its magic word and header structure with any extension. A PTS file is recognised by an integer point count header line followed by coordinate lines with any extension, or coordinate lines with the `.pts` extension. A PTX file is recognised by its 10-line header structure (grid dimensions, scanner pose, 4x4 matrix) with any extension. An XYZ / delimited text file is recognised by an explicit column header containing X, Y, Z in any extension, or by numeric coordinate lines with a recognised extension (`.xyz`, `.asc`, `.txt`, `.csv`). An SBF file is recognised by its companion `[SBF]` header structure with any extension, or by the binary signature `0x2A, 0x2A` (`**`) and record size formula (`.sbf`, `.sbf.data`, `.data`). A 3D Tiles `.pnts` tile is recognised by the `pnts` signature, version 1, and matching byte lengths. A glTF `.glb` point cloud is recognised by the `glTF` signature, version 2, and mesh primitive mode 0 (POINTS). A 3D Tiles tileset is recognised by JSON containing `asset` and `root` objects (`tileset.json`). A Potree dataset is recognised by `cloud.js` (with `octreeDir` and attribute descriptors) or `metadata.json` (version 2.x and point attributes) in `.js` or `.json`, by `.hrc` hierarchy files with 5-byte node records, or by ancestor `cloud.js`/`metadata.json` next to a `.bin` file. An EPT dataset is recognised by `ept.json` manifest structure (bounds, dataType, schema) or by companion `ept.json` next to octree tiles. A Leica PTG binary scan file is recognised by the `PTG\0` tag and magic number `0x928FA3C7` with any extension; a top-level ASCII index file is recognised by the `PTG index` header and the `.ptg` extension. A CC BIN file is recognised by the `CCB2` signature with any extension; a `.bin` file without this signature is reported as Potree when inside an octree folder or unknown.
- 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
diff --git a/docs/public-api.md b/docs/public-api.md
index 3cbbebb..076cdd2 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`, `Las`, `Pcd`, `Ply`, `Pts`, `Ptx`, `Xyz`, `Sbf`, `Tiles3d`, `Potree`, `Laz`, `Copc`, `Ept` and `LeicaPtg`. |
+| `PclFileKind` | `Unknown`, `E57`, `RecapProject`, `RecapScan`, `LeicaLgsx`, `LeicaLgs`, `FaroFls`, `PinPoint`, `EdgeWise`, `Las`, `Pcd`, `Ply`, `Pts`, `Ptx`, `Xyz`, `Sbf`, `Tiles3d`, `Potree`, `Laz`, `Copc`, `Ept`, `LeicaPtg` and `CcBin`. |
| `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), `ExcludeFilteredPoints` (default false: points the file marks as filtered are excluded; currently the `FilterBits` channel of the PinPoint sectioned layout), `TextColumns` (explicit column names or layout for delimited text point clouds), `TextDelimiter` (explicit delimiter character for delimited text), `TextCommentPrefix` (prefix for comment lines in delimited text, default `#`) and `TextCoordinateScale` (coordinate scale factor for delimited text, default 1.0). Negative `MaxPoints`, a negative magnitude limit, a negative block start or count, a non-positive or non-finite EdgeWise scale or text coordinate 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). |
@@ -45,6 +45,7 @@ is the argument, which may also be a file name.
`Potree` is recognised by `cloud.js` (with `octreeDir` and attribute descriptors) or `metadata.json` (version 2.x and point attributes) in `.js` or `.json`, by `.hrc` hierarchy files with 5-byte node records, or by ancestor `cloud.js`/`metadata.json` next to a `.bin` file.
`Ept` is recognised by `ept.json` manifest structure (bounds, dataType, schema) or by companion `ept.json` next to octree tiles.
`LeicaPtg` is recognised by the `PTG\0` tag and magic number `0x928FA3C7` with any extension, or by the `PTG index` header with the `.ptg` extension.
+ `CcBin` is recognised by the `CCB2` signature with any extension; a `.bin` file without this signature is reported as `Potree` when inside an octree folder or `Unknown`.
- `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
@@ -93,6 +94,7 @@ drop points that fail a plausibility rule (see the README), so a scan can yield
| COPC | The header count (the extended 1.4 count when it states one). It is not checked against the chunk data until read. |
| EPT | The point count declared in the manifest, or the sum of points across discovered octree nodes. |
| Leica PTG | Total valid returns across all gridded scans, determined by decoding the column validity bitmasks. |
+| CC BIN | The point count declared for the entity. Points with non-finite coordinates are skipped. |
`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
@@ -102,7 +104,7 @@ no colour.
## Format documents
`E57Document`/`E57Scan`, `RcsScanDocument`/`RcsScan`, `RcpProjectDocument`/`RcpScan`, `LgsxDocument`/`LgsxScan`/`LgsxEntry`/`LgsxSetup`,
-`FaroFlsDocument`/`FaroScan`, `PinPointDocument`/`PinPointScan`, `EdgeWiseDocument`/`EdgeWiseScan`, `LasDocument`/`LasScan`, `LazDocument`/`LazScan`, `CopcDocument`/`CopcScan`, `PcdDocument`/`PcdScan`, `PlyDocument`/`PlyScan`, `PtsDocument`/`PtsScan`, `PtxDocument`/`PtxScan`, `XyzDocument`/`XyzScan`, `SbfDocument`/`SbfScan`, `Tiles3dDocument`/`PntsScan`/`GlbScan`, `PotreeDocument`/`PotreeScan`, `EptDocument`/`EptScan` and `PtgDocument`/`PtgScan` are the readers behind
+`FaroFlsDocument`/`FaroScan`, `PinPointDocument`/`PinPointScan`, `EdgeWiseDocument`/`EdgeWiseScan`, `LasDocument`/`LasScan`, `LazDocument`/`LazScan`, `CopcDocument`/`CopcScan`, `PcdDocument`/`PcdScan`, `PlyDocument`/`PlyScan`, `PtsDocument`/`PtsScan`, `PtxDocument`/`PtxScan`, `XyzDocument`/`XyzScan`, `SbfDocument`/`SbfScan`, `Tiles3dDocument`/`PntsScan`/`GlbScan`, `PotreeDocument`/`PotreeScan`, `EptDocument`/`EptScan`, `PtgDocument`/`PtgScan` and `CcBinDocument`/`CcBinScan` 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/Formats/CcBin/CcBinDocument.cs b/src/PclIO/Formats/CcBin/CcBinDocument.cs
new file mode 100644
index 0000000..850ed76
--- /dev/null
+++ b/src/PclIO/Formats/CcBin/CcBinDocument.cs
@@ -0,0 +1,352 @@
+using System.Buffers.Binary;
+using System.Globalization;
+using System.Text;
+using PclIO.Internal;
+
+namespace PclIO.Formats.CcBin;
+
+/// Represents a CC BIN point cloud file (.bin, CCB2).
+public sealed class CcBinDocument : PclDocument
+{
+ private static readonly byte[] Magic = "CCB2"u8.ToArray();
+
+ ///
+ public override PclFileKind Kind => PclFileKind.CcBin;
+
+ ///
+ public override IReadOnlyList Scans => _scans;
+ private readonly List _scans = [];
+
+ /// Format version declared in the file header.
+ public uint Version { get; }
+
+ private CcBinDocument(string path, long fileSize, uint version)
+ : base(path, fileSize)
+ {
+ Version = version;
+ }
+
+ /// Opens a CC BIN point cloud file.
+ /// Path to the .bin file.
+ /// Read options (accepted for symmetry).
+ /// The file does not exist.
+ /// The file signature, version or entity layout is corrupted or truncated.
+ public static CcBinDocument Open(string path, PclReadOptions? options = null)
+ {
+ var fi = new FileInfo(path);
+ if (!fi.Exists) throw new FileNotFoundException("CC BIN file not found.", path);
+ long fileLength = fi.Length;
+ if (fileLength < 8)
+ throw FormatError.Truncated("CC BIN file header is smaller than 8 bytes.");
+
+ using var fs = File.OpenRead(path);
+ byte[] head = new byte[8];
+ fs.ReadExactly(head);
+
+ if (!head.AsSpan(0, 4).SequenceEqual(Magic))
+ throw FormatError.Corrupted($"Invalid CC BIN signature in '{path}'; expected 'CCB2'.");
+
+ uint version = BinaryPrimitives.ReadUInt32LittleEndian(head.AsSpan(4, 4));
+ if (version is < 20 or > 2000)
+ throw FormatError.Corrupted($"Unsupported or invalid CC BIN format version {version} in '{path}'.");
+
+ var doc = new CcBinDocument(path, fileLength, version);
+ doc.ScanPointClouds(fs, fileLength);
+
+ if (doc._scans.Count == 0)
+ throw FormatError.Corrupted($"CC BIN file '{path}' contains no recognizable point cloud entities.");
+
+ doc._metadata["Format"] = "CC BIN";
+ doc._metadata["Version"] = version.ToString(CultureInfo.InvariantCulture);
+ doc._metadata["Scans"] = doc._scans.Count.ToString(CultureInfo.InvariantCulture);
+ doc._metadata["TotalPoints"] = doc.TotalPointCount.ToString(CultureInfo.InvariantCulture);
+
+ return doc;
+ }
+
+ private void ScanPointClouds(FileStream fs, long fileLength)
+ {
+ const int BlockSize = 65536;
+ byte[] buffer = new byte[BlockSize + 512];
+ long streamPos = 8;
+
+ while (streamPos < fileLength)
+ {
+ int toRead = (int)Math.Min(BlockSize + 512, fileLength - streamPos);
+ fs.Position = streamPos;
+ int bytesRead = fs.Read(buffer, 0, toRead);
+ if (bytesRead < 44) break;
+
+ int scanLimit = bytesRead - 44;
+ for (int i = 0; i <= scanLimit; i++)
+ {
+ // Entity type f1 == 257 (0x01, 0x01, 0x00, 0x00) and f2 == 0 (0x00, 0x00, 0x00, 0x00)
+ if (buffer[i] == 0x01 && buffer[i + 1] == 0x01 && buffer[i + 2] == 0x00 && buffer[i + 3] == 0x00 &&
+ buffer[i + 4] == 0x00 && buffer[i + 5] == 0x00 && buffer[i + 6] == 0x00 && buffer[i + 7] == 0x00)
+ {
+ long entityPos = streamPos + i;
+ if (TryParsePointCloud(fs, fileLength, entityPos, _scans.Count, out var scan, out long nextOffset))
+ {
+ _scans.Add(scan);
+ streamPos = Math.Max(streamPos, nextOffset);
+ break;
+ }
+ }
+ }
+
+ streamPos += BlockSize;
+ }
+ }
+
+ private bool TryParsePointCloud(
+ FileStream fs,
+ long fileLength,
+ long entityPos,
+ int scanIndex,
+ out CcBinScan scan,
+ out long pointsEndOffset)
+ {
+ scan = default!;
+ pointsEndOffset = entityPos + 8;
+ if (entityPos + 24 > fileLength) return false;
+
+ fs.Position = entityPos + 8;
+ byte[] h = new byte[8];
+ if (fs.Read(h) < 8) return false;
+ uint id = BinaryPrimitives.ReadUInt32LittleEndian(h.AsSpan(0, 4));
+ uint nameByteLen = BinaryPrimitives.ReadUInt32BigEndian(h.AsSpan(4, 4));
+ if (nameByteLen is 0 or > 2000 || fs.Position + nameByteLen > fileLength) return false;
+
+ byte[] nameBytes = new byte[nameByteLen];
+ if (fs.Read(nameBytes) < (int)nameByteLen) return false;
+ string name = Encoding.BigEndianUnicode.GetString(nameBytes);
+
+ // QVariantMap properties
+ byte[] mapHead = new byte[8];
+ if (fs.Read(mapHead) < 8) return false;
+ uint mapType = BinaryPrimitives.ReadUInt32LittleEndian(mapHead.AsSpan(0, 4));
+ uint propCount = BinaryPrimitives.ReadUInt32LittleEndian(mapHead.AsSpan(4, 4));
+ if (mapType != 2 || propCount > 1000) return false;
+
+ var props = new Dictionary(StringComparer.OrdinalIgnoreCase);
+ byte[] kLenBuf = new byte[4];
+ byte[] vHead = new byte[5];
+ byte[] sLenBuf = new byte[4];
+
+ for (uint p = 0; p < propCount; p++)
+ {
+ if (fs.Read(kLenBuf) < 4) return false;
+ uint kLen = BinaryPrimitives.ReadUInt32BigEndian(kLenBuf);
+ if (kLen > 1000 || fs.Position + kLen > fileLength) return false;
+
+ byte[] kBytes = new byte[kLen];
+ if (fs.Read(kBytes) < (int)kLen) return false;
+ string key = Encoding.BigEndianUnicode.GetString(kBytes);
+
+ if (fs.Read(vHead) < 5) return false;
+ uint vType = BinaryPrimitives.ReadUInt32BigEndian(vHead.AsSpan(0, 4));
+ byte isNull = vHead[4];
+
+ if (vType == 6) // double
+ {
+ byte[] dBuf = new byte[8];
+ if (fs.Read(dBuf) < 8) return false;
+ if (isNull == 0)
+ {
+ double dVal = BitConverter.UInt64BitsToDouble(BinaryPrimitives.ReadUInt64BigEndian(dBuf));
+ props[key] = dVal.ToString(CultureInfo.InvariantCulture);
+ }
+ }
+ else if (vType is 2 or 3) // int / uint
+ {
+ byte[] iBuf = new byte[4];
+ if (fs.Read(iBuf) < 4) return false;
+ if (isNull == 0)
+ {
+ int iVal = BinaryPrimitives.ReadInt32BigEndian(iBuf);
+ props[key] = iVal.ToString(CultureInfo.InvariantCulture);
+ }
+ }
+ else if (vType == 1) // bool
+ {
+ int bVal = fs.ReadByte();
+ if (bVal < 0) return false;
+ if (isNull == 0)
+ {
+ props[key] = bVal != 0 ? "true" : "false";
+ }
+ }
+ else if (vType == 10) // string
+ {
+ if (fs.Read(sLenBuf) < 4) return false;
+ uint sLen = BinaryPrimitives.ReadUInt32BigEndian(sLenBuf);
+ if (sLen > 2000 || fs.Position + sLen > fileLength) return false;
+ byte[] sBytes = new byte[sLen];
+ if (fs.Read(sBytes) < (int)sLen) return false;
+ if (isNull == 0)
+ {
+ props[key] = Encoding.BigEndianUnicode.GetString(sBytes);
+ }
+ }
+ else
+ {
+ return false;
+ }
+ }
+
+ // 43 bytes: flags (8), shift (24), scale (8), marker (3)
+ byte[] ccHead = new byte[43];
+ if (fs.Read(ccHead) < 43) return false;
+
+ double sx = BinaryPrimitives.ReadDoubleLittleEndian(ccHead.AsSpan(8, 8));
+ double sy = BinaryPrimitives.ReadDoubleLittleEndian(ccHead.AsSpan(16, 8));
+ double sz = BinaryPrimitives.ReadDoubleLittleEndian(ccHead.AsSpan(24, 8));
+ double scale = BinaryPrimitives.ReadDoubleLittleEndian(ccHead.AsSpan(32, 8));
+ if (scale == 0 || !double.IsFinite(scale)) scale = 1.0;
+
+ byte[] countBuf = new byte[4];
+ if (fs.Read(countBuf) < 4) return false;
+ uint count = BinaryPrimitives.ReadUInt32LittleEndian(countBuf);
+ if (count == 0) return false;
+
+ long ptStart = fs.Position;
+ long ptBytes = (long)count * 12;
+ if (ptStart + ptBytes > fileLength) return false;
+
+ pointsEndOffset = ptStart + ptBytes;
+
+ // Check for colors right after points
+ fs.Position = pointsEndOffset;
+ int colorFlag = fs.ReadByte();
+ bool hasColors = false;
+ long colorOffset = -1;
+ byte channels = 3;
+
+ if (colorFlag == 1)
+ {
+ byte[] colH = new byte[16];
+ if (fs.Read(colH) == 16)
+ {
+ uint colNameLen = BinaryPrimitives.ReadUInt32BigEndian(colH.AsSpan(12, 4));
+ if (colNameLen < 500 && fs.Position + colNameLen + 9 <= fileLength)
+ {
+ fs.Position += colNameLen;
+ byte[] colProps = new byte[9];
+ if (fs.Read(colProps) == 9)
+ {
+ channels = colProps[8];
+ byte[] colCountBuf = new byte[4];
+ if (fs.Read(colCountBuf) == 4)
+ {
+ uint colCount = BinaryPrimitives.ReadUInt32LittleEndian(colCountBuf);
+ if (colCount == count && (channels is 3 or 4))
+ {
+ long cOffset = fs.Position;
+ long cBytes = (long)colCount * channels;
+ if (cOffset + cBytes <= fileLength)
+ {
+ hasColors = true;
+ colorOffset = cOffset;
+ fs.Position += cBytes;
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+
+ // Matrix 4x4
+ var matrix16 = new double[16];
+ bool isIdentity = true;
+ byte[] matH = new byte[8 + 64];
+ if (fs.Read(matH) == 72)
+ {
+ for (int m = 0; m < 16; m++)
+ {
+ float val = BinaryPrimitives.ReadSingleLittleEndian(matH.AsSpan(8 + m * 4, 4));
+ matrix16[m] = val;
+ int row = m / 4;
+ int col = m % 4;
+ double expected = row == col ? 1.0 : 0.0;
+ if (Math.Abs(val - expected) > 1e-6)
+ {
+ isIdentity = false;
+ }
+ }
+ }
+
+ // Scalar fields (probe for Intensity)
+ bool hasIntensity = false;
+ long intensityOffset = -1;
+ int sfFlag = fs.ReadByte();
+ if (sfFlag >= 0)
+ {
+ byte[] sfCountBuf = new byte[4];
+ if (fs.Read(sfCountBuf) == 4)
+ {
+ uint sfCount = BinaryPrimitives.ReadUInt32LittleEndian(sfCountBuf);
+ if (sfCount is > 0 and < 100)
+ {
+ byte[] sfNameBuf = new byte[256];
+ byte[] sCountBuf = new byte[4];
+ for (int s = 0; s < sfCount; s++)
+ {
+ if (fs.Position + 256 + 5 > fileLength) break;
+ if (fs.Read(sfNameBuf) < 256) break;
+ string sfName = Encoding.ASCII.GetString(sfNameBuf).TrimEnd('\0');
+ int sFlag = fs.ReadByte();
+ if (sFlag < 0 || fs.Read(sCountBuf) < 4) break;
+ uint sCount = BinaryPrimitives.ReadUInt32LittleEndian(sCountBuf);
+ long dataOffset = fs.Position;
+ long sBytes = (long)sCount * 4;
+ if (dataOffset + sBytes > fileLength) break;
+
+ if (!hasIntensity && sfName.Equals("Intensity", StringComparison.OrdinalIgnoreCase))
+ {
+ hasIntensity = true;
+ intensityOffset = dataOffset;
+ }
+
+ fs.Position += sBytes;
+ if (s + 1 < sfCount)
+ {
+ fs.Position += 219; // Skip color scale / metadata
+ }
+ }
+ }
+ }
+ }
+
+ // Construct transform:
+ // P_global = (P_local - Shift) * Scale
+ // In PclTransform: P_transformed = P_local * Scale + Translation
+ var transform = new PclTransform
+ {
+ Scale = new PclVector3(scale, scale, scale),
+ Translation = new PclVector3(-sx * scale, -sy * scale, -sz * scale),
+ Matrix4x4 = isIdentity ? null : matrix16,
+ };
+
+ string scanId = scanIndex.ToString(CultureInfo.InvariantCulture);
+ scan = new CcBinScan(
+ filePath: fs.Name,
+ id: scanId,
+ name: name,
+ pointCount: count,
+ pointOffset: ptStart,
+ hasColors: hasColors,
+ colorOffset: colorOffset,
+ colorChannels: channels,
+ hasIntensity: hasIntensity,
+ intensityOffset: intensityOffset,
+ shiftX: sx,
+ shiftY: sy,
+ shiftZ: sz,
+ scale: scale,
+ transform: transform,
+ properties: props);
+
+ return true;
+ }
+}
diff --git a/src/PclIO/Formats/CcBin/CcBinScan.cs b/src/PclIO/Formats/CcBin/CcBinScan.cs
new file mode 100644
index 0000000..23cea84
--- /dev/null
+++ b/src/PclIO/Formats/CcBin/CcBinScan.cs
@@ -0,0 +1,192 @@
+using System.Buffers.Binary;
+using System.Globalization;
+using PclIO.Internal;
+
+namespace PclIO.Formats.CcBin;
+
+/// Represents a point cloud entity inside a CC BIN file.
+public sealed class CcBinScan : PclScan
+{
+ private const int BatchRecords = 1024;
+
+ private readonly string _filePath;
+ private readonly long _pointOffset;
+ private readonly long _pointCount;
+ private readonly bool _hasColors;
+ private readonly long _colorOffset;
+ private readonly byte _colorChannels;
+ private readonly bool _hasIntensity;
+ private readonly long _intensityOffset;
+ private readonly double _shiftX;
+ private readonly double _shiftY;
+ private readonly double _shiftZ;
+ private readonly double _scale;
+
+ ///
+ public override string Id { get; }
+
+ ///
+ public override string Name { get; }
+
+ ///
+ public override long PointCount => _pointCount;
+
+ ///
+ public override bool HasColors => _hasColors;
+
+ ///
+ public override bool HasIntensities => _hasIntensity;
+
+ /// Global shift vector stored with the cloud entity.
+ public PclVector3 GlobalShift => new(_shiftX, _shiftY, _shiftZ);
+
+ /// Global scale factor stored with the cloud entity.
+ public double GlobalScale => _scale;
+
+ internal CcBinScan(
+ string filePath,
+ string id,
+ string name,
+ long pointCount,
+ long pointOffset,
+ bool hasColors,
+ long colorOffset,
+ byte colorChannels,
+ bool hasIntensity,
+ long intensityOffset,
+ double shiftX,
+ double shiftY,
+ double shiftZ,
+ double scale,
+ PclTransform transform,
+ IReadOnlyDictionary? properties = null)
+ {
+ _filePath = filePath;
+ Id = id;
+ Name = name;
+ _pointCount = pointCount;
+ _pointOffset = pointOffset;
+ _hasColors = hasColors;
+ _colorOffset = colorOffset;
+ _colorChannels = colorChannels;
+ _hasIntensity = hasIntensity;
+ _intensityOffset = intensityOffset;
+ _shiftX = shiftX;
+ _shiftY = shiftY;
+ _shiftZ = shiftZ;
+ _scale = scale;
+ Transform = transform;
+
+ _properties["TotalPoints"] = pointCount.ToString(CultureInfo.InvariantCulture);
+ _properties["HasColors"] = hasColors ? "true" : "false";
+ _properties["HasIntensity"] = hasIntensity ? "true" : "false";
+ _properties["GlobalShift"] = string.Create(CultureInfo.InvariantCulture, $"{shiftX:F6}, {shiftY:F6}, {shiftZ:F6}");
+ _properties["GlobalScale"] = scale.ToString(CultureInfo.InvariantCulture);
+
+ if (properties != null)
+ {
+ foreach (var kvp in properties)
+ {
+ _properties[kvp.Key] = kvp.Value;
+ }
+ }
+ }
+
+ ///
+ public override IEnumerable ReadPoints(PclReadOptions? options = null)
+ {
+ options ??= PclReadOptions.Default;
+ long targetCount = options.MaxPoints ?? _pointCount;
+ if (targetCount <= 0 || _pointCount == 0) yield break;
+ targetCount = Math.Min(targetCount, _pointCount);
+ int step = Math.Max(1, options.SubsampleStep);
+
+ using var fs = File.OpenRead(_filePath);
+
+ byte[] ptBuf = new byte[BatchRecords * 12];
+ byte[]? colBuf = _hasColors ? new byte[BatchRecords * _colorChannels] : null;
+ byte[]? intBuf = _hasIntensity ? new byte[BatchRecords * 4] : null;
+
+ long yielded = 0;
+ long pointIndex = 0;
+ long pointsRemaining = _pointCount;
+
+ while (pointsRemaining > 0 && yielded < targetCount)
+ {
+ int toRead = (int)Math.Min(BatchRecords, pointsRemaining);
+ int ptBytesToRead = toRead * 12;
+
+ fs.Position = _pointOffset + (pointIndex * 12);
+ int ptRead = fs.ReadAtLeast(ptBuf.AsSpan(0, ptBytesToRead), ptBytesToRead, throwOnEndOfStream: false);
+ if (ptRead < ptBytesToRead)
+ throw FormatError.Truncated($"CC BIN file ended prematurely while reading point coordinates at index {pointIndex}.");
+
+ if (_hasColors && colBuf != null)
+ {
+ int colBytesToRead = toRead * _colorChannels;
+ fs.Position = _colorOffset + (pointIndex * _colorChannels);
+ int colRead = fs.ReadAtLeast(colBuf.AsSpan(0, colBytesToRead), colBytesToRead, throwOnEndOfStream: false);
+ if (colRead < colBytesToRead)
+ throw FormatError.Truncated($"CC BIN file ended prematurely while reading colors at index {pointIndex}.");
+ }
+
+ if (_hasIntensity && intBuf != null)
+ {
+ int intBytesToRead = toRead * 4;
+ fs.Position = _intensityOffset + (pointIndex * 4);
+ int intRead = fs.ReadAtLeast(intBuf.AsSpan(0, intBytesToRead), intBytesToRead, throwOnEndOfStream: false);
+ if (intRead < intBytesToRead)
+ throw FormatError.Truncated($"CC BIN file ended prematurely while reading intensity at index {pointIndex}.");
+ }
+
+ for (int p = 0; p < toRead; p++)
+ {
+ long currentIdx = pointIndex + p;
+ if ((currentIdx % step) != 0) continue;
+
+ int ptByteOffset = p * 12;
+ float lx = BinaryPrimitives.ReadSingleLittleEndian(ptBuf.AsSpan(ptByteOffset, 4));
+ float ly = BinaryPrimitives.ReadSingleLittleEndian(ptBuf.AsSpan(ptByteOffset + 4, 4));
+ float lz = BinaryPrimitives.ReadSingleLittleEndian(ptBuf.AsSpan(ptByteOffset + 8, 4));
+
+ if (!float.IsFinite(lx) || !float.IsFinite(ly) || !float.IsFinite(lz))
+ continue;
+
+ PclColor? color = null;
+ if (_hasColors && colBuf != null)
+ {
+ int colByteOffset = p * _colorChannels;
+ byte r = colBuf[colByteOffset];
+ byte g = colBuf[colByteOffset + 1];
+ byte b = colBuf[colByteOffset + 2];
+ byte a = _colorChannels >= 4 ? colBuf[colByteOffset + 3] : (byte)255;
+ color = new PclColor(r, g, b, a);
+ }
+
+ float? intensity = null;
+ if (_hasIntensity && intBuf != null)
+ {
+ int intByteOffset = p * 4;
+ float iVal = BinaryPrimitives.ReadSingleLittleEndian(intBuf.AsSpan(intByteOffset, 4));
+ if (float.IsFinite(iVal))
+ {
+ intensity = iVal;
+ }
+ }
+
+ PclVector3 pos = new(lx, ly, lz);
+ if (options.ApplyTransform && !Transform.IsIdentity)
+ {
+ pos = Transform.TransformPoint(pos);
+ }
+
+ yield return new PclPoint(pos, Color: color, Intensity: intensity, Index: (ulong)yielded);
+ yielded++;
+ if (yielded >= targetCount) yield break;
+ }
+
+ pointIndex += toRead;
+ pointsRemaining -= toRead;
+ }
+ }
+}
diff --git a/src/PclIO/Internal/KindDetector.cs b/src/PclIO/Internal/KindDetector.cs
index 1b645a7..e277daf 100644
--- a/src/PclIO/Internal/KindDetector.cs
+++ b/src/PclIO/Internal/KindDetector.cs
@@ -28,6 +28,8 @@ internal static class KindDetector
// Leica PTG binary scan signature and magic number.
private static readonly byte[] PtgTag = [0x50, 0x54, 0x47, 0x00];
private const uint PtgMagicNumber = 0x928FA3C7;
+ // CC BIN entity file signature (CCB2).
+ private static readonly byte[] CcBinMagic = "CCB2"u8.ToArray();
public static PclFileKind Detect(string path)
{
@@ -81,6 +83,14 @@ public static PclFileKind Detect(string path)
: Path.GetExtension(path).ToLowerInvariant();
if (ext == ".bin")
{
+ using (var probeStream = File.OpenRead(path))
+ {
+ Span probeHead = stackalloc byte[4];
+ int probeRead = probeStream.ReadAtLeast(probeHead, 4, throwOnEndOfStream: false);
+ if (probeRead >= 4 && probeHead.StartsWith(CcBinMagic))
+ return PclFileKind.CcBin;
+ }
+
string? dir = Path.GetDirectoryName(Path.GetFullPath(path));
for (int depth = 0; depth < 5 && dir != null; depth++)
{
@@ -122,6 +132,9 @@ public static PclFileKind Detect(Stream stream, string? extension = null)
if (read < 4) return extension is ".c3db" or ".c3ptx" ? PclFileKind.EdgeWise : PclFileKind.Unknown;
ReadOnlySpan head = buffer[..read];
+ if (head.StartsWith(CcBinMagic))
+ return PclFileKind.CcBin;
+
if (head.Length >= 8 && head.StartsWith(PtgTag) && BinaryPrimitives.ReadUInt32LittleEndian(head[4..8]) == PtgMagicNumber)
return PclFileKind.LeicaPtg;
diff --git a/src/PclIO/PclFile.cs b/src/PclIO/PclFile.cs
index 387986c..299ef99 100644
--- a/src/PclIO/PclFile.cs
+++ b/src/PclIO/PclFile.cs
@@ -1,3 +1,4 @@
+using PclIO.Formats.CcBin;
using PclIO.Formats.Copc;
using PclIO.Formats.E57;
using PclIO.Formats.EdgeWise;
@@ -74,6 +75,7 @@ public static PclDocument Open(string path, PclReadOptions? options = null)
PclFileKind.Copc => CopcDocument.Open(path, options),
PclFileKind.Ept => EptDocument.Open(path, options),
PclFileKind.LeicaPtg => PtgDocument.Open(path, options),
+ PclFileKind.CcBin => CcBinDocument.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 4133ee9..328a827 100644
--- a/src/PclIO/PclFileKind.cs
+++ b/src/PclIO/PclFileKind.cs
@@ -68,4 +68,7 @@ public enum PclFileKind
/// Leica gridded point cloud (.ptg).
LeicaPtg = 21,
+
+ /// CC BIN point cloud entity file (.bin, CCB2).
+ CcBin = 22,
}
diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs
index 5049945..315ae98 100644
--- a/tests/PclIO.Tests/FormatTests.cs
+++ b/tests/PclIO.Tests/FormatTests.cs
@@ -1,4 +1,5 @@
using PclIO.Export;
+using PclIO.Formats.CcBin;
using PclIO.Formats.Copc;
using PclIO.Formats.E57;
using PclIO.Formats.EdgeWise;
@@ -604,7 +605,7 @@ public void E57_With_A_Partial_Scaled_Integer_Record_Is_Rejected()
using var dir = new TempDirectory();
using var doc = E57Document.Open(dir.Write("partial.e57", spec.Build()));
- Assert.Throws(() => doc.Scans[0].ReadPoints().ToList());
+ Assert.Throws(() => { _ = doc.Scans[0].ReadPoints().ToList(); });
}
[Fact]
@@ -714,7 +715,7 @@ public void E57_With_A_Partial_Spherical_Record_Is_Rejected()
using var dir = new TempDirectory();
using var doc = E57Document.Open(dir.Write("partial.e57", spec.Build()));
- Assert.Throws(() => doc.Scans[0].ReadPoints().ToList());
+ Assert.Throws(() => { _ = doc.Scans[0].ReadPoints().ToList(); });
}
[Fact]
@@ -979,7 +980,7 @@ public void E57_With_A_Partial_Colour_Record_Is_Rejected()
using var dir = new TempDirectory();
using var doc = E57Document.Open(dir.Write("partial.e57", spec.Build()));
- Assert.Throws(() => doc.Scans[0].ReadPoints().ToList());
+ Assert.Throws(() => { _ = doc.Scans[0].ReadPoints().ToList(); });
}
[Fact]
@@ -2424,7 +2425,7 @@ public void Las_With_A_Huge_Declared_Count_Fails_Cleanly_When_Read()
using var doc = LasDocument.Open(dir.Write("sample.las", bytes));
Assert.Equal(uint.MaxValue, doc.Scans[0].PointCount);
- Assert.Throws(() => doc.Scans[0].ReadPoints().ToList());
+ Assert.Throws(() => { _ = doc.Scans[0].ReadPoints().ToList(); });
}
[Fact]
@@ -2487,7 +2488,7 @@ public void Las_Truncated_Points_Are_Rejected_When_Read()
using var doc = LasDocument.Open(dir.Write("cut.las", cut));
Assert.Equal(3, doc.Scans[0].PointCount);
- Assert.Throws(() => doc.Scans[0].ReadPoints().ToList());
+ Assert.Throws(() => { _ = doc.Scans[0].ReadPoints().ToList(); });
}
[Fact]
@@ -2736,7 +2737,7 @@ public void Pcd_Truncated_Ascii_Point_Data_Is_Rejected_When_Read()
using var doc = PcdDocument.Open(dir.Write("cut.pcd", cut));
Assert.Equal(3, doc.Scans[0].PointCount);
- Assert.Throws(() => doc.Scans[0].ReadPoints().ToList());
+ Assert.Throws(() => { _ = doc.Scans[0].ReadPoints().ToList(); });
}
[Theory]
@@ -2763,7 +2764,7 @@ public void Pcd_Corrupt_Lzf_Is_Rejected_When_Read()
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());
+ Assert.Throws(() => { _ = doc.Scans[0].ReadPoints().ToList(); });
}
[Fact]
@@ -2890,7 +2891,7 @@ public void Pcd_Overlong_Ascii_Line_Is_Rejected()
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());
+ Assert.Throws(() => { _ = doc.Scans[0].ReadPoints().ToList(); });
}
[Fact]
@@ -3117,7 +3118,7 @@ public void Ply_Truncated_Vertex_Data_Is_Rejected_When_Read(string format)
using var doc = PlyDocument.Open(dir.Write("cut.ply", bytes[..(bytes.Length - 5)]));
Assert.Equal(3, doc.Scans[0].PointCount);
- Assert.Throws(() => doc.Scans[0].ReadPoints().ToList());
+ Assert.Throws(() => { _ = doc.Scans[0].ReadPoints().ToList(); });
}
[Fact]
@@ -3137,7 +3138,7 @@ public void Ply_Vertex_Line_With_The_Wrong_Value_Count_Is_Rejected()
], []);
using var doc = PlyDocument.Open(dir.Write("sample.ply", bytes));
- Assert.Throws(() => doc.Scans[0].ReadPoints().ToList());
+ Assert.Throws(() => { _ = doc.Scans[0].ReadPoints().ToList(); });
}
[Fact]
@@ -6335,4 +6336,160 @@ public void Ptg_Index_Rejects_Empty_References_Or_Missing_Files()
string missingPath = dir.Write("missing_ref.ptg", missingScanIdx);
Assert.Throws(() => PtgDocument.Open(missingPath));
}
+
+ // ---- CC BIN (.bin) ------------------------------------------------------------------------------------------
+
+ [Fact]
+ public void Cc_Bin_Reads_Points_Coordinates_Colors_And_Intensity()
+ {
+ using var dir = new TempDirectory();
+ var samplePoints = new List
+ {
+ new(1.0, 2.0, 3.0, new PclColor(255, 0, 0), 10.5f),
+ new(4.0, 5.0, 6.0, new PclColor(0, 255, 0), 20.0f),
+ new(7.0, 8.0, 9.0, new PclColor(0, 0, 255), 30.25f),
+ };
+
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin(samplePoints, name: "TestCloud");
+ string path = dir.Write("test.bin", bytes);
+
+ using var doc = CcBinDocument.Open(path);
+ Assert.Equal(PclFileKind.CcBin, doc.Kind);
+ Assert.Single(doc.Scans);
+
+ var scan = doc.Scans[0];
+ Assert.Equal("TestCloud", scan.Name);
+ Assert.Equal(3, scan.PointCount);
+ Assert.True(scan.HasColors);
+ Assert.True(scan.HasIntensities);
+
+ var points = scan.ReadPoints().ToList();
+ Assert.Equal(3, points.Count);
+
+ Assert.Equal(1.0, points[0].X, precision: 4);
+ Assert.Equal(2.0, points[0].Y, precision: 4);
+ Assert.Equal(3.0, points[0].Z, precision: 4);
+ Assert.Equal(new PclColor(255, 0, 0), points[0].Color);
+ Assert.Equal(10.5f, points[0].Intensity);
+ Assert.Equal(0UL, points[0].Index);
+
+ Assert.Equal(4.0, points[1].X, precision: 4);
+ Assert.Equal(5.0, points[1].Y, precision: 4);
+ Assert.Equal(6.0, points[1].Z, precision: 4);
+ Assert.Equal(new PclColor(0, 255, 0), points[1].Color);
+ Assert.Equal(20.0f, points[1].Intensity);
+ Assert.Equal(1UL, points[1].Index);
+
+ Assert.Equal(7.0, points[2].X, precision: 4);
+ Assert.Equal(8.0, points[2].Y, precision: 4);
+ Assert.Equal(9.0, points[2].Z, precision: 4);
+ Assert.Equal(new PclColor(0, 0, 255), points[2].Color);
+ Assert.Equal(30.25f, points[2].Intensity);
+ Assert.Equal(2UL, points[2].Index);
+ }
+
+ [Fact]
+ public void Cc_Bin_Applies_Shift_And_Scale_Transform()
+ {
+ using var dir = new TempDirectory();
+ var samplePoints = new List
+ {
+ new(100.0, 200.0, 300.0),
+ };
+
+ // Shift by (10, 20, 30) and scale by 2.0 -> transformed should be ((100 - 10) * 2, (200 - 20) * 2, (300 - 30) * 2) = (180, 360, 540)
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin(
+ samplePoints,
+ shiftX: 10.0,
+ shiftY: 20.0,
+ shiftZ: 30.0,
+ scale: 2.0);
+
+ string path = dir.Write("shifted.bin", bytes);
+ using var doc = CcBinDocument.Open(path);
+ var scan = doc.Scans[0];
+
+ // Without transform: raw local
+ var raw = scan.ReadPoints(new PclReadOptions { ApplyTransform = false }).First();
+ Assert.Equal(100.0, raw.X, precision: 4);
+ Assert.Equal(200.0, raw.Y, precision: 4);
+ Assert.Equal(300.0, raw.Z, precision: 4);
+
+ // With transform
+ var transformed = scan.ReadPoints(new PclReadOptions { ApplyTransform = true }).First();
+ Assert.Equal(180.0, transformed.X, precision: 4);
+ Assert.Equal(360.0, transformed.Y, precision: 4);
+ Assert.Equal(540.0, transformed.Z, precision: 4);
+ }
+
+ [Fact]
+ public void Cc_Bin_Supports_Subsample_And_MaxPoints()
+ {
+ using var dir = new TempDirectory();
+ var samplePoints = Enumerable.Range(0, 100)
+ .Select(i => new CcBinSamplePoint(i, i * 2, i * 3))
+ .ToList();
+
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin(samplePoints);
+ string path = dir.Write("large.bin", bytes);
+ using var doc = CcBinDocument.Open(path);
+ var scan = doc.Scans[0];
+
+ Assert.Equal(10, scan.ReadPoints(new PclReadOptions { MaxPoints = 10 }).Count());
+ Assert.Equal(20, scan.ReadPoints(new PclReadOptions { SubsampleStep = 5 }).Count());
+ Assert.Empty(scan.ReadPoints(new PclReadOptions { MaxPoints = 0 }));
+ }
+
+ [Fact]
+ public void Cc_Bin_Rejects_Invalid_Signature_Or_Version()
+ {
+ using var dir = new TempDirectory();
+ var pts = new List { new(1, 2, 3) };
+
+ // Wrong signature
+ byte[] badSig = SyntheticFixtures.CreateSyntheticCcBin(pts, rawMagic: "XXXX"u8.ToArray());
+ string path1 = dir.Write("bad_sig.bin", badSig);
+ Assert.Throws(() => CcBinDocument.Open(path1));
+
+ // Unsupported version
+ byte[] badVer = SyntheticFixtures.CreateSyntheticCcBin(pts, version: 5);
+ string path2 = dir.Write("bad_ver.bin", badVer);
+ Assert.Throws(() => CcBinDocument.Open(path2));
+ }
+
+ [Fact]
+ public void Cc_Bin_Rejects_Truncated_Files()
+ {
+ using var dir = new TempDirectory();
+ var pts = new List { new(1, 2, 3), new(4, 5, 6) };
+
+ // Header truncated < 8 bytes
+ string path1 = dir.Write("cut_header.bin", [0x43, 0x43, 0x42]);
+ Assert.Throws(() => CcBinDocument.Open(path1));
+
+ // Truncated points data
+ byte[] cutPts = SyntheticFixtures.CreateSyntheticCcBin(pts, truncatePoints: true);
+ string path2 = dir.Write("cut_points.bin", cutPts);
+ Assert.Throws(() => CcBinDocument.Open(path2));
+ }
+
+ [Fact]
+ public void Cc_Bin_Loads_Custom_Properties()
+ {
+ using var dir = new TempDirectory();
+ var pts = new List { new(1, 2, 3) };
+ var customProps = new Dictionary
+ {
+ ["Custom.Step"] = 0.05,
+ ["Scale.Factor"] = 1.25,
+ };
+
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin(pts, doubleProperties: customProps);
+ string path = dir.Write("props.bin", bytes);
+ using var doc = CcBinDocument.Open(path);
+ var scan = doc.Scans[0];
+
+ Assert.Equal("0.05", scan.Properties["Custom.Step"]);
+ Assert.Equal("1.25", scan.Properties["Scale.Factor"]);
+ }
}
diff --git a/tests/PclIO.Tests/KindDetectionTests.cs b/tests/PclIO.Tests/KindDetectionTests.cs
index a79390e..12eaa83 100644
--- a/tests/PclIO.Tests/KindDetectionTests.cs
+++ b/tests/PclIO.Tests/KindDetectionTests.cs
@@ -537,6 +537,38 @@ public void Rejects_Invalid_Content_With_Ptg_Extension()
Assert.Equal(PclFileKind.Unknown, Detect(plainText, "text.ptg"));
}
+ [Theory]
+ [InlineData("scan.bin")]
+ [InlineData("SCAN.BIN")]
+ [InlineData("scan.dat")]
+ public void Detects_Cc_Bin_By_Signature(string name)
+ {
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin([new CcBinSamplePoint(1, 2, 3)]);
+ Assert.Equal(PclFileKind.CcBin, Detect(bytes, name));
+
+ using var ms = new MemoryStream(bytes);
+ Assert.Equal(PclFileKind.CcBin, PclFile.DetectKind(ms));
+ }
+
+ [Fact]
+ public void Cc_Bin_Needs_The_Signature_Not_Just_The_Extension()
+ {
+ byte[] randomBin = [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08];
+ Assert.Equal(PclFileKind.Unknown, Detect(randomBin, "random.bin"));
+ }
+
+ [Fact]
+ public void Detects_Cc_Bin_File_Path()
+ {
+ using var tempDir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin([new CcBinSamplePoint(10, 20, 30)]);
+ string binPath = tempDir.Write("test.bin", bytes);
+ Assert.Equal(PclFileKind.CcBin, PclFile.DetectKind(binPath));
+
+ string badBin = tempDir.Write("bad.bin", [0x00, 0x01, 0x02, 0x03]);
+ Assert.Equal(PclFileKind.Unknown, PclFile.DetectKind(badBin));
+ }
+
private sealed class NonSeekableStream(byte[] bytes) : MemoryStream(bytes)
{
public override bool CanSeek => false;
diff --git a/tests/PclIO.Tests/RealFileTests.cs b/tests/PclIO.Tests/RealFileTests.cs
index 06aa577..b540409 100644
--- a/tests/PclIO.Tests/RealFileTests.cs
+++ b/tests/PclIO.Tests/RealFileTests.cs
@@ -98,6 +98,9 @@ private static void AssertReadsPoints(string extension, PclFileKind kind)
[SkippableFact]
public void Read_Real_Ptg_Points() => AssertReadsPoints(".ptg", PclFileKind.LeicaPtg);
+ [SkippableFact]
+ public void Read_Real_Cc_Bin_Points() => AssertReadsPoints(".bin", PclFileKind.CcBin);
+
[SkippableFact]
public void Read_Real_Xyz_Points() => AssertReadsPoints(".xyz", PclFileKind.Xyz);
diff --git a/tests/PclIO.Tests/SyntheticFixtures.cs b/tests/PclIO.Tests/SyntheticFixtures.cs
index 9c35ef8..5697997 100644
--- a/tests/PclIO.Tests/SyntheticFixtures.cs
+++ b/tests/PclIO.Tests/SyntheticFixtures.cs
@@ -70,6 +70,12 @@ public readonly record struct EptSamplePoint(
PclVector3? Normal = null,
byte? Classification = null);
+/// One point of a synthetic CC BIN file: position, colour and intensity.
+public readonly record struct CcBinSamplePoint(
+ double X, double Y, double Z,
+ PclColor? Color = null,
+ float? Intensity = 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
@@ -2935,4 +2941,211 @@ public static byte[] CreateSyntheticPtgIndex(
}
return Encoding.UTF8.GetBytes(sb.ToString());
}
+
+ // ---- CC BIN (.bin) ------------------------------------------------------------------------------------------
+
+ /// Creates a synthetic CC BIN point cloud file (.bin, CCB2).
+ public static byte[] CreateSyntheticCcBin(
+ IReadOnlyList points,
+ string name = "Cloud",
+ double shiftX = 0,
+ double shiftY = 0,
+ double shiftZ = 0,
+ double scale = 1.0,
+ bool withColors = true,
+ bool withIntensity = true,
+ uint version = 47,
+ double[]? matrix16 = null,
+ IReadOnlyDictionary? doubleProperties = null,
+ byte[]? rawMagic = null,
+ bool truncatePoints = false)
+ {
+ using var ms = new MemoryStream();
+
+ // 1. Magic signature (4 bytes)
+ ms.Write(rawMagic ?? "CCB2"u8.ToArray());
+
+ // 2. Version (uint32 LE)
+ Span u32Buf = stackalloc byte[4];
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, version);
+ ms.Write(u32Buf);
+
+ // 3. Entity header: f1 (257), f2 (0), id (100)
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 257);
+ ms.Write(u32Buf);
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 0);
+ ms.Write(u32Buf);
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 100);
+ ms.Write(u32Buf);
+
+ // Name (UTF-16 BE)
+ byte[] nameBytes = Encoding.BigEndianUnicode.GetBytes(name);
+ BinaryPrimitives.WriteUInt32BigEndian(u32Buf, (uint)nameBytes.Length);
+ ms.Write(u32Buf);
+ ms.Write(nameBytes);
+
+ // 4. QVariantMap properties
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 2); // mapType
+ ms.Write(u32Buf);
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, (uint)(doubleProperties?.Count ?? 0));
+ ms.Write(u32Buf);
+
+ if (doubleProperties != null)
+ {
+ Span dBuf = stackalloc byte[8];
+ foreach (var kvp in doubleProperties)
+ {
+ byte[] kBytes = Encoding.BigEndianUnicode.GetBytes(kvp.Key);
+ BinaryPrimitives.WriteUInt32BigEndian(u32Buf, (uint)kBytes.Length);
+ ms.Write(u32Buf);
+ ms.Write(kBytes);
+
+ BinaryPrimitives.WriteUInt32BigEndian(u32Buf, 6); // vType = double
+ ms.Write(u32Buf);
+ ms.WriteByte(0); // isNull = 0
+
+ BinaryPrimitives.WriteUInt64BigEndian(dBuf, BitConverter.DoubleToUInt64Bits(kvp.Value));
+ ms.Write(dBuf);
+ }
+ }
+
+ // 5. Flags (8 bytes), shift (24 bytes), scale (8 bytes), marker (3 bytes)
+ ms.WriteByte(0x01);
+ ms.WriteByte(0x00);
+ ms.WriteByte(0x01);
+ ms.WriteByte(0x00);
+ ms.WriteByte(0x00);
+ ms.WriteByte(0x00);
+ ms.WriteByte(0x00);
+ ms.WriteByte(0x00);
+
+ Span dblBuf = stackalloc byte[8];
+ BinaryPrimitives.WriteDoubleLittleEndian(dblBuf, shiftX);
+ ms.Write(dblBuf);
+ BinaryPrimitives.WriteDoubleLittleEndian(dblBuf, shiftY);
+ ms.Write(dblBuf);
+ BinaryPrimitives.WriteDoubleLittleEndian(dblBuf, shiftZ);
+ ms.Write(dblBuf);
+ BinaryPrimitives.WriteDoubleLittleEndian(dblBuf, scale);
+ ms.Write(dblBuf);
+
+ ms.WriteByte(0x00);
+ ms.WriteByte(0x00);
+ ms.WriteByte(0x03);
+
+ // 6. Point count (uint32 LE)
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, (uint)points.Count);
+ ms.Write(u32Buf);
+
+ // 7. Points data (12 bytes per point)
+ int ptCountToWrite = truncatePoints ? points.Count / 2 : points.Count;
+ Span ptBuf = stackalloc byte[12];
+ for (int i = 0; i < ptCountToWrite; i++)
+ {
+ var pt = points[i];
+ BinaryPrimitives.WriteSingleLittleEndian(ptBuf.Slice(0, 4), (float)pt.X);
+ BinaryPrimitives.WriteSingleLittleEndian(ptBuf.Slice(4, 4), (float)pt.Y);
+ BinaryPrimitives.WriteSingleLittleEndian(ptBuf.Slice(8, 4), (float)pt.Z);
+ ms.Write(ptBuf);
+ }
+
+ if (truncatePoints)
+ return ms.ToArray();
+
+ // 8. Colors
+ if (withColors)
+ {
+ ms.WriteByte(0x01); // color flag
+
+ // Header: f1, f2, id, nameLen, name ("RGB colors"), colType, colFlags, channels, colCount
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 0x10000012);
+ ms.Write(u32Buf);
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 0);
+ ms.Write(u32Buf);
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 101);
+ ms.Write(u32Buf);
+
+ byte[] colNameBytes = Encoding.BigEndianUnicode.GetBytes("RGB colors");
+ BinaryPrimitives.WriteUInt32BigEndian(u32Buf, (uint)colNameBytes.Length);
+ ms.Write(u32Buf);
+ ms.Write(colNameBytes);
+
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 6);
+ ms.Write(u32Buf);
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 0);
+ ms.Write(u32Buf);
+ ms.WriteByte(3); // channels
+
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, (uint)points.Count);
+ ms.Write(u32Buf);
+
+ Span rgb = stackalloc byte[3];
+ for (int i = 0; i < points.Count; i++)
+ {
+ var pt = points[i];
+ rgb[0] = pt.Color?.R ?? 255;
+ rgb[1] = pt.Color?.G ?? 255;
+ rgb[2] = pt.Color?.B ?? 255;
+ ms.Write(rgb);
+ }
+ }
+ else
+ {
+ ms.WriteByte(0x00);
+ }
+
+ // 9. Matrix 4x4 (8 bytes + 64 bytes)
+ Span zeros8 = stackalloc byte[8];
+ ms.Write(zeros8);
+
+ Span matBuf = stackalloc byte[64];
+ for (int m = 0; m < 16; m++)
+ {
+ float val;
+ if (matrix16 != null && m < matrix16.Length)
+ {
+ val = (float)matrix16[m];
+ }
+ else
+ {
+ int row = m / 4;
+ int col = m % 4;
+ val = row == col ? 1f : 0f;
+ }
+ BinaryPrimitives.WriteSingleLittleEndian(matBuf.Slice(m * 4, 4), val);
+ }
+ ms.Write(matBuf);
+
+ // 10. Scalar fields (Intensity)
+ if (withIntensity)
+ {
+ ms.WriteByte(0x00);
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 1); // 1 scalar field
+ ms.Write(u32Buf);
+
+ byte[] nameBuf256 = new byte[256];
+ Encoding.ASCII.GetBytes("Intensity", nameBuf256.AsSpan());
+ ms.Write(nameBuf256);
+
+ ms.WriteByte(0x01); // flag
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, (uint)points.Count);
+ ms.Write(u32Buf);
+
+ Span fltBuf = stackalloc byte[4];
+ for (int i = 0; i < points.Count; i++)
+ {
+ var pt = points[i];
+ BinaryPrimitives.WriteSingleLittleEndian(fltBuf, pt.Intensity ?? 0f);
+ ms.Write(fltBuf);
+ }
+ }
+ else
+ {
+ ms.WriteByte(0x00);
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 0);
+ ms.Write(u32Buf);
+ }
+
+ return ms.ToArray();
+ }
}
From 33e00db2d20eeac7641077e364de06c7bed96fcc Mon Sep 17 00:00:00 2001
From: mahach666 <79989386+mahach666@users.noreply.github.com>
Date: Wed, 18 Nov 2026 17:53:20 +0000
Subject: [PATCH 2/4] Fix CC BIN coordinates, multi-entity traversal, channel
validation, and detection (#37)
---
README.md | 4 +-
docs/public-api.md | 2 +-
src/PclIO/Formats/CcBin/CcBinDocument.cs | 86 +++++++++++++---------
src/PclIO/Formats/CcBin/CcBinScan.cs | 28 +++++--
src/PclIO/Internal/KindDetector.cs | 28 ++++++-
tests/PclIO.Tests/FormatTests.cs | 65 +++++++++++++++-
tests/PclIO.Tests/KindDetectionTests.cs | 18 +++++
tests/PclIO.Tests/SyntheticFixtures.cs | 94 +++++++++++++++++++++---
8 files changed, 261 insertions(+), 64 deletions(-)
diff --git a/README.md b/README.md
index 2c61510..cfe5be9 100644
--- a/README.md
+++ b/README.md
@@ -55,7 +55,7 @@ The library targets .NET 8 and .NET 10. It is managed code with no dependencies
| COPC | `.copc.laz`, `.laz` | Cloud Optimized Point Cloud (COPC octree in LAS 1.4 / LAZ): reads the octree hierarchy (root and sub-hierarchy pages) and voxel bounding boxes, center, halfsize and spacing metadata, streaming points by octree node, bounding box or across the whole dataset. LAS formats 0 to 3 are fully decompressed via LASzip arithmetic decoding; LAS 1.4 formats 6 to 8 decode uncompressed anchor points with exact positions, intensity, classification and RGB colour per octree node. |
| EPT | `ept.json`, `.laz`, `.bin`, `.zst` | Entwine Point Tile (EPT octree datasets): reads dataset manifest (`ept.json`), octree hierarchy (`ept-hierarchy/`), and point data tiles (`ept-data/`) across `"laszip"`, `"binary"`, and `"zstandard"` storage types. Supports schema dimension extraction (XYZ, intensity, classification, RGB colour, normals), spatial querying by bounding box (`FindNodes`, `ReadPoints`), depth filtering, and single-node streaming. |
| Leica PTG | `.ptg` | Leica Cyclone gridded binary exchange point clouds: binary scan files (`.ptg`) with 8-byte signature and magic (`0x928FA3C7`), ASCII metadata header (`NumRows`, `NumCols`, `%%properties`, `%%transform`), column offset array, and column validity bitmasks with single or double precision Cartesian XYZ coordinates, intensity [0..1] and 8-bit RGB colour. Top-level ASCII index files (`.ptg`) referencing binary scan files are aggregated into multi-scan documents. Coordinate transforms applied unless `ApplyTransform` is false. |
-| CC BIN | `.bin` | CC BIN binary entity files (`*.bin`, signature `CCB2`): single or multi-cloud datasets with 32-bit floating point Cartesian XYZ coordinates, global shift and scale vectors, 8-bit RGB colour arrays, 4x4 coordinate transform matrices, and scalar fields (including intensity). Coordinates are transformed by global shift and scale unless `ApplyTransform` is false. Points with non-finite coordinates are skipped. |
+| CC BIN | `.bin` | CC BIN binary entity files (`*.bin`, signature `CCB2`): single or multi-cloud datasets with 32-bit floating point Cartesian XYZ coordinates, global shift and scale vectors, 8-bit RGB colour arrays, 4x4 coordinate transform matrices, and scalar fields (including intensity). Coordinates are transformed by global shift and scale ($P_{original} = P_{local} / \text{scale} - \text{shift}$) unless `ApplyTransform` is false. Points with non-finite coordinates are skipped. Normals in modern CC entity files use quantized spherical sector indices (`ccNormalCompressor`), which has no open public specification and is not decoded under clean-room rules (`HasNormals = false`). |
### Format detection
@@ -65,7 +65,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` and `.copc.laz`. A LAZ file is recognised by the `LASF` signature, a valid LASzip VLR and the `.laz` extension. A COPC file is recognised by the LAS 1.4 header and the `copc` info variable length record with `.copc.laz` or any extension. A PCD file is recognised by its header structure with any extension. A PLY file is recognised by its magic word and header structure with any extension. A PTS file is recognised by an integer point count header line followed by coordinate lines with any extension, or coordinate lines with the `.pts` extension. A PTX file is recognised by its 10-line header structure (grid dimensions, scanner pose, 4x4 matrix) with any extension. An XYZ / delimited text file is recognised by an explicit column header containing X, Y, Z in any extension, or by numeric coordinate lines with a recognised extension (`.xyz`, `.asc`, `.txt`, `.csv`). An SBF file is recognised by its companion `[SBF]` header structure with any extension, or by the binary signature `0x2A, 0x2A` (`**`) and record size formula (`.sbf`, `.sbf.data`, `.data`). A 3D Tiles `.pnts` tile is recognised by the `pnts` signature, version 1, and matching byte lengths. A glTF `.glb` point cloud is recognised by the `glTF` signature, version 2, and mesh primitive mode 0 (POINTS). A 3D Tiles tileset is recognised by JSON containing `asset` and `root` objects (`tileset.json`). A Potree dataset is recognised by `cloud.js` (with `octreeDir` and attribute descriptors) or `metadata.json` (version 2.x and point attributes) in `.js` or `.json`, by `.hrc` hierarchy files with 5-byte node records, or by ancestor `cloud.js`/`metadata.json` next to a `.bin` file. An EPT dataset is recognised by `ept.json` manifest structure (bounds, dataType, schema) or by companion `ept.json` next to octree tiles. A Leica PTG binary scan file is recognised by the `PTG\0` tag and magic number `0x928FA3C7` with any extension; a top-level ASCII index file is recognised by the `PTG index` header and the `.ptg` extension. A CC BIN file is recognised by the `CCB2` signature with any extension; a `.bin` file without this signature is reported as Potree when inside an octree folder or unknown.
+ A LAS file is recognised by the `LASF` signature with any extension except `.laz` and `.copc.laz`. A LAZ file is recognised by the `LASF` signature, a valid LASzip VLR and the `.laz` extension. A COPC file is recognised by the LAS 1.4 header and the `copc` info variable length record with `.copc.laz` or any extension. A PCD file is recognised by its header structure with any extension. A PLY file is recognised by its magic word and header structure with any extension. A PTS file is recognised by an integer point count header line followed by coordinate lines with any extension, or coordinate lines with the `.pts` extension. A PTX file is recognised by its 10-line header structure (grid dimensions, scanner pose, 4x4 matrix) with any extension. An XYZ / delimited text file is recognised by an explicit column header containing X, Y, Z in any extension, or by numeric coordinate lines with a recognised extension (`.xyz`, `.asc`, `.txt`, `.csv`). An SBF file is recognised by its companion `[SBF]` header structure with any extension, or by the binary signature `0x2A, 0x2A` (`**`) and record size formula (`.sbf`, `.sbf.data`, `.data`). A 3D Tiles `.pnts` tile is recognised by the `pnts` signature, version 1, and matching byte lengths. A glTF `.glb` point cloud is recognised by the `glTF` signature, version 2, and mesh primitive mode 0 (POINTS). A 3D Tiles tileset is recognised by JSON containing `asset` and `root` objects (`tileset.json`). A Potree dataset is recognised by `cloud.js` (with `octreeDir` and attribute descriptors) or `metadata.json` (version 2.x and point attributes) in `.js` or `.json`, by `.hrc` hierarchy files with 5-byte node records, or by ancestor `cloud.js`/`metadata.json` next to a `.bin` file. An EPT dataset is recognised by `ept.json` manifest structure (bounds, dataType, schema) or by companion `ept.json` next to octree tiles. A Leica PTG binary scan file is recognised by the `PTG\0` tag and magic number `0x928FA3C7` with any extension; a top-level ASCII index file is recognised by the `PTG index` header and the `.ptg` extension. A CC BIN file is recognised by the `CCB2` signature and entity header structure with any extension; a `.bin` file without this structure is reported as Potree when next to an octree manifest or unknown.
- 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
diff --git a/docs/public-api.md b/docs/public-api.md
index 076cdd2..e9af4a4 100644
--- a/docs/public-api.md
+++ b/docs/public-api.md
@@ -45,7 +45,7 @@ is the argument, which may also be a file name.
`Potree` is recognised by `cloud.js` (with `octreeDir` and attribute descriptors) or `metadata.json` (version 2.x and point attributes) in `.js` or `.json`, by `.hrc` hierarchy files with 5-byte node records, or by ancestor `cloud.js`/`metadata.json` next to a `.bin` file.
`Ept` is recognised by `ept.json` manifest structure (bounds, dataType, schema) or by companion `ept.json` next to octree tiles.
`LeicaPtg` is recognised by the `PTG\0` tag and magic number `0x928FA3C7` with any extension, or by the `PTG index` header with the `.ptg` extension.
- `CcBin` is recognised by the `CCB2` signature with any extension; a `.bin` file without this signature is reported as `Potree` when inside an octree folder or `Unknown`.
+ `CcBin` is recognised by the `CCB2` signature and entity header structure with any extension; a `.bin` file without this structure is reported as `Potree` when next to an octree manifest or `Unknown`.
- `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
diff --git a/src/PclIO/Formats/CcBin/CcBinDocument.cs b/src/PclIO/Formats/CcBin/CcBinDocument.cs
index 850ed76..e336dc6 100644
--- a/src/PclIO/Formats/CcBin/CcBinDocument.cs
+++ b/src/PclIO/Formats/CcBin/CcBinDocument.cs
@@ -78,6 +78,7 @@ private void ScanPointClouds(FileStream fs, long fileLength)
if (bytesRead < 44) break;
int scanLimit = bytesRead - 44;
+ bool found = false;
for (int i = 0; i <= scanLimit; i++)
{
// Entity type f1 == 257 (0x01, 0x01, 0x00, 0x00) and f2 == 0 (0x00, 0x00, 0x00, 0x00)
@@ -88,13 +89,17 @@ private void ScanPointClouds(FileStream fs, long fileLength)
if (TryParsePointCloud(fs, fileLength, entityPos, _scans.Count, out var scan, out long nextOffset))
{
_scans.Add(scan);
- streamPos = Math.Max(streamPos, nextOffset);
+ streamPos = Math.Max(entityPos + 8, nextOffset);
+ found = true;
break;
}
}
}
- streamPos += BlockSize;
+ if (!found)
+ {
+ streamPos += BlockSize;
+ }
}
}
@@ -225,35 +230,38 @@ private bool TryParsePointCloud(
if (colorFlag == 1)
{
byte[] colH = new byte[16];
- if (fs.Read(colH) == 16)
- {
- uint colNameLen = BinaryPrimitives.ReadUInt32BigEndian(colH.AsSpan(12, 4));
- if (colNameLen < 500 && fs.Position + colNameLen + 9 <= fileLength)
- {
- fs.Position += colNameLen;
- byte[] colProps = new byte[9];
- if (fs.Read(colProps) == 9)
- {
- channels = colProps[8];
- byte[] colCountBuf = new byte[4];
- if (fs.Read(colCountBuf) == 4)
- {
- uint colCount = BinaryPrimitives.ReadUInt32LittleEndian(colCountBuf);
- if (colCount == count && (channels is 3 or 4))
- {
- long cOffset = fs.Position;
- long cBytes = (long)colCount * channels;
- if (cOffset + cBytes <= fileLength)
- {
- hasColors = true;
- colorOffset = cOffset;
- fs.Position += cBytes;
- }
- }
- }
- }
- }
- }
+ if (fs.Read(colH) < 16)
+ throw new InvalidDataException("CC BIN RGB color header is truncated.");
+
+ uint colNameLen = BinaryPrimitives.ReadUInt32BigEndian(colH.AsSpan(12, 4));
+ if (colNameLen > 500 || fs.Position + colNameLen + 9 > fileLength)
+ throw new InvalidDataException("CC BIN RGB color name or properties are truncated.");
+
+ fs.Position += colNameLen;
+ byte[] colProps = new byte[9];
+ if (fs.Read(colProps) < 9)
+ throw new InvalidDataException("CC BIN RGB color properties are truncated.");
+
+ channels = colProps[8];
+ if (channels is not (3 or 4))
+ throw new InvalidDataException($"CC BIN unsupported color channels: {channels}.");
+
+ byte[] colCountBuf = new byte[4];
+ if (fs.Read(colCountBuf) < 4)
+ throw new InvalidDataException("CC BIN RGB color count is truncated.");
+
+ uint colCount = BinaryPrimitives.ReadUInt32LittleEndian(colCountBuf);
+ if (colCount != count)
+ throw new InvalidDataException($"CC BIN color count {colCount} does not match point count {count}.");
+
+ long cOffset = fs.Position;
+ long cBytes = (long)colCount * channels;
+ if (cOffset + cBytes > fileLength)
+ throw new InvalidDataException("CC BIN RGB color data is truncated.");
+
+ hasColors = true;
+ colorOffset = cOffset;
+ fs.Position += cBytes;
}
// Matrix 4x4
@@ -279,6 +287,7 @@ private bool TryParsePointCloud(
// Scalar fields (probe for Intensity)
bool hasIntensity = false;
long intensityOffset = -1;
+ uint intensityCount = 0;
int sfFlag = fs.ReadByte();
if (sfFlag >= 0)
{
@@ -306,6 +315,7 @@ private bool TryParsePointCloud(
{
hasIntensity = true;
intensityOffset = dataOffset;
+ intensityCount = sCount;
}
fs.Position += sBytes;
@@ -319,12 +329,16 @@ private bool TryParsePointCloud(
}
// Construct transform:
- // P_global = (P_local - Shift) * Scale
- // In PclTransform: P_transformed = P_local * Scale + Translation
+ // According to Global Shift and Scale mathematics:
+ // P_shifted = (P_original + Shift) * Scale
+ // Therefore, to recover the original (global) coordinate from stored local coordinate:
+ // P_original = P_local / Scale - Shift
+ // In PclTransform: P_transformed = P_local * Transform.Scale + Transform.Translation
+ double invScale = Math.Abs(scale) > 1e-12 ? (1.0 / scale) : 1.0;
var transform = new PclTransform
{
- Scale = new PclVector3(scale, scale, scale),
- Translation = new PclVector3(-sx * scale, -sy * scale, -sz * scale),
+ Scale = new PclVector3(invScale, invScale, invScale),
+ Translation = new PclVector3(-sx, -sy, -sz),
Matrix4x4 = isIdentity ? null : matrix16,
};
@@ -340,6 +354,7 @@ private bool TryParsePointCloud(
colorChannels: channels,
hasIntensity: hasIntensity,
intensityOffset: intensityOffset,
+ intensityCount: intensityCount,
shiftX: sx,
shiftY: sy,
shiftZ: sz,
@@ -347,6 +362,7 @@ private bool TryParsePointCloud(
transform: transform,
properties: props);
+ pointsEndOffset = Math.Max(pointsEndOffset, fs.Position);
return true;
}
}
diff --git a/src/PclIO/Formats/CcBin/CcBinScan.cs b/src/PclIO/Formats/CcBin/CcBinScan.cs
index 23cea84..fa1d8e6 100644
--- a/src/PclIO/Formats/CcBin/CcBinScan.cs
+++ b/src/PclIO/Formats/CcBin/CcBinScan.cs
@@ -17,6 +17,7 @@ public sealed class CcBinScan : PclScan
private readonly byte _colorChannels;
private readonly bool _hasIntensity;
private readonly long _intensityOffset;
+ private readonly long _intensityCount;
private readonly double _shiftX;
private readonly double _shiftY;
private readonly double _shiftZ;
@@ -35,7 +36,12 @@ public sealed class CcBinScan : PclScan
public override bool HasColors => _hasColors;
///
- public override bool HasIntensities => _hasIntensity;
+ public override bool HasIntensities => _hasIntensity && _intensityCount > 0;
+
+ ///
+ /// Modern CC entity files store normals using quantized spherical sector indices (ccNormalCompressor)
+ /// which lacks a published open specification; under clean-room rules, normals are not decoded.
+ public override bool HasNormals => false;
/// Global shift vector stored with the cloud entity.
public PclVector3 GlobalShift => new(_shiftX, _shiftY, _shiftZ);
@@ -54,6 +60,7 @@ internal CcBinScan(
byte colorChannels,
bool hasIntensity,
long intensityOffset,
+ long intensityCount,
double shiftX,
double shiftY,
double shiftZ,
@@ -69,8 +76,9 @@ internal CcBinScan(
_hasColors = hasColors;
_colorOffset = colorOffset;
_colorChannels = colorChannels;
- _hasIntensity = hasIntensity;
+ _hasIntensity = hasIntensity && intensityCount > 0;
_intensityOffset = intensityOffset;
+ _intensityCount = intensityCount;
_shiftX = shiftX;
_shiftY = shiftY;
_shiftZ = shiftZ;
@@ -132,11 +140,15 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
if (_hasIntensity && intBuf != null)
{
- int intBytesToRead = toRead * 4;
- fs.Position = _intensityOffset + (pointIndex * 4);
- int intRead = fs.ReadAtLeast(intBuf.AsSpan(0, intBytesToRead), intBytesToRead, throwOnEndOfStream: false);
- if (intRead < intBytesToRead)
- throw FormatError.Truncated($"CC BIN file ended prematurely while reading intensity at index {pointIndex}.");
+ long intAvailable = Math.Max(0, Math.Min(_intensityCount - pointIndex, toRead));
+ if (intAvailable > 0)
+ {
+ int intBytesToRead = (int)intAvailable * 4;
+ fs.Position = _intensityOffset + (pointIndex * 4);
+ int intRead = fs.ReadAtLeast(intBuf.AsSpan(0, intBytesToRead), intBytesToRead, throwOnEndOfStream: false);
+ if (intRead < intBytesToRead)
+ throw FormatError.Truncated($"CC BIN file ended prematurely while reading intensity at index {pointIndex}.");
+ }
}
for (int p = 0; p < toRead; p++)
@@ -164,7 +176,7 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
}
float? intensity = null;
- if (_hasIntensity && intBuf != null)
+ if (_hasIntensity && intBuf != null && currentIdx < _intensityCount)
{
int intByteOffset = p * 4;
float iVal = BinaryPrimitives.ReadSingleLittleEndian(intBuf.AsSpan(intByteOffset, 4));
diff --git a/src/PclIO/Internal/KindDetector.cs b/src/PclIO/Internal/KindDetector.cs
index e277daf..788d196 100644
--- a/src/PclIO/Internal/KindDetector.cs
+++ b/src/PclIO/Internal/KindDetector.cs
@@ -85,9 +85,9 @@ public static PclFileKind Detect(string path)
{
using (var probeStream = File.OpenRead(path))
{
- Span probeHead = stackalloc byte[4];
- int probeRead = probeStream.ReadAtLeast(probeHead, 4, throwOnEndOfStream: false);
- if (probeRead >= 4 && probeHead.StartsWith(CcBinMagic))
+ Span probeHead = stackalloc byte[24];
+ int probeRead = probeStream.ReadAtLeast(probeHead, 24, throwOnEndOfStream: false);
+ if (probeRead >= 24 && IsCcBinStructure(probeHead))
return PclFileKind.CcBin;
}
@@ -132,7 +132,7 @@ public static PclFileKind Detect(Stream stream, string? extension = null)
if (read < 4) return extension is ".c3db" or ".c3ptx" ? PclFileKind.EdgeWise : PclFileKind.Unknown;
ReadOnlySpan head = buffer[..read];
- if (head.StartsWith(CcBinMagic))
+ if (head.StartsWith(CcBinMagic) && IsCcBinStructure(head))
return PclFileKind.CcBin;
if (head.Length >= 8 && head.StartsWith(PtgTag) && BinaryPrimitives.ReadUInt32LittleEndian(head[4..8]) == PtgMagicNumber)
@@ -1318,4 +1318,24 @@ private static bool IsPtgIndexHeader(Stream stream, long origin)
stream.Position = origin;
}
}
+
+ private static bool IsCcBinStructure(ReadOnlySpan head)
+ {
+ if (head.Length < 24 || !head.StartsWith(CcBinMagic))
+ return false;
+
+ uint version = BinaryPrimitives.ReadUInt32LittleEndian(head[4..8]);
+ if (version is < 1 or > 100)
+ return false;
+
+ uint entityType = BinaryPrimitives.ReadUInt32LittleEndian(head[8..12]);
+ if (entityType is < 1 or > 2000)
+ return false;
+
+ uint nameLen = BinaryPrimitives.ReadUInt32BigEndian(head[20..24]);
+ if (nameLen != 0xFFFF_FFFF && (nameLen > 2048 || (nameLen % 2) != 0))
+ return false;
+
+ return true;
+ }
}
diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs
index 315ae98..87d8312 100644
--- a/tests/PclIO.Tests/FormatTests.cs
+++ b/tests/PclIO.Tests/FormatTests.cs
@@ -6397,7 +6397,8 @@ public void Cc_Bin_Applies_Shift_And_Scale_Transform()
new(100.0, 200.0, 300.0),
};
- // Shift by (10, 20, 30) and scale by 2.0 -> transformed should be ((100 - 10) * 2, (200 - 20) * 2, (300 - 30) * 2) = (180, 360, 540)
+ // Shift by (10, 20, 30) and scale by 2.0 -> original global coordinates:
+ // P_global = P_local / scale - shift: (100 / 2 - 10, 200 / 2 - 20, 300 / 2 - 30) = (40, 80, 120)
byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin(
samplePoints,
shiftX: 10.0,
@@ -6417,9 +6418,65 @@ public void Cc_Bin_Applies_Shift_And_Scale_Transform()
// With transform
var transformed = scan.ReadPoints(new PclReadOptions { ApplyTransform = true }).First();
- Assert.Equal(180.0, transformed.X, precision: 4);
- Assert.Equal(360.0, transformed.Y, precision: 4);
- Assert.Equal(540.0, transformed.Z, precision: 4);
+ Assert.Equal(40.0, transformed.X, precision: 4);
+ Assert.Equal(80.0, transformed.Y, precision: 4);
+ Assert.Equal(120.0, transformed.Z, precision: 4);
+ }
+
+ [Fact]
+ public void Cc_Bin_Opens_Adjacent_Multi_Cloud_Entities()
+ {
+ using var dir = new TempDirectory();
+ var cloud1 = new List { new(1, 2, 3), new(4, 5, 6) };
+ var cloud2 = new List { new(7, 8, 9), new(10, 11, 12) };
+
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBinMultiCloud([cloud1, cloud2]);
+ string path = dir.Write("multi.bin", bytes);
+
+ using var doc = CcBinDocument.Open(path);
+ Assert.Equal(2, doc.Scans.Count);
+ Assert.Equal("Cloud_1", doc.Scans[0].Name);
+ Assert.Equal(2, doc.Scans[0].PointCount);
+ Assert.Equal("Cloud_2", doc.Scans[1].Name);
+ Assert.Equal(2, doc.Scans[1].PointCount);
+ }
+
+ [Fact]
+ public void Cc_Bin_Reads_Intensity_Within_Declared_Count_Only()
+ {
+ using var dir = new TempDirectory();
+ var samplePoints = new List
+ {
+ new(1.0, 2.0, 3.0, Intensity: 12f),
+ new(4.0, 5.0, 6.0, Intensity: 0f),
+ };
+
+ // 2 points, but only 1 intensity value declared in the scalar field
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin(
+ samplePoints,
+ declaredIntensityCount: 1);
+
+ string path = dir.Write("partial_intensity.bin", bytes);
+ using var doc = CcBinDocument.Open(path);
+ var scan = doc.Scans[0];
+
+ var points = scan.ReadPoints().ToList();
+ Assert.Equal(2, points.Count);
+ Assert.Equal(12f, points[0].Intensity);
+ Assert.Null(points[1].Intensity);
+ }
+
+ [Fact]
+ public void Cc_Bin_Rejects_Truncated_Color_Block()
+ {
+ using var dir = new TempDirectory();
+ var samplePoints = new List { new(1.0, 2.0, 3.0) };
+
+ // Color flag is 1, but file ends right after the flag
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin(samplePoints, truncateColorBlock: true);
+ string path = dir.Write("cut_color.bin", bytes);
+
+ Assert.Throws(() => CcBinDocument.Open(path));
}
[Fact]
diff --git a/tests/PclIO.Tests/KindDetectionTests.cs b/tests/PclIO.Tests/KindDetectionTests.cs
index 12eaa83..a47dea1 100644
--- a/tests/PclIO.Tests/KindDetectionTests.cs
+++ b/tests/PclIO.Tests/KindDetectionTests.cs
@@ -569,6 +569,24 @@ public void Detects_Cc_Bin_File_Path()
Assert.Equal(PclFileKind.Unknown, PclFile.DetectKind(badBin));
}
+ [Fact]
+ public void Potree_Node_With_Cc_Magic_Coordinates_Is_Detected_As_Potree_Near_Manifest()
+ {
+ using var tempDir = new TempDirectory();
+ // Write cloud.js manifest
+ tempDir.Write("cloud.js", "{ \"version\": \"1.7\", \"octreeDir\": \"data\", \"points\": 1 }"u8.ToArray());
+
+ // Create an r.bin where the first 4 coordinate bytes happen to match CCB2 ("CCB2"),
+ // but remaining bytes are raw Potree point coordinates and not CC BIN structure.
+ byte[] potreeNode = new byte[32];
+ "CCB2"u8.CopyTo(potreeNode.AsSpan(0, 4)); // X coordinate
+ BinaryPrimitives.WriteInt32LittleEndian(potreeNode.AsSpan(4, 4), 500000); // Y coordinate
+ BinaryPrimitives.WriteInt32LittleEndian(potreeNode.AsSpan(8, 4), 600000); // Z coordinate
+ string rBinPath = tempDir.Write("data/r/r.bin", potreeNode);
+
+ Assert.Equal(PclFileKind.Potree, PclFile.DetectKind(rBinPath));
+ }
+
private sealed class NonSeekableStream(byte[] bytes) : MemoryStream(bytes)
{
public override bool CanSeek => false;
diff --git a/tests/PclIO.Tests/SyntheticFixtures.cs b/tests/PclIO.Tests/SyntheticFixtures.cs
index 5697997..48e6377 100644
--- a/tests/PclIO.Tests/SyntheticFixtures.cs
+++ b/tests/PclIO.Tests/SyntheticFixtures.cs
@@ -2958,7 +2958,9 @@ public static byte[] CreateSyntheticCcBin(
double[]? matrix16 = null,
IReadOnlyDictionary? doubleProperties = null,
byte[]? rawMagic = null,
- bool truncatePoints = false)
+ bool truncatePoints = false,
+ bool truncateColorBlock = false,
+ int? declaredIntensityCount = null)
{
using var ms = new MemoryStream();
@@ -2970,12 +2972,75 @@ public static byte[] CreateSyntheticCcBin(
BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, version);
ms.Write(u32Buf);
- // 3. Entity header: f1 (257), f2 (0), id (100)
+ WriteCcBinCloudEntity(
+ ms,
+ points,
+ name: name,
+ id: 100,
+ shiftX: shiftX,
+ shiftY: shiftY,
+ shiftZ: shiftZ,
+ scale: scale,
+ withColors: withColors,
+ withIntensity: withIntensity,
+ declaredIntensityCount: declaredIntensityCount,
+ matrix16: matrix16,
+ doubleProperties: doubleProperties,
+ truncatePoints: truncatePoints,
+ truncateColorBlock: truncateColorBlock);
+
+ return ms.ToArray();
+ }
+
+ /// Creates a synthetic CC BIN file containing multiple adjacent cloud entities.
+ public static byte[] CreateSyntheticCcBinMultiCloud(
+ IReadOnlyList> clouds,
+ uint version = 47)
+ {
+ using var ms = new MemoryStream();
+ ms.Write("CCB2"u8.ToArray());
+
+ Span u32Buf = stackalloc byte[4];
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, version);
+ ms.Write(u32Buf);
+
+ for (int c = 0; c < clouds.Count; c++)
+ {
+ WriteCcBinCloudEntity(
+ ms,
+ clouds[c],
+ name: $"Cloud_{c + 1}",
+ id: (uint)(100 + c));
+ }
+
+ return ms.ToArray();
+ }
+
+ private static void WriteCcBinCloudEntity(
+ Stream ms,
+ IReadOnlyList points,
+ string name = "Cloud",
+ uint id = 100,
+ double shiftX = 0,
+ double shiftY = 0,
+ double shiftZ = 0,
+ double scale = 1.0,
+ bool withColors = true,
+ bool withIntensity = true,
+ int? declaredIntensityCount = null,
+ double[]? matrix16 = null,
+ IReadOnlyDictionary? doubleProperties = null,
+ bool truncatePoints = false,
+ bool truncateColorBlock = false)
+ {
+ Span u32Buf = stackalloc byte[4];
+
+ // 3. Entity header: f1 (257), f2 (0), id
BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 257);
ms.Write(u32Buf);
BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 0);
ms.Write(u32Buf);
- BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 100);
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, id);
ms.Write(u32Buf);
// Name (UTF-16 BE)
@@ -3050,9 +3115,15 @@ public static byte[] CreateSyntheticCcBin(
}
if (truncatePoints)
- return ms.ToArray();
+ return;
// 8. Colors
+ if (truncateColorBlock)
+ {
+ ms.WriteByte(0x01); // color flag declared, but stream ends immediately
+ return;
+ }
+
if (withColors)
{
ms.WriteByte(0x01); // color flag
@@ -3128,16 +3199,21 @@ public static byte[] CreateSyntheticCcBin(
ms.Write(nameBuf256);
ms.WriteByte(0x01); // flag
- BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, (uint)points.Count);
+ int actualIntensityCount = declaredIntensityCount ?? points.Count;
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, (uint)actualIntensityCount);
ms.Write(u32Buf);
Span fltBuf = stackalloc byte[4];
- for (int i = 0; i < points.Count; i++)
+ for (int i = 0; i < actualIntensityCount; i++)
{
- var pt = points[i];
- BinaryPrimitives.WriteSingleLittleEndian(fltBuf, pt.Intensity ?? 0f);
+ float val = i < points.Count ? (points[i].Intensity ?? 0f) : 0f;
+ BinaryPrimitives.WriteSingleLittleEndian(fltBuf, val);
ms.Write(fltBuf);
}
+
+ // Write 4 trailing bytes with float value 99f to ensure reading past actualIntensityCount would read 99
+ BinaryPrimitives.WriteSingleLittleEndian(fltBuf, 99f);
+ ms.Write(fltBuf);
}
else
{
@@ -3145,7 +3221,5 @@ public static byte[] CreateSyntheticCcBin(
BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 0);
ms.Write(u32Buf);
}
-
- return ms.ToArray();
}
}
From 0d9065f9069a0b0ebe0326f4bb2b182c873375e8 Mon Sep 17 00:00:00 2001
From: mahach666 <79989386+mahach666@users.noreply.github.com>
Date: Wed, 18 Nov 2026 18:26:51 +0000
Subject: [PATCH 3/4] Fix Potree detection precedence, truncated scalar
validation, and transform matrix composition (#37)
---
src/PclIO/Formats/CcBin/CcBinDocument.cs | 64 ++++++++++++++++++----
src/PclIO/Internal/KindDetector.cs | 22 ++++----
tests/PclIO.Tests/FormatTests.cs | 68 ++++++++++++++++++++++++
tests/PclIO.Tests/KindDetectionTests.cs | 15 +++---
tests/PclIO.Tests/SyntheticFixtures.cs | 15 ++++--
5 files changed, 155 insertions(+), 29 deletions(-)
diff --git a/src/PclIO/Formats/CcBin/CcBinDocument.cs b/src/PclIO/Formats/CcBin/CcBinDocument.cs
index e336dc6..5f5c5c9 100644
--- a/src/PclIO/Formats/CcBin/CcBinDocument.cs
+++ b/src/PclIO/Formats/CcBin/CcBinDocument.cs
@@ -301,15 +301,19 @@ private bool TryParsePointCloud(
byte[] sCountBuf = new byte[4];
for (int s = 0; s < sfCount; s++)
{
- if (fs.Position + 256 + 5 > fileLength) break;
- if (fs.Read(sfNameBuf) < 256) break;
+ if (fs.Position + 256 + 5 > fileLength)
+ throw new InvalidDataException("CC BIN scalar field header is truncated.");
+ if (fs.Read(sfNameBuf) < 256)
+ throw new InvalidDataException("CC BIN scalar field header is truncated.");
string sfName = Encoding.ASCII.GetString(sfNameBuf).TrimEnd('\0');
int sFlag = fs.ReadByte();
- if (sFlag < 0 || fs.Read(sCountBuf) < 4) break;
+ if (sFlag < 0 || fs.Read(sCountBuf) < 4)
+ throw new InvalidDataException($"CC BIN scalar field '{sfName}' count is truncated.");
uint sCount = BinaryPrimitives.ReadUInt32LittleEndian(sCountBuf);
long dataOffset = fs.Position;
long sBytes = (long)sCount * 4;
- if (dataOffset + sBytes > fileLength) break;
+ if (dataOffset + sBytes > fileLength)
+ throw new InvalidDataException($"CC BIN scalar field '{sfName}' data is truncated.");
if (!hasIntensity && sfName.Equals("Intensity", StringComparison.OrdinalIgnoreCase))
{
@@ -334,13 +338,53 @@ private bool TryParsePointCloud(
// Therefore, to recover the original (global) coordinate from stored local coordinate:
// P_original = P_local / Scale - Shift
// In PclTransform: P_transformed = P_local * Transform.Scale + Transform.Translation
- double invScale = Math.Abs(scale) > 1e-12 ? (1.0 / scale) : 1.0;
- var transform = new PclTransform
+ double invScale = (scale != 0.0 && !double.IsNaN(scale) && !double.IsInfinity(scale))
+ ? (1.0 / scale)
+ : 1.0;
+
+ PclTransform transform;
+ if (!isIdentity)
+ {
+ // When a 4x4 matrix M is present, it must be composed with the global shift and scale:
+ // P_world = (M * P_local) * invScale - Shift
+ // Row i: combined[i, j] = invScale * M[i, j], and combined[i, 3] = invScale * M[i, 3] - Shift[i]
+ var combined = new double[16];
+ combined[0] = invScale * matrix16[0];
+ combined[1] = invScale * matrix16[1];
+ combined[2] = invScale * matrix16[2];
+ combined[3] = invScale * matrix16[3] - sx;
+
+ combined[4] = invScale * matrix16[4];
+ combined[5] = invScale * matrix16[5];
+ combined[6] = invScale * matrix16[6];
+ combined[7] = invScale * matrix16[7] - sy;
+
+ combined[8] = invScale * matrix16[8];
+ combined[9] = invScale * matrix16[9];
+ combined[10] = invScale * matrix16[10];
+ combined[11] = invScale * matrix16[11] - sz;
+
+ combined[12] = 0.0;
+ combined[13] = 0.0;
+ combined[14] = 0.0;
+ combined[15] = 1.0;
+
+ transform = new PclTransform
+ {
+ Scale = new PclVector3(invScale, invScale, invScale),
+ Translation = new PclVector3(-sx, -sy, -sz),
+ Matrix4x4 = combined,
+ };
+ }
+ else
{
- Scale = new PclVector3(invScale, invScale, invScale),
- Translation = new PclVector3(-sx, -sy, -sz),
- Matrix4x4 = isIdentity ? null : matrix16,
- };
+ transform = new PclTransform
+ {
+ Scale = new PclVector3(invScale, invScale, invScale),
+ Translation = new PclVector3(-sx, -sy, -sz),
+ Matrix4x4 = null,
+ };
+ }
string scanId = scanIndex.ToString(CultureInfo.InvariantCulture);
scan = new CcBinScan(
diff --git a/src/PclIO/Internal/KindDetector.cs b/src/PclIO/Internal/KindDetector.cs
index 788d196..2784566 100644
--- a/src/PclIO/Internal/KindDetector.cs
+++ b/src/PclIO/Internal/KindDetector.cs
@@ -83,14 +83,6 @@ public static PclFileKind Detect(string path)
: Path.GetExtension(path).ToLowerInvariant();
if (ext == ".bin")
{
- using (var probeStream = File.OpenRead(path))
- {
- Span probeHead = stackalloc byte[24];
- int probeRead = probeStream.ReadAtLeast(probeHead, 24, throwOnEndOfStream: false);
- if (probeRead >= 24 && IsCcBinStructure(probeHead))
- return PclFileKind.CcBin;
- }
-
string? dir = Path.GetDirectoryName(Path.GetFullPath(path));
for (int depth = 0; depth < 5 && dir != null; depth++)
{
@@ -100,6 +92,14 @@ public static PclFileKind Detect(string path)
if (parent == dir) break;
dir = parent;
}
+
+ using (var probeStream = File.OpenRead(path))
+ {
+ Span probeHead = stackalloc byte[24];
+ int probeRead = probeStream.ReadAtLeast(probeHead, 24, throwOnEndOfStream: false);
+ if (probeRead >= 24 && IsCcBinStructure(probeHead))
+ return PclFileKind.CcBin;
+ }
}
using var stream = File.OpenRead(path);
@@ -1329,7 +1329,11 @@ private static bool IsCcBinStructure(ReadOnlySpan head)
return false;
uint entityType = BinaryPrimitives.ReadUInt32LittleEndian(head[8..12]);
- if (entityType is < 1 or > 2000)
+ if (entityType is not (1 or 257 or 33 or 34 or 65))
+ return false;
+
+ uint f2 = BinaryPrimitives.ReadUInt32LittleEndian(head[12..16]);
+ if (f2 != 0)
return false;
uint nameLen = BinaryPrimitives.ReadUInt32BigEndian(head[20..24]);
diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs
index 87d8312..0807d40 100644
--- a/tests/PclIO.Tests/FormatTests.cs
+++ b/tests/PclIO.Tests/FormatTests.cs
@@ -6479,6 +6479,74 @@ public void Cc_Bin_Rejects_Truncated_Color_Block()
Assert.Throws(() => CcBinDocument.Open(path));
}
+ [Fact]
+ public void Cc_Bin_Rejects_Truncated_Scalar_Field_Data()
+ {
+ using var dir = new TempDirectory();
+ var samplePoints = new List { new(1.0, 2.0, 3.0), new(4.0, 5.0, 6.0) };
+
+ // 2 points declared in scalar field, but stream truncated after 1 value
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin(samplePoints, truncateIntensityData: true);
+ string path = dir.Write("cut_scalar.bin", bytes);
+
+ Assert.Throws(() => CcBinDocument.Open(path));
+ }
+
+ [Fact]
+ public void Cc_Bin_Transforms_With_Tiny_Scale()
+ {
+ using var dir = new TempDirectory();
+ var samplePoints = new List { new(1.0, 0.0, 0.0) };
+
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin(
+ samplePoints,
+ scale: 1e-13);
+
+ string path = dir.Write("tiny_scale.bin", bytes);
+ using var doc = CcBinDocument.Open(path);
+ var scan = doc.Scans[0];
+
+ var point = scan.ReadPoints(new PclReadOptions { ApplyTransform = true }).First();
+ Assert.Equal(1e13, point.X, precision: 1);
+ }
+
+ [Fact]
+ public void Cc_Bin_Composes_Transform_Matrix_With_Shift_And_Scale()
+ {
+ using var dir = new TempDirectory();
+ var samplePoints = new List { new(0.0, 0.0, 0.0) };
+
+ // Rotation around X (4x4 matrix):
+ // 1 0 0 0
+ // 0 0 -1 0
+ // 0 1 0 0
+ // 0 0 0 1
+ double[] rotX =
+ [
+ 1, 0, 0, 0,
+ 0, 0, -1, 0,
+ 0, 1, 0, 0,
+ 0, 0, 0, 1
+ ];
+
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin(
+ samplePoints,
+ shiftX: 10.0,
+ shiftY: 0.0,
+ shiftZ: 0.0,
+ scale: 1.0,
+ matrix16: rotX);
+
+ string path = dir.Write("rot_shift.bin", bytes);
+ using var doc = CcBinDocument.Open(path);
+ var scan = doc.Scans[0];
+
+ var point = scan.ReadPoints(new PclReadOptions { ApplyTransform = true }).First();
+ // Point is (0, 0, 0). After rotation around X: (0, 0, 0).
+ // Then global shift and scale: P_global = P_rot / 1.0 - shiftX = 0 - 10 = -10.
+ Assert.Equal(-10.0, point.X, precision: 4);
+ }
+
[Fact]
public void Cc_Bin_Supports_Subsample_And_MaxPoints()
{
diff --git a/tests/PclIO.Tests/KindDetectionTests.cs b/tests/PclIO.Tests/KindDetectionTests.cs
index a47dea1..aa5f6f4 100644
--- a/tests/PclIO.Tests/KindDetectionTests.cs
+++ b/tests/PclIO.Tests/KindDetectionTests.cs
@@ -574,14 +574,17 @@ public void Potree_Node_With_Cc_Magic_Coordinates_Is_Detected_As_Potree_Near_Man
{
using var tempDir = new TempDirectory();
// Write cloud.js manifest
- tempDir.Write("cloud.js", "{ \"version\": \"1.7\", \"octreeDir\": \"data\", \"points\": 1 }"u8.ToArray());
+ tempDir.Write("cloud.js", "{ \"version\": \"1.7\", \"octreeDir\": \"data\", \"points\": 2 }"u8.ToArray());
- // Create an r.bin where the first 4 coordinate bytes happen to match CCB2 ("CCB2"),
- // but remaining bytes are raw Potree point coordinates and not CC BIN structure.
+ // Create an r.bin of 2 points whose raw bytes happen to match CC BIN header structure
+ // (CCB2, version=1, entityType=1, f2=0, flags=0, nameLen=0).
byte[] potreeNode = new byte[32];
- "CCB2"u8.CopyTo(potreeNode.AsSpan(0, 4)); // X coordinate
- BinaryPrimitives.WriteInt32LittleEndian(potreeNode.AsSpan(4, 4), 500000); // Y coordinate
- BinaryPrimitives.WriteInt32LittleEndian(potreeNode.AsSpan(8, 4), 600000); // Z coordinate
+ "CCB2"u8.CopyTo(potreeNode.AsSpan(0, 4));
+ BinaryPrimitives.WriteUInt32LittleEndian(potreeNode.AsSpan(4, 4), 1);
+ BinaryPrimitives.WriteUInt32LittleEndian(potreeNode.AsSpan(8, 4), 1);
+ BinaryPrimitives.WriteUInt32LittleEndian(potreeNode.AsSpan(12, 4), 0);
+ BinaryPrimitives.WriteUInt32LittleEndian(potreeNode.AsSpan(16, 4), 0);
+ BinaryPrimitives.WriteUInt32LittleEndian(potreeNode.AsSpan(20, 4), 0);
string rBinPath = tempDir.Write("data/r/r.bin", potreeNode);
Assert.Equal(PclFileKind.Potree, PclFile.DetectKind(rBinPath));
diff --git a/tests/PclIO.Tests/SyntheticFixtures.cs b/tests/PclIO.Tests/SyntheticFixtures.cs
index 48e6377..2e6e593 100644
--- a/tests/PclIO.Tests/SyntheticFixtures.cs
+++ b/tests/PclIO.Tests/SyntheticFixtures.cs
@@ -2960,6 +2960,7 @@ public static byte[] CreateSyntheticCcBin(
byte[]? rawMagic = null,
bool truncatePoints = false,
bool truncateColorBlock = false,
+ bool truncateIntensityData = false,
int? declaredIntensityCount = null)
{
using var ms = new MemoryStream();
@@ -2987,7 +2988,8 @@ public static byte[] CreateSyntheticCcBin(
matrix16: matrix16,
doubleProperties: doubleProperties,
truncatePoints: truncatePoints,
- truncateColorBlock: truncateColorBlock);
+ truncateColorBlock: truncateColorBlock,
+ truncateIntensityData: truncateIntensityData);
return ms.ToArray();
}
@@ -3031,7 +3033,8 @@ private static void WriteCcBinCloudEntity(
double[]? matrix16 = null,
IReadOnlyDictionary? doubleProperties = null,
bool truncatePoints = false,
- bool truncateColorBlock = false)
+ bool truncateColorBlock = false,
+ bool truncateIntensityData = false)
{
Span u32Buf = stackalloc byte[4];
@@ -3199,18 +3202,22 @@ private static void WriteCcBinCloudEntity(
ms.Write(nameBuf256);
ms.WriteByte(0x01); // flag
- int actualIntensityCount = declaredIntensityCount ?? points.Count;
+ int actualIntensityCount = declaredIntensityCount ?? (truncateIntensityData ? 2 : points.Count);
BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, (uint)actualIntensityCount);
ms.Write(u32Buf);
Span fltBuf = stackalloc byte[4];
- for (int i = 0; i < actualIntensityCount; i++)
+ int toWrite = truncateIntensityData ? 1 : actualIntensityCount;
+ for (int i = 0; i < toWrite; i++)
{
float val = i < points.Count ? (points[i].Intensity ?? 0f) : 0f;
BinaryPrimitives.WriteSingleLittleEndian(fltBuf, val);
ms.Write(fltBuf);
}
+ if (truncateIntensityData)
+ return;
+
// Write 4 trailing bytes with float value 99f to ensure reading past actualIntensityCount would read 99
BinaryPrimitives.WriteSingleLittleEndian(fltBuf, 99f);
ms.Write(fltBuf);
From ecf2e15f4cf983ca7e130548cb536a1393f93fbd Mon Sep 17 00:00:00 2001
From: mahach666 <79989386+mahach666@users.noreply.github.com>
Date: Wed, 18 Nov 2026 19:47:45 +0000
Subject: [PATCH 4/4] Fix CC BIN scalar metadata and coordinate edge cases
---
README.md | 4 +-
docs/public-api.md | 2 +-
src/PclIO/Formats/CcBin/CcBinDocument.cs | 195 +++++++++++----------
src/PclIO/Formats/CcBin/CcBinScan.cs | 20 +--
src/PclIO/Formats/Potree/PotreeDocument.cs | 6 +-
src/PclIO/Internal/KindDetector.cs | 28 +--
src/PclIO/Model/PclTransform.cs | 23 ++-
tests/PclIO.Tests/FormatTests.cs | 74 ++++++++
tests/PclIO.Tests/KindDetectionTests.cs | 41 +++--
9 files changed, 247 insertions(+), 146 deletions(-)
diff --git a/README.md b/README.md
index cfe5be9..21e52cb 100644
--- a/README.md
+++ b/README.md
@@ -55,7 +55,7 @@ The library targets .NET 8 and .NET 10. It is managed code with no dependencies
| COPC | `.copc.laz`, `.laz` | Cloud Optimized Point Cloud (COPC octree in LAS 1.4 / LAZ): reads the octree hierarchy (root and sub-hierarchy pages) and voxel bounding boxes, center, halfsize and spacing metadata, streaming points by octree node, bounding box or across the whole dataset. LAS formats 0 to 3 are fully decompressed via LASzip arithmetic decoding; LAS 1.4 formats 6 to 8 decode uncompressed anchor points with exact positions, intensity, classification and RGB colour per octree node. |
| EPT | `ept.json`, `.laz`, `.bin`, `.zst` | Entwine Point Tile (EPT octree datasets): reads dataset manifest (`ept.json`), octree hierarchy (`ept-hierarchy/`), and point data tiles (`ept-data/`) across `"laszip"`, `"binary"`, and `"zstandard"` storage types. Supports schema dimension extraction (XYZ, intensity, classification, RGB colour, normals), spatial querying by bounding box (`FindNodes`, `ReadPoints`), depth filtering, and single-node streaming. |
| Leica PTG | `.ptg` | Leica Cyclone gridded binary exchange point clouds: binary scan files (`.ptg`) with 8-byte signature and magic (`0x928FA3C7`), ASCII metadata header (`NumRows`, `NumCols`, `%%properties`, `%%transform`), column offset array, and column validity bitmasks with single or double precision Cartesian XYZ coordinates, intensity [0..1] and 8-bit RGB colour. Top-level ASCII index files (`.ptg`) referencing binary scan files are aggregated into multi-scan documents. Coordinate transforms applied unless `ApplyTransform` is false. |
-| CC BIN | `.bin` | CC BIN binary entity files (`*.bin`, signature `CCB2`): single or multi-cloud datasets with 32-bit floating point Cartesian XYZ coordinates, global shift and scale vectors, 8-bit RGB colour arrays, 4x4 coordinate transform matrices, and scalar fields (including intensity). Coordinates are transformed by global shift and scale ($P_{original} = P_{local} / \text{scale} - \text{shift}$) unless `ApplyTransform` is false. Points with non-finite coordinates are skipped. Normals in modern CC entity files use quantized spherical sector indices (`ccNormalCompressor`), which has no open public specification and is not decoded under clean-room rules (`HasNormals = false`). |
+| CC BIN | `.bin` | CC BIN binary entity files (`*.bin`, signature `CCB2`): single or multi-cloud datasets with 32-bit floating point Cartesian XYZ coordinates, global shift and scale vectors, 8-bit RGB colour arrays, 4x4 coordinate transform matrices, and scalar fields (including intensity). The reader applies the stored matrix, divides by the global scale and subtracts the global shift unless `ApplyTransform` is false. Points with non-finite coordinates are skipped. Scalar values beyond the declared field length are absent. Normals are not decoded. |
### Format detection
@@ -65,7 +65,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` and `.copc.laz`. A LAZ file is recognised by the `LASF` signature, a valid LASzip VLR and the `.laz` extension. A COPC file is recognised by the LAS 1.4 header and the `copc` info variable length record with `.copc.laz` or any extension. A PCD file is recognised by its header structure with any extension. A PLY file is recognised by its magic word and header structure with any extension. A PTS file is recognised by an integer point count header line followed by coordinate lines with any extension, or coordinate lines with the `.pts` extension. A PTX file is recognised by its 10-line header structure (grid dimensions, scanner pose, 4x4 matrix) with any extension. An XYZ / delimited text file is recognised by an explicit column header containing X, Y, Z in any extension, or by numeric coordinate lines with a recognised extension (`.xyz`, `.asc`, `.txt`, `.csv`). An SBF file is recognised by its companion `[SBF]` header structure with any extension, or by the binary signature `0x2A, 0x2A` (`**`) and record size formula (`.sbf`, `.sbf.data`, `.data`). A 3D Tiles `.pnts` tile is recognised by the `pnts` signature, version 1, and matching byte lengths. A glTF `.glb` point cloud is recognised by the `glTF` signature, version 2, and mesh primitive mode 0 (POINTS). A 3D Tiles tileset is recognised by JSON containing `asset` and `root` objects (`tileset.json`). A Potree dataset is recognised by `cloud.js` (with `octreeDir` and attribute descriptors) or `metadata.json` (version 2.x and point attributes) in `.js` or `.json`, by `.hrc` hierarchy files with 5-byte node records, or by ancestor `cloud.js`/`metadata.json` next to a `.bin` file. An EPT dataset is recognised by `ept.json` manifest structure (bounds, dataType, schema) or by companion `ept.json` next to octree tiles. A Leica PTG binary scan file is recognised by the `PTG\0` tag and magic number `0x928FA3C7` with any extension; a top-level ASCII index file is recognised by the `PTG index` header and the `.ptg` extension. A CC BIN file is recognised by the `CCB2` signature and entity header structure with any extension; a `.bin` file without this structure is reported as Potree when next to an octree manifest or unknown.
+ A LAS file is recognised by the `LASF` signature with any extension except `.laz` and `.copc.laz`. A LAZ file is recognised by the `LASF` signature, a valid LASzip VLR and the `.laz` extension. A COPC file is recognised by the LAS 1.4 header and the `copc` info variable length record with `.copc.laz` or any extension. A PCD file is recognised by its header structure with any extension. A PLY file is recognised by its magic word and header structure with any extension. A PTS file is recognised by an integer point count header line followed by coordinate lines with any extension, or coordinate lines with the `.pts` extension. A PTX file is recognised by its 10-line header structure (grid dimensions, scanner pose, 4x4 matrix) with any extension. An XYZ / delimited text file is recognised by an explicit column header containing X, Y, Z in any extension, or by numeric coordinate lines with a recognised extension (`.xyz`, `.asc`, `.txt`, `.csv`). An SBF file is recognised by its companion `[SBF]` header structure with any extension, or by the binary signature `0x2A, 0x2A` (`**`) and record size formula (`.sbf`, `.sbf.data`, `.data`). A 3D Tiles `.pnts` tile is recognised by the `pnts` signature, version 1, and matching byte lengths. A glTF `.glb` point cloud is recognised by the `glTF` signature, version 2, and mesh primitive mode 0 (POINTS). A 3D Tiles tileset is recognised by JSON containing `asset` and `root` objects (`tileset.json`). A Potree dataset is recognised by `cloud.js` (with `octreeDir` and attribute descriptors) or `metadata.json` (version 2.x and point attributes) in `.js` or `.json`, by `.hrc` hierarchy files with 5-byte node records, or by ancestor `cloud.js`/`metadata.json` next to a `.bin` file. An EPT dataset is recognised by `ept.json` manifest structure (bounds, dataType, schema) or by companion `ept.json` next to octree tiles. A Leica PTG binary scan file is recognised by the `PTG\0` tag and magic number `0x928FA3C7` with any extension; a top-level ASCII index file is recognised by the `PTG index` header and the `.ptg` extension. A CC BIN file is recognised by the `CCB2` signature and entity header structure with any extension; a recognised Potree manifest in an ancestor directory takes precedence for `.bin` files.
- 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
diff --git a/docs/public-api.md b/docs/public-api.md
index e9af4a4..1c985f8 100644
--- a/docs/public-api.md
+++ b/docs/public-api.md
@@ -45,7 +45,7 @@ is the argument, which may also be a file name.
`Potree` is recognised by `cloud.js` (with `octreeDir` and attribute descriptors) or `metadata.json` (version 2.x and point attributes) in `.js` or `.json`, by `.hrc` hierarchy files with 5-byte node records, or by ancestor `cloud.js`/`metadata.json` next to a `.bin` file.
`Ept` is recognised by `ept.json` manifest structure (bounds, dataType, schema) or by companion `ept.json` next to octree tiles.
`LeicaPtg` is recognised by the `PTG\0` tag and magic number `0x928FA3C7` with any extension, or by the `PTG index` header with the `.ptg` extension.
- `CcBin` is recognised by the `CCB2` signature and entity header structure with any extension; a `.bin` file without this structure is reported as `Potree` when next to an octree manifest or `Unknown`.
+ `CcBin` is recognised by the `CCB2` signature and entity header structure with any extension; a recognised Potree manifest in an ancestor directory takes precedence for `.bin` files.
- `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
diff --git a/src/PclIO/Formats/CcBin/CcBinDocument.cs b/src/PclIO/Formats/CcBin/CcBinDocument.cs
index 5f5c5c9..8e46144 100644
--- a/src/PclIO/Formats/CcBin/CcBinDocument.cs
+++ b/src/PclIO/Formats/CcBin/CcBinDocument.cs
@@ -207,7 +207,8 @@ private bool TryParsePointCloud(
double sy = BinaryPrimitives.ReadDoubleLittleEndian(ccHead.AsSpan(16, 8));
double sz = BinaryPrimitives.ReadDoubleLittleEndian(ccHead.AsSpan(24, 8));
double scale = BinaryPrimitives.ReadDoubleLittleEndian(ccHead.AsSpan(32, 8));
- if (scale == 0 || !double.IsFinite(scale)) scale = 1.0;
+ if (scale == 0 || !double.IsFinite(scale) || !double.IsFinite(sx) || !double.IsFinite(sy) || !double.IsFinite(sz))
+ throw FormatError.Corrupted("CC BIN has an invalid global shift or scale.");
byte[] countBuf = new byte[4];
if (fs.Read(countBuf) < 4) return false;
@@ -273,6 +274,8 @@ private bool TryParsePointCloud(
for (int m = 0; m < 16; m++)
{
float val = BinaryPrimitives.ReadSingleLittleEndian(matH.AsSpan(8 + m * 4, 4));
+ if (!float.IsFinite(val))
+ throw FormatError.Corrupted("CC BIN has a non-finite coordinate matrix.");
matrix16[m] = val;
int row = m / 4;
int col = m % 4;
@@ -285,105 +288,34 @@ private bool TryParsePointCloud(
}
// Scalar fields (probe for Intensity)
- bool hasIntensity = false;
long intensityOffset = -1;
uint intensityCount = 0;
- int sfFlag = fs.ReadByte();
- if (sfFlag >= 0)
+ if (fs.ReadByte() >= 0)
{
- byte[] sfCountBuf = new byte[4];
- if (fs.Read(sfCountBuf) == 4)
+ Span countBytes = stackalloc byte[4];
+ ReadScalarBytes(fs, countBytes);
+ uint fieldCount = BinaryPrimitives.ReadUInt32LittleEndian(countBytes);
+ if (fieldCount >= 100)
+ throw FormatError.Unsupported("CC BIN has 100 or more scalar fields.");
+
+ Span fieldHeader = stackalloc byte[261];
+ for (uint field = 0; field < fieldCount; field++)
{
- uint sfCount = BinaryPrimitives.ReadUInt32LittleEndian(sfCountBuf);
- if (sfCount is > 0 and < 100)
+ ReadScalarBytes(fs, fieldHeader);
+ uint valueCount = BinaryPrimitives.ReadUInt32LittleEndian(fieldHeader[257..]);
+ long dataOffset = fs.Position;
+ SkipScalarBytes(fs, (long)valueCount * sizeof(float));
+
+ if (intensityOffset < 0 &&
+ Encoding.ASCII.GetString(fieldHeader[..256]).TrimEnd('\0').Equals("Intensity", StringComparison.OrdinalIgnoreCase))
{
- byte[] sfNameBuf = new byte[256];
- byte[] sCountBuf = new byte[4];
- for (int s = 0; s < sfCount; s++)
- {
- if (fs.Position + 256 + 5 > fileLength)
- throw new InvalidDataException("CC BIN scalar field header is truncated.");
- if (fs.Read(sfNameBuf) < 256)
- throw new InvalidDataException("CC BIN scalar field header is truncated.");
- string sfName = Encoding.ASCII.GetString(sfNameBuf).TrimEnd('\0');
- int sFlag = fs.ReadByte();
- if (sFlag < 0 || fs.Read(sCountBuf) < 4)
- throw new InvalidDataException($"CC BIN scalar field '{sfName}' count is truncated.");
- uint sCount = BinaryPrimitives.ReadUInt32LittleEndian(sCountBuf);
- long dataOffset = fs.Position;
- long sBytes = (long)sCount * 4;
- if (dataOffset + sBytes > fileLength)
- throw new InvalidDataException($"CC BIN scalar field '{sfName}' data is truncated.");
-
- if (!hasIntensity && sfName.Equals("Intensity", StringComparison.OrdinalIgnoreCase))
- {
- hasIntensity = true;
- intensityOffset = dataOffset;
- intensityCount = sCount;
- }
-
- fs.Position += sBytes;
- if (s + 1 < sfCount)
- {
- fs.Position += 219; // Skip color scale / metadata
- }
- }
+ intensityOffset = dataOffset;
+ intensityCount = valueCount;
}
- }
- }
- // Construct transform:
- // According to Global Shift and Scale mathematics:
- // P_shifted = (P_original + Shift) * Scale
- // Therefore, to recover the original (global) coordinate from stored local coordinate:
- // P_original = P_local / Scale - Shift
- // In PclTransform: P_transformed = P_local * Transform.Scale + Transform.Translation
- double invScale = (scale != 0.0 && !double.IsNaN(scale) && !double.IsInfinity(scale))
- ? (1.0 / scale)
- : 1.0;
-
- PclTransform transform;
- if (!isIdentity)
- {
- // When a 4x4 matrix M is present, it must be composed with the global shift and scale:
- // P_world = (M * P_local) * invScale - Shift
- // Row i: combined[i, j] = invScale * M[i, j], and combined[i, 3] = invScale * M[i, 3] - Shift[i]
- var combined = new double[16];
- combined[0] = invScale * matrix16[0];
- combined[1] = invScale * matrix16[1];
- combined[2] = invScale * matrix16[2];
- combined[3] = invScale * matrix16[3] - sx;
-
- combined[4] = invScale * matrix16[4];
- combined[5] = invScale * matrix16[5];
- combined[6] = invScale * matrix16[6];
- combined[7] = invScale * matrix16[7] - sy;
-
- combined[8] = invScale * matrix16[8];
- combined[9] = invScale * matrix16[9];
- combined[10] = invScale * matrix16[10];
- combined[11] = invScale * matrix16[11] - sz;
-
- combined[12] = 0.0;
- combined[13] = 0.0;
- combined[14] = 0.0;
- combined[15] = 1.0;
-
- transform = new PclTransform
- {
- Scale = new PclVector3(invScale, invScale, invScale),
- Translation = new PclVector3(-sx, -sy, -sz),
- Matrix4x4 = combined,
- };
- }
- else
- {
- transform = new PclTransform
- {
- Scale = new PclVector3(invScale, invScale, invScale),
- Translation = new PclVector3(-sx, -sy, -sz),
- Matrix4x4 = null,
- };
+ if (field + 1 < fieldCount)
+ SkipScalarMetadata(fs);
+ }
}
string scanId = scanIndex.ToString(CultureInfo.InvariantCulture);
@@ -396,17 +328,90 @@ private bool TryParsePointCloud(
hasColors: hasColors,
colorOffset: colorOffset,
colorChannels: channels,
- hasIntensity: hasIntensity,
intensityOffset: intensityOffset,
intensityCount: intensityCount,
shiftX: sx,
shiftY: sy,
shiftZ: sz,
scale: scale,
- transform: transform,
+ transform: CreateTransform(scale, new PclVector3(-sx, -sy, -sz), isIdentity ? null : matrix16),
properties: props);
pointsEndOffset = Math.Max(pointsEndOffset, fs.Position);
return true;
}
+
+ private static void SkipScalarMetadata(FileStream fs)
+ {
+ SkipScalarBytes(fs, 52); // Display ranges and flags before the optional palette.
+ int hasPalette = fs.ReadByte();
+ if (hasPalette < 0)
+ throw FormatError.Truncated("CC BIN scalar field metadata");
+ if (hasPalette > 1)
+ throw FormatError.Corrupted("CC BIN scalar field palette flag is invalid.");
+
+ if (hasPalette == 1)
+ {
+ Span word = stackalloc byte[4];
+ for (int i = 0; i < 2; i++)
+ {
+ ReadScalarBytes(fs, word);
+ uint byteLength = BinaryPrimitives.ReadUInt32BigEndian(word);
+ if (byteLength == uint.MaxValue) continue;
+ if (byteLength > 4096 || (byteLength & 1) != 0)
+ throw FormatError.Corrupted("CC BIN scalar field palette string has an invalid byte length.");
+ SkipScalarBytes(fs, byteLength);
+ }
+
+ SkipScalarBytes(fs, 18); // Palette settings before the step count.
+ ReadScalarBytes(fs, word);
+ uint steps = BinaryPrimitives.ReadUInt32LittleEndian(word);
+ if (steps > 4096)
+ throw FormatError.Unsupported("CC BIN scalar field palette exceeds 4096 steps.");
+ SkipScalarBytes(fs, steps * 19L); // Position and colour for each palette step.
+ }
+
+ SkipScalarBytes(fs, 16);
+ }
+
+ private static void ReadScalarBytes(FileStream fs, Span buffer)
+ {
+ if (fs.ReadAtLeast(buffer, buffer.Length, throwOnEndOfStream: false) != buffer.Length)
+ throw FormatError.Truncated("CC BIN scalar field header or metadata");
+ }
+
+ private static void SkipScalarBytes(FileStream fs, long bytes)
+ {
+ if (bytes > fs.Length - fs.Position)
+ throw FormatError.Truncated("CC BIN scalar field data or metadata");
+ fs.Position += bytes;
+ }
+
+ private static PclTransform CreateTransform(double scale, PclVector3 translation, double[]? matrix)
+ {
+ // Divide the local coordinates before shifting them back to the original coordinate system.
+ double inverse = 1.0 / scale;
+ double[]? combined = null;
+ if (matrix != null && double.IsFinite(inverse))
+ {
+ combined = new double[16];
+ for (int i = 0; i < 12; i++)
+ combined[i] = inverse * matrix[i];
+ combined[3] += translation.X;
+ combined[7] += translation.Y;
+ combined[11] += translation.Z;
+ combined[15] = 1.0;
+ }
+
+ // The point divided by scale can be finite even when a composed coefficient overflows.
+ if (!double.IsFinite(inverse) || (combined != null && combined.Any(static x => !double.IsFinite(x))))
+ return new PclTransform { UniformScaleDivisor = scale, Translation = translation, Matrix4x4 = matrix };
+
+ return new PclTransform
+ {
+ Scale = new PclVector3(inverse, inverse, inverse),
+ Translation = translation,
+ Matrix4x4 = combined,
+ };
+ }
}
diff --git a/src/PclIO/Formats/CcBin/CcBinScan.cs b/src/PclIO/Formats/CcBin/CcBinScan.cs
index fa1d8e6..0d58ccc 100644
--- a/src/PclIO/Formats/CcBin/CcBinScan.cs
+++ b/src/PclIO/Formats/CcBin/CcBinScan.cs
@@ -15,7 +15,6 @@ public sealed class CcBinScan : PclScan
private readonly bool _hasColors;
private readonly long _colorOffset;
private readonly byte _colorChannels;
- private readonly bool _hasIntensity;
private readonly long _intensityOffset;
private readonly long _intensityCount;
private readonly double _shiftX;
@@ -36,12 +35,7 @@ public sealed class CcBinScan : PclScan
public override bool HasColors => _hasColors;
///
- public override bool HasIntensities => _hasIntensity && _intensityCount > 0;
-
- ///
- /// Modern CC entity files store normals using quantized spherical sector indices (ccNormalCompressor)
- /// which lacks a published open specification; under clean-room rules, normals are not decoded.
- public override bool HasNormals => false;
+ public override bool HasIntensities => _intensityCount > 0;
/// Global shift vector stored with the cloud entity.
public PclVector3 GlobalShift => new(_shiftX, _shiftY, _shiftZ);
@@ -58,7 +52,6 @@ internal CcBinScan(
bool hasColors,
long colorOffset,
byte colorChannels,
- bool hasIntensity,
long intensityOffset,
long intensityCount,
double shiftX,
@@ -76,7 +69,6 @@ internal CcBinScan(
_hasColors = hasColors;
_colorOffset = colorOffset;
_colorChannels = colorChannels;
- _hasIntensity = hasIntensity && intensityCount > 0;
_intensityOffset = intensityOffset;
_intensityCount = intensityCount;
_shiftX = shiftX;
@@ -87,7 +79,7 @@ internal CcBinScan(
_properties["TotalPoints"] = pointCount.ToString(CultureInfo.InvariantCulture);
_properties["HasColors"] = hasColors ? "true" : "false";
- _properties["HasIntensity"] = hasIntensity ? "true" : "false";
+ _properties["HasIntensity"] = HasIntensities ? "true" : "false";
_properties["GlobalShift"] = string.Create(CultureInfo.InvariantCulture, $"{shiftX:F6}, {shiftY:F6}, {shiftZ:F6}");
_properties["GlobalScale"] = scale.ToString(CultureInfo.InvariantCulture);
@@ -113,7 +105,7 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
byte[] ptBuf = new byte[BatchRecords * 12];
byte[]? colBuf = _hasColors ? new byte[BatchRecords * _colorChannels] : null;
- byte[]? intBuf = _hasIntensity ? new byte[BatchRecords * 4] : null;
+ byte[]? intBuf = HasIntensities ? new byte[BatchRecords * 4] : null;
long yielded = 0;
long pointIndex = 0;
@@ -138,7 +130,7 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
throw FormatError.Truncated($"CC BIN file ended prematurely while reading colors at index {pointIndex}.");
}
- if (_hasIntensity && intBuf != null)
+ if (intBuf != null)
{
long intAvailable = Math.Max(0, Math.Min(_intensityCount - pointIndex, toRead));
if (intAvailable > 0)
@@ -176,7 +168,7 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
}
float? intensity = null;
- if (_hasIntensity && intBuf != null && currentIdx < _intensityCount)
+ if (intBuf != null && currentIdx < _intensityCount)
{
int intByteOffset = p * 4;
float iVal = BinaryPrimitives.ReadSingleLittleEndian(intBuf.AsSpan(intByteOffset, 4));
@@ -190,6 +182,8 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
if (options.ApplyTransform && !Transform.IsIdentity)
{
pos = Transform.TransformPoint(pos);
+ if (!double.IsFinite(pos.X) || !double.IsFinite(pos.Y) || !double.IsFinite(pos.Z))
+ continue;
}
yield return new PclPoint(pos, Color: color, Intensity: intensity, Index: (ulong)yielded);
diff --git a/src/PclIO/Formats/Potree/PotreeDocument.cs b/src/PclIO/Formats/Potree/PotreeDocument.cs
index a62dd08..74a6d1f 100644
--- a/src/PclIO/Formats/Potree/PotreeDocument.cs
+++ b/src/PclIO/Formats/Potree/PotreeDocument.cs
@@ -25,7 +25,7 @@ namespace PclIO.Formats.Potree;
///
public sealed class PotreeDocument : PclDocument
{
- private const int MaxManifestBytes = 16 * 1024 * 1024; // 16 MB
+ private const int MaxManifestBytes = KindDetector.MaxPotreeManifestBytes;
///
public override PclFileKind Kind => PclFileKind.Potree;
@@ -132,11 +132,11 @@ public static PotreeDocument Open(string path, PclReadOptions? options = null)
for (int depth = 0; depth < 5 && dir != null; depth++)
{
string cjs = Path.Combine(dir, "cloud.js");
- if (File.Exists(cjs))
+ if (KindDetector.IsPotreeManifest(cjs))
return OpenPotree1x(cjs);
string mjs = Path.Combine(dir, "metadata.json");
- if (File.Exists(mjs))
+ if (KindDetector.IsPotreeManifest(mjs))
return OpenPotree2x(mjs);
string? parent = Path.GetDirectoryName(dir);
diff --git a/src/PclIO/Internal/KindDetector.cs b/src/PclIO/Internal/KindDetector.cs
index 2784566..c4e9011 100644
--- a/src/PclIO/Internal/KindDetector.cs
+++ b/src/PclIO/Internal/KindDetector.cs
@@ -11,6 +11,8 @@ namespace PclIO.Internal;
///
internal static class KindDetector
{
+ internal const int MaxPotreeManifestBytes = 16 * 1024 * 1024;
+
private static readonly byte[] E57Magic = "ASTM-E57"u8.ToArray();
// Container signatures at the start of the files the readers accept.
private static readonly byte[] LeicaMagic = "wild::geosystems"u8.ToArray();
@@ -86,20 +88,12 @@ public static PclFileKind Detect(string path)
string? dir = Path.GetDirectoryName(Path.GetFullPath(path));
for (int depth = 0; depth < 5 && dir != null; depth++)
{
- if (File.Exists(Path.Combine(dir, "cloud.js")) || File.Exists(Path.Combine(dir, "metadata.json")))
+ if (IsPotreeManifest(Path.Combine(dir, "cloud.js")) || IsPotreeManifest(Path.Combine(dir, "metadata.json")))
return PclFileKind.Potree;
string? parent = Path.GetDirectoryName(dir);
if (parent == dir) break;
dir = parent;
}
-
- using (var probeStream = File.OpenRead(path))
- {
- Span probeHead = stackalloc byte[24];
- int probeRead = probeStream.ReadAtLeast(probeHead, 24, throwOnEndOfStream: false);
- if (probeRead >= 24 && IsCcBinStructure(probeHead))
- return PclFileKind.CcBin;
- }
}
using var stream = File.OpenRead(path);
@@ -1103,8 +1097,16 @@ private static bool IsTilesetJsonHeader(Stream stream, long origin, string? exte
}
}
+ internal static bool IsPotreeManifest(string path)
+ {
+ if (!File.Exists(path)) return false;
+ using var stream = File.OpenRead(path);
+ return stream.Length <= MaxPotreeManifestBytes &&
+ IsPotreeJsonHeader(stream, 0, Path.GetExtension(path), MaxPotreeManifestBytes);
+ }
+
// Potree manifest: cloud.js (1.x) or metadata.json (2.x)
- private static bool IsPotreeJsonHeader(Stream stream, long origin, string? extension)
+ private static bool IsPotreeJsonHeader(Stream stream, long origin, string? extension, int maxProbeBytes = 8192)
{
if (extension != null && extension != ".js" && extension != ".json")
return false;
@@ -1112,7 +1114,7 @@ private static bool IsPotreeJsonHeader(Stream stream, long origin, string? exten
long length = stream.CanSeek ? stream.Length : long.MaxValue;
if (length - origin < 10) return false;
- int toRead = (int)Math.Min(8192, length - origin);
+ int toRead = (int)Math.Min(maxProbeBytes, length - origin);
byte[] buf = new byte[toRead];
stream.Position = origin;
try
@@ -1142,7 +1144,7 @@ private static bool IsPotreeJsonHeader(Stream stream, long origin, string? exten
}
// Potree 2.x (metadata.json)
- if (root.TryGetProperty("version", out var verElem) &&
+ if (root.TryGetProperty("version", out var verElem) && verElem.ValueKind == JsonValueKind.String &&
verElem.GetString() is { } v && v.StartsWith("2.") &&
root.TryGetProperty("points", out _) &&
(root.TryGetProperty("hierarchy", out _) || root.TryGetProperty("attributes", out _)))
@@ -1152,7 +1154,7 @@ private static bool IsPotreeJsonHeader(Stream stream, long origin, string? exten
return false;
}
- catch
+ catch (JsonException)
{
return false;
}
diff --git a/src/PclIO/Model/PclTransform.cs b/src/PclIO/Model/PclTransform.cs
index de7b01b..eeae09e 100644
--- a/src/PclIO/Model/PclTransform.cs
+++ b/src/PclIO/Model/PclTransform.cs
@@ -10,7 +10,11 @@ public sealed record PclTransform
public static PclTransform Identity { get; } = new();
/// True when translation and rotation are zero, scale is one and no matrix is set.
- public bool IsIdentity => Translation.IsZero && Rotation.IsZero && Scale == PclVector3.One && Matrix4x4 == null;
+ public bool IsIdentity => Translation.IsZero && Rotation.IsZero && Scale == PclVector3.One &&
+ UniformScaleDivisor == 1 && Matrix4x4 == null;
+
+ // Keep an otherwise unrepresentable reciprocal out of the stored scale or matrix.
+ internal double UniformScaleDivisor { get; init; } = 1;
/// Translation added after scaling; applied by when no matrix is set.
public PclVector3 Translation { get; init; } = PclVector3.Zero;
@@ -23,7 +27,7 @@ public sealed record PclTransform
///
/// Optional 4x4 row-major matrix (16 elements, translation in elements 3, 7 and 11), if the format stores one.
- /// When it has exactly 16 elements it replaces and .
+ /// When it has exactly 16 elements it normally replaces and .
///
public double[]? Matrix4x4 { get; init; }
@@ -36,15 +40,23 @@ public PclVector3 TransformPoint(PclVector3 local)
double x = local.X * m[0] + local.Y * m[1] + local.Z * m[2] + m[3];
double y = local.X * m[4] + local.Y * m[5] + local.Z * m[6] + m[7];
double z = local.X * m[8] + local.Y * m[9] + local.Z * m[10] + m[11];
- return new PclVector3(x, y, z);
+ return UniformScaleDivisor == 1 ? new PclVector3(x, y, z) : DivideAndTranslate(x, y, z);
}
+ if (UniformScaleDivisor != 1)
+ return DivideAndTranslate(local.X, local.Y, local.Z);
+
double sx = local.X * Scale.X + Translation.X;
double sy = local.Y * Scale.Y + Translation.Y;
double sz = local.Z * Scale.Z + Translation.Z;
return new PclVector3(sx, sy, sz);
}
+ private PclVector3 DivideAndTranslate(double x, double y, double z) => new(
+ x / UniformScaleDivisor + Translation.X,
+ y / UniformScaleDivisor + Translation.Y,
+ z / UniformScaleDivisor + Translation.Z);
+
///
/// Transforms a direction or normal without translation (matrix 3x3 part, otherwise per-axis scale; rotation is not applied)
/// and normalizes the result to unit length. A zero-length result returns the input unchanged.
@@ -52,19 +64,20 @@ public PclVector3 TransformPoint(PclVector3 local)
/// Direction in the scan's local space.
public PclVector3 TransformVector(PclVector3 vector)
{
+ int sign = UniformScaleDivisor < 0 ? -1 : 1;
if (Matrix4x4 is { Length: 16 } m)
{
double x = vector.X * m[0] + vector.Y * m[1] + vector.Z * m[2];
double y = vector.X * m[4] + vector.Y * m[5] + vector.Z * m[6];
double z = vector.X * m[8] + vector.Y * m[9] + vector.Z * m[10];
double len = Math.Sqrt(x * x + y * y + z * z);
- return len > 0 ? new PclVector3(x / len, y / len, z / len) : vector;
+ return len > 0 ? new PclVector3(x / len, y / len, z / len) * sign : vector;
}
double sx = vector.X * Scale.X;
double sy = vector.Y * Scale.Y;
double sz = vector.Z * Scale.Z;
double slen = Math.Sqrt(sx * sx + sy * sy + sz * sz);
- return slen > 0 ? new PclVector3(sx / slen, sy / slen, sz / slen) : vector;
+ return slen > 0 ? new PclVector3(sx / slen, sy / slen, sz / slen) * sign : vector;
}
}
diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs
index 0807d40..f38b287 100644
--- a/tests/PclIO.Tests/FormatTests.cs
+++ b/tests/PclIO.Tests/FormatTests.cs
@@ -6492,6 +6492,80 @@ public void Cc_Bin_Rejects_Truncated_Scalar_Field_Data()
Assert.Throws(() => CcBinDocument.Open(path));
}
+ [Fact]
+ public void Cc_Bin_Rejects_Truncated_Scalar_Field_Count()
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin([new(1, 2, 3)], withIntensity: false);
+ string path = dir.Write("cut_scalar_count.bin", bytes[..^2]);
+
+ Assert.Throws(() => CcBinDocument.Open(path));
+ }
+
+ [Theory]
+ [InlineData(false)]
+ [InlineData(true)]
+ public void Cc_Bin_Reads_Intensity_After_Scalar_Display_Metadata(bool withPalette)
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin([new(1, 2, 3, Intensity: 42)]);
+ int fieldStart = bytes.AsSpan().IndexOf("Intensity"u8);
+ System.Buffers.Binary.BinaryPrimitives.WriteUInt32LittleEndian(bytes.AsSpan(fieldStart - 4, 4), 2);
+ byte[] firstField = bytes[fieldStart..(fieldStart + 261 + sizeof(float))];
+ firstField.AsSpan(0, 256).Clear();
+ "Time"u8.CopyTo(firstField);
+
+ byte[] display = new byte[53];
+ byte[] palette = [];
+ if (withPalette)
+ {
+ display[^1] = 1;
+ byte[] nameAndId =
+ [
+ 0, 0, 0, 8, 0, (byte)'G', 0, (byte)'r', 0, (byte)'e', 0, (byte)'y',
+ 0, 0, 0, 2, 0, (byte)'1',
+ ];
+ byte[] paletteSteps = new byte[18 + 4 + 2 * 19];
+ paletteSteps[18] = 2;
+ palette = [..nameAndId, ..paletteSteps];
+ }
+
+ string path = dir.Write("two_scalars.bin", [..bytes.AsSpan(0, fieldStart), ..firstField, ..display,
+ ..palette, ..new byte[16], ..bytes.AsSpan(fieldStart)]);
+
+ using var doc = PclFile.Open(path);
+ Assert.Equal(42f, Assert.Single(doc.ReadAllPoints()).Intensity);
+ }
+
+ [Theory]
+ [InlineData(false)]
+ [InlineData(true)]
+ public void Cc_Bin_Transforms_Finite_Points_With_Subnormal_Scale(bool withMatrix)
+ {
+ using var dir = new TempDirectory();
+ const float x = 1e-30f;
+ double[]? matrix = withMatrix ? [1, 0, 0, 0, 0, -1, 0, 0, 0, 0, -1, 0, 0, 0, 0, 1] : null;
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin([new(x, 0, 0), new(1, 0, 0)],
+ scale: double.Epsilon, matrix16: matrix);
+
+ using var doc = PclFile.Open(dir.Write("subnormal.bin", bytes));
+ var point = Assert.Single(doc.ReadAllPoints());
+ Assert.Equal(new PclVector3(x / double.Epsilon, 0, 0), point.Position);
+ Assert.Equal(point.Position, doc.Scans[0].Transform.TransformPoint(new PclVector3(x, 0, 0)));
+ Assert.Equal(2, doc.ReadAllPoints(new PclReadOptions { ApplyTransform = false }).Count());
+ }
+
+ [Theory]
+ [InlineData(0.0)]
+ [InlineData(double.NaN)]
+ [InlineData(double.PositiveInfinity)]
+ public void Cc_Bin_Rejects_Invalid_Global_Scale(double scale)
+ {
+ using var dir = new TempDirectory();
+ var path = dir.Write("bad_scale.bin", SyntheticFixtures.CreateSyntheticCcBin([new(1, 2, 3)], scale: scale));
+ Assert.Throws(() => CcBinDocument.Open(path));
+ }
+
[Fact]
public void Cc_Bin_Transforms_With_Tiny_Scale()
{
diff --git a/tests/PclIO.Tests/KindDetectionTests.cs b/tests/PclIO.Tests/KindDetectionTests.cs
index aa5f6f4..6212be6 100644
--- a/tests/PclIO.Tests/KindDetectionTests.cs
+++ b/tests/PclIO.Tests/KindDetectionTests.cs
@@ -573,21 +573,34 @@ public void Detects_Cc_Bin_File_Path()
public void Potree_Node_With_Cc_Magic_Coordinates_Is_Detected_As_Potree_Near_Manifest()
{
using var tempDir = new TempDirectory();
- // Write cloud.js manifest
- tempDir.Write("cloud.js", "{ \"version\": \"1.7\", \"octreeDir\": \"data\", \"points\": 2 }"u8.ToArray());
-
- // Create an r.bin of 2 points whose raw bytes happen to match CC BIN header structure
- // (CCB2, version=1, entityType=1, f2=0, flags=0, nameLen=0).
- byte[] potreeNode = new byte[32];
- "CCB2"u8.CopyTo(potreeNode.AsSpan(0, 4));
- BinaryPrimitives.WriteUInt32LittleEndian(potreeNode.AsSpan(4, 4), 1);
- BinaryPrimitives.WriteUInt32LittleEndian(potreeNode.AsSpan(8, 4), 1);
- BinaryPrimitives.WriteUInt32LittleEndian(potreeNode.AsSpan(12, 4), 0);
- BinaryPrimitives.WriteUInt32LittleEndian(potreeNode.AsSpan(16, 4), 0);
- BinaryPrimitives.WriteUInt32LittleEndian(potreeNode.AsSpan(20, 4), 0);
- string rBinPath = tempDir.Write("data/r/r.bin", potreeNode);
-
+ const double scale = 0.001;
+ var (manifest, data, hierarchy) = SyntheticFixtures.CreateSyntheticPotree1x(
+ [new(0x32424343 * scale, 47 * scale, 257 * scale), new(0, 100 * scale, 0)],
+ new PclVector3(scale, scale, scale), PclVector3.Zero, hasColors: false, normalType: "",
+ hasIntensity: false, hasClassification: false);
+ tempDir.WriteText("cloud.js", manifest);
+ tempDir.WriteText("data/r/metadata.json", "{}");
+ tempDir.Write("data/r/r.hrc", hierarchy);
+ string rBinPath = tempDir.Write("data/r/r.bin", data);
+
+ Assert.Equal(PclFileKind.CcBin, Detect(data, "r.bin"));
Assert.Equal(PclFileKind.Potree, PclFile.DetectKind(rBinPath));
+ using var doc = PclFile.Open(rBinPath);
+ Assert.Equal(2, doc.ReadAllPoints().Count());
+ }
+
+ [Theory]
+ [InlineData("metadata.json")]
+ [InlineData("cloud.js")]
+ public void Unrelated_Manifest_Does_Not_Hide_Cc_Bin(string manifestName)
+ {
+ using var dir = new TempDirectory();
+ dir.WriteText(manifestName, "{}");
+ string path = dir.Write("cloud.bin", SyntheticFixtures.CreateSyntheticCcBin([new(1, 2, 3)]));
+
+ using var doc = PclFile.Open(path);
+ Assert.Equal(PclFileKind.CcBin, doc.Kind);
+ Assert.Single(doc.ReadAllPoints());
}
private sealed class NonSeekableStream(byte[] bytes) : MemoryStream(bytes)