Esacode

Docs / Blocks / Simulation

Soft body model

Turns segmented anatomy into a soft-tissue model the 3D view simulates in real time: organs that sag, sway and push each other under gravity, held by a fixed skeleton and contained by the skin (metaball method of Gianluca De Novi, PhD).

Runs on a worker (Python) Simulation Version 1.5 Code you can open and adapt

How it works

Connect the masks of each case (segmentations/ folders, as in the TotalSegmentator dataset) and its CT scan.

Following the metaball soft-tissue method of Gianluca De Novi, PhD (PhD thesis, University of Bologna, 2011: https://amsdottorato.unibo.it/id/eprint/3702/1/DeNovi_Gianluca_tesi.pdf), each structure's volume (soft structures of 1 ml or more, as in Labels to 3D models: smaller slivers have no surface to move) is approximated by a tree of spheres (medial axis approximation: the deepest point not yet covered, with its distance to the surface as radius, until Coverage is reached); the sphere centres are particles with mass (each structure weighs its density times its real volume, from its mask, and its spheres share that mass in proportion to their volumes; the skin weighs a 3 mm layer over the body's outline), joined by elastic links with damping: inside each structure (touching spheres, and a second ring that keeps its shape), between structures that touch (connective tissue), and to the skeleton, which is fixed and not subject to gravity (each bone with as many spheres as it needs to be covered; between neighbouring ribs, costal cartilages and sternum, a chest wall of fixed spheres stands for the intercostal muscles, which are not segmented, so the lungs cannot slip out between the ribs); muscles are tied to the bones where they meet them (origins and insertions: each muscle sphere that touches a bone, or comes within 6 mm, by stiff elastic links to up to 4 bone spheres).

The skin is the body's outline in the CT (above Body threshold): points every Skin spacing, joined to each other and to what lies under them, fixed where the scan cuts the body.

Each structure gets a tissue class with a stiffness (Young's modulus) and a density: liver, spleen, pancreas, kidney, thyroid and muscle as measured in healthy people by shear-wave elastography (Viceconti et al., World J Radiol 2025; Arda et al., AJR 2011), the others from the orders of magnitude in the literature; a Tissues table (tissue, match, E, density, damping) changes them.

Connect the model and the anatomy of Labels to 3D models to a 3D view: the organs move under gravity as you turn the body, and can be pulled. A plausible demo, not a validated simulation: not for clinical use.

Inputs

InputTakesWhat it is
Labels
labels
Files
gz, nii, nrrd, mha
Masks, one file per structure, in each case's segmentations/ folder Takes several connections.
Scans
scans
Files
gz, nii, nrrd, mha
The CT of each case, for the skin (the body's outline) Optional. Takes several connections.
Tissues
tissues
Table
csv
Optional: tissue, match (words of structure names, separated by ;), E (Pa), density (kg/m3), damping Optional. Takes several connections.

Outputs

OutputGivesWhat it is
Soft body
model
Files
json
<case>/<case>_softbody.json (esasim.softbody/1): bodies of spheres, links, tissues, the skin and its surface
Structures
table
Table
csv
softbody.csv: case, structure, tissue, fixed, spheres, bone_links, volume_ml, mass_g, E_pa, density
Live telemetry
telemetry
Live telemetryWhat the block sends while it runs, for views such as Chart or 3D view.

Settings

SettingDefaultWhat it does
Soft structures
structures
empty Names of the structures that move (liver, kidney_*, colon…), separated by commas; empty: all. The skeleton is always there, fixed
Spheres per structure
spheres
40 More: finer shapes, slower simulation
From 4 to 400
Spheres per bone
bone_spheres
0 0 (automatic): as many as each bone needs to be covered (ribs and costal cartilages included), at most 800. A number: at most that many per bone; fewer leave gaps the organs can slip through
From 0 to 800
Close the chest wall
chest_wall
on The intercostal muscles are not segmented: fixed spheres fill the gaps between neighbouring ribs, costal cartilages and sternum, so the lungs cannot slip out between the ribs
Coverage (%)
coverage
85 Spheres are added until they cover this share of each structure
From 30 to 100
Skin
skin
on A skin layer, from the body's outline in the CT, that contains the organs
Skin spacing (mm)
skin_spacing
40
From 8 to 200
Body threshold (HU)
body_hu
-300 CT values above it are the body (air is about -1000, fat about -100)

Where it runs

On one of your computers with the EsaSim worker: Any worker. The worker installs the Python packages it needs when they are missing: numpy</code>, <code>scipy</code>, <code>scikit-image</code>, <code>trimesh</code>, <code>fast-simplification</code>, <code>SimpleITK.

In its code, settings are ctx.params["key"], inputs ctx.inputs["id"] and outputs ctx.output("id", "name.ext"); see Custom blocks.

More in Simulation