diff --git a/CHANGELOG.md b/CHANGELOG.md
index 98868c0..ef767f7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
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.
+- The channels of a ReCap scan follow from the file: the size of the payload of the nodes tells whether the points hold a
+ colour, an intensity and a normal. `HasColors`, `HasIntensities` and `HasNormals` are no longer constants.
## [0.1.0] - 2026-11-15
diff --git a/README.md b/README.md
index 2546702..9fd3304 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 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 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. The channels of the points follow from the size of the payload of the nodes: colour and intensity when the records are long enough, and normals when the node holds the plane of them. |
| 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 1402798..654a134 100644
--- a/docs/public-api.md
+++ b/docs/public-api.md
@@ -67,9 +67,10 @@ drop points that fail a plausibility rule (see the README), so a scan can yield
| PinPoint | A manifest with a scan position list: declared by the manifest, else derived from the data file, else 0 (not known). A manifest with a data object list: always 0 (not known), so `TotalPointCount` is 0 for such a project. |
| EdgeWise | A `.c3db` database node: the count the database declares. A `.c3ptx` file: computed by walking the cluster headers when the file is opened. |
-`HasColors`, `HasIntensities` and `HasNormals` follow what the file contains, except for ReCap scan, where they are constants of the
-supported layout and always true (a single point can still have no normal), and 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.
+`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
+from the node table, so they are known after the node table has been read; a node whose points hold no colour gives its points
+no colour.
## Format documents
diff --git a/src/PclIO/Formats/Recap/RcsScanDocument.cs b/src/PclIO/Formats/Recap/RcsScanDocument.cs
index a0c6ddf..ed004bc 100644
--- a/src/PclIO/Formats/Recap/RcsScanDocument.cs
+++ b/src/PclIO/Formats/Recap/RcsScanDocument.cs
@@ -37,17 +37,17 @@ public sealed class RcsScanDocument : PclDocument
/// Point count declared in the header; it is not cross-checked against the node table.
public long DeclaredPointCount { get; }
- /// Always true: a constant of the supported layout, whose point record always has colour fields. It is not read from the file.
- public bool HasColorData { get; }
+ /// True when the file holds colour for its points; it is read from the node table.
+ public bool HasColorData => _scans.Count > 0 && _scans[0].HasColors;
///
- /// Always true: a constant of the supported layout, which can carry normals. It is not read from the file; each
- /// node decides whether its points have one, so single points may have none.
+ /// True when the file can hold normals for its points; it is read from the node table, and a single point may still
+ /// have none.
///
- public bool HasNormalData { get; }
+ public bool HasNormalData => _scans.Count > 0 && _scans[0].HasNormals;
- /// Always true: a constant of the supported layout, whose point record always has an intensity field. It is not read from the file.
- public bool HasIntensityData { get; }
+ /// True when the file holds an intensity for its points; it is read from the node table.
+ public bool HasIntensityData => _scans.Count > 0 && _scans[0].HasIntensities;
///
public override IReadOnlyList Scans => _scans;
@@ -74,9 +74,6 @@ private RcsScanDocument(
LocalBounds = localBounds;
OctreeBounds = octreeBounds;
DeclaredPointCount = pointCount;
- HasColorData = true;
- HasNormalData = true;
- HasIntensityData = true;
var scan = new RcsScan(this, path);
_scans.Add(scan);
@@ -211,13 +208,19 @@ 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 ulong MaxNodes = 500_000;
+
+ // Bytes of one point record: the position of the point and, when the node holds them, the intensity and the
+ // colour. A record without them is shorter.
private const int PointRecordSize = 16;
+ private const int PositionRecordSize = 10;
private const int NormalRecordSize = 4;
private const double Quantization = 0.0001;
private readonly RcsScanDocument _document;
private readonly string _filePath;
+ private (bool Colors, bool Intensities, bool Normals)? _channels;
+
///
public override string Id => _document.ScanGuid;
@@ -233,14 +236,14 @@ public sealed class RcsScan : PclScan
///
public override PclTransform Transform => _document.ScanTransform;
- /// Always true: a fixed constant of the supported layout, not read from the file.
- public override bool HasColors => _document.HasColorData;
+ /// True when the file holds colour for its points; it is read from the node table.
+ public override bool HasColors => Channels.Colors;
- /// Always true: a fixed constant of the supported layout, not read from the file; single points may still have no normal.
- public override bool HasNormals => _document.HasNormalData;
+ /// True when the file holds normals for its points; it is read from the node table.
+ public override bool HasNormals => Channels.Normals;
- /// Always true: a fixed constant of the supported layout, not read from the file.
- public override bool HasIntensities => _document.HasIntensityData;
+ /// True when the file holds an intensity for its points; it is read from the node table.
+ public override bool HasIntensities => Channels.Intensities;
internal RcsScan(RcsScanDocument document, string filePath)
{
@@ -250,6 +253,37 @@ internal RcsScan(RcsScanDocument document, string filePath)
private readonly record struct Node(PclVector3 TightMin, uint Points, uint Bytes);
+ // The channels of the points follow from the size of the payload of the nodes.
+ private (bool Colors, bool Intensities, bool Normals) Channels => _channels ??= DetectChannels();
+
+ private (bool, bool, bool) DetectChannels()
+ {
+ var layout = RcsLayout.ForVersion(_document.MajorVersion);
+ if (layout == null) return (false, false, false);
+
+ try
+ {
+ using var fs = File.OpenRead(_filePath);
+ var nodes = ReadNodeTable(fs, layout, out _);
+
+ bool colors = false, intensities = false, normals = false;
+ foreach (var node in nodes)
+ {
+ if (node.Points == 0) continue;
+ long bytesPerPoint = node.Bytes / node.Points;
+ if (bytesPerPoint >= PointRecordSize) { colors = true; intensities = true; }
+ if (node.Bytes >= (long)node.Points * (PointRecordSize + NormalRecordSize)) normals = true;
+ }
+
+ return (colors, intensities, normals);
+ }
+ catch (InvalidDataException)
+ {
+ // A damaged node table leaves the channels unknown.
+ return (false, false, false);
+ }
+ }
+
///
/// Streams points from the node table (experimental, major version 3 only). Throws
/// for other versions or node payloads that do not match the known layout,
@@ -286,21 +320,28 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
continue;
}
+ // The size of the payload tells which channels the points of the node hold: a record with the intensity
+ // and the colour is longer than one with the position only.
+ long bytesPerPoint = node.Bytes / node.Points;
+ bool hasColor = bytesPerPoint >= PointRecordSize;
+ int recordSize = hasColor ? PointRecordSize : PositionRecordSize;
+
// The optional normal plane follows the point records.
bool hasNormals = node.Bytes >= (long)node.Points * (PointRecordSize + NormalRecordSize);
- long normalStart = curOffset + ((long)node.Points * PointRecordSize);
+ long normalStart = curOffset + ((long)node.Points * recordSize);
fs.Position = curOffset;
- long remaining = (long)node.Points * PointRecordSize;
+ long remaining = (long)node.Points * recordSize;
long pointIdx = 0;
while (remaining > 0)
{
- int toRead = (int)Math.Min(chunkBuf.Length, remaining);
+ // A chunk holds whole records only, so the next one starts at a record boundary.
+ int toRead = (int)Math.Min(chunkBuf.Length / recordSize * recordSize, remaining);
fs.ReadExactly(chunkBuf, 0, toRead);
remaining -= toRead;
- int ptsInBlock = toRead / PointRecordSize;
+ int ptsInBlock = toRead / recordSize;
if (hasNormals)
{
long resume = fs.Position;
@@ -313,16 +354,11 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
{
if (pointIdx % step != 0) continue;
- int off = p * PointRecordSize;
+ int off = p * recordSize;
ushort v1 = Bytes.ReadUInt16LE(chunkBuf.AsSpan(off + 4, 2));
ushort v2 = Bytes.ReadUInt16LE(chunkBuf.AsSpan(off + 6, 2));
ushort v3 = Bytes.ReadUInt16LE(chunkBuf.AsSpan(off + 8, 2));
- byte intensityByte = chunkBuf[off + 12];
- byte red = chunkBuf[off + 13];
- byte green = chunkBuf[off + 14];
- byte blue = chunkBuf[off + 15];
-
// Fixed-step quantization relative to the node minimum.
double x = node.TightMin.X + (v1 * Quantization);
double y = node.TightMin.Y + (v2 * Quantization);
@@ -344,10 +380,19 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
}
}
+ // A node without colour and intensity holds the position of the point only.
+ PclColor? color = null;
+ float? intensity = null;
+ if (hasColor)
+ {
+ color = new PclColor(chunkBuf[off + 13], chunkBuf[off + 14], chunkBuf[off + 15]);
+ intensity = chunkBuf[off + 12] / 255.0f;
+ }
+
var pt = new PclPoint(
new PclVector3(x, y, z),
- Color: new PclColor(red, green, blue),
- Intensity: intensityByte / 255.0f,
+ Color: color,
+ Intensity: intensity,
Normal: normal,
Index: (ulong)yielded);
@@ -403,8 +448,13 @@ private static List ReadNodeTable(FileStream fs, RcsLayout layout, out lon
tMinX > tMaxX || tMinY > tMaxY || tMinZ > tMaxZ)
throw FormatError.Corrupted("RCS node bounds are invalid.");
- if (nbytes < (long)npts * PointRecordSize)
- throw FormatError.Unsupported("RCS node payload is smaller than the known point record layout.");
+ // The decoder reads records of exactly ten bytes (position), sixteen (position, colour and
+ // intensity) or twenty (the same plus the plane of the normals). Any other payload size would be
+ // read with the wrong stride and return wrong positions, so it is rejected instead of guessed.
+ if (nbytes != (long)npts * PositionRecordSize &&
+ nbytes != (long)npts * PointRecordSize &&
+ nbytes != (long)npts * (PointRecordSize + NormalRecordSize))
+ throw FormatError.Unsupported("RCS node payload does not match a known point record layout.");
}
nodes.Add(new Node(new PclVector3(tMinX, tMinY, tMinZ), npts, nbytes));
diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs
index 24fef5c..f74f244 100644
--- a/tests/PclIO.Tests/FormatTests.cs
+++ b/tests/PclIO.Tests/FormatTests.cs
@@ -90,6 +90,96 @@ public void Read_Synthetic_Rcs_Points_With_And_Without_Transform()
AssertNear(new PclVector3(1, 0, 0), raw[2].Normal!.Value);
}
+ [Fact]
+ public void An_Rcs_Without_Colour_Reports_No_Colour_And_No_Intensity()
+ {
+ using var dir = new TempDirectory();
+ using var doc = RcsScanDocument.Open(dir.Write("plain.rcs",
+ SyntheticFixtures.CreateSyntheticRcsWithPoints(RcsPoints, (0, 0, 0), withColor: false)));
+
+ var scan = Assert.Single(doc.Scans);
+ Assert.False(scan.HasColors);
+ Assert.False(scan.HasIntensities);
+ Assert.False(scan.HasNormals);
+ Assert.False(doc.HasColorData);
+
+ var points = scan.ReadPoints(NoTransform).ToList();
+ Assert.Equal(3, points.Count);
+ Assert.All(points, p =>
+ {
+ Assert.Null(p.Color);
+ Assert.Null(p.Intensity);
+ Assert.Null(p.Normal);
+ });
+ }
+
+ [Theory]
+ [InlineData(12)]
+ [InlineData(14)]
+ [InlineData(17)]
+ [InlineData(21)]
+ public void An_Rcs_Node_With_An_Unknown_Record_Size_Is_Rejected(int bytesPerPoint)
+ {
+ // The decoder knows records of ten, sixteen and twenty bytes; any other size would be read with the
+ // wrong stride and return wrong positions, so the file is rejected instead of guessed.
+ using var dir = new TempDirectory();
+ using var doc = RcsScanDocument.Open(dir.Write("odd.rcs",
+ SyntheticFixtures.CreateSyntheticRcsWithPoints(RcsPoints, (0, 0, 0),
+ declaredPayloadBytes: (uint)(RcsPoints.Length * bytesPerPoint))));
+
+ Assert.Throws(() => doc.Scans[0].ReadPoints().ToList());
+ }
+
+ [Fact]
+ public void An_Rcs_Position_Only_Node_Larger_Than_A_Chunk_Keeps_Record_Alignment()
+ {
+ // A chunk of 65536 bytes holds 6553 whole ten-byte records; the next chunk must start at a record
+ // boundary, not six bytes into a record.
+ var points = Enumerable.Range(0, 7000)
+ .Select(i => new RcsSamplePoint((ushort)(i % 1000), (ushort)(i / 1000), 0, 0, 0, 0, 0)).ToList();
+ using var dir = new TempDirectory();
+ using var doc = RcsScanDocument.Open(dir.Write("big.rcs",
+ SyntheticFixtures.CreateSyntheticRcsWithPoints(points, (0, 0, 0), withColor: false)));
+
+ var all = doc.Scans[0].ReadPoints(NoTransform).ToList();
+ Assert.Equal(7000, all.Count);
+ AssertNear(new PclVector3(0.0553, 0.0006, 0), all[6553].Position);
+ AssertNear(new PclVector3(0.0999, 0.0006, 0), all[6999].Position);
+ }
+
+ [Fact]
+ public void An_Rcs_With_Colour_And_Normals_Reports_Them()
+ {
+ using var dir = new TempDirectory();
+ using var doc = RcsScanDocument.Open(dir.Write("full.rcs",
+ SyntheticFixtures.CreateSyntheticRcsWithPoints(RcsPoints, (0, 0, 0), withNormals: true)));
+
+ var scan = Assert.Single(doc.Scans);
+ Assert.True(scan.HasColors);
+ Assert.True(scan.HasIntensities);
+ Assert.True(scan.HasNormals);
+ Assert.True(doc.HasColorData);
+ Assert.True(doc.HasNormalData);
+
+ var points = scan.ReadPoints(NoTransform).ToList();
+ Assert.Equal(3, points.Count);
+ Assert.All(points, p => Assert.NotNull(p.Color));
+ }
+
+ [Fact]
+ public void An_Rcs_Without_Normals_Reports_No_Normal()
+ {
+ using var dir = new TempDirectory();
+ using var doc = RcsScanDocument.Open(dir.Write("flat.rcs",
+ SyntheticFixtures.CreateSyntheticRcsWithPoints(RcsPoints, (0, 0, 0))));
+
+ var scan = Assert.Single(doc.Scans);
+ Assert.True(scan.HasColors);
+ Assert.True(scan.HasIntensities);
+ Assert.False(scan.HasNormals);
+ Assert.All(scan.ReadPoints(NoTransform), p => Assert.Null(p.Normal));
+ }
+
[Fact]
public void Read_Synthetic_Rcs_Points_Honours_Limit_And_Step()
{
diff --git a/tests/PclIO.Tests/SyntheticFixtures.cs b/tests/PclIO.Tests/SyntheticFixtures.cs
index e3231a4..62d25f7 100644
--- a/tests/PclIO.Tests/SyntheticFixtures.cs
+++ b/tests/PclIO.Tests/SyntheticFixtures.cs
@@ -35,11 +35,18 @@ public static byte[] CreateSyntheticRcs(long pointCount = 100, double tx = 1.0,
/// Point records; the position is plus 0.0001 times each offset.
/// Tight minimum of the node.
/// Whether the packed normal plane follows the records.
+ /// Whether the records hold an intensity and a colour; without them they hold the position only.
+ /// Overrides the payload size the node declares; the records stay as written.
+ /// Translation of the scan.
+ /// Translation of the scan.
+ /// Translation of the scan.
public static byte[] CreateSyntheticRcsWithPoints(IReadOnlyList points, (double X, double Y, double Z) nodeMin,
- bool withNormals = false, double tx = 0.0, double ty = 0.0, double tz = 0.0)
+ bool withNormals = false, double tx = 0.0, double ty = 0.0, double tz = 0.0, bool withColor = true, uint? declaredPayloadBytes = null)
{
- int recordBytes = points.Count * (16 + (withNormals ? 4 : 0));
- byte[] buffer = new byte[RcsNodeTableOffset + 8 + RcsNodeSize + recordBytes];
+ int recordBytes = withColor ? 16 : 10;
+ int recordBytesTotal = recordBytes + (withNormals ? 4 : 0);
+ int recordBytes_ = points.Count * recordBytesTotal;
+ byte[] buffer = new byte[RcsNodeTableOffset + 8 + RcsNodeSize + recordBytes_];
WriteRcsHeader(buffer, points.Count, tx, ty, tz);
BinaryPrimitives.WriteUInt64LittleEndian(buffer.AsSpan(RcsNodeTableOffset, 8), 1);
@@ -51,21 +58,25 @@ public static byte[] CreateSyntheticRcsWithPoints(IReadOnlyList
BinaryPrimitives.WriteDoubleLittleEndian(node.Slice(0x48 + (i * 8), 8), min[i] + 7.0);
}
BinaryPrimitives.WriteUInt32LittleEndian(node.Slice(0x64, 4), (uint)points.Count);
- BinaryPrimitives.WriteUInt32LittleEndian(node.Slice(0x68, 4), (uint)recordBytes);
+ BinaryPrimitives.WriteUInt32LittleEndian(node.Slice(0x68, 4), declaredPayloadBytes ?? (uint)recordBytes_);
- int payload = buffer.Length - recordBytes;
- int normals = payload + (points.Count * 16);
+ int payload = buffer.Length - recordBytes_;
+ int normals = payload + (points.Count * recordBytes);
for (int i = 0; i < points.Count; i++)
{
var p = points[i];
- Span record = buffer.AsSpan(payload + (i * 16), 16);
+ Span record = buffer.AsSpan(payload + (i * recordBytes), recordBytes);
BinaryPrimitives.WriteUInt16LittleEndian(record.Slice(4, 2), p.X);
BinaryPrimitives.WriteUInt16LittleEndian(record.Slice(6, 2), p.Y);
BinaryPrimitives.WriteUInt16LittleEndian(record.Slice(8, 2), p.Z);
- record[12] = p.Intensity;
- record[13] = p.R;
- record[14] = p.G;
- record[15] = p.B;
+ if (withColor)
+ {
+ record[12] = p.Intensity;
+ record[13] = p.R;
+ record[14] = p.G;
+ record[15] = p.B;
+ }
+
if (withNormals)
{
buffer[normals + (i * 4)] = (byte)p.Nx;