oxihuman-wasm

Part of the OxiHuman workspace — privacy-first, client-side human body generator in pure Rust.

Status: Stable | Tests: 168 passing | API: 68 WasmEngine methods | Version: 0.1.1 | Updated: 2026-03-13

WebAssembly bindings for OxiHuman — full browser-ready API via wasm-bindgen. A single WasmEngine struct exposes the entire OxiHuman pipeline to JavaScript/TypeScript, enabling privacy-preserving, client-side human body generation with no server round-trips.

Feature Flags

[features]
default = []
wasm = ["dep:wasm-bindgen", "dep:js-sys"]

The wasm feature is optional. Enable it when targeting browser/Node.js environments via wasm-bindgen. Without it, the crate still compiles for testing and native use.

Installation

[dependencies]
oxihuman-wasm = { version = "0.1.1", features = ["wasm"] }

Structs

`WasmEngine`

Main body generator. Exposes the full OxiHuman pipeline as 68 public #[wasm_bindgen] methods. Holds base mesh data, loaded morph targets, parameter state, physics proxies, and animation frame buffer.

`ParticleSystem`

Point particle system with configurable emit_rate and lifetime control. Created via WasmEngine::create_particle_system() and stepped via step_particles().

`Particle`

Represents a single active particle. Carries position (Float32Array), velocity (Float32Array), and age (f32).

WasmEngine API — 68 Methods

Initialization (4)

Method	Description
`new_from_obj_bytes(bytes)`	Create engine from raw OBJ mesh bytes
`new_strict()`	Create engine with strict validation policy profile
`load_target_bytes(name, bytes)`	Load a morph target from raw `.target` file bytes
`load_zip_pack_bytes(bytes)`	Load a ZIP asset pack; returns the number of targets loaded

Target Management (8)

Method	Description
`list_loaded_targets()`	Return JSON array of all loaded target names
`loaded_target_count()`	Return count of currently loaded targets
`load_target_from_json(json)`	Load a morph target from JSON descriptor
`unload_target(name)`	Remove a named target from the engine
`set_target_weight_by_name(name, weight)`	Set blend weight [0.0–1.0] for a named target
`get_target_weight_by_name(name)`	Get current blend weight for a named target
`target_count()`	Total number of registered targets (loaded + unloaded)
`get_loaded_target_names()`	Return JS array of loaded target name strings

Parameter Control (7)

Method	Description
`set_height(value)`	Set body height parameter (metres)
`set_weight(value)`	Set body weight parameter (normalized)
`set_muscle(value)`	Set musculature parameter
`set_age(value)`	Set age parameter
`set_param(key, value)`	Set any named parameter by string key
`reset_params()`	Reset all body parameters to defaults
`reset_all_weights()`	Reset all morph target blend weights to zero

JSON Import/Export (4)

Method	Description
`export_params_json()`	Serialize current parameter state to JSON
`import_params_json(json)`	Restore parameter state from JSON
`get_measurements_json()`	Return computed body measurements (height, circumferences, etc.) as JSON
`export_anim_json()`	Serialize recorded animation frames to JSON

Mesh Building (3)

Method	Description
`build_mesh_bytes()`	Build binary mesh buffer containing positions, normals, UVs, and indices
`export_quantized_bytes()`	Export mesh in QMSH quantized binary format (compact, lossy)
`get_scene_json()`	Return scene description JSON (nodes, cameras, lights)

Physics (5)

Method	Description
`get_physics_proxies_json()`	Return collision proxy shapes as JSON
`get_physics_rig_json()`	Return full physics rig descriptor as JSON
`get_capsule_chains_json()`	Return capsule chain descriptors for limbs as JSON
`step_physics(dt)`	Step physics simulation by `dt` seconds (stub)
`set_wind(x, y, z)`	Set wind force vector for cloth/particle systems (stub)

Animation (7)

Method	Description
`record_anim_frame()`	Record current parameter state as an animation frame
`clear_anim_frames()`	Clear all recorded animation frames
`anim_frame_count()`	Return number of recorded frames
`seek_anim_frame(index)`	Restore parameter state to a recorded frame by index
`play_anim_step()`	Advance playback by one frame, wrapping at end
`get_anim_fps()`	Get current animation playback rate (frames per second)
`set_anim_fps(fps)`	Set animation playback rate

Query & Analysis (6)

Method	Description
`get_vertex_count()`	Return number of vertices in the built mesh
`get_index_count()`	Return number of triangle indices in the built mesh
`get_curvature_map()`	Return per-vertex curvature values as Float32Array
`get_geodesic_distances(origin_index)`	Return geodesic distances from origin vertex as Float32Array
`query_sphere_near_point(x, y, z, radius)`	Return JSON array of vertex indices within sphere
`get_mesh_segments()`	Return JSON segment map (body part regions by vertex range)

Presets & Proportions (5)

Method	Description
`set_params_from_preset(preset_name)`	Apply a named parameter preset (e.g., `"athletic"`, `"average"`)
`apply_preset_by_name(name)`	Apply preset including morph target weights
`get_body_proportions_json()`	Return computed proportional ratios as JSON
`get_param_summary_json()`	Return a summary of all parameters and their current values as JSON
`set_allowlist(names)`	Restrict which targets are eligible for blending

LOD & Shaders (2)

Method	Description
`get_lod_scene_json()`	Return multi-LOD scene JSON (LOD0–LOD3 meshes)
`list_builtin_shaders()`	Return JSON array of built-in shader descriptor names

Cache (2)

Method	Description
`has_cached_mesh()`	Return `true` if a built mesh is cached and parameters are unchanged
`reset_incremental_cache()`	Invalidate the incremental mesh build cache

Particles (2)

Method	Description
`create_particle_system(emit_rate, lifetime)`	Create a new `ParticleSystem` with given parameters
`step_particles(system, dt)`	Advance a particle system by `dt` seconds

Expressions (2)

Method	Description
`apply_expression_blend(expression_json)`	Apply a facial expression blend from JSON descriptor
`get_cloth_state()`	Return current cloth simulation state as JSON (stub)

Free Functions

Function	Description
`parse_mesh_bytes_header(buffer)`	Parse the format header from a binary mesh buffer; returns JSON with format version and field offsets

JavaScript/TypeScript Usage

import init, { WasmEngine } from "oxihuman-wasm";

await init();

// Load base mesh from an OBJ file
const objBytes = new Uint8Array(await fetch("human_base.obj").then(r => r.arrayBuffer()));
const engine = WasmEngine.new_from_obj_bytes(objBytes);

// Load a ZIP asset pack with morph targets
const packBytes = new Uint8Array(await fetch("targets.zip").then(r => r.arrayBuffer()));
const count = engine.load_zip_pack_bytes(packBytes);
console.log(`Loaded ${count} targets`);

// Set body parameters
engine.set_height(1.75);
engine.set_weight(0.4);
engine.set_muscle(0.6);
engine.set_age(30.0);

// Build mesh and use binary data
const meshBytes = engine.build_mesh_bytes();

// Export parameters
const paramsJson = engine.export_params_json();
console.log(JSON.parse(paramsJson));

// Query measurements
const measurements = JSON.parse(engine.get_measurements_json());
console.log(measurements);

Architecture Notes

All heavy computation runs in the browser's WebAssembly sandbox — no server communication, no data leakage.
WasmEngine is !Send and single-threaded by design. For parallel workloads, use multiple instances in separate Web Workers.
Physics methods (step_physics, set_wind) and get_cloth_state are currently stubs returning placeholder data; full simulation is implemented in oxihuman-physics.
The wasm feature gate keeps native builds free of wasm-bindgen overhead, allowing the crate to be used in test harnesses and CLI pipelines without a browser target.

v0.1.1 Internal Refactor

engine.rs is now a thin re-export module (7 lines). The implementation has been split into four focused source files with no public API changes:

File	Contents
`engine_core.rs`	`WasmEngine`, `ParticleSystem`, `Particle` struct definitions and initialization
`engine_anim.rs`	Animation recording, playback, and frame management methods
`engine_targets.rs`	Morph target loading, unloading, and weight management methods
`engine_io.rs`	JSON import/export, mesh building, physics, query, and preset methods

Tests were moved to wasm_tests.rs. All public #[wasm_bindgen] method signatures are unchanged.

oxihuman-wasm 0.1.1