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 @@ -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

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/public-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 6 additions & 6 deletions src/PclIO/Formats/EdgeWise/EdgeWiseDocument.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

/// <inheritdoc/>
public override string Id { get; }

Expand Down Expand Up @@ -191,8 +189,9 @@ internal EdgeWiseScan(string id, string name, long pointCount, string filePath)

/// <summary>Streams points from the cluster file.</summary>
/// <remarks>
/// 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 <see cref="PclReadOptions.EdgeWiseCoordinateScale"/>,
/// whose default keeps the long-standing assumption of the reader (32768 units = 0.128 m). Only positions are returned.
/// </remarks>
/// <exception cref="InvalidDataException">The cluster file is truncated or malformed.</exception>
public override IEnumerable<PclPoint> ReadPoints(PclReadOptions? options = null)
Expand All @@ -201,6 +200,7 @@ public override IEnumerable<PclPoint> 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);
Expand Down Expand Up @@ -243,7 +243,7 @@ public override IEnumerable<PclPoint> 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)
Expand Down
20 changes: 20 additions & 0 deletions src/PclIO/PclReadOptions.cs
Original file line number Diff line number Diff line change
Expand Up @@ -80,4 +80,24 @@ public int SubsampleStep
/// that every stored point that passes the other rules of the reader is returned.
/// </summary>
public bool ExcludeFilteredPoints { get; init; }

private double _edgeWiseCoordinateScale = 0.128 / 32768.0;

/// <summary>
/// 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.
/// </summary>
/// <exception cref="ArgumentOutOfRangeException">The value is not finite or not above zero.</exception>
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;
}
}
}
14 changes: 14 additions & 0 deletions tests/PclIO.Tests/FormatTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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()
{
Expand Down
14 changes: 14 additions & 0 deletions tests/PclIO.Tests/OptionsAndPathTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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<ArgumentOutOfRangeException>(() => 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()
{
Expand Down
Loading