PR 1 — :format: glTF/GLB reader for the reference layer #1

Open
opened 2026-11-03 18:27:08 +11:00 by litruv · 2 comments
Owner

First PR of the reference-layer stack designed in https://git.ruv.wtf/litruv/umamo-reference-layer (see that repo issue #1 and docs/pr-stack.md).

Scope
Read-only. GLB container rules, buffer views, accessors, scene graph, skins. No rendering, no UI, no persistence.

Why first
The container rules are the part most likely to be wrong, and they are testable without a GPU or an asset. Alignment rejection, chunk padding, truncation, and the more-than-one-chunk case are all pure.

Rules enforced

  1. Chunk data is padded to a 4-byte boundary, and the padding is part of the chunk length, so the JSON text must be trimmed before parsing.
  2. The declared total length must equal the actual length. A truncated chunk is an error, not a short read.
  3. An unknown chunk type is skipped, not rejected; more than one chunk of a known type is not.
  4. An accessor byteOffset must be a multiple of the component size. A reader that ignores this returns a plausible wrong number rather than an error.
  5. A read must stay inside the buffer view byteLength. Reading past it is an error, not a zero fill.
  6. Component type 5124 (INT) is part of glTF 2.0 and must be handled; the design sketch omitted it.

Reuse
The JSON depth guard UMA_MAXIMUM_JSON_DEPTH from uma/UmaManifest.kt is applied to the glTF JSON chunk, because the parser and every walk over the tree recurse.

Tests
GlbContainerTest, GltfAccessorTest, GltfJsonDepthTest. Corpus gate under test/corpus/gltf/, self-skipping when empty, like every other corpus test.

Open question
FileRole has no category for a reference layer: it has Document, Artwork, and Sidecar. Registering glTF in FormatRegistry puts it in a picker filter built from role. This needs a decision before the codec is registered.

First PR of the reference-layer stack designed in https://git.ruv.wtf/litruv/umamo-reference-layer (see that repo issue #1 and docs/pr-stack.md). **Scope** Read-only. GLB container rules, buffer views, accessors, scene graph, skins. No rendering, no UI, no persistence. **Why first** The container rules are the part most likely to be wrong, and they are testable without a GPU or an asset. Alignment rejection, chunk padding, truncation, and the more-than-one-chunk case are all pure. **Rules enforced** 1. Chunk data is padded to a 4-byte boundary, and the padding is part of the chunk length, so the JSON text must be trimmed before parsing. 2. The declared total length must equal the actual length. A truncated chunk is an error, not a short read. 3. An unknown chunk type is skipped, not rejected; more than one chunk of a known type is not. 4. An accessor byteOffset must be a multiple of the component size. A reader that ignores this returns a plausible wrong number rather than an error. 5. A read must stay inside the buffer view byteLength. Reading past it is an error, not a zero fill. 6. Component type 5124 (INT) is part of glTF 2.0 and must be handled; the design sketch omitted it. **Reuse** The JSON depth guard UMA_MAXIMUM_JSON_DEPTH from uma/UmaManifest.kt is applied to the glTF JSON chunk, because the parser and every walk over the tree recurse. **Tests** GlbContainerTest, GltfAccessorTest, GltfJsonDepthTest. Corpus gate under test/corpus/gltf/, self-skipping when empty, like every other corpus test. **Open question** FileRole has no category for a reference layer: it has Document, Artwork, and Sidecar. Registering glTF in FormatRegistry puts it in a picker filter built from role. This needs a decision before the codec is registered.
Author
Owner

What PR 1 landed

Implementation is in module/format/src/commonMain/kotlin/org/umamo/format/gltf/ on branch issue-1-gltf-glb-reader. :format:jvmTest is green (58 glTF tests) and :format:compileKotlinIosArm64 compiles the common code.

Files: GlbReader.kt (container rules), GltfJson.kt (JSON shapes plus the depth guard), GltfEnums.kt, GltfAccessor.kt (readComponents, readFloats, readIndices, readMatrixElements), GltfFile.kt, GltfValidation.kt (firstGltfProblem), Gltf.kt (the ReadOnlyCodec).

Decisions taken while implementing

FileRole.Reference was added. FileKind had no category for a file that is read into the editor as a drawing aid. Document replaces what is open, Artwork adds layers to it, Sidecar is found beside a document. A reference model is none of those, and the picker filters are built from FileRole, so the role decides whether a .glb appears in Import Artwork. It must not. FileKind.Gltf (extension glb, alias gltf, readable, not writable) carries the new role, and the codec is registered in FormatRegistry after the model codecs.

Component type 5124 (INT) was missing from the sketch. The sketch listed six component types; glTF 2.0 §3.2.4 defines seven. It is now present, and a test reads one component of each type. It is still refused as an index accessor, because §3.2.4 restricts indices to unsigned types.

The pitch clamp is real, not caution. At pitch = ±90° the screen-right basis vector becomes a zero vector, so a camera that allows it cannot compute a right axis. verify/verify.py shows both cases: pitch 90 gives 0, pitch 89.9 gives 0.001745. The clamp is the open interval ±89.9°.

Unknown codes are reported, not thrown. Each enum refuses what it does not know (fromCode throws), but firstGltfProblem has to report the first problem in the document rather than blow up on the first bad code it happens to touch. Each enum therefore also has knowsCode, and the validator uses that. A caller that has already validated the file uses fromCode.

Sparse accessors are refused, not zero-filled. A zero-filled vertex collapses part of the mesh without saying anything.

normalized is not applied. A reference layer needs raw positions and weights, and normalizing a position would scale it by 65535. readComponents returns raw values and the test pins that.

Tests

GlbContainerTest (14), GltfAccessorTest (12), GltfValidationTest (15), GltfJsonDepthTest (3), GltfSceneGraphTest (6), GltfCodecTest (7), GltfCorpusTest (1, self-skipping).

The corpus gate is sampleWithCorpusDefault("gltf.samples", "gltf") in module/format/build.gradle.kts. It is a module-specific default rather than an entry in the shared table, because no other module reads glTF yet and a table entry would switch its gate on as a side effect.

The numbers these tests pin are the same ones verify/verify.py proves in litruv/umamo-reference-layer (30 checks, all pass).

## What PR 1 landed Implementation is in `module/format/src/commonMain/kotlin/org/umamo/format/gltf/` on branch `issue-1-gltf-glb-reader`. `:format:jvmTest` is green (58 glTF tests) and `:format:compileKotlinIosArm64` compiles the common code. Files: `GlbReader.kt` (container rules), `GltfJson.kt` (JSON shapes plus the depth guard), `GltfEnums.kt`, `GltfAccessor.kt` (`readComponents`, `readFloats`, `readIndices`, `readMatrixElements`), `GltfFile.kt`, `GltfValidation.kt` (`firstGltfProblem`), `Gltf.kt` (the `ReadOnlyCodec`). ## Decisions taken while implementing **`FileRole.Reference` was added.** `FileKind` had no category for a file that is read into the editor as a drawing aid. `Document` replaces what is open, `Artwork` adds layers to it, `Sidecar` is found beside a document. A reference model is none of those, and the picker filters are built from `FileRole`, so the role decides whether a `.glb` appears in Import Artwork. It must not. `FileKind.Gltf` (extension `glb`, alias `gltf`, readable, not writable) carries the new role, and the codec is registered in `FormatRegistry` after the model codecs. **Component type 5124 (INT) was missing from the sketch.** The sketch listed six component types; glTF 2.0 §3.2.4 defines seven. It is now present, and a test reads one component of each type. It is still refused as an index accessor, because §3.2.4 restricts indices to unsigned types. **The pitch clamp is real, not caution.** At pitch = ±90° the screen-right basis vector becomes a zero vector, so a camera that allows it cannot compute a right axis. `verify/verify.py` shows both cases: pitch 90 gives 0, pitch 89.9 gives 0.001745. The clamp is the open interval ±89.9°. **Unknown codes are reported, not thrown.** Each enum refuses what it does not know (`fromCode` throws), but `firstGltfProblem` has to report the first problem in the document rather than blow up on the first bad code it happens to touch. Each enum therefore also has `knowsCode`, and the validator uses that. A caller that has already validated the file uses `fromCode`. **Sparse accessors are refused, not zero-filled.** A zero-filled vertex collapses part of the mesh without saying anything. **`normalized` is not applied.** A reference layer needs raw positions and weights, and normalizing a position would scale it by 65535. `readComponents` returns raw values and the test pins that. ## Tests `GlbContainerTest` (14), `GltfAccessorTest` (12), `GltfValidationTest` (15), `GltfJsonDepthTest` (3), `GltfSceneGraphTest` (6), `GltfCodecTest` (7), `GltfCorpusTest` (1, self-skipping). The corpus gate is `sampleWithCorpusDefault("gltf.samples", "gltf")` in `module/format/build.gradle.kts`. It is a module-specific default rather than an entry in the shared table, because no other module reads glTF yet and a table entry would switch its gate on as a side effect. The numbers these tests pin are the same ones `verify/verify.py` proves in `litruv/umamo-reference-layer` (30 checks, all pass).
Author
Owner

Correction to the counts in my previous comment, and the work is now committed.

Commit bfec51c on branch issue-1-gltf-glb-reader (https://git.ruv.wtf/litruv/umamo/src/branch/issue-1-gltf-glb-reader): 18 files, +1937/-6.

The test counts I quoted were wrong. The correct ones are GlbContainerTest 14, GltfAccessorTest 12, GltfValidationTest 17, GltfJsonDepthTest 3, GltfSceneGraphTest 6, GltfCodecTest 7, GltfCorpusTest 1 — 60 in total, 59 of which run without a corpus. :format:jvmTest is green, and :format:compileKotlinIosArm64 compiles the common code.

Two rules the tests added while they were being written:

  1. A byteStride smaller than the element it strides over is refused. Over a 12-byte element, a stride of 4 puts two elements on the same bytes, which reads as a mesh with duplicated vertices rather than as an error.
  2. An unknown component, count, mode, or target code is reported by firstGltfProblem rather than thrown from the enum lookup. That is why each enum has knowsCode as well as fromCode: the validator must report the first problem in the document, and a caller that has already validated the file uses the throwing lookup.

No pull request yet. The branch is ready for the review panel.

Correction to the counts in my previous comment, and the work is now committed. Commit `bfec51c` on branch `issue-1-gltf-glb-reader` (https://git.ruv.wtf/litruv/umamo/src/branch/issue-1-gltf-glb-reader): 18 files, +1937/-6. The test counts I quoted were wrong. The correct ones are `GlbContainerTest` 14, `GltfAccessorTest` 12, `GltfValidationTest` 17, `GltfJsonDepthTest` 3, `GltfSceneGraphTest` 6, `GltfCodecTest` 7, `GltfCorpusTest` 1 — 60 in total, 59 of which run without a corpus. `:format:jvmTest` is green, and `:format:compileKotlinIosArm64` compiles the common code. Two rules the tests added while they were being written: 1. A `byteStride` smaller than the element it strides over is refused. Over a 12-byte element, a stride of 4 puts two elements on the same bytes, which reads as a mesh with duplicated vertices rather than as an error. 2. An unknown component, count, mode, or target code is reported by `firstGltfProblem` rather than thrown from the enum lookup. That is why each enum has `knowsCode` as well as `fromCode`: the validator must report the first problem in the document, and a caller that has already validated the file uses the throwing lookup. No pull request yet. The branch is ready for the review panel.
Sign in to join this conversation.
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: litruv/umamo#1