# 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 (rational weight per spec §"v x y z w" — preserved verbatim
through `Primitive::extras["obj:vertex_weight"]`) and the optional
`v` / `w` extra components on UVs. The widely-deployed MeshLab /
libigl / Meshroom / OpenCV `v x y z r g b` per-vertex-colour
extension is accepted at parse time, surfaced through
`Primitive::colors[0]` (alpha pinned to 1.0 since the extension only
spells out three channels), and re-emitted at the original token
width — `xyz`, `xyzw`, `xyzrgb`, or `xyzwrgb` — using the
`Primitive::extras["obj:vertex_color_present"]` bitmap so partial-
colouring inputs preserve their per-vertex partition on round-trip
rather than fabricating synthetic white. 5-float `v` lines are
rejected as ambiguous.
- `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::LineStrip` for a single `l` element
with three or more distinct vertices, `Topology::LineLoop` when
the polyline closes (last vertex equals the first; redundant
closing index dropped), or `Topology::Lines` for multi-`l`
primitives and 2-vertex segments. The encoder picks the matching
emit shape: `LineStrip` writes the natural index list,
`LineLoop` re-appends the first index to spell out the closing
edge, and `Lines` rejoins contiguous segment pairs into one
polyline rather than emitting one `l v1 v2` per pair.
- `p` point elements → `Topology::Points`. Multi-vertex `p v1 v2 v3 …`
lines pack onto one element list; mixing point and face/line elements
under one `usemtl` splits into one primitive per topology.
- `mg <group_number> [res]` merging-group state-setting → preserved
verbatim in `Primitive::extras["obj:merging_group"]`; a change
mid-stream splits the primitive (mirrors `s` behaviour).
- `bevel on/off`, `c_interp on/off`, `d_interp on/off`, and
`lod <level>` display attributes → captured per-primitive in
`Primitive::extras["obj:bevel"]` / `["obj:c_interp"]` /
`["obj:d_interp"]` / `["obj:lod"]`. Mid-stream changes split the
primitive so each one carries one consistent assignment per
attribute.
- `o <name>` → one `Mesh` per object directive (or a single mesh if the
file has no `o`).
- `g name1 name2 …` → multiple group names per line, captured in
`Primitive::extras["obj:groups"]` and re-emitted on a single `g` line.
- `s 1` / `s off` / `s 0` smoothing groups → preserved verbatim in
`Primitive::extras["obj:smoothing_group"]`; a smoothing-group change
mid-object splits the primitive so each one carries a single
consistent assignment.
- `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`.
- Free-form geometry (`vp` parameter-space vertices, `cstype`,
`deg`, `curv`, `curv2`, `surf`, `parm`, `trim`, `hole`, `scrv`,
`sp`, `end`, plus superseded `bzp` / `bsp` patches) — captured
verbatim into `Scene3D::extras["obj:vp"]` (1-based parallel vertex
pool) and `Scene3D::extras["obj:freeform_directives"]` (sequence
of `[keyword, arg1, arg2, …]` arrays). The encoder replays both
after the polygonal section so a decode → encode round-trip
preserves the directive order and arguments. Verbatim by default;
opt-in tessellation of `curv` 3D space curves, `curv2` 2D
parameter-space trimming curves, and Bezier / B-spline / Cardinal /
Taylor / basis-matrix `surf` surfaces is available via
`ObjDecoder::with_curve_tessellation(samples)` (see the per-round
notes below).
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`. The `d -halo factor` orientation-dependent
variant is detected and re-emitted via
`Material::extras["mtl:d_halo_factor"]`.
- Index of refraction (`Ni`) and illumination model (`illum`) → extras.
- Transmission filter — three mutually-exclusive forms per spec:
`Tf r g b` (with `g`/`b` defaulting to `r`),
`Tf spectral file.rfl factor` → `Material::extras["mtl:Tf:spectral"]`,
and `Tf xyz x y z` → `Material::extras["mtl:Tf:xyz"]`.
- Reflection sharpness (`sharpness`) and displacement / decal /
reflection maps (`disp` ↔ `map_disp`, `decal` ↔ `map_decal`,
`refl` ↔ `map_refl`) round-trip via extras.
- Typed reflection maps — `refl -type sphere file` and the six-face
`refl -type cube_top|cube_bottom|cube_front|cube_back|cube_left|cube_right`
cubemap. Sphere lands as `Material::extras["mtl:refl:sphere"]`;
the six face lines bundle into `Material::extras["mtl:refl:cube"]`
(one entry per face) so they don't collapse onto each other under
last-write-wins; the encoder re-emits one `refl -type <kind> ... file`
line per face / sphere in deterministic order.
- 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. Leading `-flag value`
option chunks (`-blendu`, `-bm`, `-mm`, `-clamp`, `-imfchan`, `-o`,
`-s`, `-t`, `-texres`) are parsed out of the filename and surfaced
via `Material::extras["mtl:<map_name>:options"]`; the encoder
splices them back inline.
- 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.
For path-based loading, `obj::parse_obj_from_path` resolves
`mtllib foo.mtl` references against the OBJ file's parent directory
(handles multiple MTL files per line). For round-trip mirroring of
inputs that used negative-from-end indices, the encoder accepts
`ObjEncoder::new().with_negative_indices(true)` (or the same flag on
`obj::SerializeOptions`).
## 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: polygonal subset + MTL Phong + Wavefront-PBR extension.
Round 2: multi-name `g` lines, smoothing-group state-setting (split-on-
change), `Tf` / `sharpness` / displacement-map round-trip, path-based
loader with `mtllib` resolution, and an opt-in negative-index encoder.
Round 3: `p` point elements, `mg` merging groups, `bevel` / `c_interp`
/ `d_interp` / `lod` display attributes, MTL `map_*` option flags
(`-blendu`, `-clamp`, `-bm`, …) preserved through round-trip, MTL
`d -halo factor`, encoder polyline rejoin.
Round 4: free-form geometry (`vp` parameter-space vertex pool plus
the verbatim `cstype` / `deg` / `curv` / `curv2` / `surf` / `parm` /
`trim` / `hole` / `scrv` / `sp` / `end` / `bzp` / `bsp` directive
sequence) — round-trips through `Scene3D::extras` without
tessellation.
Round 5: MTL `Tf spectral` / `Tf xyz` alternative transmission-filter
forms, `refl -type sphere` / `refl -type cube_*` typed reflection-map
sets bundled into `mtl:refl:sphere` / `mtl:refl:cube` extras, and
single-`l` polylines promoted to `Topology::LineStrip` /
`Topology::LineLoop` (with closure detection at decode time).
Round 6: per-vertex colour extension (`v x y z r g b`, MeshLab /
libigl / Meshroom de-facto) accepted on parse, populated on
`Primitive::colors[0]`, and re-emitted at the source's original
3-/4-/6-/7-token width via the `obj:vertex_color_present` bitmap.
The `v` 4th `w` weight component is now preserved through
`Primitive::extras["obj:vertex_weight"]` rather than silently dropped.
Round 7: opt-in Bezier curve tessellation —
`ObjDecoder::with_curve_tessellation(samples)` evaluates every
`cstype bezier` (and `cstype rat bezier`) `curv` directive via de
Casteljau's algorithm and emits a real `Topology::LineStrip`
primitive on a synthetic `"obj:curves"` mesh; the rational form
uses the per-vertex 4th `w` weight and projects back to 3D. Each
tessellated primitive carries provenance extras
(`obj:tessellated_curve`, `obj:curve_kind`, `obj:curve_degree`,
`obj:curve_u_range`, `obj:curve_samples`). The free-form directive
sequence still rides on `Scene3D::extras["obj:freeform_directives"]`
so re-encoding regenerates the original `cstype` / `curv` / `end`
section unchanged; the encoder filters synthetic curve primitives
out of the polygonal output. Free-form-section position pool now
rides on `Scene3D::extras["obj:positions"]` (plus parallel
`obj:position_weights` / `obj:position_colors`) so `curv` /
`surf` absolute-index references stay valid across a
decode → encode → decode cycle.
Round 8: B-spline / NURBS curve tessellation — the same
`with_curve_tessellation(samples)` knob now also evaluates
`cstype bspline` and `cstype rat bspline` `curv` directives via the
Cox-deBoor recursive basis-function formula (spec §"B-spline"),
clipped against the `[x_n, x_{K+1}]` evaluation window of the knot
vector supplied by the most-recent `parm u …` body statement.
Rational form uses the per-vertex 4th `w` weight (NURBS form) and
projects the weighted blend back to 3D. The tessellator now does
two-pass per-`cstype/end` block traversal so the `curv` header
(which comes before the `parm u …` body statement per spec) can
still resolve its knot vector. Knot-vector length is validated
against the spec condition `len == K + degree + 2` and curves with
incomplete data are skipped silently (the directive remains
captured for round-trip).
Round 9: Cardinal (Catmull-Rom) + Taylor polynomial curve
tessellation — `with_curve_tessellation(samples)` now also evaluates
`cstype cardinal` `curv` directives via the spec §"Cardinal"
conversion to Bezier control points (`b0 = c1`,
`b1 = c1 + (c2 − c0) / 6`, `b2 = c2 − (c3 − c1) / 6`, `b3 = c2`,
then cubic Bezier blend) on a sliding 4-point window, and `cstype
taylor` `curv` directives via Horner's-rule polynomial evaluation
`P(t) = Σ_{i=0..n} c_i · t^i` per spec §"Taylor". Cardinal is cubic
only (non-cubic `deg` is rejected, matching the spec's "only
defined for the cubic case" requirement); Taylor honours the
`[u_min, u_max]` parameter clip directly on the `curv` line.
Synthetic primitives carry the same `obj:tessellated_curve` /
`obj:curve_kind` (`"cardinal"` / `"taylor"`) / `obj:curve_degree` /
`obj:curve_u_range` / `obj:curve_samples` provenance and the
encoder filters them out so the source `cstype` / `curv` / `end`
block replays unchanged.
Round 10: basis-matrix curve tessellation — `with_curve_tessellation(samples)`
now also evaluates `cstype bmatrix` `curv` directives per spec
§"Basis matrix" using the user-supplied `(n + 1) × (n + 1)` basis
from `bmat u` (row-major, column index `j` varying fastest per
spec §"bmat u/v matrix") and the segment stride from
`step <stepu>` (spec §"step stepu stepv"). Each segment evaluates
`P(t) = Σ_i Σ_j B[i][j] · t^j · p_{base + i}` over the
control-point window `c_{base+1} .. c_{base+n+1}` (1-based, `base = i·stepu`).
The `bmat` and `step` keywords are now tracked alongside the other
free-form directives, so they round-trip verbatim through
`Scene3D::extras["obj:freeform_directives"]` and the encoder
replays the original `cstype bmatrix` block unchanged. Cubic
Bezier expressed as `cstype bmatrix` matches the closed-form
Bernstein evaluation; the Hermite spec example interpolates its
endpoints.
Round 11: Bezier `surf` surface tessellation — the same
`with_curve_tessellation(samples)` knob now also evaluates `surf`
elements under a `cstype bezier` (or `cstype rat bezier`) header
into a real `Topology::Triangles` grid on a synthetic mesh named
`"obj:surfaces"`, via the bivariate tensor-product de Casteljau
algorithm (spec §"Rational and non-rational curves and surfaces",
§"Bezier"). Control points are read in the spec's row-major
u-fastest order (§"Surface vertex data — control points": "i = 0
to K1 for j = 0, …"); the `surf` line's `v/vt/vn` references are
parsed for their leading position index (negative relative-from-end
indices honoured). A single patch of declared degree `deg degu degv`
needs exactly `(degu + 1) × (degv + 1)` control points; mismatched
counts (multi-patch grids, which Bezier can't decompose without a
`step` stride) are left captured-only. The surface is sampled at a
`(samples + 1) × (samples + 1)` lattice and triangulated CCW
(front = u-right, v-up per the spec note). Each synthetic primitive
carries provenance extras (`obj:tessellated_surface`,
`obj:surface_kind`, `obj:surface_degree`, `obj:surface_u_range`,
`obj:surface_v_range`, `obj:surface_samples`) plus the shared
`obj:tessellated_curve` sentinel so the encoder filters it out and
replays the original `cstype` / `deg` / `surf` / `parm` / `end`
block unchanged from `Scene3D::extras["obj:freeform_directives"]`.
The rational form uses each control point's 4th `w` weight and
projects the weighted blend back to 3D.
Round 12: B-spline / NURBS `surf` surface tessellation — the same
`with_curve_tessellation(samples)` knob now also evaluates `surf`
elements under a `cstype bspline` (or `cstype rat bspline`) header
into a `Topology::Triangles` grid on the synthetic `"obj:surfaces"`
mesh, via the bivariate tensor-product Cox-deBoor formula
`S(u, v) = Σ_i Σ_j N_{i,nu}(u) · N_{j,nv}(v) · d_{i,j}` (spec
§"B-spline"). The per-direction control-grid size comes from the
`parm u` / `parm v` knot vectors (`(len(parm u) − degu − 1) ×
(len(parm v) − degv − 1)`, spec §"B-spline" condition 6 applied
independently in u and v); the `surf` range is clipped against each
direction's `[x_n, x_{K+1}]` evaluation window. The rational (NURBS)
form blends the per-vertex `w` weights and projects via the weighted
denominator. Reuses the round-8 `bspline_basis` Cox-deBoor routine,
so a clamped quadratic patch matches the equivalent Bezier patch
sample-for-sample. Synthetic primitives carry the same
`obj:tessellated_surface` / `obj:surface_kind`
(`"bspline"` / `"rat_bspline"`) / `obj:surface_degree` /
`obj:surface_u_range` / `obj:surface_v_range` / `obj:surface_samples`
provenance and the encoder filters them out, replaying the original
`cstype` / `deg` / `surf` / `parm u` / `parm v` / `end` block
unchanged.
Round 13: Cardinal (Catmull-Rom) `surf` surface tessellation — the
same `with_curve_tessellation(samples)` knob now also evaluates `surf`
elements under a `cstype cardinal` (or `cstype rat cardinal`) header
into a `Topology::Triangles` grid on the synthetic `"obj:surfaces"`
mesh, via the bivariate tensor-product Cardinal evaluation
`S(u, v) = Σ_i Σ_j C_i(u) · C_j(v) · d_{i,j}` (spec §"Cardinal").
Each parametric direction reuses the spec's Cardinal→Bezier per-
segment conversion (`b0 = c1`, `b1 = c1 + (c2 − c0) / 6`,
`b2 = c2 − (c3 − c1) / 6`, `b3 = c2`) on a sliding 4-point window: the
u pass collapses every v-row, then a v pass runs over the collapsed
points. Cardinal is cubic-only per spec, so non-`3 3` degrees stay
captured-only; the control grid comes from the `parm u` / `parm v`
extents (`K = parm_count + 1` per direction) or, when `parm` carries
only the 2-value range, the square single patch (`√total`). A single
bicubic patch's parametric corners interpolate the interior 2×2
control block exactly (spec: "all but the first and last row and
column of control points are interpolated"). The `rat cardinal` form
routes to the same evaluator (unit-weight default). Synthetic
primitives carry the same `obj:tessellated_surface` / `obj:surface_kind`
(`"cardinal"`) / `obj:surface_degree` / `obj:surface_u_range` /
`obj:surface_v_range` / `obj:surface_samples` provenance and the
encoder filters them out, replaying the original
`cstype` / `deg` / `surf` / `parm` / `end` block unchanged.
Round 14: Taylor polynomial `surf` surface tessellation — the same
`with_curve_tessellation(samples)` knob now also evaluates `surf`
elements under a `cstype taylor` (or `cstype rat taylor`) header into
a `Topology::Triangles` grid on the synthetic `"obj:surfaces"` mesh,
via the bivariate tensor-product Horner-rule polynomial evaluation
`S(u, v) = Σ_i Σ_j c_{i,j} · u^i · v^j` (spec §"Taylor"). Control
points are the polynomial coefficients laid out row-major u-fastest
(spec §"Surface vertex data — control points"); a single Taylor
patch of declared degree `deg degu degv` needs exactly
`(degu + 1) × (degv + 1)` coefficient vectors. The `surf s0 s1 t0 t1`
range supplies the global parameter clip; Taylor surfaces evaluate
against the raw parameter values directly (not a normalised `[0, 1]`
re-parameterisation). The spec note in §"Free-form curve/surface
body statements" says the rational form "does not make sense for
Taylor", so `rat taylor` routes to the same evaluator without per-
vertex weight blending. Synthetic primitives carry the same
`obj:tessellated_surface` / `obj:surface_kind` (`"taylor"`) /
`obj:surface_degree` / `obj:surface_u_range` / `obj:surface_v_range`
/ `obj:surface_samples` provenance and the encoder filters them out,
replaying the original `cstype` / `deg` / `surf` / `parm` / `end`
block unchanged.
Round 14 (depth): `cargo fuzz` harness — `fuzz/fuzz_targets/parse_obj.rs`
and `fuzz/fuzz_targets/parse_mtl.rs` drive attacker-controlled bytes
through every public decoder entry point and assert panic-freedom (no
panic / abort / debug-overflow / out-of-bounds index for any input).
The first 180-second `parse_obj` run found two real crashes that are
now fixed and pinned by regression tests in `tests/fuzz_regressions.rs`:
* `parse_face_vertex` admitted an empty leading slot (so `f /1 /2`
and `p /13` and `l /1 /2` produced `fv.v == 0` which then panicked
on `(fv.v - 1) as usize` underflow downstream). Fix: require a
non-empty position component at parse time so the `fv.v >= 1`
invariant holds end-to-end.
* `tessellate_surfaces` allocated `Vec::with_capacity(cols * rows)`
for the Bezier control-grid pool without bounding the product
against the declared control-vertex count, so `deg 111111` blew
past available memory. Fix: `checked_add` / `checked_mul` on the
grid extents and an early "expected != entry control-count" bail
so the allocation never runs for mismatched grids. Same defence
applied to the `cstype bmatrix` `(n + 1) × (n + 1)` basis-size
check.
Subsequent 180-second runs against `parse_obj` (corpus grew to ~8.8k
discovered inputs) and `parse_mtl` (corpus grew to ~1.1k) finished
without further crashes / OOM / timeouts. The fuzz subcrate's
`Cargo.lock` is tracked for reproducible builds; transient
`fuzz/target/`, `fuzz/corpus/`, and `fuzz/artifacts/` paths sit on
`.gitignore`.
Round 182: basis-matrix `surf` surface tessellation — the same
`with_curve_tessellation(samples)` knob now also evaluates `surf`
elements under a `cstype bmatrix` (or `cstype rat bmatrix`) header
into a `Topology::Triangles` grid on the synthetic `"obj:surfaces"`
mesh, via the bivariate tensor-product polynomial
`S(u, v) = Σ_a Σ_b (Σ_p B_u[a][p] · u^p) (Σ_q B_v[b][q] · v^q) ·
c_{base_u + a, base_v + b}` (spec §"Basis matrix",
§"bmat u/v matrix", §"step stepu stepv"). Per-direction basis
matrices come from `bmat u` / `bmat v` (row-major, column index
varying fastest); per-direction segment strides come from
`step stepu stepv`. The per-direction control-grid extent inverts the
spec relation `parm = (K − n) / s + 2` to `K = (parm − 2) · s + n + 1`,
applied independently in u and v ("For surfaces, the above description
applies independently to each parametric direction."). Multi-patch
grids decompose into per-segment patch windows starting at
`(seg_u · stepu, seg_v · stepv)`, so the spec §"Examples" cubic
Bezier-as-bmatrix surface single-patch case matches the equivalent
`cstype bezier` patch sample-for-sample. The `rat bmatrix` qualifier
routes to the same evaluator without per-vertex weight blending
(matches the round-10 1D curve behaviour). Synthetic primitives carry
the same `obj:tessellated_surface` / `obj:surface_kind` (`"bmatrix"`) /
`obj:surface_degree` / `obj:surface_u_range` / `obj:surface_v_range` /
`obj:surface_samples` provenance and the encoder filters them out,
replaying the original `cstype` / `deg` / `bmat u` / `bmat v` /
`step` / `parm u` / `parm v` / `surf` / `end` block unchanged.
Round 188: 2D trimming-curve (`curv2`) tessellation — the same
`with_curve_tessellation(samples)` knob now also evaluates every
`curv2` directive (the parameter-space curve referenced by
`trim` / `hole` / `scrv`, spec §"curv2") into a `Topology::LineStrip`
polyline on a new synthetic mesh named `"obj:curves2"`. A `curv2`
references `vp` parameter vertices (spec §"vp u v w") and lies in the
2D parameter space of the surface it trims, so each `vp (u, v)` is
lifted into a flat `[u, v, 0.0]` control point and run through the
same Bezier / B-spline / Cardinal / Taylor / basis-matrix evaluators
the 3D `curv` path uses — the sampled `x`/`y` are the parameter-space
coordinates, `z` stays `0.0`. Unlike `curv`, a `curv2` line carries
no inline `u0 u1`; the B-spline evaluation window comes from the
block's `parm u` knot vector. The optional 3rd `vp` coordinate is the
rational weight (default `1.0`; the `vp` `0.0` padding default reads
back as `1.0` for the rational forms). Negative `curv2` indices
resolve relative-from-end against the `vp` pool (spec §"Special point"
example `curv2 -6 -5 …`). Synthetic primitives carry the shared
`obj:tessellated_curve` sentinel plus a `obj:curve2` marker and the
`obj:curve_kind` / `obj:curve_degree` / `obj:curve_u_range` /
`obj:curve_samples` provenance; the encoder filters them out and
replays the original `cstype` / `curv2` / `parm` / `end` block
unchanged from `Scene3D::extras["obj:freeform_directives"]`.
The `.mod` binary form remains out of scope; multi-patch Bezier
surface decomposition (Bezier carries no `step` stride) and full
surface clipping against the `trim` / `hole` loops (the loops' `curv2`
curves now tessellate, but the surface mesh is not yet clipped to
them) are the remaining gaps.
## License
MIT. See [LICENSE](./LICENSE).