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)