# Drosophila mesh provenance

`drosophila-flybody.glb` is derived from the FlyBody fruit-fly model, developed collaboratively by Google DeepMind and HHMI Janelia Research Campus, hosted by TuragaLab.

- Upstream: https://github.com/TuragaLab/flybody
- Pinned source commit: `d015e9bfe441bd90ae431bac24c55cb74bdbce26`
- License: Apache License 2.0, retained locally in `LICENSE-flybody`.
- License source: https://github.com/TuragaLab/flybody/blob/d015e9bfe441bd90ae431bac24c55cb74bdbce26/LICENSE
- Mesh source directory: https://github.com/TuragaLab/flybody/tree/d015e9bfe441bd90ae431bac24c55cb74bdbce26/flybody/fruitfly/assets
- Direct download pattern: `https://raw.githubusercontent.com/TuragaLab/flybody/d015e9bfe441bd90ae431bac24c55cb74bdbce26/flybody/fruitfly/assets/{filename}.obj`
- Source hierarchy: https://raw.githubusercontent.com/TuragaLab/flybody/d015e9bfe441bd90ae431bac24c55cb74bdbce26/flybody/fruitfly/assets/fruitfly.xml

Research reference: Vaxenburg et al., *Whole-body physics simulation of fruit fly locomotion*, Nature 643, 1312–1320 (2025). https://doi.org/10.1038/s41586-025-09029-4

Recommended displayed credit: **Fruit-fly anatomy adapted from FlyBody (Google DeepMind / HHMI Janelia), Apache 2.0.** Link FlyBody and the retained license.

Modifications made September 11, 2026: OBJ geometry welded and selectively simplified with meshoptimizer; original component hierarchy and quaternion transforms reconstructed from `fruitfly.xml`; simulation-only geometries, lights and cameras omitted; original material colors converted to glTF PBR materials; wing membranes retained as transparent, double-sided surfaces; all assets placed in a centered Y-up scene and scaled 20 times from MuJoCo model units. No animation clips or joint constraints were exported. Display transformations do not change the source licensing.

# Integration

- GLB file: `drosophila-flybody.glb`, 3,600,052 bytes; 192,074 triangles; 85 material-separated meshes. No compression extension or additional decoder required.
- All 85 original OBJ source files retained in `flybody/`, total 140,210,018 bytes. Source raw OBJ files are heavily duplicated and much larger than the exported GLB.
- Load with standard Three.js `GLTFLoader`. Use one geometry for both palette variants and clone materials for independent styling.
- Named body groups include `head`, `wing_left`, `wing_right`, `abdomen`, `abdomen_2` through `abdomen_7`, `haltere_left`, `haltere_right`, `coxa_T1_left`, `coxa_T1_right`, and similarly T2/T3. The first abdomen segment is the `abdomen` group and the eighth is geometry `abdomen_8_surface` inside `abdomen_6`. The hierarchy retains child femur, tibia, tarsus and claw groups. Render meshes append `_surface` to their original geom names.
- Named materials: `body`, `red` (eyes), `ocelli`, `black`, `bristle-brown`, `lower`, `brown` (wing veins and claws), `membrane` (wings).
- `flybody_root` carries a -90-degree X rotation and uniform scale 20. The result is Y-up, head toward +X, wings spread along Z. Bounding extents in exported scene units are approximately 6.0254 X × 3.6808 Y × 12.2325 Z. Scene is centered at origin.
- Body-level local transforms retain the original MuJoCo axes; animate with additive rotations relative to the loaded baseline quaternion. Wing groups use their actual anatomical joint origins. Joint values are neutral zero configuration, so wings are spread, rather than walking/flying simulation poses.
- Transparent membranes should keep `depthWrite=false` if restyling materials in Three.js. Original alpha is 0.4. Preserve double-sided rendering.
- `extract_model.py`, `convert.mjs`, `flybody-model.json`, and `conversion-stats.json` retain the conversion recipe and per-component geometry statistics.

# Rest pose and gait notes

For both wings, the same source-defined rest angles work because the source base quaternions mirror the anatomy. Starting from each loaded baseline quaternion, multiply (postmultiply, in this order): local Z rotation +1.5 rad, local X rotation +0.7 rad, local Y rotation -1.0 rad. These are the `yaw`, `roll` and `pitch` joint `springref` values in the original XML. The resting wings overlap above the abdomen and point backward (-X). Loaded base quaternions must be retained and reset before every animation update to avoid accumulating rotations.

The neutral leg pose already places all six claw meshes very nearly in one horizontal plane: minimum Y lies between -1.8259 and -1.8404 across the feet. An outer wrapper Y translation of +1.8405 places the unscaled asset on ground Y=0. Multiply that offset by any added uniform display scale. For a different pose, update matrices and calculate a foot-only bounding box, then use the minimum Y to set the wrapper height. Avoid setting `flybody_root.position.y` directly to this value, since that node already has a centering translation.

For a subtle illustrative tripod gait, alternate phase groups A = T1-left/T2-right/T3-left and B = T1-right/T2-left/T3-right by pi. Let `p=2*pi*frequency*time+phase`, `swing=max(0,sin(p))`. Relative to the original local baseline, a reasonable starting approximation is coxa local Y = `0.10*cos(p)`, coxa local X = `0.08*swing`, femur local X = `-0.05*swing`, tibia local X = `0.12*swing`. Apply identical signs on both sides because the mirrored source frames account for left/right orientation. Frequency 1.5–2.0 Hz reads clearly at UI scale. These are procedural presentation angles, not a validated biomechanics simulation; slight foot slip is expected. Quantitative numerical pose checks are in `gait-derivatives.json` (XYZ endpoint displacements per radian) and `pose-research.mjs`.

The separate wing rest angles above are backed by the source model defaults; the gait angles are a conservative visualization approximation. Keep idle motion smaller (head local X about ±0.02 rad, body vertical about ±0.02 scene units) so it does not obscure structure.

Alternative considered: EPFL NeuroMechFly/FlyGym has a smaller ~2,000-triangle-per-part model and a convenient derivative at https://github.com/NeLy-EPFL/fly-svg-maker/tree/main/assets with explicit mesh attribution. FlyBody was selected for its distinctive detailed compound eyes, bristles, antennal structure, separate wing veins and membranes, and fine abdomen anatomy.