Skip to content

3D preview of E57 point clouds (#373) - #453

Merged
Sebagrei merged 4 commits into
mainfrom
feature/373-e57-point-cloud-preview
Nov 22, 2026
Merged

Sebagrei merged 4 commits into
mainfrom
feature/373-e57-point-cloud-preview

Conversation

@Sebagrei

Copy link
Copy Markdown
Collaborator

E57 point clouds (.e57, ASTM E2807) now get a 3D preview. The parser was written for this project, and it runs in the isolated preview child.

Closes #373

What changed

  • Research page first (docs/src/research/e57-preview.md, own commit): the ASTM E2807 sections the preview uses (header, 1 KiB pages with CRC-32C, the XML tree, compressed-vector packets, the bit-pack codec, pose, colour and intensity limits, invalid states) and the libE57 format notes. It also explains why we wrote our own bounded reader and did not use the e57 crate. No new dependency.
  • src/mesh/e57.rs:
    • every page checksum is checked before anything is parsed. A mismatch refuses the file and names the page. Big-endian (what libE57 writes) and little-endian checksums are both accepted;
    • XML limits: at most 64 MiB, 1 000 000 elements and depth 64;
    • every data3D scan is read, in cartesian or spherical coordinates, as floats or scaled integers;
    • each scan is moved by its pose (quaternion and translation), and metres are converted to mm;
    • colours are scaled by colorLimits. A scan without colours keeps its intensity as a colour-mapped field;
    • invalid points, images2D and unknown fields are left out;
    • the cloud is thinned evenly over all scans (stride_within, which shares its budget with stride_for).
  • Dispatch: "e57" was added in mesh::read, plus PreviewFormat::E57 (a point cloud). Because of that, cadformat now reports a preview for e57.
  • "Thinned" note:
    • Mesh::thinned holds the number of points in the file;
    • in TCMESH01 it is flag 8: a u64 placed between the field section and the face count, so older viewers are not affected;
    • the shared viewer shows thinned for the preview from N points;
    • LAS, PTS/XYZ and point-only OFF (thin_out) set it too.
    • Fix included: a PTS file whose point count was underestimated used to end with one point over the budget, and failed with point cloud not thinned out.
  • Desktop: E57 was added to the point-cloud lists (no Export STL, no similar-parts link).
  • Fuzzing:
    • new target fuzz/fuzz_targets/e57.rs, also added to the fuzz.yml matrix and to fuzz_harness::TARGETS;
    • the harness also feeds the input with its page checksums recomputed, so the fuzzer gets past the CRC check;
    • seed fuzz/seeds/e57/three-points.e57, generated by a small writer script;
    • tests/parser_corpus.rs entry. MESH_FORMATS now includes e57.
  • Docs:
    • CHANGELOG (Unreleased), README Features;
    • reference/formats.md (new section E57 in the 3D preview), guide/files.md, guide/desktop.md, desktop/README.md;
    • dev/fuzzing.md, dev/threat-model.md, reference/architecture.md;
    • OPEN_WORK (3D preview of E57 point clouds (scanner exports) #373 ticked, E57 dropped from the "not previewed" list), and the CLAUDE.md architecture map.

How it was tested

Not compiled or tested locally. Builds are not allowed on this machine, so CI is the check. Only cargo fmt --all was run.

Tests added (synthetic files from a minimal E57 writer in the test module):

  • multi-scan files with poses, aligned;
  • spherical and scaled-integer coordinates (with an offset);
  • colours, with and without colorLimits;
  • intensity only;
  • invalid points, unknown fields and images;
  • even thinning across scans, with the note surviving encode/decode;
  • a flipped byte, refused with the page named;
  • little-endian checksums accepted;
  • damaged structure: a cut-off file, wrong version or page size, fewer points than claimed, no coordinates, no scans, a Blob field;
  • the bit stream across packets;
  • the CRC-32C check value;
  • TCMESH01 flag 8 combined with fields and face counts;
  • stride_within;
  • the PreviewFormat and cadformat mappings.

Not covered:

  • No openly licensed real E57 scan was found for tests/fixtures. The libE57 samples do not have a clear redistribution licence. This is listed as open in OPEN_WORK.
  • The viewer JS change could not be checked with node --check (no Node.js on this machine).

Checklist

  • This is my own work (or my AI agent's, written from its own
    knowledge), or openly licensed material under a compatible licence
    that is credited. It contains no code decompiled, disassembled or
    rewritten from proprietary software
    and no leaked code
    (CONTRIBUTING.md).
  • Reading a file format: the research page in docs/src/research/ names
    the sample files and specifications each finding came from.
  • The documentation is updated in this pull request (CHANGELOG.md,
    README.md, docs/src/**, docs/OPEN_WORK.md where it applies).
  • cargo fmt --all --check, cargo clippy --all-targets -- -D warnings
    and cargo test pass locally, or CI runs them. (Only fmt was run locally. CI runs clippy and the tests.)

🤖 Generated with Claude Code

fork and others added 3 commits November 22, 2026 20:20
Format sections of ASTM E2807 and the libE57 notes the preview needs,
and why an own bounded reader instead of the e57 crate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Own bounded reader src/mesh/e57.rs in the isolated preview process: the
CRC-32C of every 1 KiB page is checked first (a damaged file is refused
with the page named), the XML section is parsed with size, element and
depth limits, every data3D scan is read (cartesian or spherical, float or
scaled integer), moved by its pose and converted from metres to mm;
colours scaled by colorLimits, otherwise the intensity as a colour-mapped
field; invalid points, images and unknown fields are left out. Points are
thinned evenly over all scans with the same budget as LAS and PTS.

Thinned point clouds now carry the point count of the file (TCMESH01 flag
8, between the fields and the face count) and the viewer says so; LAS,
PTS/XYZ and point-only OFF set it too. PTS files whose point count was
underestimated no longer fail with "not thinned out".

PreviewFormat::E57, fuzz target e57 (re-seals the page checksums so the
fuzzer reaches the parser) with a seed, corpus entry, docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- PTS/XYZ: thin evenly over the whole file when the row estimate was too
  low (drop every second kept point and double the stride at the budget),
  with a test
- unit test that reads the committed fuzz seed (3 points, 0.1 m pose)
- research page: source of every format finding (ASTM text not available)
- formats.md, configuration.md: E57 shares the mesh size cap; raise it and
  the preview memory limit for real scans

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Sebagrei
Sebagrei marked this pull request as ready for review November 22, 2026 20:51
…-cloud-preview

# Conflicts:
#	CHANGELOG.md
#	desktop/README.md
#	docs/src/SUMMARY.md
#	docs/src/dev/threat-model.md
#	docs/src/research/index.md
@Sebagrei
Sebagrei merged commit 1e4e8d9 into main Nov 22, 2026
3 of 8 checks passed
@Sebagrei
Sebagrei deleted the feature/373-e57-point-cloud-preview branch November 22, 2026 20:58
Sebagrei added a commit that referenced this pull request Nov 22, 2026
)

Resolving the conflicts of #440–#453 left duplicate *Changed*/*Fixed*
sections under [Unreleased] in CHANGELOG.md, a half-merged #408
paragraph in docs/OPEN_WORK.md (now one paragraph: done #415, #416,
#418, #419, #420, #407, #422, #423; left #424 and the named follow-ups)
and two *Revisions* rows in docs/src/reference/api.md. Text only,
nothing dropped (checked: same non-heading lines before and after in
CHANGELOG).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: fork <fork@foo.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3D preview of E57 point clouds (scanner exports)

1 participant