# Public anatomy and contact replay subset

Prepared 2026-09-17 from existing LifeCode artifacts. Sources remain unchanged.

`atlas-hepatobiliary.glb` is a compact, self-contained atlas assembly: liver,
gallbladder, native bile-duct curve and four native hepatic artery curves. The
liver and gallbladder carry two embedded real human tissue photographs. This is
an anatomical atlas with photographic appearance, not a patient CT model or
patient-matched texture. See its metadata and the `licenses` directory.

The source laparoscopy scene had moved the gallbladder by the explicitly authored
teaching traction [13, 10, -9] mm. The extraction undoes exactly that translation,
returning to the atlas pose. The rest of the selected mesh data, texture pixels,
UVs and normals are unchanged. No teaching cystic duct/artery segments, patient,
bed, instruments or operative animation are included in this extracted GLB.
The preserved bile duct and arteries are tubes built from native atlas curves.

The atlas GLB is in metres with +Y superior, +X anatomical right, +Z posterior.
It is centered on the liver. An initial Three.js camera is [0.25,-0.18,-0.32],
target [0,-0.025,0], with up [0,1,0]. Keep imported texture maps, texture transforms
and material settings. Appropriate soft lighting is needed to inspect this
actual asset in the site. The preview and download should use this same file.

`patient-liver.glb` is the unmodified patient-derived diagnostic surface from the
SOFA experiment. It has semantic color, no tissue photo. Although GLB is normally
Y-up, this particular source explicitly preserves **LPS coordinates**, +Z
superior, metres, identity basis. Use camera.up.set(0,0,1), or apply exactly one
common rigid axis conversion to all replay vertices, rest vertices and probe.
Never mix the atlas GLB and patient replay as if they were one patient's anatomy.

## Browser replay contract

`replay-summary.json` gives the selected case, physical parameters, evidence and
file paths. `replay-frames.json` is a compact UI index, with actual time, phase,
probe and force/displacement metrics for each saved geometry. `replay-reader.mjs`
loads the arrays and returns zero-copy typed-array views of saved states.

All binary arrays are little-endian, C-order, and have no header:

| File | Type and shape | Units |
| --- | --- | --- |
| `replay/geometry/vertices.f32` | float32 [8838,3] | LPS metres, input rest state |
| `replay/geometry/triangles.u32` | uint32 [17668,3] | zero-based vertex indices |
| `replay/cases/…/positions.f32` | float32 [45,8838,3] | LPS metres, actual saved positions |

For frame `i`, use float offset `i * 8838 * 3`, length `8838 * 3`; equivalently
byte offset `i * 106056`. In `case.json`, `frames.times_s[i]`,
`frames.probe_centers_lps_m[i]`, and `frames.phase[i]` describe that exact state.
The corresponding scalar sample is
`samples[frames.source_sample_indices[i]]`. The case retains every one of its
225 native scalar samples, while surface geometry was saved every 0.05 s.

First saved frame is t=0.05 s; last is t=2.25 s. Input rest geometry is separate,
not a fabricated time-zero solver frame. At physical 1× scale, displacement is
submillimetric. A fixed displacement-color legend can show it clearly without
changing positions. A playback slider should select discrete native frames and
show the selected source time. Browser playback does not recompute mechanics.

The 12 mm sphere radius is physical. Contact force comes from the native SOFA
constraint impulse, mapped through J transpose and divided by dt, then checked
against nodal dynamic balance. Displaying the impulse itself as newtons is wrong.
The whole-run peak contact force is 0.0111414366 N; whole-run maximum displacement
is 0.0005824992 m. These whole-run peaks need not coincide with the same saved frame.

## What the displayed experiment actually solves

SOFA 26.06.00, 17,537 tetrahedral nodes, 76,262 tetrahedra; all 8,838 source surface
vertices and 17,668 triangles are retained. Fifteen native numerical checks pass
for this selected recorded run. The independent batch review includes 27 passing
cases; the public subset contains just this one case.

The tissue is small-strain isotropic linear FEM (`method=small`): E=5000 Pa,
Poisson ratio 0.4, density 1050 kg/m³. Rayleigh alpha=8 /s, beta=0.02 s; gravity=0.
These are generic, uncalibrated numerical assumptions. Support fixes 2252 inferior
surface nodes in all three directions. The radius-12-mm rigid sphere follows
a prescribed trajectory; tissue displacement is solver-computed. Native
unilateral frictionless contact uses coefficient mu=0, contact distance 20 µm,
initial clearance 200 µm, implicit Euler dt=0.01 s. The selected schedule loads
to 0.5 mm indentation at 2 mm/s, holds 0.5 s, unloads and recovers for 1 s.

This experiment has no puncture, fracture, cutting, adhesion, friction, blood
flow or large-strain material model. Patient material calibration, anatomical
support calibration, clinical validation and spatial mesh convergence are not
claimed. The CT-derived organ geometry does not establish any of those properties.

## Wider library capabilities: separate implementations

The website's staged injection, biopsy, laparoscopy, angioplasty and other
procedural demonstrations include prescribed geometry/kinematics. Their visual
realism does not imply tissue/contact-force prediction. The extracted atlas
asset has no mechanics attached.

There are separate executable research models: layered SOFA needle interaction,
MuJoCo elastic suture cable, muscle-driven joint dynamics, and reduced numerical
circulation/transport/thermal models. They should be described by their specific
equations and evidence, not promoted as a single clinically validated simulator.

The current `layered_puncture` implementation consumes the liver/skin/fat/passive
muscle Maxwell material presets in real finite elements; the earlier
`materials/integration-status.json` predates that four-layer integration.
Those coefficients are authored assumptions, not measured tissue fits. The
four-layer model has a 48×48 mm authored abdominal patch, not CT-derived wall
layers; empirical force-threshold entry and path-history cutting resistance,
not crack propagation or topology changes. It is a separate model from this
linear patient-liver contact replay. See `capabilities.json` for compact facts.

Licenses: atlas mesh adaptation CC BY-SA 4.0 with underlying BodyParts3D credit;
liver photograph public domain; gallbladder photograph CC BY-SA 3.0. The
patient-derived surface/replay retain the complete `LicenseRef-Slicer-1.0` text,
including Part B, in `replay/LICENSE-source.txt`. Source data are modified LifeCode
derivatives for research; do not imply source-author endorsement. Preparation
code and reader follow the project's Apache-2.0 code license.