Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down
2 changes: 1 addition & 1 deletion docs/public-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down
70 changes: 56 additions & 14 deletions src/PclIO/Formats/Leica/LgsxDocument.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down Expand Up @@ -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,
};
}

Expand All @@ -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)
Expand All @@ -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(
Expand All @@ -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)
Expand All @@ -264,16 +273,16 @@ public static LgsxDocument Open(string path, PclReadOptions? options = null)
}

/// <summary>
/// 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.
/// </summary>
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);

/// <summary>
/// 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.
/// </summary>
private static SetupRecord? ReadSetupRecord(FileStream fs, LgsxSetup setup)
{
Expand Down Expand Up @@ -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);
}

/// <summary>
/// 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.
/// </summary>
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;
}

/// <summary>
Expand Down Expand Up @@ -457,6 +491,9 @@ public sealed record LgsxSetup(string Id, string Name, ulong Offset, ulong Size)

/// <summary>Length of the range of the point data that belongs to the setup, in bytes.</summary>
public ulong PointLength { get; init; }

/// <summary>Number of points of the setup, or -1 when the container does not state it.</summary>
public long PointCount { get; init; } = -1;
}

/// <summary>
Expand Down Expand Up @@ -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;

Expand All @@ -499,11 +539,12 @@ public sealed class LgsxScan : PclScan
public override string Name { get; }

/// <summary>
/// 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.
/// </summary>
/// <exception cref="InvalidDataException">The point data is malformed; the exception is thrown by the first access.</exception>
public override long PointCount => _pointCount >= 0 ? _pointCount : _pointCount = CountPoints();
public override long PointCount =>
_declaredPointCount ?? (_pointCount >= 0 ? _pointCount : _pointCount = CountPoints());

/// <summary>True when the first point block carries colour planes.</summary>
public override bool HasColors => Channels.Colors;
Expand All @@ -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;
}
Expand Down
5 changes: 3 additions & 2 deletions tests/PclIO.Tests/CliTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
36 changes: 36 additions & 0 deletions tests/PclIO.Tests/FormatTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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<InvalidDataException>(() => scan.ReadPoints().ToList());
}

[Fact]
public void A_Lgsx_Block_Is_Not_Cut_At_65536_Points()
{
Expand Down
Loading
Loading