From 726cede7de19ece4d9d86f2fa20ce95de55e3449 Mon Sep 17 00:00:00 2001
From: mahach666 <79989386+mahach666@users.noreply.github.com>
Date: Wed, 18 Nov 2026 20:37:39 +0000
Subject: [PATCH] Read packed CCB2 point normals
---
CHANGELOG.md | 1 +
README.md | 2 +-
docs/public-api.md | 2 +-
src/PclIO/Formats/CcBin/CcBinDocument.cs | 182 ++++++++++++++---------
src/PclIO/Formats/CcBin/CcBinScan.cs | 71 ++++++++-
tests/PclIO.Tests/FormatTests.cs | 78 ++++++++++
tests/PclIO.Tests/SyntheticFixtures.cs | 62 +++++---
7 files changed, 300 insertions(+), 98 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 297dbe4..115b543 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
+- Read packed CC BIN point normals in file versions 41, 42 and 50.
- 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 21e52cb..a1fe843 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). 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. |
+| 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. Packed normals are supported in file versions 41, 42 and 50. |
### Format detection
diff --git a/docs/public-api.md b/docs/public-api.md
index 1c985f8..7a00678 100644
--- a/docs/public-api.md
+++ b/docs/public-api.md
@@ -94,7 +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. |
+| CC BIN | The point count declared for the entity. Points with non-finite coordinates are skipped. Packed point normals are decoded in file versions 41, 42 and 50. A stored zero direction is returned as `PclVector3.Zero`. |
`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
diff --git a/src/PclIO/Formats/CcBin/CcBinDocument.cs b/src/PclIO/Formats/CcBin/CcBinDocument.cs
index 8e46144..07c8097 100644
--- a/src/PclIO/Formats/CcBin/CcBinDocument.cs
+++ b/src/PclIO/Formats/CcBin/CcBinDocument.cs
@@ -8,6 +8,8 @@ namespace PclIO.Formats.CcBin;
/// Represents a CC BIN point cloud file (.bin, CCB2).
public sealed class CcBinDocument : PclDocument
{
+ private const int ArrayFooterPrefixSize = 8;
+ private const int ArrayFooterWithMatrixSize = ArrayFooterPrefixSize + 16 * sizeof(float);
private static readonly byte[] Magic = "CCB2"u8.ToArray();
///
@@ -223,99 +225,55 @@ private bool TryParsePointCloud(
// Check for colors right after points
fs.Position = pointsEndOffset;
- int colorFlag = fs.ReadByte();
- bool hasColors = false;
+ bool hasColors = ReadArrayFlag(fs, "color");
long colorOffset = -1;
byte channels = 3;
- if (colorFlag == 1)
+ if (hasColors)
{
- byte[] colH = new byte[16];
- 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];
+ var (_, colorChannels, colCount) = ReadArrayHeader(fs, "color");
+ channels = colorChannels;
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;
+ colorOffset = fs.Position;
long cBytes = (long)colCount * channels;
- if (cOffset + cBytes > fileLength)
+ if (cBytes > fileLength - colorOffset)
throw new InvalidDataException("CC BIN RGB color data is truncated.");
-
- 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));
- 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;
- double expected = row == col ? 1.0 : 0.0;
- if (Math.Abs(val - expected) > 1e-6)
- {
- isIdentity = false;
- }
- }
- }
+ double[]? matrix = hasColors ? ReadColorArrayFooter(fs) : null;
+ long normalOffset = ReadNormalOffset(fs, count);
// Scalar fields (probe for Intensity)
long intensityOffset = -1;
uint intensityCount = 0;
- if (fs.ReadByte() >= 0)
+ 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++)
{
- 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++)
- {
- ReadScalarBytes(fs, fieldHeader);
- uint valueCount = BinaryPrimitives.ReadUInt32LittleEndian(fieldHeader[257..]);
- long dataOffset = fs.Position;
- SkipScalarBytes(fs, (long)valueCount * sizeof(float));
+ 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))
- {
- intensityOffset = dataOffset;
- intensityCount = valueCount;
- }
-
- if (field + 1 < fieldCount)
- SkipScalarMetadata(fs);
+ if (intensityOffset < 0 &&
+ Encoding.ASCII.GetString(fieldHeader[..256]).TrimEnd('\0').Equals("Intensity", StringComparison.OrdinalIgnoreCase))
+ {
+ intensityOffset = dataOffset;
+ intensityCount = valueCount;
}
+
+ if (field + 1 < fieldCount)
+ SkipScalarMetadata(fs);
}
string scanId = scanIndex.ToString(CultureInfo.InvariantCulture);
@@ -328,19 +286,97 @@ private bool TryParsePointCloud(
hasColors: hasColors,
colorOffset: colorOffset,
colorChannels: channels,
+ normalOffset: normalOffset,
intensityOffset: intensityOffset,
intensityCount: intensityCount,
shiftX: sx,
shiftY: sy,
shiftZ: sz,
scale: scale,
- transform: CreateTransform(scale, new PclVector3(-sx, -sy, -sz), isIdentity ? null : matrix16),
+ transform: CreateTransform(scale, new PclVector3(-sx, -sy, -sz), matrix),
+ normalTransform: normalOffset >= 0 && (matrix != null || scale < 0)
+ ? new PclTransform { Matrix4x4 = matrix, UniformScaleDivisor = Math.Sign(scale) }
+ : null,
properties: props);
pointsEndOffset = Math.Max(pointsEndOffset, fs.Position);
return true;
}
+ private bool HasShortArrayFooter => Version is 41 or 42;
+ private int ArrayFooterSize => HasShortArrayFooter ? ArrayFooterPrefixSize : ArrayFooterWithMatrixSize;
+
+ private static bool ReadArrayFlag(FileStream fs, string attribute) => fs.ReadByte() switch
+ {
+ 0 => false,
+ 1 => true,
+ -1 => throw FormatError.Truncated($"CC BIN {attribute} array flag"),
+ _ => throw FormatError.Corrupted($"CC BIN {attribute} array flag is invalid."),
+ };
+
+ private static (ulong Type, byte Components, uint Count) ReadArrayHeader(FileStream fs, string attribute)
+ {
+ Span header = stackalloc byte[16];
+ if (fs.ReadAtLeast(header, header.Length, throwOnEndOfStream: false) != header.Length)
+ throw FormatError.Truncated($"CC BIN {attribute} array header");
+
+ uint nameLength = BinaryPrimitives.ReadUInt32BigEndian(header[12..]);
+ if (nameLength > 500 || (nameLength & 1) != 0)
+ throw FormatError.Corrupted($"CC BIN {attribute} array name has an invalid byte length.");
+ if (nameLength > fs.Length - fs.Position)
+ throw FormatError.Truncated($"CC BIN {attribute} array name");
+ fs.Position += nameLength;
+
+ Span properties = stackalloc byte[9 + sizeof(uint)];
+ if (fs.ReadAtLeast(properties, properties.Length, throwOnEndOfStream: false) != properties.Length)
+ throw FormatError.Truncated($"CC BIN {attribute} array properties");
+ return (BinaryPrimitives.ReadUInt64LittleEndian(header), properties[8],
+ BinaryPrimitives.ReadUInt32LittleEndian(properties[9..]));
+ }
+
+ private double[]? ReadColorArrayFooter(FileStream fs)
+ {
+ Span footer = stackalloc byte[ArrayFooterWithMatrixSize];
+ var data = footer[..ArrayFooterSize];
+ if (fs.ReadAtLeast(data, data.Length, throwOnEndOfStream: false) != data.Length)
+ throw FormatError.Truncated("CC BIN color array footer");
+ if (HasShortArrayFooter) return null;
+
+ var matrix = new double[16];
+ bool isIdentity = true;
+ for (int i = 0; i < matrix.Length; i++)
+ {
+ float value = BinaryPrimitives.ReadSingleLittleEndian(data[(ArrayFooterPrefixSize + i * sizeof(float))..]);
+ if (!float.IsFinite(value))
+ throw FormatError.Corrupted("CC BIN has a non-finite coordinate matrix.");
+ matrix[i] = value;
+ double expected = i % 5 == 0 ? 1.0 : 0.0;
+ isIdentity &= Math.Abs(value - expected) <= 1e-6;
+ }
+
+ return isIdentity ? null : matrix;
+ }
+
+ private long ReadNormalOffset(FileStream fs, uint pointCount)
+ {
+ if (!ReadArrayFlag(fs, "normal")) return -1;
+ if (!HasShortArrayFooter && Version != 50)
+ throw FormatError.Unsupported($"CC BIN normals in version {Version}.");
+
+ var (type, components, count) = ReadArrayHeader(fs, "normal");
+ if (type != 0x40000012 || components != 1)
+ throw FormatError.Unsupported("CC BIN normal array encoding.");
+ if (count != pointCount)
+ throw FormatError.Corrupted($"CC BIN normal count {count} does not match point count {pointCount}.");
+
+ long offset = fs.Position;
+ long bytes = (long)count * sizeof(uint) + ArrayFooterSize;
+ if (bytes > fs.Length - offset)
+ throw FormatError.Truncated("CC BIN normal array data or footer");
+ fs.Position += bytes;
+ return offset;
+ }
+
private static void SkipScalarMetadata(FileStream fs)
{
SkipScalarBytes(fs, 52); // Display ranges and flags before the optional palette.
diff --git a/src/PclIO/Formats/CcBin/CcBinScan.cs b/src/PclIO/Formats/CcBin/CcBinScan.cs
index 0d58ccc..c734c34 100644
--- a/src/PclIO/Formats/CcBin/CcBinScan.cs
+++ b/src/PclIO/Formats/CcBin/CcBinScan.cs
@@ -8,6 +8,8 @@ namespace PclIO.Formats.CcBin;
public sealed class CcBinScan : PclScan
{
private const int BatchRecords = 1024;
+ private const int NormalLevels = 9;
+ private const uint ZeroNormalCode = 1u << (2 * NormalLevels + 3);
private readonly string _filePath;
private readonly long _pointOffset;
@@ -15,6 +17,8 @@ public sealed class CcBinScan : PclScan
private readonly bool _hasColors;
private readonly long _colorOffset;
private readonly byte _colorChannels;
+ private readonly long _normalOffset;
+ private readonly PclTransform? _normalTransform;
private readonly long _intensityOffset;
private readonly long _intensityCount;
private readonly double _shiftX;
@@ -34,6 +38,9 @@ public sealed class CcBinScan : PclScan
///
public override bool HasColors => _hasColors;
+ ///
+ public override bool HasNormals => _normalOffset >= 0;
+
///
public override bool HasIntensities => _intensityCount > 0;
@@ -52,6 +59,7 @@ internal CcBinScan(
bool hasColors,
long colorOffset,
byte colorChannels,
+ long normalOffset,
long intensityOffset,
long intensityCount,
double shiftX,
@@ -59,6 +67,7 @@ internal CcBinScan(
double shiftZ,
double scale,
PclTransform transform,
+ PclTransform? normalTransform,
IReadOnlyDictionary? properties = null)
{
_filePath = filePath;
@@ -69,6 +78,8 @@ internal CcBinScan(
_hasColors = hasColors;
_colorOffset = colorOffset;
_colorChannels = colorChannels;
+ _normalOffset = normalOffset;
+ _normalTransform = normalTransform;
_intensityOffset = intensityOffset;
_intensityCount = intensityCount;
_shiftX = shiftX;
@@ -79,6 +90,7 @@ internal CcBinScan(
_properties["TotalPoints"] = pointCount.ToString(CultureInfo.InvariantCulture);
_properties["HasColors"] = hasColors ? "true" : "false";
+ _properties["HasNormals"] = HasNormals ? "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);
@@ -105,6 +117,7 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
byte[] ptBuf = new byte[BatchRecords * 12];
byte[]? colBuf = _hasColors ? new byte[BatchRecords * _colorChannels] : null;
+ byte[]? normalBuf = HasNormals ? new byte[BatchRecords * sizeof(uint)] : null;
byte[]? intBuf = HasIntensities ? new byte[BatchRecords * 4] : null;
long yielded = 0;
@@ -143,6 +156,14 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
}
}
+ if (normalBuf != null)
+ {
+ int bytes = toRead * sizeof(uint);
+ fs.Position = _normalOffset + pointIndex * sizeof(uint);
+ if (fs.ReadAtLeast(normalBuf.AsSpan(0, bytes), bytes, throwOnEndOfStream: false) != bytes)
+ throw FormatError.Truncated($"CC BIN normal codes at index {pointIndex}");
+ }
+
for (int p = 0; p < toRead; p++)
{
long currentIdx = pointIndex + p;
@@ -186,7 +207,19 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
continue;
}
- yield return new PclPoint(pos, Color: color, Intensity: intensity, Index: (ulong)yielded);
+ PclVector3? normal = null;
+ if (normalBuf != null)
+ {
+ uint code = BinaryPrimitives.ReadUInt32LittleEndian(normalBuf.AsSpan(p * sizeof(uint)));
+ if (code > ZeroNormalCode)
+ throw FormatError.Corrupted($"CC BIN normal code {code} is invalid at index {currentIdx}.");
+ var direction = DecodeNormal(code);
+ normal = options.ApplyTransform && _normalTransform != null
+ ? _normalTransform.TransformVector(direction)
+ : direction;
+ }
+
+ yield return new PclPoint(pos, Color: color, Intensity: intensity, Normal: normal, Index: (ulong)yielded);
yielded++;
if (yielded >= targetCount) yield break;
}
@@ -195,4 +228,40 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
pointsRemaining -= toRead;
}
}
+
+ private static PclVector3 DecodeNormal(uint code)
+ {
+ if (code == ZeroNormalCode) return PclVector3.Zero;
+
+ // Each pair of bits selects a corner of the octahedral face or its reflected center.
+ int x = 0, y = 0, z = 0;
+ int step = 1 << NormalLevels;
+ for (int bit = 2 * (NormalLevels - 1); bit >= 0; bit -= 2)
+ {
+ step /= 2;
+ switch ((code >> bit) & 3)
+ {
+ case 0: x += step; break;
+ case 1: y += step; break;
+ case 2: z += step; break;
+ case 3:
+ x += step;
+ y += step;
+ z += step;
+ step = -step;
+ break;
+ }
+ }
+
+ x = 2 * x + step;
+ y = 2 * y + step;
+ z = 2 * z + step;
+ uint signs = code >> (2 * NormalLevels);
+ if ((signs & 4) != 0) x = -x;
+ if ((signs & 2) != 0) y = -y;
+ if ((signs & 1) != 0) z = -z;
+
+ double length = Math.Sqrt(x * x + y * y + z * z);
+ return new PclVector3(x / length, y / length, z / length);
+ }
}
diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs
index f38b287..29bb1fe 100644
--- a/tests/PclIO.Tests/FormatTests.cs
+++ b/tests/PclIO.Tests/FormatTests.cs
@@ -6362,6 +6362,7 @@ public void Cc_Bin_Reads_Points_Coordinates_Colors_And_Intensity()
Assert.Equal(3, scan.PointCount);
Assert.True(scan.HasColors);
Assert.True(scan.HasIntensities);
+ Assert.False(scan.HasNormals);
var points = scan.ReadPoints().ToList();
Assert.Equal(3, points.Count);
@@ -6423,6 +6424,83 @@ public void Cc_Bin_Applies_Shift_And_Scale_Transform()
Assert.Equal(120.0, transformed.Z, precision: 4);
}
+ [Theory]
+ [InlineData(41u, false)]
+ [InlineData(42u, true)]
+ [InlineData(50u, false)]
+ [InlineData(50u, true)]
+ public void Cc_Bin_Reads_Normals_Across_Batches_And_Optional_Colors(uint version, bool withColors)
+ {
+ using var dir = new TempDirectory();
+ var points = Enumerable.Range(0, 1027).Select(i => new CcBinSamplePoint(i, 0, 0, Intensity: i)).ToArray();
+ var codes = new uint[points.Length];
+ codes[513] = 0x130000;
+ codes[1026] = 0x200000;
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin(points, version: version, withColors: withColors,
+ normalCodes: codes);
+
+ using var doc = PclFile.Open(dir.Write("normals.bin", bytes));
+ var scan = Assert.Single(doc.Scans);
+ Assert.True(scan.HasNormals);
+ Assert.True(scan.HasIntensities);
+ Assert.Equal(withColors, scan.HasColors);
+
+ var sample = scan.ReadPoints(new PclReadOptions { SubsampleStep = 513, MaxPoints = 3 }).ToArray();
+ Assert.Equal(new[] { 0d, 513d, 1026d }, sample.Select(p => p.X));
+ Assert.Equal(new float?[] { 0, 513, 1026 }, sample.Select(p => p.Intensity));
+ double axisLength = Math.Sqrt(1023 * 1023 + 2);
+ Assert.Equal(new PclVector3(1023 / axisLength, 1 / axisLength, 1 / axisLength), sample[0].Normal);
+ double reflectedLength = Math.Sqrt(1 + 2 * 511 * 511);
+ Assert.Equal(new PclVector3(-1 / reflectedLength, 511 / reflectedLength, 511 / reflectedLength), sample[1].Normal);
+ Assert.Equal(PclVector3.Zero, sample[2].Normal);
+ }
+
+ [Fact]
+ public void Cc_Bin_Transforms_Normal_Directions_Without_Shift_Or_Scale_Magnitude()
+ {
+ using var dir = new TempDirectory();
+ double[] matrix = [0, -1, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin([new(1, 0, 0)], version: 50, normalCodes: [0],
+ matrix16: matrix, shiftX: 12, scale: 1e-200);
+
+ using var doc = PclFile.Open(dir.Write("rotated.bin", bytes));
+ var a = Assert.Single(doc.ReadAllPoints(new PclReadOptions { ApplyTransform = false })).Normal!.Value;
+ var b = Assert.Single(doc.ReadAllPoints()).Normal!.Value;
+ Assert.Equal(-a.Y, b.X, precision: 14);
+ Assert.Equal(a.X, b.Y, precision: 14);
+ Assert.Equal(a.Z, b.Z, precision: 14);
+ }
+
+ [Fact]
+ public void Cc_Bin_Rejects_Truncated_And_Mismatched_Normal_Arrays()
+ {
+ using var dir = new TempDirectory();
+ byte[] mismatch = SyntheticFixtures.CreateSyntheticCcBin([new(1, 2, 3), new(4, 5, 6)], version: 50,
+ normalCodes: [0]);
+ Assert.Throws(() => CcBinDocument.Open(dir.Write("bad_count.bin", mismatch)));
+
+ byte[] truncated = SyntheticFixtures.CreateSyntheticCcBin([new(1, 2, 3)], version: 50,
+ normalCodes: [0], withIntensity: false);
+ Assert.Throws(() => CcBinDocument.Open(dir.Write("cut_normals.bin", truncated[..^5])));
+ }
+
+ [Fact]
+ public void Cc_Bin_Rejects_Out_Of_Range_Normal_Codes()
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin([new(1, 2, 3)], version: 50, normalCodes: [0x200001]);
+ using var doc = CcBinDocument.Open(dir.Write("bad_index.bin", bytes));
+ Assert.Throws(() => doc.ReadAllPoints().Single());
+ }
+
+ [Fact]
+ public void Cc_Bin_Rejects_Normals_In_An_Unsupported_Version()
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticCcBin([new(1, 2, 3)], version: 47, normalCodes: [0]);
+ Assert.Throws(() => CcBinDocument.Open(dir.Write("unsupported_normals.bin", bytes)));
+ }
+
[Fact]
public void Cc_Bin_Opens_Adjacent_Multi_Cloud_Entities()
{
diff --git a/tests/PclIO.Tests/SyntheticFixtures.cs b/tests/PclIO.Tests/SyntheticFixtures.cs
index 2e6e593..5a4adc4 100644
--- a/tests/PclIO.Tests/SyntheticFixtures.cs
+++ b/tests/PclIO.Tests/SyntheticFixtures.cs
@@ -2961,7 +2961,8 @@ public static byte[] CreateSyntheticCcBin(
bool truncatePoints = false,
bool truncateColorBlock = false,
bool truncateIntensityData = false,
- int? declaredIntensityCount = null)
+ int? declaredIntensityCount = null,
+ IReadOnlyList? normalCodes = null)
{
using var ms = new MemoryStream();
@@ -2984,6 +2985,8 @@ public static byte[] CreateSyntheticCcBin(
scale: scale,
withColors: withColors,
withIntensity: withIntensity,
+ version: version,
+ normalCodes: normalCodes,
declaredIntensityCount: declaredIntensityCount,
matrix16: matrix16,
doubleProperties: doubleProperties,
@@ -3012,7 +3015,8 @@ public static byte[] CreateSyntheticCcBinMultiCloud(
ms,
clouds[c],
name: $"Cloud_{c + 1}",
- id: (uint)(100 + c));
+ id: (uint)(100 + c),
+ version: version);
}
return ms.ToArray();
@@ -3029,6 +3033,8 @@ private static void WriteCcBinCloudEntity(
double scale = 1.0,
bool withColors = true,
bool withIntensity = true,
+ uint version = 47,
+ IReadOnlyList? normalCodes = null,
int? declaredIntensityCount = null,
double[]? matrix16 = null,
IReadOnlyDictionary? doubleProperties = null,
@@ -3080,8 +3086,8 @@ private static void WriteCcBinCloudEntity(
// 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(withColors ? (byte)1 : (byte)0);
+ ms.WriteByte(normalCodes != null ? (byte)1 : (byte)0);
ms.WriteByte(0x00);
ms.WriteByte(0x00);
ms.WriteByte(0x00);
@@ -3168,32 +3174,34 @@ private static void WriteCcBinCloudEntity(
ms.WriteByte(0x00);
}
- // 9. Matrix 4x4 (8 bytes + 64 bytes)
- Span zeros8 = stackalloc byte[8];
- ms.Write(zeros8);
+ int footerSize = version is 41 or 42 ? 8 : 72;
+ if (withColors) WriteCcBinArrayFooter(ms, footerSize, matrix16);
- Span matBuf = stackalloc byte[64];
- for (int m = 0; m < 16; m++)
+ // 9. Optional packed normals.
+ ms.WriteByte(normalCodes != null ? (byte)1 : (byte)0);
+ if (normalCodes != null)
{
- float val;
- if (matrix16 != null && m < matrix16.Length)
- {
- val = (float)matrix16[m];
- }
- else
+ byte[] normalsName = Encoding.BigEndianUnicode.GetBytes("Normals");
+ Span header = stackalloc byte[16];
+ BinaryPrimitives.WriteUInt64LittleEndian(header, 0x40000012);
+ BinaryPrimitives.WriteUInt32LittleEndian(header[8..], 102);
+ BinaryPrimitives.WriteUInt32BigEndian(header[12..], (uint)normalsName.Length);
+ ms.Write(header);
+ ms.Write(normalsName);
+ ms.Write(new byte[] { 6, 0, 0, 0, 0, 0, 0, 0, 1 });
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, (uint)normalCodes.Count);
+ ms.Write(u32Buf);
+ foreach (uint code in normalCodes)
{
- int row = m / 4;
- int col = m % 4;
- val = row == col ? 1f : 0f;
+ BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, code);
+ ms.Write(u32Buf);
}
- BinaryPrimitives.WriteSingleLittleEndian(matBuf.Slice(m * 4, 4), val);
+ WriteCcBinArrayFooter(ms, footerSize);
}
- ms.Write(matBuf);
// 10. Scalar fields (Intensity)
if (withIntensity)
{
- ms.WriteByte(0x00);
BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 1); // 1 scalar field
ms.Write(u32Buf);
@@ -3224,9 +3232,19 @@ private static void WriteCcBinCloudEntity(
}
else
{
- ms.WriteByte(0x00);
BinaryPrimitives.WriteUInt32LittleEndian(u32Buf, 0);
ms.Write(u32Buf);
}
}
+
+ private static void WriteCcBinArrayFooter(Stream ms, int size, double[]? matrix = null)
+ {
+ byte[] footer = new byte[size];
+ for (int i = 0; i < (size - 8) / 4; i++)
+ {
+ float value = matrix != null && i < matrix.Length ? (float)matrix[i] : i % 5 == 0 ? 1f : 0f;
+ BinaryPrimitives.WriteSingleLittleEndian(footer.AsSpan(8 + i * 4), value);
+ }
+ ms.Write(footer);
+ }
}