Development

Development

cargo fmt --check
RUSTFLAGS='-D warnings' cargo build --locked
cargo test --locked
cargo clippy --all-targets -- -D warnings

Tests cover coordinate precision, scientific notation, negative indices, UV seams, material parameters, mesh ranges, VRML defaults, concave polygons, one primitive per material under shuffled and interleaved face orders, 16/32-bit index selection, output cleanup, inspect reports matching across OBJ and imported glTF, and texel coverage against a brute-force overlap test. The glTF writer uses Serde for metadata and a small binary writer, with no mesh-owning library or C/C++ dependency. CI builds and tests on Linux, macOS and Windows.

Optional format validation with Khronos's validator, for models that fit in memory (it loads the whole .bin):

npm install --prefix /tmp/objtools-validator gltf-validator
NODE_PATH=/tmp/objtools-validator/node_modules node tools/validate_gltf.cjs terrain.gltf

For a real import with Linux process-memory monitoring:

python3 tools/monitor_import.py input.obj destination/model.gltf --center --progress --tmp-dir destination

The monitor writes import logs, one-second RSS samples and a peak-memory report beside the model. RSS includes the mapped spools (evictable page cache); the anonymous figure is the importer's own heap.

End-to-end check against Blender

tools/e2e_blender checks that a glTF looks the same after import. For each Khronos sample asset, it renders the source and the output in Blender from the same cameras, then compares the pixels and what Blender loaded.

cargo build --release
python3 tools/e2e_blender/harness.py --models DamagedHelmet,Duck
python3 tools/e2e_blender/harness.py --negative DamagedHelmet

It needs a release build, Blender on PATH, Pillow and network access. Validator results appear if NODE_PATH reaches gltf-validator. Downloads, renders and the report (out/e2e/report.html) stay in out/e2e, which git ignores. Results are saved as they come, so an interrupted run resumes. --negative breaks an output on purpose, to prove the difference is flagged.

The full catalogue takes about two hours, so this isn't part of CI. The last results are in glTF extensions. MeshoptCubeTest shows as different on Blender 5.2, because its importer decodes meshopt's COLOR filter with the exponential one, which miscolours the source.

Documentation

The README covers installation, the complete command reference and inspection statistics. This wiki has two sections: Conversion for format support and conversion policies, and How it works for implementation details. It has its own Git repository and history. Wiki sources are not tracked in the main repository.

Clone the wiki to read or edit its Markdown pages locally:

git clone git@github.com:sdumetz/objtools.wiki.git ../objtools.wiki

Edit the relevant pages in that checkout, then review and publish the changes:

git -C ../objtools.wiki diff
git -C ../objtools.wiki add -- '*.md'
git -C ../objtools.wiki commit -m "Update documentation"
git -C ../objtools.wiki push

For an existing checkout, run git -C ../objtools.wiki pull --ff-only before editing. Update the README and wiki at the appropriate level of detail when user-visible behaviour changes.

How it works · Documentation home