diff --git a/CHANGELOG.md b/CHANGELOG.md index ef767f7..035b202 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 layout is rejected with a message that names the version and the described ones. - The channels of a ReCap scan follow from the file: the size of the payload of the nodes tells whether the points hold a 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. ## [0.1.0] - 2026-11-15 diff --git a/README.md b/README.md index 9fd3304..ac19306 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ The library targets .NET 8 and .NET 10. It is managed code with no dependencies | --- | --- | --- | | ASTM E57 | `.e57` | Points decoded for a defined subset: uncompressed bit-packed streams with single or double precision Cartesian coordinates, 8-bit colour and 8-bit intensity. Pose translation and rotation are applied. Scaled-integer coordinates, spherical coordinates and other codecs are not supported: a scan that uses them lists normally and fails when its points are read. Per-point validity flags and images are not read, so points flagged as invalid are returned as stored, and colour or intensity fields of any other type or range are ignored. Page checksums are verified. | | ReCap scan | `.rcs` | Experimental. The header is read; point decoding covers 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. Node transforms are exposed as data and are not applied to points. | +| 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. | diff --git a/src/PclIO/Formats/Recap/RcpProjectDocument.cs b/src/PclIO/Formats/Recap/RcpProjectDocument.cs index 83f8ae6..5b40ba0 100644 --- a/src/PclIO/Formats/Recap/RcpProjectDocument.cs +++ b/src/PclIO/Formats/Recap/RcpProjectDocument.cs @@ -8,8 +8,9 @@ namespace PclIO.Formats.Recap; /// /// Reads a ReCap project archive (.rcp) and lists its scan nodes. Referenced .rcs files are looked up next to the -/// project; paths stored in the archive are never followed outside the project folder. Node transforms are parsed -/// and exposed as data but are not applied to points. +/// project; paths stored in the archive are never followed outside the project folder. The transform of a scan node +/// places the scan in the project and is applied to its points unless reading asks not to; when the manifest states +/// no transform for a node, the transform of the scan file is used. /// public sealed class RcpProjectDocument : PclDocument { @@ -103,13 +104,13 @@ public static RcpProjectDocument Open(string path, PclReadOptions? options = nul (!long.TryParse(numPointsStr, NumberStyles.Integer, CultureInfo.InvariantCulture, out numPoints) || numPoints < 0)) throw FormatError.Corrupted($"Invalid point count for scan '{name}'."); - var transform = ParseNodeTransform(node); + var (transform, transformStated) = ParseNodeTransform(node); string? resolvedRcsPath = ResolveRcsPath(projectDir, supportDir, rawRcsPath, name); if (resolvedRcsPath == null) project._warnings.Add($"Scan '{name}': scan file was not found next to the project or its path was rejected; it yields no points."); - project._scans.Add(new RcpScan(id, name, numPoints, transform, resolvedRcsPath)); + project._scans.Add(new RcpScan(id, name, numPoints, transform, resolvedRcsPath, transformStated)); index++; } @@ -206,12 +207,16 @@ private static XDocument BuildDocument(XmlReader reader) // Components may be written as x/y/z, X/Y/Z, or (for rotation) Yaw/Pitch/Roll; the first one present is used. // Rotation is informational only: Yaw, Pitch and Roll fill the X, Y and Z components in that order, with no // rotation convention implied, and PclTransform does not apply them. - private static PclTransform ParseNodeTransform(XElement node) + // The second value tells whether the project states a transform that places the node. Only the translation and + // the scale place it; a node that states a rotation alone leaves the placement to the transform of the scan file. + private static (PclTransform Transform, bool Stated) ParseNodeTransform(XElement node) { var transElem = node.Element("Translation"); var rotElem = node.Element("Rotation"); var scaleElem = node.Element("Scale"); + bool stated = transElem != null || scaleElem != null; + double tx = ParseDouble(transElem?.Attribute("x")?.Value ?? transElem?.Attribute("X")?.Value, 0); double ty = ParseDouble(transElem?.Attribute("y")?.Value ?? transElem?.Attribute("Y")?.Value, 0); double tz = ParseDouble(transElem?.Attribute("z")?.Value ?? transElem?.Attribute("Z")?.Value, 0); @@ -224,12 +229,14 @@ private static PclTransform ParseNodeTransform(XElement node) double sy = ParseDouble(scaleElem?.Attribute("y")?.Value ?? scaleElem?.Attribute("Y")?.Value, 1); double sz = ParseDouble(scaleElem?.Attribute("z")?.Value ?? scaleElem?.Attribute("Z")?.Value, 1); - return new PclTransform + var transform = new PclTransform { Translation = new PclVector3(tx, ty, tz), Rotation = new PclVector3(rx, ry, rz), Scale = new PclVector3(sx, sy, sz) }; + + return (transform, stated); } // Looks for the scan file inside the project folder only; every candidate goes through SafePath. @@ -276,6 +283,9 @@ private static double ParseDouble(string? text, double fallback) /// Scan node of a ReCap project. public sealed class RcpScan : PclScan { + // True when the project states a transform for the node; it then places the scan. + private readonly bool _transformStated; + /// public override string Id { get; } @@ -297,19 +307,20 @@ public sealed class RcpScan : PclScan /// public override bool HasIntensities => RcsFilePath != null; - internal RcpScan(string id, string name, long pointCount, PclTransform transform, string? rcsFilePath) + internal RcpScan(string id, string name, long pointCount, PclTransform transform, string? rcsFilePath, bool transformStated) { Id = id; Name = name; PointCount = pointCount; Transform = transform; RcsFilePath = rcsFilePath; + _transformStated = transformStated; } /// - /// Streams the points of the referenced .rcs file with that file's own header transform. The project node - /// is data only and is not applied. Yields nothing when the file was not found - /// (the document records a warning). + /// Streams the points of the referenced .rcs file. The transform of the project places the scan in the project, so + /// it is applied to the points instead of the transform of the scan file; when the project states no transform, the + /// transform of the scan file is used. Yields nothing when the file was not found (the document records a warning). /// public override IEnumerable ReadPoints(PclReadOptions? options = null) { @@ -317,9 +328,26 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null) if (RcsFilePath == null) yield break; using var rcsDoc = RcsScanDocument.Open(RcsFilePath, options); - foreach (var pt in rcsDoc.ReadAllPoints(options)) + + // The transform of the project and the one of the scan file place the scan in the same way, so only one of + // them is applied. + bool place = options.ApplyTransform && _transformStated; + PclReadOptions readOptions = place ? options with { ApplyTransform = false } : options; + + foreach (var pt in rcsDoc.ReadAllPoints(readOptions)) { - yield return pt; + if (!place) + { + yield return pt; + continue; + } + + // The placement moves the position and re-orients the normal with it, as the scan-file transform does. + yield return pt with + { + Position = Transform.TransformPoint(pt.Position), + Normal = pt.Normal is { } n ? Transform.TransformVector(n) : null + }; } } } diff --git a/src/PclIO/Formats/Recap/RcsScanDocument.cs b/src/PclIO/Formats/Recap/RcsScanDocument.cs index ed004bc..3d49960 100644 --- a/src/PclIO/Formats/Recap/RcsScanDocument.cs +++ b/src/PclIO/Formats/Recap/RcsScanDocument.cs @@ -308,8 +308,9 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null) long curOffset = payloadStart; byte[] chunkBuf = new byte[65536]; - // Normals are read per chunk, so memory stays constant however large a node is. - byte[] normalBuf = new byte[chunkBuf.Length / PointRecordSize * NormalRecordSize]; + // Normals are read per chunk, so memory stays constant however large a node is. Sized for the shortest + // record, which packs the most points per chunk. + byte[] normalBuf = new byte[chunkBuf.Length / PositionRecordSize * NormalRecordSize]; foreach (var node in nodes) { diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs index f74f244..99f983d 100644 --- a/tests/PclIO.Tests/FormatTests.cs +++ b/tests/PclIO.Tests/FormatTests.cs @@ -287,6 +287,91 @@ public void Rcp_Scan_Is_Read_From_The_Support_Folder() Assert.Equal(3, doc.ReadAllPoints(NoTransform).Count()); } + [Fact] + public void An_Rcp_Applies_The_Transform_Of_The_Project_To_Its_Points() + { + using var dir = new TempDirectory(); + string rcp = dir.Write("site.rcp", SyntheticFixtures.CreateSyntheticRcpZip()); + dir.Write(Path.Combine("site Support", "scan1.rcs"), + SyntheticFixtures.CreateSyntheticRcsWithPoints(RcsPoints, (0, 0, 0))); + + using var doc = RcpProjectDocument.Open(rcp); + + // The project places the scan at (10.5, 20.5, 5). + var moved = doc.ReadAllPoints().ToList(); + var raw = doc.ReadAllPoints(NoTransform).ToList(); + Assert.Equal(3, moved.Count); + for (int i = 0; i < moved.Count; i++) + { + AssertNear(new PclVector3(raw[i].X + 10.5, raw[i].Y + 20.5, raw[i].Z + 5.0), moved[i].Position); + } + } + + [Fact] + public void An_Rcp_Without_A_Transform_Of_The_Project_Uses_The_Transform_Of_The_Scan_File() + { + using var dir = new TempDirectory(); + string rcp = dir.Write("site.rcp", SyntheticFixtures.CreateSyntheticRcpZip(withTransform: false)); + dir.Write(Path.Combine("site Support", "scan1.rcs"), + SyntheticFixtures.CreateSyntheticRcsWithPoints(RcsPoints, (0, 0, 0), tx: 1.0, ty: 2.0, tz: 3.0)); + + using var doc = RcpProjectDocument.Open(rcp); + + var points = doc.ReadAllPoints().ToList(); + Assert.Equal(3, points.Count); + AssertNear(new PclVector3(1.1, 2.2, 3.3), points[0].Position); + } + + [Fact] + public void An_Rcp_With_A_Damaged_Transform_Is_Rejected() + { + using var dir = new TempDirectory(); + string manifest = SyntheticFixtures.RcpManifest("scan1.rcs", "Station 1") + .Replace("", ""); + + Assert.Throws(() => RcpProjectDocument.Open(dir.Write("site.rcp", SyntheticFixtures.CreateZip("project.xml", manifest)))); + } + + [Fact] + public void An_Rcp_Placement_Reorients_The_Normals_With_The_Points() + { + // A non-uniform scale stretches the geometry; the normals must be re-oriented with it, not left in the + // local space of the scan. + using var dir = new TempDirectory(); + string manifest = SyntheticFixtures.RcpManifest("scan1.rcs", "Station 1") + .Replace("", "") + .Replace("", ""); + string rcp = dir.Write("site.rcp", SyntheticFixtures.CreateZip("project.xml", manifest)); + var points = new[] { new RcsSamplePoint(1000, 0, 0, 0, 0, 0, 0, 89, 0, 89) }; + dir.Write(Path.Combine("site Support", "scan1.rcs"), + SyntheticFixtures.CreateSyntheticRcsWithPoints(points, (0, 0, 0), withNormals: true)); + + using var doc = RcpProjectDocument.Open(rcp); + var pt = Assert.Single(doc.ReadAllPoints()); + AssertNear(new PclVector3(0.2, 0, 0), pt.Position); + AssertNear(new PclVector3(2 / Math.Sqrt(5), 0, 1 / Math.Sqrt(5)), pt.Normal!.Value); + } + + [Fact] + public void An_Rcp_Node_That_States_Only_A_Rotation_Keeps_The_Transform_Of_The_Scan_File() + { + // A rotation is informational and places nothing; stating one alone must not suppress the placement that + // the scan file itself declares. + using var dir = new TempDirectory(); + string manifest = SyntheticFixtures.RcpManifest("scan1.rcs", "Station 1") + .Replace("", "") + .Replace("", "") + .Replace("", ""); + string rcp = dir.Write("site.rcp", SyntheticFixtures.CreateZip("project.xml", manifest)); + dir.Write(Path.Combine("site Support", "scan1.rcs"), + SyntheticFixtures.CreateSyntheticRcsWithPoints(RcsPoints, (0, 0, 0), tx: 1.0, ty: 2.0, tz: 3.0)); + + using var doc = RcpProjectDocument.Open(rcp); + var points = doc.ReadAllPoints().ToList(); + Assert.Equal(3, points.Count); + AssertNear(new PclVector3(1.1, 2.2, 3.3), points[0].Position); + } + // ---- E57 ------------------------------------------------------------------------------------------------- [Fact] diff --git a/tests/PclIO.Tests/SyntheticFixtures.cs b/tests/PclIO.Tests/SyntheticFixtures.cs index 62d25f7..619e101 100644 --- a/tests/PclIO.Tests/SyntheticFixtures.cs +++ b/tests/PclIO.Tests/SyntheticFixtures.cs @@ -116,10 +116,11 @@ private static void WriteRcsHeader(byte[] buffer, long pointCount, double tx, do // ---- ReCap project (.rcp) ------------------------------------------------------------------------------------- /// A project archive with one scan node whose file is named by . - public static byte[] CreateSyntheticRcpZip(string scanPath = "Scans/scan1.rcs", string scanName = "Station 1", string xmlPrologue = "") => - CreateZip("project.xml", RcpManifest(scanPath, scanName, xmlPrologue)); + public static byte[] CreateSyntheticRcpZip(string scanPath = "Scans/scan1.rcs", string scanName = "Station 1", string xmlPrologue = "", + bool withTransform = true) => + CreateZip("project.xml", RcpManifest(scanPath, scanName, xmlPrologue, withTransform)); - public static string RcpManifest(string scanPath, string scanName, string xmlPrologue = "") => $""" + public static string RcpManifest(string scanPath, string scanName, string xmlPrologue = "", bool withTransform = true) => $""" {xmlPrologue} @@ -127,9 +128,11 @@ public static string RcpManifest(string scanPath, string scanName, string xmlPro {SecurityElement.Escape(scanPath)} + {(withTransform ? """ + """ : "")} """;