From 7fc2c2bc1fbf678c570c2c7c0be348176c1eb9f6 Mon Sep 17 00:00:00 2001 From: mahach666 <79989386+mahach666@users.noreply.github.com> Date: Mon, 16 Nov 2026 02:19:36 +0000 Subject: [PATCH] Describe the node layouts of a ReCap scan in one place --- CHANGELOG.md | 2 + README.md | 2 +- docs/public-api.md | 2 +- src/PclIO/Formats/Recap/RcsScanDocument.cs | 58 ++++++++++++++++------ tests/PclIO.Tests/FormatTests.cs | 34 +++++++++++++ 5 files changed, 81 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aa1891d..98868c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - The layout of the samples of a FARO scan folder is derived from the size of its data stream and the size of the grid, and the scale of the intensity from the values that are stored. The warning about an assumed layout is only made when the sizes do not fit. +- The node layout of a ReCap scan is described in one place per container version. A file of a version without a described + layout is rejected with a message that names the version and the described ones. ## [0.1.0] - 2026-11-15 diff --git a/README.md b/README.md index a59d4c7..2546702 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ The library targets .NET 8 and .NET 10. It is managed code with no dependencies | Format | Extensions | Support level | | --- | --- | --- | | ASTM E57 | `.e57` | Points decoded for a defined subset: uncompressed bit-packed streams with single or double precision Cartesian coordinates, 8-bit colour and 8-bit intensity. Pose translation and rotation are applied. Scaled-integer coordinates, spherical coordinates and other codecs are not supported: a scan that uses them lists normally and fails when its points are read. Per-point validity flags and images are not read, so points flagged as invalid are returned as stored, and colour or intensity fields of any other type or range are ignored. Page checksums are verified. | -| ReCap scan | `.rcs` | Experimental. The header is read; point decoding covers only the node layout of major version 3, and any other layout is rejected. Colour and intensity are decoded, and normals when a node has them. `HasColors`, `HasIntensities` and `HasNormals` are fixed for this layout and are not read from the file. | +| ReCap scan | `.rcs` | Experimental. The header is read; point decoding covers the node layouts that are described in the code, which is the one of major version 3. A file of another version is listed with its header, but reading its points fails with a message that names the version. A further layout is described only when the files of that version may be used for the tests, so that its offsets can be verified. Colour and intensity are decoded, and normals when a node has them. `HasColors`, `HasIntensities` and `HasNormals` are fixed for this layout and are not read from the file. | | ReCap project | `.rcp` | Lists the scans of the project manifest and opens the `.rcs` files it finds next to the project. Node transforms are exposed as data and are not applied to points. | | Leica scan container | `.lgsx`, `.lgs` | Experimental. Points are decoded from the compressed point blocks: position, and colour, intensity and normals when the block has them. When the container assigns its points to its setups, there is one scan per setup, named after the setup, with the pose and the bounds of the setup when its record holds them; the pose is applied unless `ApplyTransform` is false. When the container does not assign its points, all points of the container form one scan and a warning says so. The point count is taken from the container when it states one; otherwise it is found by decoding the data, which is slow on large files. | | FARO scan | `.fls`, or a FARO scan folder | Experimental. The scan grid and angles are read from the stored parameters and points are projected from the range grid; a file without them fails to open. The point count is the number of valid returns, which is counted on the first access; `FaroScan.GridSize` is the size of the scan grid. For a scan folder the layout of the samples is derived from the size of the data stream and the size of the grid, and the scale of the intensity from the values that are stored; when the sizes do not fit, the layout is assumed and a warning says so. | diff --git a/docs/public-api.md b/docs/public-api.md index 6aa00df..1402798 100644 --- a/docs/public-api.md +++ b/docs/public-api.md @@ -60,7 +60,7 @@ drop points that fail a plausibility rule (see the README), so a scan can yield | Reader | `PointCount` | |---|---| | E57 | Declared by the file. It is not checked against the point data until the points are read. | -| ReCap scan | Declared in the header. It is not checked against the node table. | +| ReCap scan | Declared in the header. It is not checked against the node table. The node layout of major version 3 is decoded; a file of another version is listed but its points cannot be read (`RcsScanDocument.DecodedNodeLayoutVersions` names the decoded versions). | | ReCap project | Declared by the project manifest; 0 when the manifest states none. | | Leica | The number of points the container states, when it states one; otherwise it is computed. The computed value needs the first access to decode all of the point data and caches the result, which can be slow on large files; the access throws `InvalidDataException` for corrupt data. A container that assigns its points to its setups has one scan per setup, each with the id and the name of its setup; otherwise the container is one scan with the id `unified-cloud`. The `Transform` and the `Bounds` of a setup are read from its record and are empty when the record does not hold them. | | FARO | The number of valid returns, which is counted on the first access by reading the distance data of the scan; `FaroScan.GridSize` is the size of the scan grid (rows times columns). For a folder scan the grid size is limited by the size of the data stream, and `FaroScan.RecordSize` is the size of one sample in bytes. | diff --git a/src/PclIO/Formats/Recap/RcsScanDocument.cs b/src/PclIO/Formats/Recap/RcsScanDocument.cs index 5345780..a0c6ddf 100644 --- a/src/PclIO/Formats/Recap/RcsScanDocument.cs +++ b/src/PclIO/Formats/Recap/RcsScanDocument.cs @@ -5,14 +5,17 @@ namespace PclIO.Formats.Recap; /// -/// Reads the header of a ReCap scan file (.rcs). Point decoding is experimental: only the node layout of -/// major version 3 is supported, and any other layout is rejected instead of guessed. +/// Reads the header of a ReCap scan file (.rcs). Point decoding is experimental: only the node layouts that are +/// described in are decoded, and any other version is rejected instead of guessed. /// public sealed class RcsScanDocument : PclDocument { /// public override PclFileKind Kind => PclFileKind.RecapScan; + /// Major versions of the container whose node layout the reader decodes. + public static IReadOnlyList DecodedNodeLayoutVersions { get; } = [3]; + /// Container major version from the header. public uint MajorVersion { get; } @@ -175,14 +178,38 @@ public static RcsScanDocument Open(string path, PclReadOptions? options = null) } } +/// +/// The layout of the node table of a ReCap scan file, one per container major version. +/// +/// +/// A layout is described only when the files of that version may be used for the tests, so that its offsets can be +/// verified. A file of a version without a described layout is listed with its header, but its points cannot be read: +/// the reader rejects it with a message that names the version. +/// +/// Major version of the container that the layout belongs to. +/// Offset of the node table in the file, in bytes. +/// Size of one entry of the node table, in bytes. +internal sealed record RcsLayout(uint MajorVersion, long NodeTableOffset, int NodeSize) +{ + // The layout of major version 3: the node table starts at a fixed offset and the node payloads occupy the end + // of the file. + private static readonly RcsLayout Version3 = new(3, 98605, 368); + + private static readonly RcsLayout[] Described = [Version3]; + + /// The layout of the given major version, or null when the version has no described layout. + public static RcsLayout? ForVersion(uint majorVersion) => + Described.FirstOrDefault(l => l.MajorVersion == majorVersion); + + /// The major versions whose layout is described, for a message that names them. + public static string DescribedVersions => string.Join(", ", Described.Select(l => l.MajorVersion)); +} + /// Individual scan of an RCS file. public sealed class RcsScan : PclScan { // Layout of major version 3: the node table starts at a fixed offset and the node // payloads occupy the end of the file. Both are verified against the file length before use. - private const uint SupportedMajorVersion = 3; - private const long NodeTableOffset = 98605; - private const int NodeSize = 368; private const ulong MaxNodes = 500_000; private const int PointRecordSize = 16; private const int NormalRecordSize = 4; @@ -233,16 +260,17 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null) { options ??= PclReadOptions.Default; if (PointCount == 0) yield break; - if (_document.MajorVersion != SupportedMajorVersion) - throw FormatError.Unsupported( - $"RCS container version {_document.MajorVersion}.{_document.MinorVersion}; only major version {SupportedMajorVersion} is decoded."); + + var layout = RcsLayout.ForVersion(_document.MajorVersion) + ?? throw FormatError.Unsupported( + $"RCS container version {_document.MajorVersion}.{_document.MinorVersion}: the layout of its node table is not described. The described versions are {RcsLayout.DescribedVersions}."); long targetCount = options.MaxPoints ?? PointCount; int step = Math.Max(1, options.SubsampleStep); long yielded = 0; using var fs = File.OpenRead(_filePath); - var nodes = ReadNodeTable(fs, out long payloadStart); + var nodes = ReadNodeTable(fs, layout, out long payloadStart); long curOffset = payloadStart; byte[] chunkBuf = new byte[65536]; @@ -337,26 +365,26 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null) } // Reads and validates the node table; payloadStart is where the first node payload begins. - private static List ReadNodeTable(FileStream fs, out long payloadStart) + private static List ReadNodeTable(FileStream fs, RcsLayout layout, out long payloadStart) { - if (fs.Length < NodeTableOffset + 8) throw FormatError.Truncated("RCS node table"); + if (fs.Length < layout.NodeTableOffset + 8) throw FormatError.Truncated("RCS node table"); - fs.Position = NodeTableOffset; + fs.Position = layout.NodeTableOffset; Span countBuf = stackalloc byte[8]; fs.ReadExactly(countBuf); ulong numNodes = Bytes.ReadUInt64LE(countBuf); - long tableEnd = NodeTableOffset + 8 + ((long)Math.Min(numNodes, MaxNodes + 1) * NodeSize); + long tableEnd = layout.NodeTableOffset + 8 + ((long)Math.Min(numNodes, MaxNodes + 1) * layout.NodeSize); if (numNodes > MaxNodes || tableEnd > fs.Length) throw FormatError.Corrupted("RCS node table does not fit in the file."); var nodes = new List((int)numNodes); - byte[] nodeBuf = new byte[NodeSize]; + byte[] nodeBuf = new byte[layout.NodeSize]; long totalPayloadBytes = 0; for (ulong i = 0; i < numNodes; i++) { - fs.ReadExactly(nodeBuf, 0, NodeSize); + fs.ReadExactly(nodeBuf, 0, layout.NodeSize); double tMinX = Bytes.ReadDoubleLE(nodeBuf.AsSpan(0x30, 8)); double tMinY = Bytes.ReadDoubleLE(nodeBuf.AsSpan(0x38, 8)); diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs index 5453c1d..24fef5c 100644 --- a/tests/PclIO.Tests/FormatTests.cs +++ b/tests/PclIO.Tests/FormatTests.cs @@ -114,6 +114,40 @@ public void Rcs_Of_An_Unsupported_Major_Version_Is_Rejected_At_Read_Time() Assert.Throws(() => doc.ReadAllPoints().ToList()); } + [Fact] + public void An_Rcs_Of_A_Version_Without_A_Described_Layout_Is_Rejected_With_A_Message_That_Names_It() + { + using var dir = new TempDirectory(); + byte[] bytes = SyntheticFixtures.CreateSyntheticRcsWithPoints(RcsPoints, (0, 0, 0)); + bytes[8] = 4; + using var doc = RcsScanDocument.Open(dir.Write("new.rcs", bytes)); + + // The file is listed with its header, but its points cannot be decoded. + Assert.Equal(4u, doc.MajorVersion); + var error = Assert.Throws(() => doc.ReadAllPoints().ToList()); + Assert.Contains("4", error.Message, StringComparison.Ordinal); + Assert.Contains("3", error.Message, StringComparison.Ordinal); + } + + [Fact] + public void The_Node_Layouts_That_Are_Decoded_Are_Named() + { + Assert.Equal([3u], RcsScanDocument.DecodedNodeLayoutVersions); + } + + [Fact] + public void An_Rcs_With_A_Truncated_Node_Table_Is_Rejected() + { + using var dir = new TempDirectory(); + byte[] bytes = SyntheticFixtures.CreateSyntheticRcsWithPoints(RcsPoints, (0, 0, 0)); + + // The file ends in the middle of the node table. + string path = dir.Write("short.rcs", bytes[..(98605 + 100)]); + using var doc = RcsScanDocument.Open(path); + + Assert.Throws(() => doc.ReadAllPoints().ToList()); + } + // ---- ReCap project ---------------------------------------------------------------------------------------- [Fact]