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 @@ -31,6 +31,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
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.
- The normals (`Normals`) of the PinPoint sectioned layout are read when the file holds them, and `HasNormals` reports
what the file contains.

## [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 @@ -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 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. |
| 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 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
Expand Down
12 changes: 6 additions & 6 deletions src/PclIO/Formats/PinPoint/PinPointDocument.cs
Original file line number Diff line number Diff line change
Expand Up @@ -344,7 +344,7 @@ internal sealed class ChannelTable

public bool HasIntensities => Packed ? PackedPoints > 0 && IntensitiesLength > 0 : IntensitiesLength >= 1;

public bool HasNormals => NormalsLength >= 12;
public bool HasNormals => Packed ? PackedPoints > 0 && NormalsLength > 0 : NormalsLength >= 12;

/// <summary>True when the file holds a per-point flags channel (one byte per stored point).</summary>
public bool HasFilterBits => Packed ? PackedPoints > 0 && FilterLength > 0 : false;
Expand Down Expand Up @@ -462,9 +462,9 @@ internal PinPointScan(string id, string name, long pointCount, PclTransform tran
/// <para>
/// 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), 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.
/// ("Points"), colours ("RGB8", three bytes per point), intensities ("Intensities8"), normals ("Normals", three
/// float32 components per point) 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.
/// </para>
/// <para>
/// By default every stored point that passes the plausibility rule above is returned. With
Expand Down Expand Up @@ -506,7 +506,7 @@ private IEnumerable<PclPoint> ReadChannels(PinPointDocument.ChannelTable table,
int colorSize = table.ColorSize;
long pointTotal = table.PointCount;
long colorTotal = !table.HasColors ? 0 : table.Packed ? pointTotal : table.ColorsLength / colorSize;
long normalTotal = !table.HasNormals ? 0 : table.NormalsLength / 12;
long normalTotal = !table.HasNormals ? 0 : table.Packed ? pointTotal : table.NormalsLength / 12;
long intensityTotal = !table.HasIntensities ? 0 : table.Packed ? pointTotal : table.IntensitiesLength;

using var points = OpenChannel(table, table.PointsOffset, table.PointsLength, pointTotal > 0);
Expand Down Expand Up @@ -590,7 +590,7 @@ private IEnumerable<PclPoint> 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, filters })
foreach (var stream in new[] { points, colors, normals, intensities, filters })
if (stream != null && stream.ReadByte() >= 0) throw FormatError.Corrupted("a compressed channel holds more data than it declares");
}
}
Expand Down
6 changes: 4 additions & 2 deletions src/PclIO/Formats/PinPoint/PinPointPackedLayout.cs
Original file line number Diff line number Diff line change
Expand Up @@ -110,8 +110,9 @@ private static PinPointDocument.ChannelTable ReadChannels(FileStream fs, List<st
position += (long)streamLength;

// Each channel with a meaning here holds a fixed number of bytes per point; the stream says how many it decodes to.
// "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 };
// "FilterBits" holds one flag byte per point, "Normals" three float32 components per point;
// "RowColIndex" and unknown channels are skipped.
int elementSize = name switch { "Points" => 12, "RGB8" => 3, "Intensities8" => 1, "FilterBits" => 1, "Normals" => 12, _ => 0 };
if (elementSize == 0) continue;
if (!seen.Add(name)) throw FormatError.Corrupted($"channel '{name}' is listed twice");

Expand All @@ -123,6 +124,7 @@ private static PinPointDocument.ChannelTable ReadChannels(FileStream fs, List<st
if (name == "Points") (table.PointsOffset, table.PointsLength) = (streamOffset, (long)streamLength);
else if (name == "RGB8") (table.ColorsOffset, table.ColorsLength) = (streamOffset, (long)streamLength);
else if (name == "FilterBits") (table.FilterOffset, table.FilterLength) = (streamOffset, (long)streamLength);
else if (name == "Normals") (table.NormalsOffset, table.NormalsLength) = (streamOffset, (long)streamLength);
else (table.IntensitiesOffset, table.IntensitiesLength) = (streamOffset, (long)streamLength);
}

Expand Down
10 changes: 9 additions & 1 deletion tests/PclIO.Tests/PinPointPackedFixtures.cs
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,13 @@ internal static class PinPointPackedFixtures
/// <summary>Creates a file. Colours are RGB (three bytes per point), intensities one byte per point.</summary>
/// <param name="runEncodedColors">Stores the colour channel as one literal followed by copies, which needs identical colours.</param>
/// <param name="filterBits">One flag byte per point; a non-zero flag marks the point as filtered. All zero by default.</param>
/// <param name="normals">Three float32 components per point. Absent by default.</param>
public static PackedBin Create(IReadOnlyList<(float X, float Y, float Z)> points, byte[]? rgb = null, byte[]? intensities = null,
bool runEncodedColors = false, byte[]? filterBits = null)
bool runEncodedColors = false, byte[]? filterBits = null, float[]? normals = null)
{
int n = points.Count;
if (filterBits != null && filterBits.Length != n) throw new ArgumentException("One flag byte per point is needed.", nameof(filterBits));
if (normals != null && normals.Length != n * 3) throw new ArgumentException("Three components per point are needed.", nameof(normals));
byte[] positions = new byte[n * 12];
for (int i = 0; i < n; i++)
{
Expand All @@ -37,6 +39,12 @@ public static PackedBin Create(IReadOnlyList<(float X, float Y, float Z)> points
};
if (rgb != null) channels.Add(("RGB8", runEncodedColors ? Runs(rgb, 3) : Literals(rgb)));
if (intensities != null) channels.Add(("Intensities8", Literals(intensities)));
if (normals != null)
{
byte[] raw = new byte[normals.Length * 4];
for (int i = 0; i < normals.Length; i++) BinaryPrimitives.WriteSingleLittleEndian(raw.AsSpan(i * 4, 4), normals[i]);
channels.Add(("Normals", Literals(raw)));
}

return Assemble(channels, n);
}
Expand Down
35 changes: 35 additions & 0 deletions tests/PclIO.Tests/PinPointPackedTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ public void Colour_And_Intensity_Are_Absent_Without_Their_Channels()
var scan = (PinPointScan)Assert.Single(doc.Scans);
Assert.False(scan.HasColors);
Assert.False(scan.HasIntensities);
Assert.False(scan.HasNormals);
Assert.All(ReadAll(doc), p =>
{
Assert.Null(p.Color);
Expand All @@ -55,6 +56,40 @@ public void Colour_And_Intensity_Are_Absent_Without_Their_Channels()
});
}

[Fact]
public void Normals_Are_Read_When_The_File_Holds_Them()
{
using var dir = new TempDirectory();
using var doc = Open(dir, PinPointPackedFixtures.Create(Three, normals: [0, 0, 1, 0, 0, 0, 1, 0, 0]));

var scan = (PinPointScan)Assert.Single(doc.Scans);
Assert.True(scan.HasNormals);

var points = ReadAll(doc);
Assert.Equal(3, points.Count);
Assert.Equal(new PclVector3(0, 0, 1), points[0].Normal);
Assert.Null(points[1].Normal);
Assert.Equal(new PclVector3(1, 0, 0), points[2].Normal);
}

[Fact]
public void A_Normals_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)),
("Normals", PinPointPackedFixtures.Literals(new byte[Three.Length * 12 - 1])),
], Three.Length);

using var doc = PinPointDocument.Open(SyntheticFixtures.WritePinPointProject(dir, bad.Bytes));

Assert.Contains(doc.Warnings, w => w.Contains("Normals", StringComparison.Ordinal));
Assert.Throws<InvalidDataException>(() => ReadAll(doc));
}

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