diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6f0933b..e373d46 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -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
diff --git a/README.md b/README.md
index badeb7a..5dc6c11 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 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
diff --git a/src/PclIO/Formats/PinPoint/PinPointDocument.cs b/src/PclIO/Formats/PinPoint/PinPointDocument.cs
index 8a5a781..2aada22 100644
--- a/src/PclIO/Formats/PinPoint/PinPointDocument.cs
+++ b/src/PclIO/Formats/PinPoint/PinPointDocument.cs
@@ -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;
/// True when the file holds a per-point flags channel (one byte per stored point).
public bool HasFilterBits => Packed ? PackedPoints > 0 && FilterLength > 0 : false;
@@ -462,9 +462,9 @@ 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), 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.
///
///
/// By default every stored point that passes the plausibility rule above is returned. With
@@ -506,7 +506,7 @@ private IEnumerable 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);
@@ -590,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, 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");
}
}
diff --git a/src/PclIO/Formats/PinPoint/PinPointPackedLayout.cs b/src/PclIO/Formats/PinPoint/PinPointPackedLayout.cs
index ea6af2d..1fe10e7 100644
--- a/src/PclIO/Formats/PinPoint/PinPointPackedLayout.cs
+++ b/src/PclIO/Formats/PinPoint/PinPointPackedLayout.cs
@@ -110,8 +110,9 @@ private static PinPointDocument.ChannelTable ReadChannels(FileStream fs, List 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");
@@ -123,6 +124,7 @@ private static PinPointDocument.ChannelTable ReadChannels(FileStream fs, ListCreates 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.
+ /// Three float32 components per point. Absent by default.
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++)
{
@@ -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);
}
diff --git a/tests/PclIO.Tests/PinPointPackedTests.cs b/tests/PclIO.Tests/PinPointPackedTests.cs
index 8757211..4cd017d 100644
--- a/tests/PclIO.Tests/PinPointPackedTests.cs
+++ b/tests/PclIO.Tests/PinPointPackedTests.cs
@@ -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);
@@ -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(() => ReadAll(doc));
+ }
+
[Fact]
public void Flagged_Points_Are_Returned_By_Default_And_Excluded_On_Request()
{