oxideav-obj 0.0.0

Pure-Rust Wavefront OBJ + MTL 3D mesh codec — implements oxideav-mesh3d's Decoder/Encoder traits
Documentation

oxideav-obj

Pure-Rust Wavefront OBJ + MTL 3D mesh codec. Implements the oxideav_mesh3d::Mesh3DDecoder and Mesh3DEncoder traits, plugging into the wider OxideAV codec ecosystem.

OBJ is the universal mesh-interchange format published by Wavefront Technologies in the early 1990s as Appendix B of the Advanced Visualizer manual. This crate implements the polygonal subset (the part that modern loaders actually load):

  • v / vt / vn vertex data — with the optional w 4th component on positions and the optional v / w extra components on UVs.
  • f faces in all four index syntaxes (v, v/vt, v//vn, v/vt/vn), with 1-based indexing and the negative-index relative-from-end shorthand. Polygons (n-gons) are fan-triangulated on read; the original per-face arity is stashed in Mesh::extras["obj:original_face_arities"] so the encoder can re-emit n-gons rather than triangles.
  • l line elements → Topology::Lines.
  • o <name> → one Mesh per object directive (or a single mesh if the file has no o).
  • g <name> → group-name capture in Primitive::extras["obj:groups"].
  • s smoothing groups → Primitive::extras["obj:smoothing_group"].
  • mtllib <file.mtl> [<file2.mtl> …] and usemtl <name> — each usemtl switch starts a fresh Primitive so a multi-material OBJ becomes a Mesh with N primitives, each with its own MaterialId.

The companion MTL parser/serialiser handles:

  • Phong colours (Ka / Kd / Ks / Ke) → glTF base_color (from Kd) + emissive_factor (from Ke); Ka / Ks and the Ns exponent are stashed in Material::extras for round-trip.
  • Transparency (d dissolve / Tr = 1 - d) → AlphaMode::Blend
    • base_color.a.
  • Index of refraction (Ni) and illumination model (illum) → extras.
  • Texture references (map_Kd → base_color_texture, map_Bump → normal_texture, map_d etc.) emitted as ImageData::External { uri, mime: None } — the caller resolves paths against the OBJ file's directory.
  • Wavefront-PBR extension (Pr roughness, Pm metallic, Pc clearcoat, Ps sheen, map_Pr / map_Pm) → Material::roughness / Material::metallic / metallic_roughness_texture.

Both decoders are registered against Mesh3DRegistry under the default-on registry cargo feature; drop the feature for a free-standing build that only exposes ObjDecoder / ObjEncoder and the oxideav_mesh3d standalone trait surface.

Sourcing

The Wavefront spec is mirrored in the OxideAV docs repository:

  • docs/3d/obj/wavefront-obj-spec.txt — Martin Reddy plain-text Appendix B1 mirror.
  • docs/3d/obj/wavefront-mtl-spec.html — Paul Bourke MTL mirror (carries the original Copyright 1995 Alias|Wavefront, Inc. notice).
  • docs/3d/obj/paulbourke-obj-reference.html — Paul Bourke OBJ cross-check mirror.

This crate was implemented strictly from those references — no existing OBJ loader (tinyobj, assimp, blender io_scene_obj, three.js OBJLoader) was consulted.

Status

Round 1 (this commit): polygonal subset + MTL Phong + Wavefront-PBR extension. Free-form curves/surfaces (curv, surf, parm, trim, hole, scrv, sp, end), the vp parameter-space vertex, the p point element, the mg merging-group, the bevel / c_interp / d_interp / lod display attributes, and the .mod binary form are not implemented. Files using only those features will decode to an empty scene; files that mix them with polygonal data will decode the polygonal part and ignore the rest.

License

MIT. See LICENSE.