From ddb561744c5d45d9d33c6efaa3683460da7e00a9 Mon Sep 17 00:00:00 2001
From: mahach666 <79989386+mahach666@users.noreply.github.com>
Date: Mon, 16 Nov 2026 01:49:41 +0000
Subject: [PATCH] Take the point count of a Leica scan from the container when
it states one
---
CHANGELOG.md | 2 +
README.md | 2 +-
docs/public-api.md | 2 +-
src/PclIO/Formats/Leica/LgsxDocument.cs | 70 ++++++++++++++++++++-----
tests/PclIO.Tests/CliTests.cs | 5 +-
tests/PclIO.Tests/FormatTests.cs | 36 +++++++++++++
tests/PclIO.Tests/SyntheticFixtures.cs | 31 ++++++++---
7 files changed, 122 insertions(+), 26 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a3e3dae..c472fd6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
setup. A container that does not assign its points to its setups still opens as one scan, with a warning.
- The pose and the bounds of a Leica setup are read from the record of the setup and applied to its points, unless
`ApplyTransform` is false. A record that does not hold usable values is left unread, and the setup keeps an unknown pose.
+- The point count of a Leica scan is taken from the container when it states one, so that reading it does not decode the
+ point data. Only a container without that number still needs the decoding.
## [0.1.0] - 2026-11-15
diff --git a/README.md b/README.md
index 56f610c..2221728 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,7 @@ The library targets .NET 8 and .NET 10. It is managed code with no dependencies
| 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 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 found by decoding the data, which is slow on large files. |
+| 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 grid size, not a count of valid returns. Folder scans are read with an assumed record layout and intensity scale (a warning says so). |
| PinPoint project | `.srf`, `.smf`, or a folder with `ScanProject.json` or `.smf`/`.srf` files | Experimental. The manifest (scan names, ids, poses, counts) is read. Points come from the referenced `.bin` files, in either of two layouts: a table of named channels, or numbered sections with a property table and Snappy-compressed channels, which PclIO decodes itself. Colour, intensity and normals are reported only when the file has that channel; in the second layout only positions, colours and intensities are read, and the per-point flags and grid indices stored beside them are not interpreted, so every stored point that passes the plausibility rule below is returned. A manifest with a scan position list takes the point count from the manifest, else from the data file; a manifest with a data object list always reports 0 because that count is not known. |
| EdgeWise | `.c3db`, `.c3ptx` | Experimental. A `.c3db` point database lists the scan clusters and a `.c3ptx` is one cluster file; the cluster files give positions only. The scale of the cluster positions is not stored in the files, so it is an assumption of the reader and positions are only as exact as it. |
diff --git a/docs/public-api.md b/docs/public-api.md
index 7c85fc8..c2a8928 100644
--- a/docs/public-api.md
+++ b/docs/public-api.md
@@ -62,7 +62,7 @@ drop points that fail a plausibility rule (see the README), so a scan can yield
| 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 project | Declared by the project manifest; 0 when the manifest states none. |
-| Leica | Computed. The container does not store it, so the first access decodes 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. |
+| 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 | Approximate: the size of the scan grid (rows times columns), not the number of valid returns. For a folder scan it is limited by the size of the data stream. |
| 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. |
diff --git a/src/PclIO/Formats/Leica/LgsxDocument.cs b/src/PclIO/Formats/Leica/LgsxDocument.cs
index 4fc881e..1158f58 100644
--- a/src/PclIO/Formats/Leica/LgsxDocument.cs
+++ b/src/PclIO/Formats/Leica/LgsxDocument.cs
@@ -20,8 +20,11 @@ public sealed class LgsxDocument : PclDocument
private const int TailBytes = 4096;
// Size of the record of a setup: the translation and the bounds of the setup as six doubles, then the offset
- // and the length of the range of the point data that belongs to it.
- private const int SetupRecordSize = 88;
+ // and the length of the range of the point data that belongs to it and the number of its points.
+ private const int SetupRecordSize = 96;
+
+ // Offset of the number of points of the point data in the header of the payload; zero when it is not stored.
+ private const int PayloadPointCountOffset = 0x28;
private static readonly TimeSpan RegexTimeout = TimeSpan.FromSeconds(1);
@@ -202,6 +205,7 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null)
Bounds = record.Bounds,
PointOffset = record.PointOffset,
PointLength = record.PointLength,
+ PointCount = record.PointCount,
};
}
@@ -216,6 +220,9 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null)
? AssignBlocksToSetups(path, pointCloudEntry, document._setups)
: null;
+ // The number of points is read from the container when it states it; otherwise it is counted by decoding.
+ long? declaredCount = pointCloudEntry != null ? ReadDeclaredPointCount(fs, pointCloudEntry) : null;
+
if (assignments != null)
{
foreach (var (setup, blockStarts) in assignments)
@@ -227,7 +234,8 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null)
pointCloudEntry: pointCloudEntry!,
blockStarts: blockStarts,
transform: setup.Translation is { } translation ? new PclTransform { Translation = translation } : null,
- bounds: setup.Bounds));
+ bounds: setup.Bounds,
+ declaredPointCount: setup.PointCount >= 0 ? setup.PointCount : null));
}
document._warnings.Add(
@@ -242,7 +250,8 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null)
id: "unified-cloud",
name: Path.GetFileNameWithoutExtension(path),
path: path,
- pointCloudEntry: pointCloudEntry));
+ pointCloudEntry: pointCloudEntry,
+ declaredPointCount: declaredCount));
}
if (scanSetups.Count > 0)
@@ -264,16 +273,16 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null)
}
///
- /// The record of a setup: the translation of the setup, the bounds of its points and the range of the point
- /// blocks it owns inside the point data.
+ /// The record of a setup: the translation of the setup, the bounds of its points, the range of the point
+ /// blocks it owns inside the point data and the number of its points.
///
- private sealed record SetupRecord(PclVector3 Translation, PclBounds Bounds, ulong PointOffset, ulong PointLength);
+ private sealed record SetupRecord(PclVector3 Translation, PclBounds Bounds, ulong PointOffset, ulong PointLength, long PointCount);
///
/// Reads the record of a setup from the payload of its container entry. The record holds the translation of the
/// setup and the bounds of its points as six doubles, then the offset and the length of the range of the point
- /// blocks it owns. A record that is too short or holds values that are not usable is left unread, so that the
- /// setup keeps an unknown pose instead of a wrong one.
+ /// blocks it owns and the number of its points. A record that is too short or holds values that are not usable is
+ /// left unread, so that the setup keeps an unknown pose instead of a wrong one.
///
private static SetupRecord? ReadSetupRecord(FileStream fs, LgsxSetup setup)
{
@@ -304,8 +313,33 @@ private sealed record SetupRecord(PclVector3 Translation, PclBounds Bounds, ulon
ulong pointOffset = Bytes.ReadUInt64LE(data.AsSpan(72, 8));
ulong pointLength = Bytes.ReadUInt64LE(data.AsSpan(80, 8));
+ ulong pointCount = Bytes.ReadUInt64LE(data.AsSpan(88, 8));
+
+ return new SetupRecord(
+ new PclVector3(tx, ty, tz),
+ bounds,
+ pointOffset,
+ pointLength,
+ pointCount > long.MaxValue ? -1 : (long)pointCount);
+ }
+
+ ///
+ /// Reads the number of points that the header of the point data declares, or null when it declares none.
+ /// A damaged header yields no count, so that the points are counted by decoding them.
+ ///
+ private static long? ReadDeclaredPointCount(FileStream fs, LgsxEntry entry)
+ {
+ long payloadOffset = (long)entry.Offset;
+ if (payloadOffset < 0 || payloadOffset > fs.Length - 64) return null;
+
+ fs.Position = payloadOffset;
+ byte[] header = new byte[64];
+ fs.ReadExactly(header);
+ if (!header.AsSpan(0, 4).SequenceEqual(PointDataMagic)) return null;
- return new SetupRecord(new PclVector3(tx, ty, tz), bounds, pointOffset, pointLength);
+ ulong count = Bytes.ReadUInt64LE(header.AsSpan(PayloadPointCountOffset, 8));
+ if (count == 0 || count > long.MaxValue) return null;
+ return (long)count;
}
///
@@ -457,6 +491,9 @@ public sealed record LgsxSetup(string Id, string Name, ulong Offset, ulong Size)
/// Length of the range of the point data that belongs to the setup, in bytes.
public ulong PointLength { get; init; }
+
+ /// Number of points of the setup, or -1 when the container does not state it.
+ public long PointCount { get; init; } = -1;
}
///
@@ -489,6 +526,9 @@ public sealed class LgsxScan : PclScan
// Start offsets of the blocks that belong to this scan; null when the scan holds all blocks of the container.
private readonly long[]? _blockStarts;
+ // Number of points the container states for this scan; null when it states none.
+ private readonly long? _declaredPointCount;
+
private long _pointCount = -1;
private (bool Colors, bool Intensities, bool Normals)? _channels;
@@ -499,11 +539,12 @@ public sealed class LgsxScan : PclScan
public override string Name { get; }
///
- /// Number of points this scan yields. The container does not store it, so the first access decodes
- /// the whole point data and caches the result; this can be slow for large files.
+ /// Number of points this scan yields. The number the container states is used when it states one; otherwise the
+ /// first access decodes the whole point data and caches the result, which can be slow for large files.
///
/// The point data is malformed; the exception is thrown by the first access.
- public override long PointCount => _pointCount >= 0 ? _pointCount : _pointCount = CountPoints();
+ public override long PointCount =>
+ _declaredPointCount ?? (_pointCount >= 0 ? _pointCount : _pointCount = CountPoints());
/// True when the first point block carries colour planes.
public override bool HasColors => Channels.Colors;
@@ -517,13 +558,14 @@ public sealed class LgsxScan : PclScan
private (bool Colors, bool Intensities, bool Normals) Channels => _channels ??= DetectChannels();
internal LgsxScan(string id, string name, string path, LgsxEntry? pointCloudEntry, long[]? blockStarts = null,
- PclTransform? transform = null, PclBounds? bounds = null)
+ PclTransform? transform = null, PclBounds? bounds = null, long? declaredPointCount = null)
{
Id = id;
Name = name;
_filePath = path;
_entry = pointCloudEntry;
_blockStarts = blockStarts;
+ _declaredPointCount = declaredPointCount;
if (transform != null) Transform = transform;
if (bounds != null) Bounds = bounds.Value;
}
diff --git a/tests/PclIO.Tests/CliTests.cs b/tests/PclIO.Tests/CliTests.cs
index 64b4728..2d52e11 100644
--- a/tests/PclIO.Tests/CliTests.cs
+++ b/tests/PclIO.Tests/CliTests.cs
@@ -650,8 +650,9 @@ public void Export_To_A_Path_Without_A_Containing_Folder_Is_A_Usage_Error()
[InlineData("scans")]
public void A_Count_That_Fails_On_Its_First_Access_Writes_No_Partial_Output(params string[] command)
{
- // The Leica point count is decoded on first access; the failure must come before the first line of output.
- byte[] bytes = SyntheticFixtures.CreateSyntheticLgsx();
+ // The Leica point count is decoded on first access when the container does not state it; the failure must come
+ // before the first line of output.
+ byte[] bytes = SyntheticFixtures.CreateSyntheticLgsx(withPointCount: false);
int block = System.Text.Encoding.Latin1.GetString(bytes).IndexOf("APRN", StringComparison.Ordinal);
Array.Fill(bytes, (byte)0xA5, block + 0x40, Math.Min(32, bytes.Length - block - 0x40));
using var dir = new TempDirectory();
diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs
index 4c3b3d9..809a983 100644
--- a/tests/PclIO.Tests/FormatTests.cs
+++ b/tests/PclIO.Tests/FormatTests.cs
@@ -467,6 +467,42 @@ public void A_Lgsx_Container_Whose_Setup_Names_Share_An_Id_Stays_One_Scan()
Assert.Contains(doc.Warnings, w => w.Contains("points are not assigned to them", StringComparison.Ordinal));
}
+ [Fact]
+ public void The_Point_Count_Of_A_Lgsx_Container_Is_The_One_The_Container_States()
+ {
+ using var dir = new TempDirectory();
+ using var doc = LgsxDocument.Open(dir.Write("site.lgsx", SyntheticFixtures.CreateSyntheticLgsx()));
+
+ // The count of the container and the count of the decoded points are the same.
+ var scan = Assert.Single(doc.Scans);
+ Assert.Equal(5, scan.PointCount);
+ Assert.Equal(scan.PointCount, scan.ReadPoints().LongCount());
+ }
+
+ [Fact]
+ public void The_Point_Count_Of_The_Setups_Of_A_Lgsx_Container_Is_The_One_The_Container_States()
+ {
+ using var dir = new TempDirectory();
+ using var doc = LgsxDocument.Open(dir.Write("site.lgsx",
+ SyntheticFixtures.CreateSyntheticLgsx(setupCount: 3, assignPointsToSetups: true)));
+
+ Assert.Equal([2L, 2L, 1L], doc.Scans.Select(s => s.PointCount));
+ Assert.Equal([2L, 2L, 1L], doc.Scans.Select(s => s.ReadPoints().LongCount()));
+ }
+
+ [Fact]
+ public void The_Point_Count_Of_A_Lgsx_Scan_Does_Not_Decode_The_Points()
+ {
+ using var dir = new TempDirectory();
+ using var doc = LgsxDocument.Open(dir.Write("site.lgsx", SyntheticFixtures.CreateSyntheticLgsx(damagedPointData: true)));
+
+ var scan = Assert.Single(doc.Scans);
+
+ // The count comes from the container, so the damaged point data is not decoded to find it.
+ Assert.Equal(5, scan.PointCount);
+ Assert.Throws(() => scan.ReadPoints().ToList());
+ }
+
[Fact]
public void A_Lgsx_Block_Is_Not_Cut_At_65536_Points()
{
diff --git a/tests/PclIO.Tests/SyntheticFixtures.cs b/tests/PclIO.Tests/SyntheticFixtures.cs
index 211bef3..6a09096 100644
--- a/tests/PclIO.Tests/SyntheticFixtures.cs
+++ b/tests/PclIO.Tests/SyntheticFixtures.cs
@@ -153,9 +153,11 @@ public static byte[] CreateZip(string entryName, string text)
/// True lets every setup declare the range of the first block.
/// True names the second setup so its id after the last dash equals the first's.
/// True writes a setup record whose translation is not a number.
+ /// True writes point blocks whose compressed frames cannot be decoded.
+ /// False leaves the number of points out of the header of the point data.
public static byte[] CreateSyntheticLgsx(IReadOnlyList? points = null, bool withColorAndIntensity = false, bool withPointData = true,
IReadOnlyList? extraPlanes = null, int setupCount = 1, bool assignPointsToSetups = false, bool overlappingSetupRanges = false,
- bool collidingSetupNames = false, bool damagedSetupRecord = false)
+ bool collidingSetupNames = false, bool damagedSetupRecord = false, bool damagedPointData = false, bool withPointCount = true)
{
points ??= DefaultLeicaPoints;
using var ms = new MemoryStream();
@@ -169,7 +171,7 @@ public static byte[] CreateSyntheticLgsx(IReadOnlyList? points
: new List> { points };
(byte[] payload, List<(long Start, long Length)> blocks) =
- BuildLeicaPayload(groups, withColorAndIntensity, extraPlanes ?? []);
+ BuildLeicaPayload(groups, withColorAndIntensity, extraPlanes ?? [], damagedPointData, withPointCount);
// The point data follows the container entries and their records, so its start is known before they are written.
var setupNames = Enumerable.Range(0, setupCount).Select(i => "SETUP-" + (3 + i)).ToList();
@@ -203,7 +205,9 @@ public static byte[] CreateSyntheticLgsx(IReadOnlyList? points
bool hasBlock = i < blocks.Count;
int blockIndex = overlappingSetupRanges ? 0 : i;
WriteSetupRecord(bw, i, hasBlock ? payloadStart + blocks[blockIndex].Start : 0,
- hasBlock ? (ulong)blocks[blockIndex].Length : 0, damaged: damagedSetupRecord);
+ hasBlock ? (ulong)blocks[blockIndex].Length : 0,
+ hasBlock ? groups[blockIndex].Count : 0,
+ damaged: damagedSetupRecord);
}
long pointEntry = ms.Position;
@@ -221,10 +225,12 @@ public static byte[] CreateSyntheticLgsx(IReadOnlyList? points
}
// The size of the record of a setup.
- public const int SetupRecordSize = 88;
+ public const int SetupRecordSize = 96;
- // Writes the record of a setup: the translation and the bounds of the setup, then the range of its points.
- private static void WriteSetupRecord(BinaryWriter bw, int setupIndex, long pointOffset, ulong pointLength, bool damaged)
+ // Writes the record of a setup: the translation and the bounds of the setup, then the range of its points
+ // and the number of them.
+ private static void WriteSetupRecord(BinaryWriter bw, int setupIndex, long pointOffset, ulong pointLength,
+ long pointCount, bool damaged)
{
double[] translation = damaged
? [double.NaN, 2 + setupIndex, 3 + setupIndex]
@@ -241,6 +247,7 @@ private static void WriteSetupRecord(BinaryWriter bw, int setupIndex, long point
bw.Write((ulong)pointOffset);
bw.Write(pointLength);
+ bw.Write((ulong)pointCount);
}
// Distributes the points over the setups; a setup without points gets no block.
@@ -291,15 +298,18 @@ private static void WriteEntry(BinaryWriter bw, string name, ulong payloadOffset
// Builds the point data payload: a header, then one block per group of points.
private static (byte[] Payload, List<(long Start, long Length)> Blocks) BuildLeicaPayload(
- IReadOnlyList> groups, bool full, IReadOnlyList extraPlanes)
+ IReadOnlyList> groups, bool full, IReadOnlyList extraPlanes, bool damaged = false,
+ bool withPointCount = true)
{
using var ms = new MemoryStream();
using var bw = new BinaryWriter(ms);
- // Payload header: signature and the offset of the first block.
+ // Payload header: signature, the offset of the first block and the number of points.
byte[] header = new byte[64];
"mMPK"u8.CopyTo(header);
BinaryPrimitives.WriteUInt32LittleEndian(header.AsSpan(0x20, 4), 64);
+ if (withPointCount)
+ BinaryPrimitives.WriteUInt64LittleEndian(header.AsSpan(0x28, 8), (ulong)groups.Sum(g => g.Count));
bw.Write(header);
var blocks = new List<(long Start, long Length)>();
@@ -309,6 +319,11 @@ private static (byte[] Payload, List<(long Start, long Length)> Blocks) BuildLei
if (group.Count == 0) continue;
var frames = BuildFrames(group, full, extraPlanes);
+ if (damaged)
+ {
+ // A frame whose descriptor is not valid: the header of the block stays readable, the data does not.
+ foreach (byte[] broken in frames) broken[4] = 0x5A;
+ }
int blockLength = 8 + 128 + frames.Sum(f => 8 + f.Length);
long start = ms.Position;