diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1f1e2e9..fabf711 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -59,6 +59,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1.2 with point format 2 stays the default and is byte-identical to before. A projected `EPSG:NNNN` coordinate system
of the source is written as a GeoTIFF record for LAS 1.2 when asked; LAS 1.4 point formats 6 and above require WKT,
which the exporter does not produce, so a 1.4 file carries no coordinate system record.
+- Leica scans read a block range with opt-in parallel decoding: the new `PclReadOptions.Blocks` selects the blocks of the
+ scan in file order (per scan) and the new `PclReadOptions.MaxDegreeOfParallelism` (default 1, sequential streaming)
+ decodes the selected blocks in parallel, keeping file order, consecutive `Index` values and `MaxPoints`/`SubsampleStep`
+ semantics. Other readers ignore both options. A damaged block fails the read in both paths (the parallel failure is
+ unwrapped, not an `AggregateException`); a truncated read reports no incomplete-data warning.
## [0.1.0] - 2026-11-15
diff --git a/README.md b/README.md
index 07ae215..f0c6317 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ PclIO is a .NET library and command line tool that reads point cloud files from
## What it does
- Detects the format of a file or folder from its content, extension or layout (`PclFile.DetectKind`).
-- Opens a file as a `PclDocument` with its scans, bounds, transforms, metadata and warnings, and streams the points (`ReadAllPoints`, `PclScan.ReadPoints`) with a point limit, a subsampling step and an optional scan transform.
+- Opens a file as a `PclDocument` with its scans, bounds, transforms, metadata and warnings, and streams the points (`ReadAllPoints`, `PclScan.ReadPoints`) with a point limit, a subsampling step and an optional scan transform. Leica scans additionally read a block range with opt-in parallel decoding.
- Exports to ASPRS LAS 1.2 (point format 2) and 1.4 (point formats 6 to 8), ASCII XYZ, ASCII PTS and JSON.
- Ships the command line tool `pclio` with `info`, `scans`, `points` and `export`.
@@ -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 or scaled-integer coordinates (raw value times scale plus offset), or spherical range, azimuth and elevation converted to Cartesian points, with 8-bit colour and 8-bit intensity, or colour with a wider Integer range from zero and intensity as a wider Integer, a Float or a scaled integer. Pose translation and rotation are applied. Only plain bit-packing is decoded: a scan whose codecs vector names another codec lists normally and fails when its points are read, and the message names it. Per-point validity flags skip invalid points and clear invalid channels when their streams hold one flag byte per record; other shapes are not interpreted. Images are not read, so a scan with them still lists and reads its points. Page checksums are verified. |
| ReCap scan | `.rcs` | Experimental. The header is read; point decoding covers the node layouts that are described in the code, which is the one of major version 3. A file of another version is listed with its header, but reading its points fails with a message that names the version. A further layout is described only when the files of that version may be used for the tests, so that its offsets can be verified. The channels of the points follow from the size of the payload of the nodes: colour and intensity when the records are long enough, and normals when the node holds the plane of them. |
| ReCap project | `.rcp` | Lists the scans of the project manifest and opens the `.rcs` files it finds next to the project. The transform of a scan node places the scan in the project and is applied to its points unless `ApplyTransform` is false; when the manifest states no transform, the transform of the scan file is used. |
-| 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. |
+| 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. `PclReadOptions.Blocks` reads only the blocks of the scan in that file-order range (per scan, so a setup scan ranges over its own blocks); `PclReadOptions.MaxDegreeOfParallelism` above 1 decodes those blocks in parallel and still yields the points in file order with consecutive `Index` values. |
| FARO scan | `.fls`, or a FARO scan folder | Experimental. The scan grid and angles are read from the stored parameters and points are projected from the range grid; a file without them fails to open. The point count is the number of valid returns, which is counted on the first access; `FaroScan.GridSize` is the size of the scan grid. For a scan folder the layout of the samples is derived from the size of the data stream and the size of the grid, and the scale of the intensity from the values that are stored; when the sizes do not fit, the layout is assumed and a warning says so. |
| 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 positions, colours, intensities, normals (`Normals`, three float32 components per point) and the per-point flags (`FilterBits`, one byte per point) are read, while the grid indices stored beside them are not interpreted, so by default every stored point that passes the plausibility rule below is returned. With `PclReadOptions.ExcludeFilteredPoints` the points with a non-zero flag are not 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 takes it from the data file the object refers to, and every location that shares one file reports its full count, because the shares are not recorded. |
| 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, as three 16-bit offsets from the cluster centre per point. The scale of the offsets is not stored in the files, so the reader assumes 32768 units = 0.128 m unless the caller states it with `PclReadOptions.EdgeWiseCoordinateScale`. |
@@ -202,6 +202,7 @@ See the [public API](docs/public-api.md) for the supported surface and [dependen
- The decoders other than E57 cover only the file layouts they were written for. Files written by other software versions can be rejected.
- Readers limit the sizes and counts that a file declares; the numbers are listed under Limits. A file that exceeds a limit is rejected, with the exceptions described there. Some readers drop points that fail a plausibility rule; see Data filters.
- `SubsampleStep` is applied inside each format's internal blocks, so the spacing is approximate. `MaxPoints` limits one read call.
+- `Blocks` selects the blocks of a scan in file order and is honoured only by the Leica reader; other readers read the whole scan and ignore it. `MaxDegreeOfParallelism` above 1 decodes the selected Leica blocks in parallel and still yields the points in file order; other readers read sequentially and ignore it. Sequential Leica decoding holds one block at a time, while the parallel read holds the decoded points of the selected blocks. The default is 1: sequential streaming.
- A scan transform is scale and translation, or a 4x4 matrix when the format gives one. Rotation values of a `PclTransform` are stored for information and are not applied by `TransformPoint`.
- LAS and PTS export read the source twice (the header needs the count), so the source must be re-enumerable; memory does not depend on the number of points. A point without intensity is written with full intensity and a point without colour as white, because these formats have no "missing" value. LAS stores coordinates with the configured scale (1 mm by default), so the extent of each axis must fit 32-bit integers at that scale; the default offset is the minimum of the data.
- Normals are read where a format has them, but no exporter writes them.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 6613526..dae8bac 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -103,7 +103,7 @@ file that exceeds a limit is rejected with `InvalidDataException`, with the exce
non-finite coordinate or a coordinate beyond `PclReadOptions.MaxCoordinateMagnitude` in the file's own unit (5000 by default),
and Leica padding entries. A scan can therefore yield fewer points than `PointCount`. The rules and the limits on file sizes
and counts are listed in the repository README.
-- `SubsampleStep` is applied inside each format's internal blocks, so the spacing is approximate; `MaxPoints` limits one read call.
+- `SubsampleStep` is applied inside each format's internal blocks, so the spacing is approximate; `MaxPoints` limits one read call. Leica scans additionally accept `Blocks` (a file-order range of the scan's blocks) and `MaxDegreeOfParallelism` (above 1 decodes the selected blocks in parallel, keeping file order with consecutive `Index` values).
- LAS and PTS export read the source twice; memory does not depend on the number of points. A point without intensity is written with full
intensity and a point without colour as white. LAS uses a 1 mm scale by default, so the extent of each axis must fit 32-bit integers at the configured scale.
- Normals are read where a format has them but no exporter writes them.
diff --git a/docs/public-api.md b/docs/public-api.md
index 6ab84f7..25c33d2 100644
--- a/docs/public-api.md
+++ b/docs/public-api.md
@@ -15,7 +15,8 @@ format-specific members can change when the support for that format changes.
|---|---|
| `PclFile` | Static entry point. `DetectKind(path)` and `DetectKind(stream, extension)` return a `PclFileKind`; `Open(path, options)` detects the format and returns a `PclDocument`. |
| `PclFileKind` | `Unknown`, `E57`, `RecapProject`, `RecapScan`, `LeicaLgsx`, `LeicaLgs`, `FaroFls`, `PinPoint` and `EdgeWise`. |
-| `PclReadOptions` | `MaxPoints` (limit of one read call, null for all, 0 for none), `MaxCoordinateMagnitude` (default 5000, null for no limit; NaN and infinite coordinates are never returned; currently only PinPoint applies it), `EdgeWiseCoordinateScale` (default 0.128 / 32768 metres per unit; the files do not declare it), `SubsampleStep` (1 keeps every point, N keeps about one in N), `ApplyTransform` (default true), `Strict` (default false: a reader that finds incomplete data fails with `InvalidDataException` instead of adding a warning) and `ExcludeFilteredPoints` (default false: points the file marks as filtered are excluded; currently the `FilterBits` channel of the PinPoint sectioned layout). Negative `MaxPoints`, a negative magnitude limit, a non-positive or non-finite EdgeWise scale and a step below 1 throw `ArgumentOutOfRangeException`. `PclReadOptions.Default` has no limit. |
+| `PclReadOptions` | `MaxPoints` (limit of one read call, null for all, 0 for none), `MaxCoordinateMagnitude` (default 5000, null for no limit; NaN and infinite coordinates are never returned; currently only PinPoint applies it), `EdgeWiseCoordinateScale` (default 0.128 / 32768 metres per unit; the files do not declare it), `SubsampleStep` (1 keeps every point, N keeps about one in N), `Blocks` (range of the scan's blocks in file order, null for all; currently only Leica honours it), `MaxDegreeOfParallelism` (default 1: sequential; above 1 decodes the selected Leica blocks in parallel, keeping file order), `ApplyTransform` (default true), `Strict` (default false: a reader that finds incomplete data fails with `InvalidDataException` instead of adding a warning) and `ExcludeFilteredPoints` (default false: points the file marks as filtered are excluded; currently the `FilterBits` channel of the PinPoint sectioned layout). Negative `MaxPoints`, a negative magnitude limit, a negative block start or count, a non-positive or non-finite EdgeWise scale and a step or parallelism below 1 throw `ArgumentOutOfRangeException`. `PclReadOptions.Default` has no limit. |
+| `BlockRange` | `StartBlock` (zero-based index of the first block to read) and `BlockCount` (how many blocks at most, null for all from the start on; a range past the last block yields no points, 0 yields none). |
`Open` throws `FileNotFoundException` for a missing path, `DirectoryNotFoundException` when a directory the reader needs is
missing or disappears while reading, `NotSupportedException` for an unrecognised format or an unsupported feature, and
@@ -62,7 +63,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. Points that the validity flags mark as invalid are skipped, so a read can yield fewer points. |
| ReCap scan | Declared in the header. It is not checked against the node table. The node layout of major version 3 is decoded; a file of another version is listed but its points cannot be read (`RcsScanDocument.DecodedNodeLayoutVersions` names the decoded versions). |
| ReCap project | Declared by the project manifest; 0 when the manifest states none. |
-| 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. |
+| 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. `Blocks` applies per scan in file order; a truncated read (fewer points yielded than selected, via `MaxPoints`) reports no incomplete-data warning. |
| FARO | The number of valid returns, which is counted on the first access by reading the distance data of the scan; `FaroScan.GridSize` is the size of the scan grid (rows times columns). For a folder scan the grid size is limited by the size of the data stream, and `FaroScan.RecordSize` is the size of one sample in bytes. |
| 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: derived from the data file the object refers to, else 0 (not known); locations that share one file each report its full count. |
| 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/BlockRange.cs b/src/PclIO/BlockRange.cs
new file mode 100644
index 0000000..476c240
--- /dev/null
+++ b/src/PclIO/BlockRange.cs
@@ -0,0 +1,35 @@
+namespace PclIO;
+
+/// Which blocks of a scan to read: a range of the scan's blocks in file order.
+public record struct BlockRange
+{
+ private int _startBlock;
+ private int? _blockCount;
+
+ /// Zero-based index of the first block to read. Must not be negative; 0 starts at the first block.
+ /// The value is negative.
+ public int StartBlock
+ {
+ get => _startBlock;
+ init
+ {
+ ArgumentOutOfRangeException.ThrowIfNegative(value);
+ _startBlock = value;
+ }
+ }
+
+ ///
+ /// How many blocks to read at most, or null for all of them from on.
+ /// A range that runs past the last block simply ends there; 0 yields no points.
+ ///
+ /// The value is negative.
+ public int? BlockCount
+ {
+ get => _blockCount;
+ init
+ {
+ ArgumentOutOfRangeException.ThrowIfNegative(value ?? 0);
+ _blockCount = value;
+ }
+ }
+}
diff --git a/src/PclIO/Formats/Leica/LgsxDocument.cs b/src/PclIO/Formats/Leica/LgsxDocument.cs
index 9e8aaaf..144f93f 100644
--- a/src/PclIO/Formats/Leica/LgsxDocument.cs
+++ b/src/PclIO/Formats/Leica/LgsxDocument.cs
@@ -629,10 +629,15 @@ private sealed record Block(double ScaleX, double ScaleY, double ScaleZ, double
/// keep consecutive values.
///
///
+ /// With only the blocks of the scan in that range are read; without it all
+ /// of them are. With above one the blocks decode in parallel
+ /// and the points still come out in file order; only the blocks of the scan are ever held decoded at once in the
+ /// sequential read, while the parallel read holds the decoded points of the selected blocks.
+ ///
+ ///
/// Data that the reader cannot use is counted and reported in the warnings of the document: the points that were
- /// dropped as padding, the compressed streams that were skipped because they are too large, the point blocks that
- /// carry no positions or whose frame list ends before the block does, and the point data that ends at a block the
- /// reader does not know. With the read fails with
+ /// dropped as padding, the compressed streams that were skipped because they are too large and the point data
+ /// that ends at a block the reader does not know. With the read fails with
/// instead of the warning.
///
///
@@ -651,102 +656,185 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
// The counters describe this read alone; they start at zero every time.
var state = new ReadState();
- using var fs = File.OpenRead(_filePath);
- foreach (var block in ReadBlocks(fs, state))
+ if (options.MaxDegreeOfParallelism > 1)
{
- var frames = block.Frames;
- byte[] p0 = frames[0];
- byte[] p1 = frames[1];
- byte[] p2 = frames[2];
- byte[] p3 = frames[3];
+ foreach (var pt in ReadPointsParallelOrdered(options, step, targetCount, state)) yield return pt;
+ yield break;
+ }
- // Optional channels follow the position planes; normals are the last three planes.
- byte[][]? colPlanes = frames.Count >= ColorFrames ? [frames[12], frames[13]] : null;
- byte[][]? intPlanes = frames.Count >= IntensityFrames ? [frames[14], frames[15]] : null;
- byte[][]? normPlanes = frames.Count >= NormalFrames ? [frames[^3], frames[^2], frames[^1]] : null;
+ using var fs = File.OpenRead(_filePath);
+ var chain = ScanBlockChain(fs);
+ SetChainEnd(fs, state, chain);
+ var selected = ApplyBlockRange(chain.ScanChain, options.Blocks);
+ long decodedLimit = DecodedAllowanceBytes + (fs.Length * DecodedBytesPerFileByte);
+ long decodedBytes = 0;
- int numPoints = Math.Min(p0.Length, Math.Min(p1.Length, Math.Min(p2.Length, p3.Length)));
+ foreach (var (blockStart, blockLength) in selected)
+ {
+ var (block, added, skippedStreams, unusable, incomplete) = DecodeBlock(fs, blockStart, blockLength);
+ state.SkippedStreams += skippedStreams;
+ state.UnusableBlocks += unusable;
+ state.IncompleteBlocks += incomplete;
- for (int i = 0; i < numPoints; i++)
- {
- if (i % step != 0) continue;
+ // Every decoded block counts toward the total, including one that carries no positions: many small
+ // blocks that each expand a lot would otherwise make the file cost unbounded time.
+ decodedBytes += added;
+ if (decodedBytes > decodedLimit)
+ throw FormatError.Corrupted("the point data decompresses to more than the accepted total size.");
- uint val = (uint)(p0[i] | (p1[i] << 8) | (p2[i] << 16) | (p3[i] << 24));
- if (val == 0 && i > 0 && p0[i] == 0 && p1[i] == 0)
- {
- // The slot holds no point: it is padding or a point at the origin of the block.
- state.DroppedPoints++;
- continue;
- }
+ if (block == null) continue;
+ state.BlocksRead++;
- // Unpack the three 10-bit coordinates from the packed code.
- uint xm = 0, ym = 0, zm = 0;
- for (int b = 0; b < 10; b++)
- {
- xm |= ((val >> (b * 3)) & 1) << b;
- ym |= ((val >> (b * 3 + 1)) & 1) << b;
- zm |= ((val >> (b * 3 + 2)) & 1) << b;
- }
-
- double x = block.MinX + (xm * block.ScaleX);
- double y = block.MinY + (ym * block.ScaleY);
- double z = block.MinZ + (zm * block.ScaleZ);
+ var points = UnpackBlock(block, step, options.ApplyTransform, Transform, (ulong)yielded, out long dropped);
+ state.DroppedPoints += dropped;
- // 16-bit packed colour; zero means no colour.
- PclColor? color = null;
- if (colPlanes != null && i < colPlanes[0].Length && i < colPlanes[1].Length)
- {
- ushort cval = (ushort)(colPlanes[0][i] | (colPlanes[1][i] << 8));
- if (cval != 0)
- {
- byte red = (byte)(((cval >> 11) & 0x1F) * 255 / 31);
- byte green = (byte)(((cval >> 5) & 0x3F) * 255 / 63);
- byte blue = (byte)((cval & 0x1F) * 255 / 31);
- color = new PclColor(red, green, blue);
- }
- }
+ foreach (var pt in points)
+ {
+ yield return pt;
+ yielded++;
+ if (yielded >= targetCount) yield break;
+ }
+ }
- // 16-bit intensity; unknown when the plane is absent.
- float? intensity = null;
- if (intPlanes != null && i < intPlanes[0].Length && i < intPlanes[1].Length)
- {
- ushort ival = (ushort)(intPlanes[0][i] | (intPlanes[1][i] << 8));
- intensity = ival / 65535.0f;
- }
+ // The whole point data was read, so what it did not hold can be reported.
+ ReportIncompleteData(options.Strict, state);
+ }
- // Signed-byte components; all zero means no normal.
- PclVector3? normal = null;
- if (normPlanes != null && i < normPlanes[0].Length && i < normPlanes[1].Length && i < normPlanes[2].Length)
- {
- sbyte nx = (sbyte)normPlanes[0][i];
- sbyte ny = (sbyte)normPlanes[1][i];
- sbyte nz = (sbyte)normPlanes[2][i];
- if (nx != 0 || ny != 0 || nz != 0)
+ /// Decodes the selected blocks in parallel and yields their points in file order.
+ ///
+ /// Every block decodes on its own stream, so blocks never share a file position. The whole selection is
+ /// decoded even when stops the reading early;
+ /// only caps how many of the decoded points are yielded. Warnings and the strict failure behave as in the
+ /// sequential read, except that a truncated read (fewer points yielded than decoded) reports nothing.
+ ///
+ private IEnumerable ReadPointsParallelOrdered(PclReadOptions options, int step, long targetCount, ReadState state)
+ {
+ List?[] perBlock;
+ using (var fs = File.OpenRead(_filePath))
+ {
+ var chain = ScanBlockChain(fs);
+ SetChainEnd(fs, state, chain);
+ var selected = ApplyBlockRange(chain.ScanChain, options.Blocks);
+ long decodedLimit = DecodedAllowanceBytes + (fs.Length * DecodedBytesPerFileByte);
+
+ perBlock = new List?[selected.Count];
+ long dropped = 0, skipped = 0, blocks = 0, decodedTotal = 0, unusable = 0, incomplete = 0;
+ try
+ {
+ Parallel.For(0, selected.Count,
+ new ParallelOptions { MaxDegreeOfParallelism = options.MaxDegreeOfParallelism },
+ () => File.OpenRead(_filePath),
+ (i, _, stream) =>
{
- normal = new PclVector3(nx / 127.0, ny / 127.0, nz / 127.0);
- }
- }
+ var (blockStart, blockLength) = selected[i];
+ var (block, added, skippedStreams, u, inc) = DecodeBlock(stream, blockStart, blockLength);
+ Interlocked.Add(ref skipped, skippedStreams);
+ Interlocked.Add(ref unusable, u);
+ Interlocked.Add(ref incomplete, inc);
- var pt = new PclPoint(
- new PclVector3(x, y, z),
- Color: color,
- Intensity: intensity,
- Normal: normal,
- Index: (ulong)yielded);
+ // Every decoded block counts toward the total, including one that carries no positions.
+ if (Interlocked.Add(ref decodedTotal, added) > decodedLimit)
+ throw FormatError.Corrupted("the point data decompresses to more than the accepted total size.");
- if (options.ApplyTransform)
- pt = pt with { Position = Transform.TransformPoint(pt.Position) };
+ if (block == null)
+ {
+ perBlock[i] = [];
+ }
+ else
+ {
+ perBlock[i] = UnpackBlock(block, step, options.ApplyTransform, Transform, 0, out long d);
+ Interlocked.Add(ref dropped, d);
+ Interlocked.Increment(ref blocks);
+ }
+
+ return stream;
+ },
+ static stream => stream.Dispose());
+ }
+ catch (AggregateException ex) when (ex.InnerExceptions.Count > 0)
+ {
+ System.Runtime.ExceptionServices.ExceptionDispatchInfo.Capture(ex.InnerExceptions[0]).Throw();
+ throw;
+ }
- yield return pt;
- yielded++;
+ state.DroppedPoints = dropped;
+ state.SkippedStreams = skipped;
+ state.BlocksRead = blocks;
+ state.UnusableBlocks = unusable;
+ state.IncompleteBlocks = incomplete;
+ }
+
+ long yielded = 0;
+ foreach (var list in perBlock)
+ {
+ if (list == null) continue;
+ foreach (var pt in list)
+ {
if (yielded >= targetCount) yield break;
+ yield return pt with { Index = (ulong)yielded };
+ yielded++;
}
}
- // The whole point data was read, so what it did not hold can be reported.
+ if (yielded >= targetCount) yield break;
+
+ // The whole selection was yielded, so what it did not hold can be reported.
ReportIncompleteData(options.Strict, state);
}
+ /// Chain of point blocks for this scan: the full payload chain and the scan's own blocks in file order.
+ private (List<(long Start, long Length)> FullChain, List<(long Start, long Length)> ScanChain, long PayloadEnd) ScanBlockChain(FileStream fs)
+ {
+ var full = LgsxDocument.ReadBlockChain(fs, _entry!);
+ long payloadEnd = (long)_entry!.Offset + (long)_entry.Size;
+ var scan = new List<(long Start, long Length)>(full.Count);
+ foreach (var item in full)
+ if (BelongsToScan(item.Start)) scan.Add(item);
+ return (full, scan, payloadEnd);
+ }
+
+ /// Slices a scan chain to a block range in file order; a range past the last block yields nothing.
+ private static List<(long Start, long Length)> ApplyBlockRange(List<(long Start, long Length)> scanChain, BlockRange? range)
+ {
+ if (range is null) return scanChain;
+ int start = range.Value.StartBlock;
+ if (start < 0) start = 0;
+ if (start >= scanChain.Count) return [];
+ int count = range.Value.BlockCount ?? (scanChain.Count - start);
+ if (count <= 0) return [];
+ count = Math.Min(count, scanChain.Count - start);
+ return scanChain.GetRange(start, count);
+ }
+
+ ///
+ /// Records whether the point data ends at a block the reader does not know, and how many blocks the payload
+ /// holds. The gap belongs to the payload, so only the unified scan or the scan that owns the last block reports
+ /// it. An empty chain means the very first chunk is unknown; when a full block could have fit there, that is the
+ /// same condition.
+ ///
+ private void SetChainEnd(FileStream fs, ReadState state,
+ (List<(long Start, long Length)> FullChain, List<(long Start, long Length)> ScanChain, long PayloadEnd) chain)
+ {
+ state.ChainBlocks = chain.FullChain.Count;
+
+ if (_blockStarts != null && (chain.FullChain.Count == 0 || !BelongsToScan(chain.FullChain[^1].Start)))
+ return;
+
+ if (chain.FullChain.Count > 0)
+ {
+ long lastEnd = chain.FullChain[^1].Start + chain.FullChain[^1].Length;
+ if (chain.PayloadEnd - lastEnd >= 8 + 128) state.ChainEndedEarly = true;
+ }
+ else
+ {
+ fs.Position = (long)_entry!.Offset;
+ byte[] payloadHeader = new byte[64];
+ fs.ReadExactly(payloadHeader);
+ long firstBlock = (long)_entry.Offset + Bytes.ReadUInt32LE(payloadHeader.AsSpan(0x20, 4));
+ if (chain.PayloadEnd - firstBlock >= 8 + 128) state.ChainEndedEarly = true;
+ }
+ }
+
///
/// Reports the data that the point data did not hold: the points that were dropped as padding, the compressed
/// streams that were skipped, the point blocks that carry no positions or whose frame list is cut short, and the
@@ -842,32 +930,15 @@ private IEnumerable ReadBlocks(FileStream fs, ReadState state)
state.BlocksRead++;
yield return new Block(scaleX, scaleY, scaleZ, minX, minY, minZ, frames);
}
- else state.UnusableBlocks++;
}
- else state.UnusableBlocks++;
}
// Data that is left in the point data but that is not a point block means that the reader did not read
- // everything the container holds. The gap belongs to the payload, so only the unified scan or the scan
- // that owns the last block reports it, and the count is the count of the whole chain.
- state.ChainBlocks = chain.Count;
- if (_blockStarts == null || (chain.Count > 0 && BelongsToScan(chain[^1].Start)))
+ // everything the container holds.
+ if (chain.Count > 0)
{
- if (chain.Count > 0)
- {
- long lastEnd = chain[^1].Start + chain[^1].Length;
- if (payloadEnd - lastEnd >= 8 + 128) state.ChainEndedEarly = true;
- }
- else
- {
- // An empty chain means the very first chunk is not a point block. When a full block could have
- // fit there, the point data ends at a block the reader does not know, just as with a later one.
- fs.Position = (long)_entry!.Offset;
- byte[] payloadHeader = new byte[64];
- fs.ReadExactly(payloadHeader);
- long firstBlock = (long)_entry.Offset + Bytes.ReadUInt32LE(payloadHeader.AsSpan(0x20, 4));
- if (payloadEnd - firstBlock >= 8 + 128) state.ChainEndedEarly = true;
- }
+ long lastEnd = chain[^1].Start + chain[^1].Length;
+ if (payloadEnd - lastEnd >= 8 + 128) state.ChainEndedEarly = true;
}
}
@@ -875,15 +946,168 @@ private IEnumerable ReadBlocks(FileStream fs, ReadState state)
private bool BelongsToScan(long blockStart) =>
_blockStarts == null || Array.BinarySearch(_blockStarts, blockStart) >= 0;
- private List ReadAllFrames(FileStream fs, long offset, long maxOffset, ReadState state)
+ /// Decodes one point block on its own stream without touching shared read state.
+ ///
+ /// The block with its planes, the decoded bytes, the skipped streams, and whether the block is unusable (fewer
+ /// than four planes) or its frame list is cut short; the block is null when it holds no positions.
+ ///
+ /// The block header or its planes are malformed or oversized.
+ private static (Block? Block, long DecodedBytes, long SkippedStreams, long Unusable, long Incomplete) DecodeBlock(FileStream fs, long blockStart, long blockLength)
+ {
+ if (blockStart < 0 || blockLength < 8 + 128 || blockStart + blockLength > fs.Length)
+ throw FormatError.Corrupted("point block range is outside the file.");
+
+ byte[] blockHeader = new byte[128];
+ fs.Position = blockStart + 8;
+ fs.ReadExactly(blockHeader);
+
+ double scaleX = Bytes.ReadDoubleLE(blockHeader.AsSpan(0x34, 8));
+ double scaleY = Bytes.ReadDoubleLE(blockHeader.AsSpan(0x3C, 8));
+ double scaleZ = Bytes.ReadDoubleLE(blockHeader.AsSpan(0x44, 8));
+ double minX = Bytes.ReadDoubleLE(blockHeader.AsSpan(0x4C, 8));
+ double minY = Bytes.ReadDoubleLE(blockHeader.AsSpan(0x54, 8));
+ double minZ = Bytes.ReadDoubleLE(blockHeader.AsSpan(0x5C, 8));
+
+ long blockEnd = blockStart + blockLength;
+
+ // Find the first compressed frame; its 8-byte length prefix precedes it.
+ 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++)
+ {
+ if (searchBuf.AsSpan(s, 4).SequenceEqual(FrameMagic))
+ {
+ firstFrame = s;
+ break;
+ }
+ }
+
+ if (firstFrame < 8) return (null, 0, 0, 1, 0);
+
+ long firstFrameOffset = blockStart + firstFrame;
+ var (frames, decodedBytes, skippedStreams, incomplete) = ReadAllFramesLocal(fs, firstFrameOffset, blockEnd);
+
+ // Blocks with fewer than four planes carry no positions.
+ if (frames.Count < 4) return (null, decodedBytes, skippedStreams, 1, incomplete);
+
+ if (!(double.IsFinite(scaleX) && scaleX > 0 && double.IsFinite(scaleY) && scaleY > 0 &&
+ double.IsFinite(scaleZ) && scaleZ > 0 &&
+ double.IsFinite(minX) && double.IsFinite(minY) && double.IsFinite(minZ)))
+ throw FormatError.Corrupted("point block has an invalid coordinate scale or origin.");
+
+ return (new Block(scaleX, scaleY, scaleZ, minX, minY, minZ, frames), decodedBytes, skippedStreams, 0, incomplete);
+ }
+
+ /// Unpacks the planes of one block into points, dropping padding slots. The first returned point gets and the rest keep consecutive values; counts dropped slots.
+ private static List UnpackBlock(Block block, int step, bool applyTransform, PclTransform transform, ulong baseIndex, out long dropped)
+ {
+ var frames = block.Frames;
+ byte[] p0 = frames[0];
+ byte[] p1 = frames[1];
+ byte[] p2 = frames[2];
+ byte[] p3 = frames[3];
+
+ // Optional channels follow the position planes; normals are the last three planes.
+ byte[][]? colPlanes = frames.Count >= ColorFrames ? [frames[12], frames[13]] : null;
+ byte[][]? intPlanes = frames.Count >= IntensityFrames ? [frames[14], frames[15]] : null;
+ byte[][]? normPlanes = frames.Count >= NormalFrames ? [frames[^3], frames[^2], frames[^1]] : null;
+
+ int numPoints = Math.Min(p0.Length, Math.Min(p1.Length, Math.Min(p2.Length, p3.Length)));
+ var points = new List(Math.Max(0, (numPoints + step - 1) / step));
+ dropped = 0;
+ ulong yielded = baseIndex;
+
+ for (int i = 0; i < numPoints; i++)
+ {
+ if (i % step != 0) continue;
+
+ uint val = (uint)(p0[i] | (p1[i] << 8) | (p2[i] << 16) | (p3[i] << 24));
+ if (val == 0 && i > 0 && p0[i] == 0 && p1[i] == 0)
+ {
+ // The slot holds no point: it is padding or a point at the origin of the block.
+ dropped++;
+ continue;
+ }
+
+ // Unpack the three 10-bit coordinates from the packed code.
+ uint xm = 0, ym = 0, zm = 0;
+ for (int b = 0; b < 10; b++)
+ {
+ xm |= ((val >> (b * 3)) & 1) << b;
+ ym |= ((val >> (b * 3 + 1)) & 1) << b;
+ zm |= ((val >> (b * 3 + 2)) & 1) << b;
+ }
+
+ double x = block.MinX + (xm * block.ScaleX);
+ double y = block.MinY + (ym * block.ScaleY);
+ double z = block.MinZ + (zm * block.ScaleZ);
+
+ // 16-bit packed colour; zero means no colour.
+ PclColor? color = null;
+ if (colPlanes != null && i < colPlanes[0].Length && i < colPlanes[1].Length)
+ {
+ ushort cval = (ushort)(colPlanes[0][i] | (colPlanes[1][i] << 8));
+ if (cval != 0)
+ {
+ byte red = (byte)(((cval >> 11) & 0x1F) * 255 / 31);
+ byte green = (byte)(((cval >> 5) & 0x3F) * 255 / 63);
+ byte blue = (byte)((cval & 0x1F) * 255 / 31);
+ color = new PclColor(red, green, blue);
+ }
+ }
+
+ // 16-bit intensity; unknown when the plane is absent.
+ float? intensity = null;
+ if (intPlanes != null && i < intPlanes[0].Length && i < intPlanes[1].Length)
+ {
+ ushort ival = (ushort)(intPlanes[0][i] | (intPlanes[1][i] << 8));
+ intensity = ival / 65535.0f;
+ }
+
+ // Signed-byte components; all zero means no normal.
+ PclVector3? normal = null;
+ if (normPlanes != null && i < normPlanes[0].Length && i < normPlanes[1].Length && i < normPlanes[2].Length)
+ {
+ sbyte nx = (sbyte)normPlanes[0][i];
+ sbyte ny = (sbyte)normPlanes[1][i];
+ sbyte nz = (sbyte)normPlanes[2][i];
+ if (nx != 0 || ny != 0 || nz != 0)
+ {
+ normal = new PclVector3(nx / 127.0, ny / 127.0, nz / 127.0);
+ }
+ }
+
+ var pt = new PclPoint(
+ new PclVector3(x, y, z),
+ Color: color,
+ Intensity: intensity,
+ Normal: normal,
+ Index: yielded);
+
+ if (applyTransform)
+ pt = pt with { Position = transform.TransformPoint(pt.Position) };
+
+ points.Add(pt);
+ yielded++;
+ }
+
+ return points;
+ }
+
+ /// Reads the frames of one block without touching shared read state.
+ private static (List Frames, long DecodedBytes, long SkippedStreams, long Incomplete) ReadAllFramesLocal(FileStream fs, long offset, long maxOffset)
{
var list = new List();
long limit = Math.Min(maxOffset, fs.Length);
- if (offset < 0 || offset + 8 >= limit) return list;
+ if (offset < 0 || offset + 8 >= limit) return (list, 0, 0, 0);
fs.Position = offset;
byte[] lenBuf = new byte[8];
long totalBytes = 0;
+ long skipped = 0;
+ long incomplete = 0;
while (fs.Position + 8 <= limit)
{
@@ -896,14 +1120,14 @@ private List ReadAllFrames(FileStream fs, long offset, long maxOffset, R
// A stream that is larger than the accepted size is skipped: the rest of the block is lost with it.
if (fLen > MaxCompressedFrameBytes)
{
- state.SkippedStreams++;
+ skipped++;
break;
}
// A frame list that ends before the block does leaves the rest of the block unread.
if ((long)fLen > limit - fs.Position)
{
- state.IncompleteBlocks++;
+ incomplete = 1;
break;
}
@@ -912,10 +1136,58 @@ private List ReadAllFrames(FileStream fs, long offset, long maxOffset, R
if (!fData.AsSpan().StartsWith(FrameMagic))
{
- state.IncompleteBlocks++;
+ incomplete = 1;
+ break;
+ }
+
+ if (list.Count >= MaxFramesPerBlock)
+ throw FormatError.Corrupted($"point block has more than {MaxFramesPerBlock} planes.");
+
+ // The size cap is checked against the frame's declared size before any allocation.
+ byte[] plane = ZstdDecoder.Decompress(fData, MaxFrameBytes);
+
+ totalBytes += plane.Length;
+ if (totalBytes > MaxBlockBytes)
+ throw FormatError.Corrupted($"point block decompresses to more than {MaxBlockBytes} bytes.");
+
+ list.Add(plane);
+ }
+
+ return (list, totalBytes, skipped, incomplete);
+ }
+
+ private List ReadAllFrames(FileStream fs, long offset, long maxOffset, ReadState state)
+ {
+ var list = new List();
+ long limit = Math.Min(maxOffset, fs.Length);
+ if (offset < 0 || offset + 8 >= limit) return list;
+
+ fs.Position = offset;
+ byte[] lenBuf = new byte[8];
+ long totalBytes = 0;
+
+ while (fs.Position + 8 <= limit)
+ {
+ fs.ReadExactly(lenBuf);
+
+ // A zero length marks the end of the frame list.
+ ulong fLen = Bytes.ReadUInt64LE(lenBuf);
+ if (fLen == 0) break;
+
+ // A stream that is larger than the accepted size is skipped: the rest of the block is lost with it.
+ if (fLen > MaxCompressedFrameBytes)
+ {
+ state.SkippedStreams++;
break;
}
+ if ((long)fLen > limit - fs.Position) break;
+
+ byte[] fData = new byte[(int)fLen];
+ fs.ReadExactly(fData);
+
+ if (!fData.AsSpan().StartsWith(FrameMagic)) break;
+
if (list.Count >= MaxFramesPerBlock)
throw FormatError.Corrupted($"point block has more than {MaxFramesPerBlock} planes.");
diff --git a/src/PclIO/PclReadOptions.cs b/src/PclIO/PclReadOptions.cs
index d478341..e782c7d 100644
--- a/src/PclIO/PclReadOptions.cs
+++ b/src/PclIO/PclReadOptions.cs
@@ -100,4 +100,30 @@ public double EdgeWiseCoordinateScale
_edgeWiseCoordinateScale = value;
}
}
+
+ ///
+ /// Blocks of a scan to read, in file order; null reads all of the scan's blocks. A range that runs past the last
+ /// block simply ends there. Only readers whose points come in independent blocks use this option; the others read
+ /// the whole scan and ignore it. Currently only the Leica reader honours it.
+ ///
+ public BlockRange? Blocks { get; init; }
+
+ private int _maxDegreeOfParallelism = 1;
+
+ ///
+ /// How many blocks a reader may decode at once. The points keep file order whatever the value is.
+ /// Only readers with independent blocks use this option; the others read sequentially and ignore it.
+ /// Currently only the Leica reader decodes in parallel, holding the decoded points of the blocks in flight.
+ /// The default is 1: sequential decoding with constant memory besides the block being read.
+ ///
+ /// The value is less than 1.
+ public int MaxDegreeOfParallelism
+ {
+ get => _maxDegreeOfParallelism;
+ init
+ {
+ ArgumentOutOfRangeException.ThrowIfLessThan(value, 1);
+ _maxDegreeOfParallelism = value;
+ }
+ }
}
diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs
index 6182e88..7d52cb3 100644
--- a/tests/PclIO.Tests/FormatTests.cs
+++ b/tests/PclIO.Tests/FormatTests.cs
@@ -1300,6 +1300,20 @@ public void A_Lgsx_Block_With_Fewer_Than_Four_Planes_Is_Reported()
Assert.Contains(doc.Warnings, w => w.Contains("1 point blocks were skipped because they hold fewer than four planes", StringComparison.Ordinal));
}
+ [Fact]
+ public void A_Lgsx_Parallel_Read_Reports_Unusable_Blocks_As_The_Sequential_Read_Does()
+ {
+ // Blocks that carry no positions are counted in both read paths; the parallel path must not drop them
+ // from the incomplete-data report.
+ using var dir = new TempDirectory();
+ using var doc = LgsxDocument.Open(dir.Write("site.lgsx",
+ SyntheticFixtures.CreateSyntheticLgsx(blockCount: 4, fewPlanes: true)));
+
+ var scan = Assert.Single(doc.Scans);
+ Assert.Empty(scan.ReadPoints(new PclReadOptions { MaxDegreeOfParallelism = 4 }));
+ Assert.Contains(doc.Warnings, w => w.Contains("4 point blocks were skipped because they hold fewer than four planes", StringComparison.Ordinal));
+ }
+
[Fact]
public void Interleaved_Reads_Of_A_Lgsx_Scan_Keep_Their_Own_Counts()
{
@@ -1411,6 +1425,202 @@ public void Lgsx_Honours_Limit_And_Step()
Assert.Empty(scan.ReadPoints(new PclReadOptions { MaxPoints = 0 }));
}
+ private static IReadOnlyList SixLeicaPoints =>
+ [
+ new(1, 2, 3),
+ new(4, 5, 6),
+ new(7, 8, 9),
+ new(10, 11, 12),
+ new(13, 14, 15),
+ new(16, 17, 18),
+ ];
+
+ private static List ExpectedLeicaPositions(IReadOnlyList written) =>
+ [.. written.Select(p => new PclVector3(
+ SyntheticFixtures.LeicaOriginX + (p.X * SyntheticFixtures.LeicaScale),
+ SyntheticFixtures.LeicaOriginY + (p.Y * SyntheticFixtures.LeicaScale),
+ SyntheticFixtures.LeicaOriginZ + (p.Z * SyntheticFixtures.LeicaScale)))];
+
+ [Fact]
+ public void Lgsx_Range_Reads_Only_The_Selected_Blocks_In_File_Order()
+ {
+ using var dir = new TempDirectory();
+ using var doc = LgsxDocument.Open(dir.Write("multi.lgsx",
+ SyntheticFixtures.CreateSyntheticLgsx(SixLeicaPoints, blockCount: 3)));
+ var scan = Assert.Single(doc.Scans);
+ var expected = ExpectedLeicaPositions(SixLeicaPoints);
+
+ var middle = scan.ReadPoints(new PclReadOptions { Blocks = new BlockRange { StartBlock = 1, BlockCount = 1 } }).ToList();
+ Assert.Equal(2, middle.Count);
+ Assert.Equal([0UL, 1UL], middle.Select(p => p.Index));
+ AssertNear(expected[2], middle[0].Position);
+ AssertNear(expected[3], middle[1].Position);
+
+ var tail = scan.ReadPoints(new PclReadOptions { Blocks = new BlockRange { StartBlock = 2 } }).ToList();
+ Assert.Equal(2, tail.Count);
+ AssertNear(expected[4], tail[0].Position);
+ AssertNear(expected[5], tail[1].Position);
+ }
+
+ [Fact]
+ public void Lgsx_Range_Past_The_Last_Block_Yields_No_Points()
+ {
+ using var dir = new TempDirectory();
+ using var doc = LgsxDocument.Open(dir.Write("multi.lgsx",
+ SyntheticFixtures.CreateSyntheticLgsx(SixLeicaPoints, blockCount: 3)));
+ var scan = Assert.Single(doc.Scans);
+
+ Assert.Empty(scan.ReadPoints(new PclReadOptions { Blocks = new BlockRange { StartBlock = 3 } }));
+ Assert.Empty(scan.ReadPoints(new PclReadOptions { Blocks = new BlockRange { StartBlock = 1, BlockCount = 0 } }));
+ Assert.Empty(scan.ReadPoints(new PclReadOptions { Blocks = new BlockRange { StartBlock = 10, BlockCount = 5 } }));
+ }
+
+ [Fact]
+ public void Lgsx_Parallel_Read_Matches_The_Sequential_Read_In_Order()
+ {
+ using var dir = new TempDirectory();
+ using var doc = LgsxDocument.Open(dir.Write("multi.lgsx",
+ SyntheticFixtures.CreateSyntheticLgsx(SixLeicaPoints, blockCount: 3)));
+ var scan = Assert.Single(doc.Scans);
+
+ var sequential = scan.ReadPoints(NoTransform).ToList();
+ var parallel = scan.ReadPoints(new PclReadOptions { ApplyTransform = false, MaxDegreeOfParallelism = 4 }).ToList();
+
+ Assert.Equal(sequential.Count, parallel.Count);
+ Assert.Equal(sequential.Select(p => p.Index), parallel.Select(p => p.Index));
+ for (int i = 0; i < sequential.Count; i++)
+ AssertNear(sequential[i].Position, parallel[i].Position);
+ Assert.Equal([0UL, 1UL, 2UL, 3UL, 4UL, 5UL], parallel.Select(p => p.Index));
+ }
+
+ [Fact]
+ public void Lgsx_Parallel_Read_With_A_Range_Matches_The_Sequential_Range()
+ {
+ using var dir = new TempDirectory();
+ using var doc = LgsxDocument.Open(dir.Write("multi.lgsx",
+ SyntheticFixtures.CreateSyntheticLgsx(SixLeicaPoints, blockCount: 3)));
+ var scan = Assert.Single(doc.Scans);
+ var range = new PclReadOptions { ApplyTransform = false, Blocks = new BlockRange { StartBlock = 1, BlockCount = 2 } };
+
+ var sequential = scan.ReadPoints(range).ToList();
+ var parallel = scan.ReadPoints(range with { MaxDegreeOfParallelism = 4 }).ToList();
+
+ Assert.Equal(4, sequential.Count);
+ Assert.Equal(sequential.Select(p => p.Position), parallel.Select(p => p.Position));
+ Assert.Equal([0UL, 1UL, 2UL, 3UL], parallel.Select(p => p.Index));
+ }
+
+ [Fact]
+ public void Lgsx_Parallel_Read_Caps_At_MaxPoints_With_Consecutive_Index()
+ {
+ using var dir = new TempDirectory();
+ using var doc = LgsxDocument.Open(dir.Write("multi.lgsx",
+ SyntheticFixtures.CreateSyntheticLgsx(SixLeicaPoints, blockCount: 3)));
+ var scan = Assert.Single(doc.Scans);
+
+ var capped = scan.ReadPoints(new PclReadOptions { ApplyTransform = false, MaxPoints = 3, MaxDegreeOfParallelism = 4 }).ToList();
+ Assert.Equal(3, capped.Count);
+ Assert.Equal([0UL, 1UL, 2UL], capped.Select(p => p.Index));
+
+ var sequential = scan.ReadPoints(new PclReadOptions { ApplyTransform = false, MaxPoints = 3 }).ToList();
+ for (int i = 0; i < 3; i++) AssertNear(sequential[i].Position, capped[i].Position);
+ }
+
+ [Fact]
+ public void Lgsx_Damaged_Block_Fails_And_A_Range_Around_It_Reads()
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticLgsx(SixLeicaPoints, blockCount: 3, damagedBlock: 1);
+ using var doc = LgsxDocument.Open(dir.Write("damaged.lgsx", bytes));
+ var scan = Assert.Single(doc.Scans);
+
+ Assert.Throws(() => scan.ReadPoints(NoTransform).ToList());
+ var parallelError = Assert.Throws(() =>
+ scan.ReadPoints(new PclReadOptions { ApplyTransform = false, MaxDegreeOfParallelism = 4 }).ToList());
+ Assert.IsNotType(parallelError);
+
+ // The blocks around the damaged one still read.
+ var first = scan.ReadPoints(new PclReadOptions { ApplyTransform = false, Blocks = new BlockRange { StartBlock = 0, BlockCount = 1 } }).ToList();
+ Assert.Equal(2, first.Count);
+ var last = scan.ReadPoints(new PclReadOptions { ApplyTransform = false, Blocks = new BlockRange { StartBlock = 2, BlockCount = 1 } }).ToList();
+ Assert.Equal(2, last.Count);
+ }
+
+ [Fact]
+ public void Lgsx_Truncated_File_Fails_In_Both_Read_Paths()
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticLgsx(SixLeicaPoints, blockCount: 2);
+
+ // Truncate the second block in place: its declared length runs past the file.
+ byte[] magic = [(byte)'A', (byte)'P', (byte)'R', (byte)'N'];
+ int first = bytes.AsSpan().IndexOf(magic);
+ Assert.True(first >= 0);
+ int second = bytes.AsSpan()[(first + 4)..].IndexOf(magic);
+ Assert.True(second >= 0);
+ int lengthAt = first + 4 + second + 4;
+ BitConverter.GetBytes(uint.MaxValue).CopyTo(bytes, lengthAt);
+
+ using var doc = LgsxDocument.Open(dir.Write("cut.lgsx", bytes));
+ var scan = Assert.Single(doc.Scans);
+
+ Assert.Throws(() => scan.ReadPoints(NoTransform).ToList());
+ Assert.Throws(() =>
+ scan.ReadPoints(new PclReadOptions { ApplyTransform = false, MaxDegreeOfParallelism = 4 }).ToList());
+ }
+
+ [Fact]
+ public void Lgsx_Truncated_Read_By_MaxPoints_Reports_No_Incomplete_Data()
+ {
+ using var dir = new TempDirectory();
+ using var doc = LgsxDocument.Open(dir.Write("site.lgsx",
+ SyntheticFixtures.CreateSyntheticLgsx(SixLeicaPoints, blockCount: 1, unknownBlock: true)));
+ var scan = Assert.Single(doc.Scans);
+
+ Assert.Equal(5, scan.ReadPoints(new PclReadOptions { MaxPoints = 5 }).Count());
+ Assert.DoesNotContain(doc.Warnings, w => w.Contains("incomplete", StringComparison.Ordinal));
+
+ var parallel = scan.ReadPoints(new PclReadOptions { MaxPoints = 5, MaxDegreeOfParallelism = 4 }).ToList();
+ Assert.Equal(5, parallel.Count);
+ Assert.DoesNotContain(doc.Warnings, w => w.Contains("incomplete", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void Lgsx_Strict_Mode_Fails_For_A_Selected_Damaged_Block()
+ {
+ using var dir = new TempDirectory();
+ byte[] bytes = SyntheticFixtures.CreateSyntheticLgsx(SixLeicaPoints, blockCount: 2, damagedBlock: 1);
+ using var doc = LgsxDocument.Open(dir.Write("damaged.lgsx", bytes));
+ var scan = Assert.Single(doc.Scans);
+
+ Assert.Throws(() => scan.ReadPoints(new PclReadOptions { Strict = true }).ToList());
+ Assert.Throws(() => scan.ReadPoints(new PclReadOptions
+ {
+ Blocks = new BlockRange { StartBlock = 1, BlockCount = 1 },
+ Strict = true,
+ MaxDegreeOfParallelism = 4,
+ }).ToList());
+ }
+
+ [Fact]
+ public void Other_Readers_Ignore_Blocks_And_Parallel_Options()
+ {
+ using var dir = new TempDirectory();
+ var spec = new E57Spec { Points = [new E57SamplePoint(1, 2, 3, 0, 0, 0, 0), new E57SamplePoint(4, 5, 6, 0, 0, 0, 0)] };
+ using var doc = E57Document.Open(dir.Write("small.e57", spec.Build()));
+
+ var plain = doc.Scans[0].ReadPoints(NoTransform).ToList();
+ var ranged = doc.Scans[0].ReadPoints(new PclReadOptions
+ {
+ ApplyTransform = false,
+ Blocks = new BlockRange { StartBlock = 1, BlockCount = 1 },
+ MaxDegreeOfParallelism = 4,
+ }).ToList();
+
+ Assert.Equal(plain.Count, ranged.Count);
+ for (int i = 0; i < plain.Count; i++) AssertNear(plain[i].Position, ranged[i].Position);
+ }
+
[Fact]
public void Lgsx_Without_A_Point_Data_Entry_Warns_And_Yields_No_Points()
{
diff --git a/tests/PclIO.Tests/OptionsAndPathTests.cs b/tests/PclIO.Tests/OptionsAndPathTests.cs
index 82f9dc2..70f576b 100644
--- a/tests/PclIO.Tests/OptionsAndPathTests.cs
+++ b/tests/PclIO.Tests/OptionsAndPathTests.cs
@@ -20,6 +20,8 @@ public void Default_Options_Read_Everything_And_Apply_The_Transform()
Assert.True(options.ApplyTransform);
Assert.False(options.Strict);
Assert.False(options.ExcludeFilteredPoints);
+ Assert.Null(options.Blocks);
+ Assert.Equal(1, options.MaxDegreeOfParallelism);
Assert.Equal(options, PclReadOptions.Default);
}
@@ -108,6 +110,39 @@ public void Las_Options_Default_To_1_2_Format_2_And_A_Millimetre()
Assert.Equal(options, PclLasOptions.Default);
}
+ [Theory]
+ [InlineData(-1)]
+ [InlineData(int.MinValue)]
+ public void A_Negative_Block_Start_Is_Rejected(int value) =>
+ Assert.Throws(() => new BlockRange { StartBlock = value });
+
+ [Theory]
+ [InlineData(-1)]
+ [InlineData(int.MinValue)]
+ public void A_Negative_Block_Count_Is_Rejected(int value) =>
+ Assert.Throws(() => new BlockRange { BlockCount = value });
+
+ [Fact]
+ public void A_Block_Range_Of_Zero_Count_And_Null_Count_Is_Accepted()
+ {
+ Assert.Equal(0, new BlockRange { StartBlock = 2, BlockCount = 0 }.BlockCount);
+ Assert.Null(new BlockRange { StartBlock = 2 }.BlockCount);
+ }
+
+ [Theory]
+ [InlineData(0)]
+ [InlineData(-1)]
+ [InlineData(int.MinValue)]
+ public void A_Parallelism_Below_One_Is_Rejected(int value) =>
+ Assert.Throws(() => new PclReadOptions { MaxDegreeOfParallelism = value });
+
+ [Fact]
+ public void A_Parallelism_Of_One_Or_More_Is_Accepted()
+ {
+ Assert.Equal(1, new PclReadOptions { MaxDegreeOfParallelism = 1 }.MaxDegreeOfParallelism);
+ Assert.Equal(4, new PclReadOptions { MaxDegreeOfParallelism = 4 }.MaxDegreeOfParallelism);
+ }
+
[Fact]
public void A_Limit_Applies_To_The_Total_Across_All_Scans()
{
diff --git a/tests/PclIO.Tests/SyntheticFixtures.cs b/tests/PclIO.Tests/SyntheticFixtures.cs
index 619e101..8774428 100644
--- a/tests/PclIO.Tests/SyntheticFixtures.cs
+++ b/tests/PclIO.Tests/SyntheticFixtures.cs
@@ -174,10 +174,13 @@ public static byte[] CreateZip(string entryName, string text)
/// True writes a chunk the reader does not know before the point blocks.
/// True ends the frame list of a block with a length prefix that declares more bytes than the block holds.
/// True writes the blocks with fewer than four planes, so they carry no positions.
+ /// When above zero, splits the points into that many blocks without assigning them to setups.
+ /// When not negative, only the block with this zero-based index holds damaged frames.
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 damagedPointData = false, bool withPointCount = true,
- bool oversizedFrame = false, bool unknownBlock = false, bool unknownFirstBlock = false, bool truncatedFrameList = false, bool fewPlanes = false)
+ bool oversizedFrame = false, bool unknownBlock = false, bool unknownFirstBlock = false, bool truncatedFrameList = false, bool fewPlanes = false,
+ int blockCount = 0, int damagedBlock = -1)
{
points ??= DefaultLeicaPoints;
using var ms = new MemoryStream();
@@ -186,13 +189,13 @@ 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)
+ var groups = blockCount > 0 ? SplitPoints(points, blockCount)
+ : assignPointsToSetups ? SplitPoints(points, setupCount)
: new List> { points };
(byte[] payload, List<(long Start, long Length)> blocks) =
BuildLeicaPayload(groups, withColorAndIntensity, extraPlanes ?? [], damagedPointData, withPointCount, oversizedFrame, unknownBlock,
- unknownFirstBlock, truncatedFrameList, fewPlanes);
+ unknownFirstBlock, truncatedFrameList, fewPlanes, damagedBlock);
// 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();
@@ -321,7 +324,7 @@ private static void WriteEntry(BinaryWriter bw, string name, ulong payloadOffset
private static (byte[] Payload, List<(long Start, long Length)> Blocks) BuildLeicaPayload(
IReadOnlyList> groups, bool full, IReadOnlyList extraPlanes, bool damaged = false,
bool withPointCount = true, bool oversizedFrame = false, bool unknownBlock = false,
- bool unknownFirstBlock = false, bool truncatedFrameList = false, bool fewPlanes = false)
+ bool unknownFirstBlock = false, bool truncatedFrameList = false, bool fewPlanes = false, int damagedBlock = -1)
{
using var ms = new MemoryStream();
using var bw = new BinaryWriter(ms);
@@ -343,6 +346,7 @@ private static (byte[] Payload, List<(long Start, long Length)> Blocks) BuildLei
}
var blocks = new List<(long Start, long Length)>();
+ int blockIndex = 0;
foreach (var group in groups)
{
// A setup without points has no block of its own.
@@ -350,12 +354,14 @@ private static (byte[] Payload, List<(long Start, long Length)> Blocks) BuildLei
var frames = BuildFrames(group, full, extraPlanes);
if (fewPlanes) frames = [.. frames.Take(3)];
- if (damaged)
+ if (damaged || blockIndex == damagedBlock)
{
// 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;
}
+ blockIndex++;
+
// A frame whose declared length is above the accepted size is skipped by the reader.
const ulong OversizedLength = 20_000_000;
int blockLength = 8 + 128 + frames.Sum(f => 8 + f.Length) + (oversizedFrame ? 8 : 0) + (truncatedFrameList ? 8 : 0);