From 5940aa3242aedef9a3110a21694ea8b2529f8e5f Mon Sep 17 00:00:00 2001 From: mahach666 <79989386+mahach666@users.noreply.github.com> Date: Mon, 16 Nov 2026 03:41:30 +0000 Subject: [PATCH 1/2] Convert spherical coordinates of E57 scans to Cartesian points --- CHANGELOG.md | 2 + README.md | 2 +- src/PclIO/Formats/E57/E57Document.cs | 139 +++++++++++++++++++++++---- tests/PclIO.Tests/FormatTests.cs | 109 +++++++++++++++++++++ 4 files changed, 233 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index da32f4b..6b5ba2e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -42,6 +42,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 a fixed 1 MiB, so streams with copies further back decode within bounded memory. - Scaled-integer Cartesian coordinates of E57 scans are decoded (raw value times scale plus offset, with the binary width from the range of the field). +- Spherical coordinates of E57 scans are converted to Cartesian points as the standard defines; scaled integers work for + the spherical components too. ## [0.1.0] - 2026-11-15 diff --git a/README.md b/README.md index 18e43b0..b854cae 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ The library targets .NET 8 and .NET 10. It is managed code with no dependencies | Format | Extensions | Support level | | --- | --- | --- | -| ASTM E57 | `.e57` | Points decoded for a defined subset: uncompressed bit-packed streams with single or double precision Cartesian coordinates or scaled-integer coordinates (raw value times scale plus offset), 8-bit colour and 8-bit intensity. Pose translation and rotation are applied. 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. | +| ASTM E57 | `.e57` | Points decoded for a defined subset: uncompressed bit-packed streams with single or double precision Cartesian coordinates or scaled-integer coordinates (raw value times scale plus offset), or spherical range, azimuth and elevation converted to Cartesian points, with 8-bit colour and 8-bit intensity. Pose translation and rotation are applied. 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. 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. | diff --git a/src/PclIO/Formats/E57/E57Document.cs b/src/PclIO/Formats/E57/E57Document.cs index 9ba2d55..346377e 100644 --- a/src/PclIO/Formats/E57/E57Document.cs +++ b/src/PclIO/Formats/E57/E57Document.cs @@ -11,7 +11,8 @@ namespace PclIO.Formats.E57; /// Supported: the file header, the checksummed page layout, the XML section, scan names, ids, Cartesian bounds and /// poses (translation and rotation quaternion), and points stored as uncompressed bit-packed streams where /// Cartesian X/Y/Z are single or double precision floats or scaled integers (raw value times scale plus offset), -/// and colour or intensity are Integer fields in the range 0..255. +/// or spherical range, azimuth and elevation converted to Cartesian points, and colour or intensity are Integer +/// fields in the range 0..255. /// Not supported (reported with when points are read): integer coordinates, /// other codecs, and packets whose streams hold different record counts. /// Spherical coordinates, per-point invalid-state flags, images and 2D data are not interpreted. @@ -275,7 +276,7 @@ internal sealed class E57PointLayout public int StreamCount { get; } - /// Stream index of Cartesian X, Y and Z. + /// Stream index of Cartesian X, Y and Z, or all -1 when the scan stores spherical coordinates. public int[] Coordinate { get; } = [-1, -1, -1]; /// Bytes per record of the Cartesian streams: 4 or 8 for floats, 1, 2, 4 or 8 for scaled integers. @@ -293,6 +294,27 @@ internal sealed class E57PointLayout /// Offset of the scaled axes; 0 for float axes. public double[] CoordinateOffset { get; } = new double[3]; + /// True when the scan stores spherical coordinates (range, azimuth, elevation) instead of Cartesian ones. + public bool IsSpherical { get; private set; } + + /// Stream index of spherical range, azimuth and elevation, or all -1 for Cartesian scans. + public int[] Spherical { get; } = [-1, -1, -1]; + + /// Bytes per record of the spherical streams, sized as the Cartesian ones are. + public int[] SphericalSize { get; } = new int[3]; + + /// True for the spherical components stored as scaled integers. + public bool[] SphericalScaled { get; } = new bool[3]; + + /// True for the scaled spherical components whose range is not negative. + public bool[] SphericalUnsigned { get; } = new bool[3]; + + /// Scale of the scaled spherical components; 1 otherwise. + public double[] SphericalScale { get; } = [1, 1, 1]; + + /// Offset of the scaled spherical components; 0 otherwise. + public double[] SphericalOffset { get; } = new double[3]; + /// Stream index of red, green and blue, or all -1 when colour is not decoded. public int[] Color { get; } = [-1, -1, -1]; @@ -339,6 +361,14 @@ internal sealed class E57PointLayout _ => -1, }; + int spherical = field.Name.LocalName switch + { + "sphericalRange" => 0, + "sphericalAzimuth" => 1, + "sphericalElevation" => 2, + _ => -1, + }; + if (axis >= 0) { if (layout.Coordinate[axis] >= 0) @@ -369,6 +399,36 @@ internal sealed class E57PointLayout layout.CoordinateScale[axis] = scale; layout.CoordinateOffset[axis] = offset; } + else if (spherical >= 0) + { + if (layout.Spherical[spherical] >= 0) + { + unsupportedReason = "a spherical field is duplicated"; + return null; + } + + int size = FloatSize(field); + if (size != 0) + { + layout.Spherical[spherical] = i; + layout.SphericalSize[spherical] = size; + continue; + } + + int scaledSize = ScaledIntegerSize(field, out double scale, out double offset, out bool unsigned); + if (scaledSize == 0) + { + unsupportedReason = "a spherical field is neither a single or double precision float nor a scaled integer with a sized range"; + return null; + } + + layout.Spherical[spherical] = i; + layout.SphericalSize[spherical] = scaledSize; + layout.SphericalScaled[spherical] = true; + layout.SphericalUnsigned[spherical] = unsigned; + layout.SphericalScale[spherical] = scale; + layout.SphericalOffset[spherical] = offset; + } else if (IsByteRange(field)) { int channel = field.Name.LocalName switch @@ -383,12 +443,25 @@ internal sealed class E57PointLayout } } - if (layout.Coordinate.Any(c => c < 0)) + bool hasCartesian = layout.Coordinate.All(c => c >= 0); + bool hasSpherical = layout.Spherical.All(c => c >= 0); + if (hasCartesian && hasSpherical) + { + unsupportedReason = "the point prototype has both cartesian and spherical coordinates"; + return null; + } + + if (!hasCartesian && !hasSpherical) { - unsupportedReason = "the point prototype lacks cartesianX, cartesianY or cartesianZ"; + bool sawSpherical = layout.Spherical.Any(c => c >= 0); + unsupportedReason = sawSpherical + ? "the point prototype lacks sphericalRange, sphericalAzimuth or sphericalElevation" + : "the point prototype lacks cartesianX, cartesianY or cartesianZ"; return null; } + layout.IsSpherical = hasSpherical; + // Colour is all-or-nothing. if (layout.Color.Any(c => c < 0)) Array.Fill(layout.Color, -1); return layout; @@ -574,7 +647,9 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null) { if ((consumed + i) % step != 0) continue; - var coords = new PclVector3(ReadAxis(layout, pkt, starts, 0, i), ReadAxis(layout, pkt, starts, 1, i), ReadAxis(layout, pkt, starts, 2, i)); + var coords = layout.IsSpherical + ? ReadSpherical(layout, pkt, starts, i) + : new PclVector3(ReadAxis(layout, pkt, starts, 0, i), ReadAxis(layout, pkt, starts, 1, i), ReadAxis(layout, pkt, starts, 2, i)); PclColor? color = null; if (layout.HasColor) @@ -604,12 +679,25 @@ public override IEnumerable ReadPoints(PclReadOptions? options = null) private static int RecordsInPacket(E57PointLayout layout, int[] lengths) { int records = -1; - for (int axis = 0; axis < 3; axis++) + if (layout.IsSpherical) + { + for (int component = 0; component < 3; component++) + { + int size = layout.SphericalSize[component]; + int length = lengths[layout.Spherical[component]]; + if (length % size != 0) throw FormatError.Corrupted("E57 spherical stream holds a partial record."); + Agree(ref records, length / size); + } + } + else { - int size = layout.CoordinateSize[axis]; - int length = lengths[layout.Coordinate[axis]]; - if (length % size != 0) throw FormatError.Corrupted("E57 coordinate stream holds a partial record."); - Agree(ref records, length / size); + for (int axis = 0; axis < 3; axis++) + { + int size = layout.CoordinateSize[axis]; + int length = lengths[layout.Coordinate[axis]]; + if (length % size != 0) throw FormatError.Corrupted("E57 coordinate stream holds a partial record."); + Agree(ref records, length / size); + } } if (layout.HasColor) @@ -628,17 +716,32 @@ private static void Agree(ref int records, int count) records = count; } - private static double ReadAxis(E57PointLayout layout, byte[] packet, int[] starts, int axis, int index) - { - int stream = layout.Coordinate[axis]; - int size = layout.CoordinateSize[axis]; - if (!layout.CoordinateScaled[axis]) - return ReadCoordinate(packet, starts[stream], size, index); + private static double ReadAxis(E57PointLayout layout, byte[] packet, int[] starts, int axis, int index) => + ReadNumber(packet, starts[layout.Coordinate[axis]], layout.CoordinateSize[axis], index, + layout.CoordinateScaled[axis], layout.CoordinateUnsigned[axis], layout.CoordinateScale[axis], layout.CoordinateOffset[axis]); - return ReadScaledInteger(packet, starts[stream], size, index, - layout.CoordinateUnsigned[axis], layout.CoordinateScale[axis], layout.CoordinateOffset[axis]); + // Spherical coordinates as the E57 standard defines them: range in the file's unit, azimuth and elevation in radians. + private static PclVector3 ReadSpherical(E57PointLayout layout, byte[] packet, int[] starts, int index) + { + double range = ReadNumber(packet, starts[layout.Spherical[0]], layout.SphericalSize[0], index, + layout.SphericalScaled[0], layout.SphericalUnsigned[0], layout.SphericalScale[0], layout.SphericalOffset[0]); + double azimuth = ReadNumber(packet, starts[layout.Spherical[1]], layout.SphericalSize[1], index, + layout.SphericalScaled[1], layout.SphericalUnsigned[1], layout.SphericalScale[1], layout.SphericalOffset[1]); + double elevation = ReadNumber(packet, starts[layout.Spherical[2]], layout.SphericalSize[2], index, + layout.SphericalScaled[2], layout.SphericalUnsigned[2], layout.SphericalScale[2], layout.SphericalOffset[2]); + + double cosElevation = Math.Cos(elevation); + return new PclVector3( + range * cosElevation * Math.Sin(azimuth), + range * cosElevation * Math.Cos(azimuth), + range * Math.Sin(elevation)); } + private static double ReadNumber(byte[] packet, int start, int size, int index, bool scaled, bool unsigned, double scale, double offset) => + scaled + ? ReadScaledInteger(packet, start, size, index, unsigned, scale, offset) + : ReadCoordinate(packet, start, size, index); + private static double ReadCoordinate(byte[] packet, int start, int size, int index) => size == 4 ? Bytes.ReadSingleLE(packet.AsSpan(start + index * 4, 4)) diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs index 58118fc..cd526f2 100644 --- a/tests/PclIO.Tests/FormatTests.cs +++ b/tests/PclIO.Tests/FormatTests.cs @@ -593,6 +593,115 @@ public void E57_With_A_Partial_Scaled_Integer_Record_Is_Rejected() Assert.Throws(() => doc.Scans[0].ReadPoints().ToList()); } + [Fact] + public void E57_With_Spherical_Coordinates_Is_Decoded() + { + const string prototype = """ + + + + + + """; + byte[] rs = [.. BitConverter.GetBytes(2.0f), .. BitConverter.GetBytes(1.0f), .. BitConverter.GetBytes(2.0f)]; + byte[] azs = [.. BitConverter.GetBytes(0.0), .. BitConverter.GetBytes(Math.PI / 2), .. BitConverter.GetBytes(Math.PI)]; + byte[] els = [.. BitConverter.GetBytes(0.0), .. BitConverter.GetBytes(0.0), .. BitConverter.GetBytes(Math.PI / 6)]; + var spec = new E57Spec { PrototypeXml = prototype, Points = [], RecordCount = 3, RawPackets = E57Spec.DataPacket([rs, azs, els]) }; + using var dir = new TempDirectory(); + using var doc = E57Document.Open(dir.Write("spherical.e57", spec.Build())); + + var scan = Assert.Single(doc.Scans); + Assert.False(scan.HasColors); + Assert.False(scan.HasIntensities); + + var plain = scan.ReadPoints(NoTransform).ToList(); + Assert.Equal(3, plain.Count); + AssertNear(new PclVector3(0, 2, 0), plain[0].Position); + AssertNear(new PclVector3(1, 0, 0), plain[1].Position); + AssertNear(new PclVector3(0, -Math.Sqrt(3), 1), plain[2].Position); + + // The pose of the scan moves the converted points as it moves Cartesian ones. + var moved = scan.ReadPoints().ToList(); + AssertNear(new PclVector3(1.5, 4.5, 3.5), moved[0].Position); + } + + [Fact] + public void E57_With_Spherical_Coordinates_As_Scaled_Integers_Is_Decoded() + { + const string prototype = """ + + + + + + """; + byte[] rs = [.. BitConverter.GetBytes((ushort)2000)]; + byte[] azs = [.. BitConverter.GetBytes(0.0f)]; + byte[] els = [.. BitConverter.GetBytes((short)0)]; + var spec = new E57Spec { PrototypeXml = prototype, Points = [], RecordCount = 1, RawPackets = E57Spec.DataPacket([rs, azs, els]) }; + using var dir = new TempDirectory(); + using var doc = E57Document.Open(dir.Write("scaled-spherical.e57", spec.Build())); + + var point = Assert.Single(doc.Scans[0].ReadPoints(NoTransform)); + AssertNear(new PclVector3(0, 2, 0), point.Position); + } + + [Fact] + public void E57_With_A_Partial_Spherical_Triple_Lists_But_Is_Not_Decoded() + { + const string prototype = """ + + + + + """; + using var dir = new TempDirectory(); + using var doc = E57Document.Open(dir.Write("spherical.e57", new E57Spec { PrototypeXml = prototype }.Build())); + + Assert.Single(doc.Scans); + Assert.Throws(() => doc.Scans[0].ReadPoints().ToList()); + } + + [Fact] + public void E57_With_Both_Cartesian_And_Spherical_Coordinates_Lists_But_Is_Not_Decoded() + { + const string prototype = """ + + + + + + + + + """; + using var dir = new TempDirectory(); + using var doc = E57Document.Open(dir.Write("both.e57", new E57Spec { PrototypeXml = prototype }.Build())); + + Assert.Single(doc.Scans); + Assert.Throws(() => doc.Scans[0].ReadPoints().ToList()); + } + + [Fact] + public void E57_With_A_Partial_Spherical_Record_Is_Rejected() + { + const string prototype = """ + + + + + + """; + byte[] rs = [.. BitConverter.GetBytes(2.0f), .. BitConverter.GetBytes(1.0f)]; + byte[] azs = [.. BitConverter.GetBytes(0.0f), 0x00, 0x00]; + byte[] els = [.. BitConverter.GetBytes(0.0f), .. BitConverter.GetBytes(0.0f)]; + var spec = new E57Spec { PrototypeXml = prototype, Points = [], RecordCount = 2, RawPackets = E57Spec.DataPacket([rs, azs, els]) }; + using var dir = new TempDirectory(); + using var doc = E57Document.Open(dir.Write("partial.e57", spec.Build())); + + Assert.Throws(() => doc.Scans[0].ReadPoints().ToList()); + } + // ---- Leica ----------------------------------------------------------------------------------------------- [Fact] From ee38a26836960a466e24c6028660419936d224d8 Mon Sep 17 00:00:00 2001 From: mahach666 <79989386+mahach666@users.noreply.github.com> Date: Tue, 17 Nov 2026 13:20:33 +0000 Subject: [PATCH 2/2] Convert E57 spherical coordinates with the azimuth measured from the positive X axis --- src/PclIO/Formats/E57/E57Document.cs | 6 ++++-- tests/PclIO.Tests/FormatTests.cs | 11 ++++++----- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/src/PclIO/Formats/E57/E57Document.cs b/src/PclIO/Formats/E57/E57Document.cs index 346377e..452191d 100644 --- a/src/PclIO/Formats/E57/E57Document.cs +++ b/src/PclIO/Formats/E57/E57Document.cs @@ -720,7 +720,9 @@ private static double ReadAxis(E57PointLayout layout, byte[] packet, int[] start ReadNumber(packet, starts[layout.Coordinate[axis]], layout.CoordinateSize[axis], index, layout.CoordinateScaled[axis], layout.CoordinateUnsigned[axis], layout.CoordinateScale[axis], layout.CoordinateOffset[axis]); - // Spherical coordinates as the E57 standard defines them: range in the file's unit, azimuth and elevation in radians. + // Spherical coordinates as the E57 standard defines them: range in the file's unit, azimuth and elevation in + // radians. The azimuth is the counterclockwise rotation of the positive X axis about the positive Z axis, and + // the elevation is measured up from the XY plane, so x = r cos(el) cos(az), y = r cos(el) sin(az), z = r sin(el). private static PclVector3 ReadSpherical(E57PointLayout layout, byte[] packet, int[] starts, int index) { double range = ReadNumber(packet, starts[layout.Spherical[0]], layout.SphericalSize[0], index, @@ -732,8 +734,8 @@ private static PclVector3 ReadSpherical(E57PointLayout layout, byte[] packet, in double cosElevation = Math.Cos(elevation); return new PclVector3( - range * cosElevation * Math.Sin(azimuth), range * cosElevation * Math.Cos(azimuth), + range * cosElevation * Math.Sin(azimuth), range * Math.Sin(elevation)); } diff --git a/tests/PclIO.Tests/FormatTests.cs b/tests/PclIO.Tests/FormatTests.cs index cd526f2..ba228cd 100644 --- a/tests/PclIO.Tests/FormatTests.cs +++ b/tests/PclIO.Tests/FormatTests.cs @@ -616,13 +616,14 @@ public void E57_With_Spherical_Coordinates_Is_Decoded() var plain = scan.ReadPoints(NoTransform).ToList(); Assert.Equal(3, plain.Count); - AssertNear(new PclVector3(0, 2, 0), plain[0].Position); - AssertNear(new PclVector3(1, 0, 0), plain[1].Position); - AssertNear(new PclVector3(0, -Math.Sqrt(3), 1), plain[2].Position); + // Azimuth is measured from the positive X axis: az=0 lies on +X, az=pi/2 on +Y. + AssertNear(new PclVector3(2, 0, 0), plain[0].Position); + AssertNear(new PclVector3(0, 1, 0), plain[1].Position); + AssertNear(new PclVector3(-Math.Sqrt(3), 0, 1), plain[2].Position); // The pose of the scan moves the converted points as it moves Cartesian ones. var moved = scan.ReadPoints().ToList(); - AssertNear(new PclVector3(1.5, 4.5, 3.5), moved[0].Position); + AssertNear(new PclVector3(3.5, 2.5, 3.5), moved[0].Position); } [Fact] @@ -643,7 +644,7 @@ public void E57_With_Spherical_Coordinates_As_Scaled_Integers_Is_Decoded() using var doc = E57Document.Open(dir.Write("scaled-spherical.e57", spec.Build())); var point = Assert.Single(doc.Scans[0].ReadPoints(NoTransform)); - AssertNear(new PclVector3(0, 2, 0), point.Position); + AssertNear(new PclVector3(2, 0, 0), point.Position); } [Fact]