From 993e93cb138e56a1dc76d70ff8f4f6f71b4c0408 Mon Sep 17 00:00:00 2001
From: mahach666 <79989386+mahach666@users.noreply.github.com>
Date: Mon, 16 Nov 2026 03:17:29 +0000
Subject: [PATCH] Read the per-point flags of the PinPoint sectioned layout
---
CHANGELOG.md | 2 +
README.md | 2 +-
docs/public-api.md | 2 +-
.../Formats/PinPoint/PinPointDocument.cs | 32 ++++++++++++---
.../Formats/PinPoint/PinPointPackedLayout.cs | 4 +-
src/PclIO/PclReadOptions.cs | 8 ++++
tests/PclIO.Tests/PinPointPackedFixtures.cs | 6 ++-
tests/PclIO.Tests/PinPointPackedTests.cs | 39 +++++++++++++++++++
8 files changed, 85 insertions(+), 10 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 035b202..6f0933b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,6 +29,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
colour, an intensity and a normal. `HasColors`, `HasIntensities` and `HasNormals` are no longer constants.
- The transform of a ReCap project scan node is applied to its points unless `ApplyTransform` is false; when the manifest
states no transform, the transform of the scan file is used.
+- The per-point flags (`FilterBits`) of the PinPoint sectioned layout are read and validated. The new
+ `PclReadOptions.ExcludeFilteredPoints` excludes the points with a non-zero flag; by default every stored point is returned.
## [0.1.0] - 2026-11-15
diff --git a/README.md b/README.md
index ac19306..badeb7a 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,7 @@ The library targets .NET 8 and .NET 10. It is managed code with no dependencies
| 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. |
| 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 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. |
+| 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 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 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. |
### Format detection
diff --git a/docs/public-api.md b/docs/public-api.md
index 654a134..c471be9 100644
--- a/docs/public-api.md
+++ b/docs/public-api.md
@@ -15,7 +15,7 @@ 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), `SubsampleStep` (1 keeps every point, N keeps about one in N), `ApplyTransform` (default true) and `Strict` (default false: a reader that finds incomplete data fails with `InvalidDataException` instead of adding a warning). Negative `MaxPoints` 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), `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` and a step below 1 throw `ArgumentOutOfRangeException`. `PclReadOptions.Default` has no limit. |
`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
diff --git a/src/PclIO/Formats/PinPoint/PinPointDocument.cs b/src/PclIO/Formats/PinPoint/PinPointDocument.cs
index 43725d4..8a5a781 100644
--- a/src/PclIO/Formats/PinPoint/PinPointDocument.cs
+++ b/src/PclIO/Formats/PinPoint/PinPointDocument.cs
@@ -326,6 +326,7 @@ internal sealed class ChannelTable
public long ColorsOffset, ColorsLength;
public long NormalsOffset, NormalsLength;
public long IntensitiesOffset, IntensitiesLength;
+ public long FilterOffset, FilterLength;
/// True when the channels are Snappy streams, with the point count stored in .
public bool Packed;
@@ -345,6 +346,9 @@ internal sealed class ChannelTable
public bool HasNormals => NormalsLength >= 12;
+ /// True when the file holds a per-point flags channel (one byte per stored point).
+ public bool HasFilterBits => Packed ? PackedPoints > 0 && FilterLength > 0 : false;
+
/// Reads the table, or returns null when the file has neither layout.
public static ChannelTable? TryRead(FileStream fs)
{
@@ -431,6 +435,9 @@ public sealed class PinPointScan : PclScan
/// True only when the point data file has a normals channel.
public override bool HasNormals => _table is { HasNormals: true };
+ /// True when the point data file holds a per-point flags channel ("FilterBits", one byte per stored point).
+ public bool HasFilterBits => _table is { HasFilterBits: true };
+
internal PinPointScan(string id, string name, long pointCount, PclTransform transform, string? binFilePath,
PinPointDocument.ChannelTable? table)
{
@@ -455,8 +462,15 @@ internal PinPointScan(string id, string name, long pointCount, PclTransform tran
///
/// A point data file whose layout is neither a table of named channels nor a list of sections with a property table is
/// not decoded, because the file does not describe its layout. Of the channels of the sectioned layout the positions
- /// ("Points"), colours ("RGB8", three bytes per point) and intensities ("Intensities8") are read; the per-point flags
- /// and the grid indices stored next to them are not interpreted, so every stored point is returned.
+ /// ("Points"), colours ("RGB8", three bytes per point), intensities ("Intensities8") and per-point flags
+ /// ("FilterBits", one byte per point) are read; a non-zero flag marks the point as filtered. The grid indices stored
+ /// beside them ("RowColIndex") are not interpreted.
+ ///
+ ///
+ /// By default every stored point that passes the plausibility rule above is returned. With
+ /// the points that the flags mark as filtered are not returned
+ /// and are not counted in the running values. The exact meaning of the individual flag
+ /// bits is not confirmed by test files, so any non-zero value counts as filtered.
///
///
/// The point data file is damaged.
@@ -475,15 +489,19 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null)
if (table == null) throw FormatError.Unsupported("point data file without a recognised channel layout");
- foreach (var pt in ReadChannels(table, targetCount, step, options.ApplyTransform)) yield return pt;
+ foreach (var pt in ReadChannels(table, targetCount, step, options)) yield return pt;
}
// Points are decoded in batches, so that reading cost does not depend on the number of calls into the streams.
private const int Batch = 4096;
- private IEnumerable ReadChannels(PinPointDocument.ChannelTable table, long targetCount, int step, bool applyTransform)
+ private IEnumerable ReadChannels(PinPointDocument.ChannelTable table, long targetCount, int step, PclReadOptions options)
{
if (targetCount <= 0) yield break;
+ bool applyTransform = options.ApplyTransform;
+
+ // A point whose flag byte is not zero is marked as filtered; it is only skipped when the caller asks for it.
+ bool skipFiltered = options.ExcludeFilteredPoints && table.HasFilterBits;
int colorSize = table.ColorSize;
long pointTotal = table.PointCount;
@@ -495,11 +513,13 @@ private IEnumerable ReadChannels(PinPointDocument.ChannelTable table,
using var colors = OpenChannel(table, table.ColorsOffset, table.ColorsLength, colorTotal > 0);
using var normals = OpenChannel(table, table.NormalsOffset, table.NormalsLength, normalTotal > 0);
using var intensities = OpenChannel(table, table.IntensitiesOffset, table.IntensitiesLength, intensityTotal > 0);
+ using var filters = OpenChannel(table, table.FilterOffset, table.FilterLength, skipFiltered);
byte[] pointBytes = new byte[Batch * 12];
byte[] colorBytes = new byte[Batch * colorSize];
byte[] normalBytes = new byte[Batch * 12];
byte[] intensityBytes = new byte[Batch];
+ byte[] filterBytes = new byte[Batch];
long yielded = 0;
long start = 0;
@@ -515,10 +535,12 @@ private IEnumerable ReadChannels(PinPointDocument.ChannelTable table,
if (normalCount > 0) normals!.ReadExactly(normalBytes, 0, normalCount * 12);
int intensityCount = intensities == null ? 0 : (int)Math.Clamp(intensityTotal - start, 0, count);
if (intensityCount > 0) intensities!.ReadExactly(intensityBytes, 0, intensityCount);
+ if (filters != null) filters.ReadExactly(filterBytes, 0, count);
for (int j = 0; j < count && yielded < targetCount; j++)
{
if ((start + j) % step != 0) continue;
+ if (filters != null && filterBytes[j] != 0) continue;
var record = pointBytes.AsSpan(j * 12, 12);
float x = Bytes.ReadSingleLE(record[..4]);
@@ -568,7 +590,7 @@ private IEnumerable ReadChannels(PinPointDocument.ChannelTable table,
// Once every point has been read, a compressed stream must end there: bytes after its last element are an error.
if (table.Packed && start >= pointTotal)
{
- foreach (var stream in new[] { points, colors, intensities })
+ foreach (var stream in new[] { points, colors, intensities, filters })
if (stream != null && stream.ReadByte() >= 0) throw FormatError.Corrupted("a compressed channel holds more data than it declares");
}
}
diff --git a/src/PclIO/Formats/PinPoint/PinPointPackedLayout.cs b/src/PclIO/Formats/PinPoint/PinPointPackedLayout.cs
index 85fa47f..ea6af2d 100644
--- a/src/PclIO/Formats/PinPoint/PinPointPackedLayout.cs
+++ b/src/PclIO/Formats/PinPoint/PinPointPackedLayout.cs
@@ -110,7 +110,8 @@ private static PinPointDocument.ChannelTable ReadChannels(FileStream fs, List 12, "RGB8" => 3, "Intensities8" => 1, _ => 0 };
+ // "FilterBits" holds one flag byte per point; "RowColIndex" and unknown channels are skipped.
+ int elementSize = name switch { "Points" => 12, "RGB8" => 3, "Intensities8" => 1, "FilterBits" => 1, _ => 0 };
if (elementSize == 0) continue;
if (!seen.Add(name)) throw FormatError.Corrupted($"channel '{name}' is listed twice");
@@ -121,6 +122,7 @@ private static PinPointDocument.ChannelTable ReadChannels(FileStream fs, List
public bool Strict { get; init; }
+
+ ///
+ /// Whether points that the file marks as filtered are excluded from the read. Currently only the PinPoint
+ /// sectioned layout marks points: its "FilterBits" channel holds one flag byte per stored point, and a non-zero
+ /// flag means the point is filtered. Readers without such a channel ignore this option. The default is false, so
+ /// that every stored point that passes the other rules of the reader is returned.
+ ///
+ public bool ExcludeFilteredPoints { get; init; }
}
diff --git a/tests/PclIO.Tests/PinPointPackedFixtures.cs b/tests/PclIO.Tests/PinPointPackedFixtures.cs
index ab15909..252295d 100644
--- a/tests/PclIO.Tests/PinPointPackedFixtures.cs
+++ b/tests/PclIO.Tests/PinPointPackedFixtures.cs
@@ -15,10 +15,12 @@ internal static class PinPointPackedFixtures
/// Creates a file. Colours are RGB (three bytes per point), intensities one byte per point.
/// Stores the colour channel as one literal followed by copies, which needs identical colours.
+ /// One flag byte per point; a non-zero flag marks the point as filtered. All zero by default.
public static PackedBin Create(IReadOnlyList<(float X, float Y, float Z)> points, byte[]? rgb = null, byte[]? intensities = null,
- bool runEncodedColors = false)
+ bool runEncodedColors = false, byte[]? filterBits = null)
{
int n = points.Count;
+ if (filterBits != null && filterBits.Length != n) throw new ArgumentException("One flag byte per point is needed.", nameof(filterBits));
byte[] positions = new byte[n * 12];
for (int i = 0; i < n; i++)
{
@@ -31,7 +33,7 @@ public static PackedBin Create(IReadOnlyList<(float X, float Y, float Z)> points
{
("RowColIndex", Literals(new byte[n * 8])),
("Points", Literals(positions)),
- ("FilterBits", Literals(new byte[n])),
+ ("FilterBits", Literals(filterBits ?? new byte[n])),
};
if (rgb != null) channels.Add(("RGB8", runEncodedColors ? Runs(rgb, 3) : Literals(rgb)));
if (intensities != null) channels.Add(("Intensities8", Literals(intensities)));
diff --git a/tests/PclIO.Tests/PinPointPackedTests.cs b/tests/PclIO.Tests/PinPointPackedTests.cs
index fedc9fd..8757211 100644
--- a/tests/PclIO.Tests/PinPointPackedTests.cs
+++ b/tests/PclIO.Tests/PinPointPackedTests.cs
@@ -55,6 +55,45 @@ public void Colour_And_Intensity_Are_Absent_Without_Their_Channels()
});
}
+ [Fact]
+ public void Flagged_Points_Are_Returned_By_Default_And_Excluded_On_Request()
+ {
+ using var dir = new TempDirectory();
+ var bin = PinPointPackedFixtures.Create(Three, filterBits: [0, 1, 0]);
+ using var doc = Open(dir, bin);
+
+ var scan = (PinPointScan)Assert.Single(doc.Scans);
+ Assert.True(scan.HasFilterBits);
+
+ // By default every stored point is returned.
+ var all = ReadAll(doc);
+ Assert.Equal(3, all.Count);
+
+ // On request the point with a non-zero flag is not returned, and the rest keeps consecutive indices.
+ var kept = ReadAll(doc, new PclReadOptions { ApplyTransform = false, ExcludeFilteredPoints = true });
+ Assert.Equal(2, kept.Count);
+ Assert.Equal([0UL, 1UL], kept.Select(p => p.Index));
+ Assert.Equal([(1.0, 2.0, 3.0), (7.0, 8.0, -9.25)], kept.Select(p => (p.X, p.Y, p.Z)));
+ }
+
+ [Fact]
+ public void A_FilterBits_Channel_With_The_Wrong_Size_Is_Rejected()
+ {
+ using var dir = new TempDirectory();
+ byte[] positions = new byte[Three.Length * 12];
+ var bad = PinPointPackedFixtures.Assemble(
+ [
+ ("RowColIndex", PinPointPackedFixtures.Literals(new byte[Three.Length * 8])),
+ ("Points", PinPointPackedFixtures.Literals(positions)),
+ ("FilterBits", PinPointPackedFixtures.Literals(new byte[Three.Length - 1])),
+ ], Three.Length);
+
+ using var doc = PinPointDocument.Open(SyntheticFixtures.WritePinPointProject(dir, bad.Bytes));
+
+ Assert.Contains(doc.Warnings, w => w.Contains("FilterBits", StringComparison.Ordinal));
+ Assert.Throws(() => ReadAll(doc));
+ }
+
[Fact]
public void The_Point_Count_Comes_From_The_Data_Section_Unless_The_Manifest_Gives_One()
{