From a6d7890653aa9a62dc9e835e6ec37ffb4cd1fd06 Mon Sep 17 00:00:00 2001 From: mahach666 <79989386+mahach666@users.noreply.github.com> Date: Mon, 16 Nov 2026 01:41:26 +0000 Subject: [PATCH 1/2] Separate the setups of a Leica container into scans --- CHANGELOG.md | 5 + README.md | 2 +- docs/public-api.md | 4 +- src/PclIO/Formats/Leica/LgsxDocument.cs | 242 +++++++++++++++++++----- tests/PclIO.Tests/FormatTests.cs | 65 +++++++ tests/PclIO.Tests/SyntheticFixtures.cs | 123 +++++++++--- 6 files changed, 358 insertions(+), 83 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index afe7be0..32960f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- 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. + ## [0.1.0] - 2026-11-15 First release. diff --git a/README.md b/README.md index b6ea73d..64dcb96 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. Poses and bounds are not read, all points of a container form one scan (setups are not separated; a warning says so), 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; 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. | | 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 32c5c17..5783502 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. 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`. | | 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. | @@ -73,7 +73,7 @@ are true when the `.rcs` file was found and false otherwise, without the file be ## Format documents -`E57Document`/`E57Scan`, `RcsScanDocument`/`RcsScan`, `RcpProjectDocument`/`RcpScan`, `LgsxDocument`/`LgsxScan`/`LgsxEntry`, +`E57Document`/`E57Scan`, `RcsScanDocument`/`RcsScan`, `RcpProjectDocument`/`RcpScan`, `LgsxDocument`/`LgsxScan`/`LgsxEntry`/`LgsxSetup`, `FaroFlsDocument`/`FaroScan`, `PinPointDocument`/`PinPointScan` and `EdgeWiseDocument`/`EdgeWiseScan` are the readers behind `PclFile.Open`. Each has a static `Open` method and format-specific properties (for example the E57 version or the FARO scanner model). Their XML documentation states what each reader supports. Prefer `PclFile.Open`, which detects the format and chooses the reader. diff --git a/src/PclIO/Formats/Leica/LgsxDocument.cs b/src/PclIO/Formats/Leica/LgsxDocument.cs index dd74fd0..59486c4 100644 --- a/src/PclIO/Formats/Leica/LgsxDocument.cs +++ b/src/PclIO/Formats/Leica/LgsxDocument.cs @@ -10,6 +10,10 @@ public sealed class LgsxDocument : PclDocument // Signature constants the parser needs to recognise the container. private static ReadOnlySpan ContainerMagic => "wild::geosystems"u8; + // Signature of the point data payload and of a point block inside it. + internal static ReadOnlySpan PointDataMagic => "mMPK"u8; + internal static ReadOnlySpan BlockMagic => "APRN"u8; + // Bounds on file-declared sizes so crafted files cannot force large reads. private const int MaxTocEntries = 10_000; private const int EntryHeaderBytes = 128; @@ -36,11 +40,15 @@ public sealed class LgsxDocument : PclDocument /// Table of contents entries in file order. public IReadOnlyList Entries => _entries; + /// Setups listed in the container, in file order. + public IReadOnlyList Setups => _setups; + /// public override IReadOnlyList Scans => _scans; private readonly List _scans = []; private readonly List _entries = []; + private readonly List _setups = []; private readonly bool _isLgsLegacy; private LgsxDocument(string path, long fileSize, string guid, string version, bool isLegacy) @@ -173,22 +181,51 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null) else if (name.StartsWith("SETUP-", StringComparison.OrdinalIgnoreCase)) { int lastDash = name.LastIndexOf('-'); - if (lastDash > 0) scanSetups.Add(name[(lastDash + 1)..]); + if (lastDash > 0) + { + string setupId = name[(lastDash + 1)..]; + scanSetups.Add(setupId); + document._setups.Add(new LgsxSetup(setupId, name, payloadOffset, payloadLength)); + } } } - // One scan for the whole container: the file's assignment of points to setups is not read. - if (scanSetups.Count > 0 || pointCloudEntry != null) + // The points are assigned to the setups when the container says which part of the point data belongs to + // each of them; otherwise all points stay in one scan. + var assignments = pointCloudEntry != null + ? AssignBlocksToSetups(path, pointCloudEntry, document._setups) + : null; + + if (assignments != null) { - document._scans.Add(new LgsxScan( - id: "unified-cloud", - name: Path.GetFileNameWithoutExtension(path), - path: path, - pointCloudEntry: pointCloudEntry)); + foreach (var (setup, blockStarts) in assignments) + { + document._scans.Add(new LgsxScan( + id: setup.Id, + name: setup.Name, + path: path, + pointCloudEntry: pointCloudEntry!, + blockStarts: blockStarts)); + } + + document._warnings.Add( + $"The container lists {document._setups.Count} setups; its points are assigned to {assignments.Count} of them."); } + else + { + // One scan for the whole container: the file's assignment of points to setups is not read. + if (scanSetups.Count > 0 || pointCloudEntry != null) + { + document._scans.Add(new LgsxScan( + id: "unified-cloud", + name: Path.GetFileNameWithoutExtension(path), + path: path, + pointCloudEntry: pointCloudEntry)); + } - if (scanSetups.Count > 0) - document._warnings.Add($"The container lists {scanSetups.Count} setup entries; points are not assigned to them and are returned as one scan."); + if (scanSetups.Count > 0) + document._warnings.Add($"The container lists {scanSetups.Count} setup entries; points are not assigned to them and are returned as one scan."); + } if (document._scans.Count > 0) { @@ -199,6 +236,123 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null) 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. + /// + private static List<(LgsxSetup Setup, long[] BlockStarts)>? AssignBlocksToSetups( + string path, LgsxEntry pointCloudEntry, List setups) + { + if (setups.Count == 0) return 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. + 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 (start < payloadStart || end > payloadEnd) continue; + owners.Add((setup, start, end)); + } + + if (owners.Count == 0) return null; + + // Two setups that claim the same part of the point data would make the assignment ambiguous. + for (int i = 0; i < owners.Count; i++) + for (int j = i + 1; j < owners.Count; j++) + if (owners[i].Start < owners[j].End && owners[j].Start < owners[i].End) + return null; + + List<(long Start, long Length)> chain; + try + { + chain = ReadBlockChain(path, pointCloudEntry); + } + catch (InvalidDataException) + { + // The point data is damaged; the scan reports it when its points are read. + return null; + } + + var bySetup = new Dictionary>(StringComparer.Ordinal); + foreach (var (blockStart, _) in chain) + { + var owner = owners.Find(o => blockStart >= o.Start && blockStart < o.End); + if (owner.Setup is null) return null; // a block that no setup owns + if (!bySetup.TryGetValue(owner.Setup.Id, out var starts)) + { + starts = []; + bySetup[owner.Setup.Id] = starts; + } + + starts.Add(blockStart); + } + + if (bySetup.Count == 0) return null; + + var result = new List<(LgsxSetup, long[])>(); + foreach (var setup in setups) + if (bySetup.TryGetValue(setup.Id, out var starts)) + result.Add((setup, [.. starts])); + return result; + } + + /// Reads the chain of point blocks of a point data payload: their start offsets and their lengths. + /// The payload or a block header is malformed. + internal static List<(long Start, long Length)> ReadBlockChain(string path, LgsxEntry entry) + { + using var fs = File.OpenRead(path); + return ReadBlockChain(fs, entry); + } + + /// Reads the chain of point blocks of a point data payload: their start offsets and their lengths. + /// The payload or a block header is malformed. + internal static List<(long Start, long Length)> ReadBlockChain(FileStream fs, LgsxEntry entry) + { + var chain = new List<(long Start, long Length)>(); + + long fileLength = fs.Length; + long payloadOffset = (long)entry.Offset; + if (payloadOffset > fileLength - 64) throw FormatError.Truncated("the point data header"); + + fs.Position = payloadOffset; + byte[] payloadHeader = new byte[64]; + fs.ReadExactly(payloadHeader); + if (!payloadHeader.AsSpan(0, 4).SequenceEqual(PointDataMagic)) + throw FormatError.Corrupted("point data signature mismatch."); + + // The first block offset is relative to the payload start. + uint blockRelOffset = Bytes.ReadUInt32LE(payloadHeader.AsSpan(0x20, 4)); + long curBlockOffset = payloadOffset + blockRelOffset; + if (curBlockOffset <= payloadOffset || curBlockOffset >= fileLength) + throw FormatError.Corrupted("first point block offset is outside the file."); + + byte[] magicBuf = new byte[8]; + while (curBlockOffset + 64 < fileLength) + { + fs.Position = curBlockOffset; + fs.ReadExactly(magicBuf); + + // Anything other than a block signature ends the chain. + if (!magicBuf.AsSpan(0, 4).SequenceEqual(BlockMagic)) break; + + uint chunkLen = Bytes.ReadUInt32LE(magicBuf.AsSpan(4, 4)); + if (chunkLen < 8 + 128 || chunkLen > fileLength - curBlockOffset) + throw FormatError.Corrupted("point block length is outside the file."); + + chain.Add((curBlockOffset, chunkLen)); + curBlockOffset += chunkLen; + } + + return chain; + } } /// Table of contents entry inside a Leica scan container. @@ -207,15 +361,20 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null) /// Payload length in bytes. 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); + /// -/// Scan representation in a Leica LGS/LGSx container: all points of the container as one scan. -/// Setups are not separated and poses are not applied. +/// Scan representation in a Leica LGS/LGSx container: the points of one setup, or all points of the container when +/// the container does not assign them to its setups. /// public sealed class LgsxScan : PclScan { - // Signature constants the parser needs to recognise point data. - private static ReadOnlySpan PayloadMagic => "mMPK"u8; - private static ReadOnlySpan BlockMagic => "APRN"u8; + // Signature of a compressed frame inside a point block. private static ReadOnlySpan FrameMagic => [0x28, 0xB5, 0x2F, 0xFD]; // Limits that bound memory and work for sizes declared by the file. @@ -236,6 +395,9 @@ public sealed class LgsxScan : PclScan private readonly string _filePath; private readonly LgsxEntry? _entry; + // Start offsets of the blocks that belong to this scan; null when the scan holds all blocks of the container. + private readonly long[]? _blockStarts; + private long _pointCount = -1; private (bool Colors, bool Intensities, bool Normals)? _channels; @@ -263,12 +425,13 @@ 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) + internal LgsxScan(string id, string name, string path, LgsxEntry? pointCloudEntry, long[]? blockStarts = null) { Id = id; Name = name; _filePath = path; _entry = pointCloudEntry; + _blockStarts = blockStarts; } /// Decoded planes of one point block together with its coordinate frame. @@ -397,43 +560,20 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null) } } - /// Walks the chain of point blocks and yields those that carry point planes. + /// Walks the chain of point blocks and yields those that carry point planes and belong to this scan. private IEnumerable ReadBlocks(FileStream fs) { - long payloadOffset = (long)_entry!.Offset; long fileLength = fs.Length; - if (payloadOffset > fileLength - 64) throw FormatError.Truncated("the point data header"); - - fs.Position = payloadOffset; - byte[] payloadHeader = new byte[64]; - fs.ReadExactly(payloadHeader); - if (!payloadHeader.AsSpan(0, 4).SequenceEqual(PayloadMagic)) - throw FormatError.Corrupted("point data signature mismatch."); - - // The first block offset is relative to the payload start. - uint blockRelOffset = Bytes.ReadUInt32LE(payloadHeader.AsSpan(0x20, 4)); - long curBlockOffset = payloadOffset + blockRelOffset; - if (curBlockOffset <= payloadOffset || curBlockOffset >= fileLength) - throw FormatError.Corrupted("first point block offset is outside the file."); - long decodedLimit = DecodedAllowanceBytes + (fileLength * DecodedBytesPerFileByte); long decodedBytes = 0; - byte[] magicBuf = new byte[8]; byte[] blockHeader = new byte[128]; - // chunkLen is at least the header size, so every iteration advances. - while (curBlockOffset + 64 < fileLength) + foreach (var (blockStart, blockLength) in LgsxDocument.ReadBlockChain(fs, _entry!)) { - fs.Position = curBlockOffset; - fs.ReadExactly(magicBuf); - - // Anything other than a block signature ends the chain. - if (!magicBuf.AsSpan(0, 4).SequenceEqual(BlockMagic)) yield break; - - uint chunkLen = Bytes.ReadUInt32LE(magicBuf.AsSpan(4, 4)); - if (chunkLen < 8 + blockHeader.Length || chunkLen > fileLength - curBlockOffset) - throw FormatError.Corrupted("point block length is outside the file."); + if (!BelongsToScan(blockStart)) continue; + // The block header follows the 8-byte block signature and length. + fs.Position = blockStart + 8; fs.ReadExactly(blockHeader); double scaleX = Bytes.ReadDoubleLE(blockHeader.AsSpan(0x34, 8)); @@ -443,11 +583,11 @@ private IEnumerable ReadBlocks(FileStream fs) double minY = Bytes.ReadDoubleLE(blockHeader.AsSpan(0x54, 8)); double minZ = Bytes.ReadDoubleLE(blockHeader.AsSpan(0x5C, 8)); - long blockEnd = curBlockOffset + chunkLen; + long blockEnd = blockStart + blockLength; // Find the first compressed frame; its 8-byte length prefix precedes it. - byte[] searchBuf = new byte[(int)Math.Min(1024L, chunkLen)]; - fs.Position = curBlockOffset + 8; + byte[] searchBuf = new byte[(int)Math.Min(1024L, blockLength)]; + fs.Position = blockStart + 8; int bytesRead = fs.Read(searchBuf, 0, searchBuf.Length); int firstFrame = -1; for (int s = 0; s < bytesRead - 4; s++) @@ -461,7 +601,7 @@ private IEnumerable ReadBlocks(FileStream fs) if (firstFrame >= 8) { - long firstFrameOffset = curBlockOffset + firstFrame; + long firstFrameOffset = blockStart + firstFrame; var frames = ReadAllFrames(fs, firstFrameOffset, blockEnd); // Many small blocks that each expand a lot would otherwise make the file cost unbounded time. @@ -480,11 +620,13 @@ private IEnumerable ReadBlocks(FileStream fs) yield return new Block(scaleX, scaleY, scaleZ, minX, minY, minZ, frames); } } - - curBlockOffset = blockEnd; } } + // A scan without its own blocks holds all of them; otherwise only the blocks the container assigned to it. + private bool BelongsToScan(long blockStart) => + _blockStarts == null || Array.BinarySearch(_blockStarts, blockStart) >= 0; + private static List ReadAllFrames(FileStream fs, long offset, long maxOffset) { var list = new List(); diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs index d2fc4a6..fdb84b9 100644 --- a/tests/PclIO.Tests/FormatTests.cs +++ b/tests/PclIO.Tests/FormatTests.cs @@ -335,6 +335,71 @@ public void A_Lgsx_Container_With_Several_Setups_Is_One_Scan_With_All_Points_And Assert.Contains(doc.Warnings, w => w.Contains("3 setup entries", StringComparison.Ordinal)); } + [Fact] + public void A_Lgsx_Container_That_Assigns_Its_Points_To_Its_Setups_Has_One_Scan_Per_Setup() + { + using var dir = new TempDirectory(); + byte[] bytes = SyntheticFixtures.CreateSyntheticLgsx(setupCount: 3, assignPointsToSetups: true); + using var doc = LgsxDocument.Open(dir.Write("site.lgsx", bytes)); + + Assert.Equal(3, doc.Scans.Count); + Assert.Equal(["SETUP-3", "SETUP-4", "SETUP-5"], doc.Scans.Select(s => s.Name)); + Assert.Equal(["3", "4", "5"], doc.Scans.Select(s => s.Id)); + Assert.Equal(["3", "4", "5"], doc.Setups.Select(s => s.Id)); + + // The points of all setups together are the points of the container. + Assert.Equal(5, doc.TotalPointCount); + 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. + var expected = new List(); + foreach (var group in new[] { 2, 2, 1 }) + { + for (int i = 0; i < group; i++) + { + var written = SyntheticFixtures.DefaultLeicaPoints[expected.Count]; + expected.Add(new PclVector3( + SyntheticFixtures.LeicaOriginX + (written.X * SyntheticFixtures.LeicaScale), + SyntheticFixtures.LeicaOriginY + (written.Y * SyntheticFixtures.LeicaScale), + SyntheticFixtures.LeicaOriginZ + (written.Z * SyntheticFixtures.LeicaScale))); + } + } + + var all = doc.ReadAllPoints().Select(p => p.Position).ToList(); + for (int i = 0; i < expected.Count; i++) AssertNear(expected[i], all[i]); + } + + [Fact] + public void A_Lgsx_Setup_Without_Points_Gets_No_Scan() + { + using var dir = new TempDirectory(); + byte[] bytes = SyntheticFixtures.CreateSyntheticLgsx( + points: [SyntheticFixtures.DefaultLeicaPoints[0], SyntheticFixtures.DefaultLeicaPoints[1]], + setupCount: 4, assignPointsToSetups: true); + using var doc = LgsxDocument.Open(dir.Write("site.lgsx", bytes)); + + // Four setups are listed, but only the two with points become scans. + Assert.Equal(4, doc.Setups.Count); + Assert.Equal(2, doc.Scans.Count); + Assert.Equal(["SETUP-3", "SETUP-4"], doc.Scans.Select(s => s.Name)); + Assert.Equal(2, doc.TotalPointCount); + } + + [Fact] + public void A_Lgsx_Container_Whose_Setups_Claim_The_Same_Points_Stays_One_Scan() + { + // Two setups that declare the same range of the point data cannot be told apart, so the points stay together. + using var dir = new TempDirectory(); + using var doc = LgsxDocument.Open(dir.Write("site.lgsx", + SyntheticFixtures.CreateSyntheticLgsx(setupCount: 2, assignPointsToSetups: true, overlappingSetupRanges: true))); + + var scan = Assert.Single(doc.Scans); + Assert.Equal("unified-cloud", scan.Id); + Assert.Equal(5, scan.PointCount); + Assert.Contains(doc.Warnings, w => w.Contains("points are not assigned to them", StringComparison.Ordinal)); + } + [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 868ca67..b4fd179 100644 --- a/tests/PclIO.Tests/SyntheticFixtures.cs +++ b/tests/PclIO.Tests/SyntheticFixtures.cs @@ -146,8 +146,13 @@ public static byte[] CreateZip(string entryName, string text) /// False leaves the point data entry out. /// Raw plane contents appended to the block after its position (and colour and intensity) planes. /// Number of setup entries written before the point data entry. + /// + /// True gives every setup its own point block and declares the range of that block in the point data, so that + /// the container assigns its points to its setups. False leaves the setup entries without a range. + /// + /// True lets every setup declare the range of the first block. public static byte[] CreateSyntheticLgsx(IReadOnlyList? points = null, bool withColorAndIntensity = false, bool withPointData = true, - IReadOnlyList? extraPlanes = null, int setupCount = 1) + IReadOnlyList? extraPlanes = null, int setupCount = 1, bool assignPointsToSetups = false, bool overlappingSetupRanges = false) { points ??= DefaultLeicaPoints; using var ms = new MemoryStream(); @@ -155,16 +160,33 @@ public static byte[] CreateSyntheticLgsx(IReadOnlyList? points bw.Write("wild::geosystems"u8.ToArray()); + // The groups of points, one per block of the point data. + var groups = assignPointsToSetups + ? SplitPoints(points, setupCount) + : new List> { 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. + var setupNames = Enumerable.Range(0, setupCount).Select(i => "SETUP-" + (3 + i)).ToList(); + long payloadStart = ms.Position + setupNames.Sum(EntrySize) + EntrySize("PointCloud"); + // Container entries as the reader expects them. var setupEntries = new List(); for (int i = 0; i < setupCount; i++) { setupEntries.Add(ms.Position); - WriteEntry(bw, "SETUP-" + (3 + i), 0, 0); + + // A setup owns the block it declares; without a range the setup has no points of its own. + bool hasBlock = assignPointsToSetups && 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); } + long pointEntry = ms.Position; - long payloadStart = pointEntry + (withPointData ? 12 + "PointCloud".Length + 17 : 0); - byte[] payload = withPointData ? BuildLeicaPayload(points, withColorAndIntensity, extraPlanes ?? []) : []; if (withPointData) WriteEntry(bw, "PointCloud", (ulong)payloadStart, (ulong)payload.Length); bw.Write(payload); @@ -178,6 +200,25 @@ public static byte[] CreateSyntheticLgsx(IReadOnlyList? points return ms.ToArray(); } + // Distributes the points over the setups; a setup without points gets no block. + private static List> SplitPoints(IReadOnlyList points, int setupCount) + { + var groups = new List>(); + if (setupCount <= 0) return groups; + + int perGroup = points.Count / setupCount; + int extra = points.Count % setupCount; + int index = 0; + for (int g = 0; g < setupCount; g++) + { + int take = perGroup + (g < extra ? 1 : 0); + groups.Add([.. points.Skip(index).Take(take)]); + index += take; + } + + return groups; + } + public static readonly IReadOnlyList DefaultLeicaPoints = [ new(0, 0, 0, 0xF800, 0xFFFF), @@ -192,6 +233,9 @@ public static byte[] CreateSyntheticLgsx(IReadOnlyList? points public const double LeicaOriginY = 200.0; public const double LeicaOriginZ = 300.0; + // The bytes a container entry of the given name takes. + private static int EntrySize(string name) => 29 + name.Length; + private static void WriteEntry(BinaryWriter bw, string name, ulong payloadOffset, ulong payloadLength) { bw.Write(new byte[10]); @@ -202,7 +246,50 @@ private static void WriteEntry(BinaryWriter bw, string name, ulong payloadOffset bw.Write(payloadLength); } - private static byte[] BuildLeicaPayload(IReadOnlyList points, bool full, IReadOnlyList extraPlanes) + // 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) + { + using var ms = new MemoryStream(); + using var bw = new BinaryWriter(ms); + + // Payload header: signature and the offset of the first block. + byte[] header = new byte[64]; + "mMPK"u8.CopyTo(header); + BinaryPrimitives.WriteUInt32LittleEndian(header.AsSpan(0x20, 4), 64); + bw.Write(header); + + var blocks = new List<(long Start, long Length)>(); + foreach (var group in groups) + { + // A setup without points has no block of its own. + if (group.Count == 0) continue; + + var frames = BuildFrames(group, full, extraPlanes); + int blockLength = 8 + 128 + frames.Sum(f => 8 + f.Length); + long start = ms.Position; + + bw.Write("APRN"u8.ToArray()); + bw.Write((uint)blockLength); + byte[] blockHeader = new byte[128]; + double[] frame = [LeicaScale, LeicaScale, LeicaScale, LeicaOriginX, LeicaOriginY, LeicaOriginZ]; + for (int i = 0; i < frame.Length; i++) + BinaryPrimitives.WriteDoubleLittleEndian(blockHeader.AsSpan(0x34 + (i * 8), 8), frame[i]); + bw.Write(blockHeader); + foreach (byte[] f in frames) + { + bw.Write((ulong)f.Length); + bw.Write(f); + } + + blocks.Add((start, blockLength)); + } + + return (ms.ToArray(), blocks); + } + + // The compressed planes of one point block: the four position planes and the optional ones. + private static List BuildFrames(IReadOnlyList points, bool full, IReadOnlyList extraPlanes) { int planeCount = full ? 16 : 4; int n = points.Count; @@ -232,31 +319,7 @@ private static byte[] BuildLeicaPayload(IReadOnlyList points, var frames = new List(); foreach (byte[] plane in planes.Concat(extraPlanes)) frames.Add(RawZstdFrame.Wrap(plane)); - - int blockLength = 8 + 128 + frames.Sum(f => 8 + f.Length); - using var ms = new MemoryStream(); - using var bw = new BinaryWriter(ms); - - // Payload header: signature and the offset of the first block. - byte[] header = new byte[64]; - "mMPK"u8.CopyTo(header); - BinaryPrimitives.WriteUInt32LittleEndian(header.AsSpan(0x20, 4), 64); - bw.Write(header); - - bw.Write("APRN"u8.ToArray()); - bw.Write((uint)blockLength); - byte[] blockHeader = new byte[128]; - double[] frame = [LeicaScale, LeicaScale, LeicaScale, LeicaOriginX, LeicaOriginY, LeicaOriginZ]; - for (int i = 0; i < frame.Length; i++) - BinaryPrimitives.WriteDoubleLittleEndian(blockHeader.AsSpan(0x34 + (i * 8), 8), frame[i]); - bw.Write(blockHeader); - foreach (byte[] f in frames) - { - bw.Write((ulong)f.Length); - bw.Write(f); - } - - return ms.ToArray(); + return frames; } // ---- PinPoint ------------------------------------------------------------------------------------------------- From 8f4f89d076ec5d80a2b8ba9975e2b01867e9bd68 Mon Sep 17 00:00:00 2001 From: mahach666 <79989386+mahach666@users.noreply.github.com> Date: Tue, 17 Nov 2026 12:53:47 +0000 Subject: [PATCH 2/2] Keep the Leica cloud unified when setup entry names share an id --- src/PclIO/Formats/Leica/LgsxDocument.cs | 8 ++++++++ tests/PclIO.Tests/FormatTests.cs | 18 ++++++++++++++++++ tests/PclIO.Tests/SyntheticFixtures.cs | 6 +++++- 3 files changed, 31 insertions(+), 1 deletion(-) diff --git a/src/PclIO/Formats/Leica/LgsxDocument.cs b/src/PclIO/Formats/Leica/LgsxDocument.cs index 59486c4..b0b8bc4 100644 --- a/src/PclIO/Formats/Leica/LgsxDocument.cs +++ b/src/PclIO/Formats/Leica/LgsxDocument.cs @@ -264,6 +264,14 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null) if (owners.Count == 0) return null; + // Setups are matched by the id after the last dash of their entry name. Two entries whose names end in the + // same suffix share that id, and both would receive the blocks assigned to it, returning points twice. + // The assignment is ambiguous, so the points stay together. + for (int i = 0; i < setups.Count; i++) + for (int j = i + 1; j < setups.Count; j++) + if (setups[i].Id.Equals(setups[j].Id, StringComparison.Ordinal)) + return null; + // Two setups that claim the same part of the point data would make the assignment ambiguous. for (int i = 0; i < owners.Count; i++) for (int j = i + 1; j < owners.Count; j++) diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs index fdb84b9..e5e9e1b 100644 --- a/tests/PclIO.Tests/FormatTests.cs +++ b/tests/PclIO.Tests/FormatTests.cs @@ -400,6 +400,24 @@ public void A_Lgsx_Container_Whose_Setups_Claim_The_Same_Points_Stays_One_Scan() Assert.Contains(doc.Warnings, w => w.Contains("points are not assigned to them", StringComparison.Ordinal)); } + [Fact] + public void A_Lgsx_Container_Whose_Setup_Names_Share_An_Id_Stays_One_Scan() + { + // Two entry names ending in the same suffix share the id after the last dash. Assigning blocks by that id + // would hand both setups the same blocks and return every point twice, so the points stay together. + using var dir = new TempDirectory(); + using var doc = LgsxDocument.Open(dir.Write("site.lgsx", + SyntheticFixtures.CreateSyntheticLgsx(setupCount: 2, assignPointsToSetups: true, collidingSetupNames: true))); + + Assert.Equal(["3", "3"], doc.Setups.Select(s => s.Id)); + var scan = Assert.Single(doc.Scans); + Assert.Equal("unified-cloud", scan.Id); + Assert.Equal(5, scan.PointCount); + Assert.Equal(5, scan.ReadPoints().Count()); + Assert.Equal(5, doc.TotalPointCount); + Assert.Contains(doc.Warnings, w => w.Contains("points are not assigned to them", StringComparison.Ordinal)); + } + [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 b4fd179..89e6526 100644 --- a/tests/PclIO.Tests/SyntheticFixtures.cs +++ b/tests/PclIO.Tests/SyntheticFixtures.cs @@ -151,8 +151,10 @@ public static byte[] CreateZip(string entryName, string text) /// the container assigns its points to its setups. False leaves the setup entries without a range. /// /// 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. 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) + IReadOnlyList? extraPlanes = null, int setupCount = 1, bool assignPointsToSetups = false, bool overlappingSetupRanges = false, + bool collidingSetupNames = false) { points ??= DefaultLeicaPoints; using var ms = new MemoryStream(); @@ -170,6 +172,8 @@ public static byte[] CreateSyntheticLgsx(IReadOnlyList? points // The point data follows the container entries, 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"); // Container entries as the reader expects them.