From 9e2559b4d8d9ee6066c840808a633d8ddf0872e5 Mon Sep 17 00:00:00 2001 From: Seth Parker Date: Fri, 4 Sep 2026 16:07:42 -0400 Subject: [PATCH] docs(conductor): register PLY Binary IO and write_mesh options tracks PLY Binary IO (#25) covers binary write support and making read_ply honor the endianness declared in the file header. These land together: read_ply currently reinterprets raw bytes as native regardless of what the header says, so a writer that can emit binary must not be able to produce files the reader refuses or silently misreads. Sequenced before ply-multichart_20260624 (#19) -- both rewrite write_ply_header and write_ply_data, multichart is Pending at 0/15, and binary IO is the live need. write_mesh Options Struct (#26) is deferred from that work and not scoped: PLYFormat lands on write_ply only, because a PLY-only value is meaningless for half of write_mesh's inputs. Registered so the intention is discoverable. Co-Authored-By: Claude Opus 5 --- conductor/tracks.md | 2 + .../tracks/mesh-io-options_20260904/index.md | 30 ++++++++++++ .../mesh-io-options_20260904/metadata.json | 17 +++++++ .../tracks/ply-binary-io_20260904/index.md | 49 +++++++++++++++++++ .../ply-binary-io_20260904/metadata.json | 17 +++++++ 5 files changed, 115 insertions(+) create mode 100644 conductor/tracks/mesh-io-options_20260904/index.md create mode 100644 conductor/tracks/mesh-io-options_20260904/metadata.json create mode 100644 conductor/tracks/ply-binary-io_20260904/index.md create mode 100644 conductor/tracks/ply-binary-io_20260904/metadata.json diff --git a/conductor/tracks.md b/conductor/tracks.md index 456f9fe..d0a5e93 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -7,5 +7,7 @@ | [x] | mesh-io_20260323 | Mesh IO | 2026-03-23 | 2026-06-24 | | [ ] | ply-multichart_20260624 | Multi-Chart PLY Write Support | 2026-06-24 | 2026-06-24 | | [ ] | acvd_20260904 | ACVD Remeshing | 2026-09-04 | 2026-09-04 | +| [ ] | ply-binary-io_20260904 | PLY Binary IO | 2026-09-04 | 2026-09-04 | +| [ ] | mesh-io-options_20260904 | write_mesh Options Struct | 2026-09-04 | 2026-09-04 | diff --git a/conductor/tracks/mesh-io-options_20260904/index.md b/conductor/tracks/mesh-io-options_20260904/index.md new file mode 100644 index 0000000..4458a5e --- /dev/null +++ b/conductor/tracks/mesh-io-options_20260904/index.md @@ -0,0 +1,30 @@ +# Track: write_mesh Options Struct + +**ID:** mesh-io-options_20260904 +**Status:** Pending + +## Documents + +- Specification — not yet written +- Implementation Plan — not yet written + +## Summary + +Let callers control backend-specific writer behavior through `write_mesh` +without dropping to the format-specific entry points and losing extension +dispatch. + +Deferred from [ply-binary-io_20260904](../ply-binary-io_20260904/index.md), +where `PLYFormat` lands on `write_ply` only: a PLY-only value is meaningless for +half of `write_mesh`'s inputs, and there is no good answer to what +`write_mesh("out.obj", mesh, PLYFormat::Binary)` should do. + +Not scoped or scheduled — registered so the intention is discoverable rather +than living only in a design conversation. Open questions are listed on the +GitHub issue. + +## Quick Links + +- [Back to Tracks](../../tracks.md) +- [Product Context](../../product.md) +- GitHub issue: educelab/libcore#26 diff --git a/conductor/tracks/mesh-io-options_20260904/metadata.json b/conductor/tracks/mesh-io-options_20260904/metadata.json new file mode 100644 index 0000000..6dd9d05 --- /dev/null +++ b/conductor/tracks/mesh-io-options_20260904/metadata.json @@ -0,0 +1,17 @@ +{ + "id": "mesh-io-options_20260904", + "title": "write_mesh Options Struct", + "type": "feature", + "status": "pending", + "created": "2026-09-04T00:00:00+0200", + "updated": "2026-09-04T00:00:00+0200", + "issue": 26, + "phases": { + "total": 0, + "completed": 0 + }, + "tasks": { + "total": 0, + "completed": 0 + } +} diff --git a/conductor/tracks/ply-binary-io_20260904/index.md b/conductor/tracks/ply-binary-io_20260904/index.md new file mode 100644 index 0000000..6d82948 --- /dev/null +++ b/conductor/tracks/ply-binary-io_20260904/index.md @@ -0,0 +1,49 @@ +# Track: PLY Binary IO + +**ID:** ply-binary-io_20260904 +**Status:** Pending + +## Documents + +- Specification — not yet written +- Implementation Plan — not yet written + +## Summary + +Add binary PLY write support, and make `read_ply` honor the endianness declared +in the file header rather than reinterpreting raw bytes as native. These are one +contract and land together: a writer that can emit binary must not produce files +the reader refuses or silently misreads. + +Design decisions are recorded on the GitHub issue. In brief: + +- Public `educelab::PLYFormat { ASCII, Binary }` on all three `write_ply` tiers, + defaulting to `ASCII`. Kept separate from `detail::PLYHeader::Format`. +- `Binary` writes native-endian and labels the header accordingly; scalars are + always `float32` regardless of the mesh's `T`. +- The writer mirrors the reader's record batching — precomputed offsets, one + `write` per vertex. +- Read swaps bytes when file order differs from host order, at the two choke + points every binary scalar passes through. The swap applies to the raw + fixed-width value *before* the cast to the destination type. +- Faces exceeding the `uchar` list-count limits throw: 255 corners for + `vertex_indices`, 127 for `texcoord` (which writes `2*N`). + +Round-trip tests do not anchor this work. The sized-alias bug in #24 survived +because the suite only ever read what libcore wrote; a byte-order mistake shared +by reader and writer round-trips just as happily. The reader gets a hand-crafted +big-endian fixture, the writer a byte-level assertion against hand-derived bytes. + +## Sequencing + +Lands before [ply-multichart_20260624](../ply-multichart_20260624/index.md) +(#19) — both rewrite `write_ply_header` and `write_ply_data`, multichart is +Pending at 0/15, and this is the live need. + +Depends on #24 (sized PLY type aliases). + +## Quick Links + +- [Back to Tracks](../../tracks.md) +- [Product Context](../../product.md) +- GitHub issue: educelab/libcore#25 diff --git a/conductor/tracks/ply-binary-io_20260904/metadata.json b/conductor/tracks/ply-binary-io_20260904/metadata.json new file mode 100644 index 0000000..27c2306 --- /dev/null +++ b/conductor/tracks/ply-binary-io_20260904/metadata.json @@ -0,0 +1,17 @@ +{ + "id": "ply-binary-io_20260904", + "title": "PLY Binary IO", + "type": "feature", + "status": "pending", + "created": "2026-09-04T00:00:00+0200", + "updated": "2026-09-04T00:00:00+0200", + "issue": 25, + "phases": { + "total": 0, + "completed": 0 + }, + "tasks": { + "total": 0, + "completed": 0 + } +}