From c753073fe88995cf315727f4f0437ff2bed35151 Mon Sep 17 00:00:00 2001 From: mahach666 <79989386+mahach666@users.noreply.github.com> Date: Mon, 16 Nov 2026 01:45:38 +0000 Subject: [PATCH] Read the pose and the bounds of the setups of a Leica container --- CHANGELOG.md | 2 + README.md | 2 +- docs/public-api.md | 2 +- src/PclIO/Formats/Leica/LgsxDocument.cs | 116 +++++++++++++++++++++--- tests/PclIO.Tests/FormatTests.cs | 53 ++++++++++- tests/PclIO.Tests/SyntheticFixtures.cs | 57 ++++++++++-- 6 files changed, 204 insertions(+), 28 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 32960f1..a3e3dae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Leica containers that assign their points to their setups now open as one scan per setup, with the id and the name of the 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. ## [0.1.0] - 2026-11-15 diff --git a/README.md b/README.md index 64dcb96..56f610c 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; when it does not, all points of the container form one scan and a warning says so. Poses and bounds are not read, and 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 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 5783502..7c85fc8 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`. | +| 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. | | 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 b0b8bc4..4fc881e 100644 --- a/src/PclIO/Formats/Leica/LgsxDocument.cs +++ b/src/PclIO/Formats/Leica/LgsxDocument.cs @@ -19,6 +19,10 @@ public sealed class LgsxDocument : PclDocument private const int EntryHeaderBytes = 128; 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; + private static readonly TimeSpan RegexTimeout = TimeSpan.FromSeconds(1); private static readonly Regex GuidPattern = new( @@ -185,7 +189,23 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null) { string setupId = name[(lastDash + 1)..]; scanSetups.Add(setupId); - document._setups.Add(new LgsxSetup(setupId, name, payloadOffset, payloadLength)); + + var setup = new LgsxSetup(setupId, name, payloadOffset, payloadLength); + + // The payload of a setup entry holds its record: the pose, the bounds and the range of its points. + var record = ReadSetupRecord(fs, setup); + if (record != null) + { + setup = setup with + { + Translation = record.Translation, + Bounds = record.Bounds, + PointOffset = record.PointOffset, + PointLength = record.PointLength, + }; + } + + document._setups.Add(setup); } } } @@ -205,7 +225,9 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null) name: setup.Name, path: path, pointCloudEntry: pointCloudEntry!, - blockStarts: blockStarts)); + blockStarts: blockStarts, + transform: setup.Translation is { } translation ? new PclTransform { Translation = translation } : null, + bounds: setup.Bounds)); } document._warnings.Add( @@ -231,17 +253,65 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null) { if (pointCloudEntry == null) document._warnings.Add("No point data entry was found; scans have no readable points."); - document._warnings.Add("Scan poses and bounds are not read; points are reported in container coordinates."); + + if (assignments != null) + document._warnings.Add($"The poses and the bounds of {assignments.Count} setups are read and applied."); + else + document._warnings.Add("Scan poses and bounds are not read; points are reported in container coordinates."); } return document; } /// - /// Assigns the point blocks of the point data to the setups that own them. A setup owns a range of the point data - /// when the range it declares lies inside the point data; a block belongs to the setup whose range holds it. - /// Returns null when the container does not assign all of its points to setups, so that the caller can fall - /// back to a single scan. + /// 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. + /// + private sealed record SetupRecord(PclVector3 Translation, PclBounds Bounds, ulong PointOffset, ulong PointLength); + + /// + /// 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. + /// + private static SetupRecord? ReadSetupRecord(FileStream fs, LgsxSetup setup) + { + if (setup.Size < SetupRecordSize) return null; + if (setup.Offset >= (ulong)fs.Length || setup.Size > (ulong)fs.Length - setup.Offset) return null; + + fs.Position = (long)setup.Offset; + byte[] data = new byte[SetupRecordSize]; + fs.ReadExactly(data); + + double tx = Bytes.ReadDoubleLE(data.AsSpan(0, 8)); + double ty = Bytes.ReadDoubleLE(data.AsSpan(8, 8)); + double tz = Bytes.ReadDoubleLE(data.AsSpan(16, 8)); + double minX = Bytes.ReadDoubleLE(data.AsSpan(24, 8)); + double minY = Bytes.ReadDoubleLE(data.AsSpan(32, 8)); + double minZ = Bytes.ReadDoubleLE(data.AsSpan(40, 8)); + double maxX = Bytes.ReadDoubleLE(data.AsSpan(48, 8)); + double maxY = Bytes.ReadDoubleLE(data.AsSpan(56, 8)); + double maxZ = Bytes.ReadDoubleLE(data.AsSpan(64, 8)); + + if (!double.IsFinite(tx) || !double.IsFinite(ty) || !double.IsFinite(tz) || + !double.IsFinite(minX) || !double.IsFinite(minY) || !double.IsFinite(minZ) || + !double.IsFinite(maxX) || !double.IsFinite(maxY) || !double.IsFinite(maxZ)) + return null; + + var bounds = new PclBounds(new PclVector3(minX, minY, minZ), new PclVector3(maxX, maxY, maxZ)); + if (bounds.IsEmpty) return null; + + ulong pointOffset = Bytes.ReadUInt64LE(data.AsSpan(72, 8)); + ulong pointLength = Bytes.ReadUInt64LE(data.AsSpan(80, 8)); + + return new SetupRecord(new PclVector3(tx, ty, tz), bounds, pointOffset, pointLength); + } + + /// + /// Assigns the point blocks of the point data to the setups that own them. A setup owns the range of the point + /// data that its record declares; a block belongs to the setup whose range holds it. Returns null when the + /// container does not assign all of its points to setups, so that the caller can fall back to a single scan. /// private static List<(LgsxSetup Setup, long[] BlockStarts)>? AssignBlocksToSetups( string path, LgsxEntry pointCloudEntry, List setups) @@ -251,13 +321,13 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null) long payloadStart = (long)pointCloudEntry.Offset; long payloadEnd = payloadStart + (long)pointCloudEntry.Size; - // Only a setup whose range lies inside the point data can own points of it. + // Only a setup whose record declares a range inside the point data can own points of it. var owners = new List<(LgsxSetup Setup, long Start, long End)>(); foreach (var setup in setups) { - if (setup.Size == 0) continue; - long start = (long)setup.Offset; - long end = start + (long)setup.Size; + if (setup.PointLength == 0) continue; + long start = (long)setup.PointOffset; + long end = start + (long)setup.PointLength; if (start < payloadStart || end > payloadEnd) continue; owners.Add((setup, start, end)); } @@ -372,9 +442,22 @@ public sealed record LgsxEntry(string Name, ulong Offset, ulong Size); /// A setup listed in a Leica scan container. /// Identifier of the setup, the part of the entry name after its last dash. /// Name of the container entry that lists the setup. -/// Offset of the range the setup declares, in bytes from the start of the file. -/// Length of the range the setup declares, in bytes. -public sealed record LgsxSetup(string Id, string Name, ulong Offset, ulong Size); +/// Offset of the record of the setup, in bytes from the start of the file. +/// Length of the record of the setup, in bytes. +public sealed record LgsxSetup(string Id, string Name, ulong Offset, ulong Size) +{ + /// Translation of the setup, or null when its record does not hold one. + public PclVector3? Translation { get; init; } + + /// Bounds of the points of the setup, or null when its record does not hold them. + public PclBounds? Bounds { get; init; } + + /// Offset of the range of the point data that belongs to the setup, in bytes from the start of the file. + public ulong PointOffset { get; init; } + + /// Length of the range of the point data that belongs to the setup, in bytes. + public ulong PointLength { get; init; } +} /// /// Scan representation in a Leica LGS/LGSx container: the points of one setup, or all points of the container when @@ -433,13 +516,16 @@ 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) + internal LgsxScan(string id, string name, string path, LgsxEntry? pointCloudEntry, long[]? blockStarts = null, + PclTransform? transform = null, PclBounds? bounds = null) { Id = id; Name = name; _filePath = path; _entry = pointCloudEntry; _blockStarts = blockStarts; + if (transform != null) Transform = transform; + if (bounds != null) Bounds = bounds.Value; } /// Decoded planes of one point block together with its coordinate frame. diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs index e5e9e1b..4c3b3d9 100644 --- a/tests/PclIO.Tests/FormatTests.cs +++ b/tests/PclIO.Tests/FormatTests.cs @@ -352,8 +352,9 @@ public void A_Lgsx_Container_That_Assigns_Its_Points_To_Its_Setups_Has_One_Scan_ Assert.Equal(5, doc.ReadAllPoints().Count()); Assert.Equal([2L, 2L, 1L], doc.Scans.Select(s => s.PointCount)); - // Every setup holds the points of its own block. + // Every setup holds the points of its own block, in the frame of the container. var expected = new List(); + int setup = 0; foreach (var group in new[] { 2, 2, 1 }) { for (int i = 0; i < group; i++) @@ -364,12 +365,60 @@ public void A_Lgsx_Container_That_Assigns_Its_Points_To_Its_Setups_Has_One_Scan_ SyntheticFixtures.LeicaOriginY + (written.Y * SyntheticFixtures.LeicaScale), SyntheticFixtures.LeicaOriginZ + (written.Z * SyntheticFixtures.LeicaScale))); } + + setup++; } - var all = doc.ReadAllPoints().Select(p => p.Position).ToList(); + var all = doc.ReadAllPoints(NoTransform).Select(p => p.Position).ToList(); for (int i = 0; i < expected.Count; i++) AssertNear(expected[i], all[i]); } + [Fact] + public void A_Lgsx_Setup_Reads_Its_Pose_And_Its_Bounds_And_Applies_The_Pose() + { + using var dir = new TempDirectory(); + using var doc = LgsxDocument.Open(dir.Write("site.lgsx", + SyntheticFixtures.CreateSyntheticLgsx(setupCount: 2, assignPointsToSetups: true))); + + var first = doc.Scans[0]; + var second = doc.Scans[1]; + + // Every setup record holds the translation and the bounds of its setup. + Assert.Equal(new PclVector3(1, 2, 3), first.Transform.Translation); + Assert.Equal(new PclVector3(2, 3, 4), second.Transform.Translation); + Assert.Equal(new PclBounds( + new PclVector3(SyntheticFixtures.LeicaOriginX, SyntheticFixtures.LeicaOriginY, SyntheticFixtures.LeicaOriginZ), + new PclVector3( + SyntheticFixtures.LeicaOriginX + (1023 * SyntheticFixtures.LeicaScale), + SyntheticFixtures.LeicaOriginY + (1023 * SyntheticFixtures.LeicaScale), + SyntheticFixtures.LeicaOriginZ + (1023 * SyntheticFixtures.LeicaScale))), first.Bounds); + + // The pose moves the points; without it they stay as they are stored. + var moved = first.ReadPoints().ToList(); + var raw = first.ReadPoints(NoTransform).ToList(); + Assert.Equal(3, moved.Count); + for (int i = 0; i < moved.Count; i++) + { + AssertNear(new PclVector3(raw[i].X + 1, raw[i].Y + 2, raw[i].Z + 3), moved[i].Position); + } + } + + [Fact] + public void A_Lgsx_Setup_With_A_Damaged_Record_Keeps_An_Unknown_Pose() + { + using var dir = new TempDirectory(); + using var doc = LgsxDocument.Open(dir.Write("site.lgsx", + SyntheticFixtures.CreateSyntheticLgsx(setupCount: 2, assignPointsToSetups: true, damagedSetupRecord: true))); + + // The record of the first setup holds a value that is not a number, so it is not read; the setups keep no + // points of their own and the container stays one scan. + var scan = Assert.Single(doc.Scans); + Assert.Equal("unified-cloud", scan.Id); + Assert.Equal(PclTransform.Identity, scan.Transform); + Assert.True(scan.Bounds.IsEmpty); + Assert.Contains(doc.Warnings, w => w.Contains("points are not assigned to them", StringComparison.Ordinal)); + } + [Fact] public void A_Lgsx_Setup_Without_Points_Gets_No_Scan() { diff --git a/tests/PclIO.Tests/SyntheticFixtures.cs b/tests/PclIO.Tests/SyntheticFixtures.cs index 89e6526..211bef3 100644 --- a/tests/PclIO.Tests/SyntheticFixtures.cs +++ b/tests/PclIO.Tests/SyntheticFixtures.cs @@ -152,9 +152,10 @@ 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. 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 collidingSetupNames = false, bool damagedSetupRecord = false) { points ??= DefaultLeicaPoints; using var ms = new MemoryStream(); @@ -170,24 +171,39 @@ public static byte[] CreateSyntheticLgsx(IReadOnlyList? points (byte[] payload, List<(long Start, long Length)> blocks) = BuildLeicaPayload(groups, withColorAndIntensity, extraPlanes ?? []); - // The point data follows the container entries, so its start is known before they are written. + // 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(); if (collidingSetupNames && setupCount >= 2) setupNames[1] = "SETUP-A-" + setupNames[0]["SETUP-".Length..]; - long payloadStart = ms.Position + setupNames.Sum(EntrySize) + EntrySize("PointCloud"); + + var entryOffsets = new long[setupCount]; + var recordOffsets = new long[setupCount]; + long position = ms.Position; + for (int i = 0; i < setupCount; i++) + { + entryOffsets[i] = position; + position += EntrySize(setupNames[i]); + recordOffsets[i] = position; + position += assignPointsToSetups ? SetupRecordSize : 0; + } + + long payloadStart = position + EntrySize("PointCloud"); // Container entries as the reader expects them. var setupEntries = new List(); for (int i = 0; i < setupCount; i++) { - setupEntries.Add(ms.Position); + setupEntries.Add(entryOffsets[i]); + + // A setup owns the block it declares; without a record the setup has no points of its own. + bool hasRecord = assignPointsToSetups; + WriteEntry(bw, setupNames[i], hasRecord ? (ulong)recordOffsets[i] : 0, hasRecord ? (ulong)SetupRecordSize : 0); + if (!hasRecord) continue; - // A setup owns the block it declares; without a range the setup has no points of its own. - bool hasBlock = assignPointsToSetups && i < blocks.Count; + bool hasBlock = i < blocks.Count; int blockIndex = overlappingSetupRanges ? 0 : i; - WriteEntry(bw, setupNames[i], - hasBlock ? (ulong)(payloadStart + blocks[blockIndex].Start) : 0, - hasBlock ? (ulong)blocks[blockIndex].Length : 0); + WriteSetupRecord(bw, i, hasBlock ? payloadStart + blocks[blockIndex].Start : 0, + hasBlock ? (ulong)blocks[blockIndex].Length : 0, damaged: damagedSetupRecord); } long pointEntry = ms.Position; @@ -204,6 +220,29 @@ public static byte[] CreateSyntheticLgsx(IReadOnlyList? points return ms.ToArray(); } + // The size of the record of a setup. + public const int SetupRecordSize = 88; + + // 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) + { + double[] translation = damaged + ? [double.NaN, 2 + setupIndex, 3 + setupIndex] + : [1 + setupIndex, 2 + setupIndex, 3 + setupIndex]; + + double[] bounds = + [ + LeicaOriginX, LeicaOriginY, LeicaOriginZ, + LeicaOriginX + (1023 * LeicaScale), LeicaOriginY + (1023 * LeicaScale), LeicaOriginZ + (1023 * LeicaScale), + ]; + + foreach (double value in translation.Concat(bounds)) + bw.Write(value); + + bw.Write((ulong)pointOffset); + bw.Write(pointLength); + } + // Distributes the points over the setups; a setup without points gets no block. private static List> SplitPoints(IReadOnlyList points, int setupCount) {