Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/public-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
182 changes: 109 additions & 73 deletions src/PclIO/Formats/CcBin/CcBinDocument.cs
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ namespace PclIO.Formats.CcBin;
/// <summary>Represents a CC BIN point cloud file (.bin, CCB2).</summary>
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();

/// <inheritdoc />
Expand Down Expand Up @@ -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<byte> 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<byte> fieldHeader = stackalloc byte[261];
for (uint field = 0; field < fieldCount; field++)
{
Span<byte> 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<byte> 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);
Expand All @@ -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<byte> 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<byte> 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<byte> 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.
Expand Down
Loading
Loading