diff --git a/CHANGELOG.md b/CHANGELOG.md index 09352bb..b248d17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -49,6 +49,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 integer are decoded; other shapes stay unread. - The E57 reader decodes plain bit-packing only and names any other codec of the scan in the rejection message. The point prototype limit is the packet header bound of 65535 fields. +- The EdgeWise cluster position scale is now `PclReadOptions.EdgeWiseCoordinateScale`, so the caller states it; the + default keeps the long-standing assumption (32768 units = 0.128 m). ## [0.1.0] - 2026-11-15 diff --git a/README.md b/README.md index 116d0b8..78c9e66 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ The library targets .NET 8 and .NET 10. It is managed code with no dependencies | 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, 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. 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. | +| 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`. | ### Format detection @@ -198,7 +198,7 @@ See the [public API](docs/public-api.md) for the supported surface and [dependen ## Limitations - Version 0.1.0 is a preview. The API can change before 1.0. -- Only the subsets listed under Supported formats are read. Anything else fails with exit code 3 (`InvalidDataException` or `NotSupportedException` in the library) instead of being guessed, apart from the assumptions named under Supported formats (the FARO folder record layout, the EdgeWise position scale and the ReCap scan channel flags). +- Only the subsets listed under Supported formats are read. Anything else fails with exit code 3 (`InvalidDataException` or `NotSupportedException` in the library) instead of being guessed, apart from the assumptions named under Supported formats (the FARO folder record layout and the EdgeWise position scale unless the caller states it with `PclReadOptions.EdgeWiseCoordinateScale`). - 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. diff --git a/docs/public-api.md b/docs/public-api.md index b885904..a1676a8 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), `MaxCoordinateMagnitude` (default 5000, null for no limit; NaN and infinite coordinates are never returned; currently only PinPoint applies 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 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), `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. | `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/EdgeWise/EdgeWiseDocument.cs b/src/PclIO/Formats/EdgeWise/EdgeWiseDocument.cs index bafb083..f555280 100644 --- a/src/PclIO/Formats/EdgeWise/EdgeWiseDocument.cs +++ b/src/PclIO/Formats/EdgeWise/EdgeWiseDocument.cs @@ -153,13 +153,11 @@ public static EdgeWiseDocument Open(string path, PclReadOptions? options = null) public sealed class EdgeWiseScan : PclScan { // Cluster file: a cluster count, then per cluster a centre, a point count and its points. + // A point record holds three 16-bit offsets from the centre; wider records are not decoded. private const int ClusterHeaderSize = 16; private const int PointSize = 6; private const int ChunkPoints = 8192; - // Reader assumption: the file does not declare this scale (32768 units = 0.128 m); positions are only as exact as it. - private const double CoordScale = 0.128 / 32768.0; - /// public override string Id { get; } @@ -191,8 +189,9 @@ internal EdgeWiseScan(string id, string name, long pointCount, string filePath) /// Streams points from the cluster file. /// - /// The binary layout has no signature or version, so it is checked only for size consistency, and the fixed-point - /// scale of the point offsets is an assumption of this reader. Only positions are returned. + /// The binary layout has no signature or version, so it is checked only for size consistency. A point record holds + /// three 16-bit offsets from the cluster centre; the scale comes from , + /// whose default keeps the long-standing assumption of the reader (32768 units = 0.128 m). Only positions are returned. /// /// The cluster file is truncated or malformed. public override IEnumerable ReadPoints(PclReadOptions? options = null) @@ -201,6 +200,7 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null) long targetCount = options.MaxPoints ?? PointCount; int step = Math.Max(1, options.SubsampleStep); + double scale = options.EdgeWiseCoordinateScale; long yielded = 0; using var fs = File.OpenRead(FilePath); @@ -243,7 +243,7 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null) short dz = Bytes.ReadInt16LE(pointBuffer.AsSpan(off + 4, 2)); var pt = new PclPoint( - new PclVector3(cx + (dx * CoordScale), cy + (dy * CoordScale), cz + (dz * CoordScale)), + new PclVector3(cx + (dx * scale), cy + (dy * scale), cz + (dz * scale)), Index: (ulong)yielded); if (options.ApplyTransform) diff --git a/src/PclIO/PclReadOptions.cs b/src/PclIO/PclReadOptions.cs index 786546e..d478341 100644 --- a/src/PclIO/PclReadOptions.cs +++ b/src/PclIO/PclReadOptions.cs @@ -80,4 +80,24 @@ public int SubsampleStep /// that every stored point that passes the other rules of the reader is returned. /// public bool ExcludeFilteredPoints { get; init; } + + private double _edgeWiseCoordinateScale = 0.128 / 32768.0; + + /// + /// Fixed-point scale of the 16-bit point offsets in EdgeWise cluster files, in metres per unit: a stored offset + /// counts this many metres from the cluster centre. The files do not declare the scale, so the default of + /// 0.128 / 32768 keeps the long-standing assumption of the reader; set it explicitly when the files use another + /// scale. Other readers ignore this option. Must be finite and above zero. + /// + /// The value is not finite or not above zero. + public double EdgeWiseCoordinateScale + { + get => _edgeWiseCoordinateScale; + init + { + if (!double.IsFinite(value) || value <= 0) + throw new ArgumentOutOfRangeException(nameof(value), "The EdgeWise coordinate scale must be finite and above zero."); + _edgeWiseCoordinateScale = value; + } + } } diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs index 9377101..6182e88 100644 --- a/tests/PclIO.Tests/FormatTests.cs +++ b/tests/PclIO.Tests/FormatTests.cs @@ -1678,6 +1678,20 @@ public void Read_Synthetic_EdgeWise_Cluster_File() Assert.Equal(2, scan.ReadPoints(new PclReadOptions { MaxPoints = 2 }).Count()); } + [Fact] + public void An_EdgeWise_Scan_Reads_With_The_Stated_Coordinate_Scale() + { + using var dir = new TempDirectory(); + using var doc = EdgeWiseDocument.Open(dir.Write("cluster.c3ptx", SyntheticFixtures.CreateSyntheticC3ptx(Clusters))); + + var scan = Assert.Single(doc.Scans); + var points = scan.ReadPoints(new PclReadOptions { EdgeWiseCoordinateScale = 0.001 }).ToList(); + + Assert.Equal(3, points.Count); + AssertNear(new PclVector3(1, 2, 3), points[0].Position); + AssertNear(new PclVector3(2, 1, 3 + (32767 * 0.001)), points[1].Position); + } + [Fact] public void Read_Synthetic_EdgeWise_Database_And_Skip_Missing_Cluster_Files() { diff --git a/tests/PclIO.Tests/OptionsAndPathTests.cs b/tests/PclIO.Tests/OptionsAndPathTests.cs index 2e0d365..4f896b0 100644 --- a/tests/PclIO.Tests/OptionsAndPathTests.cs +++ b/tests/PclIO.Tests/OptionsAndPathTests.cs @@ -14,6 +14,7 @@ public void Default_Options_Read_Everything_And_Apply_The_Transform() Assert.Null(options.MaxPoints); Assert.Equal(5000.0, options.MaxCoordinateMagnitude); + Assert.Equal(0.128 / 32768.0, options.EdgeWiseCoordinateScale); Assert.Equal(1, options.SubsampleStep); Assert.True(options.ApplyTransform); Assert.False(options.Strict); @@ -65,6 +66,19 @@ public void A_Magnitude_Limit_Of_Zero_Or_More_Is_Accepted() Assert.Equal(1e9, new PclReadOptions { MaxCoordinateMagnitude = 1e9 }.MaxCoordinateMagnitude); } + [Theory] + [InlineData(0.0)] + [InlineData(-1.0)] + [InlineData(double.NaN)] + [InlineData(double.PositiveInfinity)] + [InlineData(double.NegativeInfinity)] + public void A_Non_Positive_Or_Non_Finite_EdgeWise_Scale_Is_Rejected(double value) => + Assert.Throws(() => new PclReadOptions { EdgeWiseCoordinateScale = value }); + + [Fact] + public void A_Positive_Finite_EdgeWise_Scale_Is_Accepted() => + Assert.Equal(0.001, new PclReadOptions { EdgeWiseCoordinateScale = 0.001 }.EdgeWiseCoordinateScale); + [Fact] public void A_Limit_Applies_To_The_Total_Across_All_Scans() {