Skip to main content

qualia_client_core/wellfair/
anatomy_pack.rs

1//! Produce a shippable **curated `.hmc` anatomy asset pack** for a model.
2//!
3//! The full CCF/HRA reference body is ~200–290 MB of GLB per model — too large to
4//! bundle into a release. This builds a *curated* subset (a representative set of
5//! organs across body systems, tens of MB) into a single `.hmc` bundle (see
6//! [`qualia_core_db::bundle`]): each organ is a sealed `.10d` entry carrying an
7//! `AnatomyOrganMeta` (system + approximate position + neutral colour). The
8//! bundle is the artefact shipped in the desktop release resources and published
9//! for the web demo, so a fresh install / the online demo renders a real body
10//! with no per-user download.
11//!
12//! This is a **producer** (used by the `build_anatomy_pack` example / CI), not a
13//! runtime path — it does blocking network I/O against the HRA endpoints.
14
15#![cfg(not(target_arch = "wasm32"))]
16
17use std::collections::HashMap;
18use std::path::Path;
19
20use serde::Serialize;
21use wellfare_core::anatomy::{normalize_organ_key, system_memberships_for_organ, AnatomyModel};
22
23use qualia_core_db::bundle::BundleWriter;
24use qualia_core_db::q42_volume::UnifiedVolumeBuilder;
25use qualia_core_db::render::anatomy_pack::AnatomyOrganMeta;
26use qualia_core_db::{NQuin, QUINS_PER_BLOCK};
27
28use super::anatomy_body::{body_container, compile_body, organ_container, CompiledOrgan};
29use super::ccf_resolver::{discover_ref_organs, fetch_glb, organs_for_model, HRA_SPARQL_ENDPOINT};
30
31/// The default curated organ set — normalised base tokens (laterality/sex/`.glb`
32/// stripped). A representative spread across body systems, kept small so the pack
33/// is tens of MB. Discovery reports which of these were actually found.
34pub const CURATED_ORGAN_TOKENS: &[&str] = &[
35    // nervous
36    "brain",
37    "spinal-cord",
38    // circulatory
39    "heart",
40    // respiratory
41    "lung",
42    "trachea",
43    "larynx",
44    "main-bronchus",
45    // digestive
46    "liver",
47    "pancreas",
48    "small-intestine",
49    "large-intestine",
50    "mouth",
51    // urinary
52    "kidney",
53    "urinary-bladder",
54    "ureter",
55    // immune / lymphatic
56    "spleen",
57    "thymus",
58    "lymph-node",
59    // integumentary (skin — the outer body surface; the mixer defaults it muted so it
60    // doesn't occlude the organs, and peels it on demand)
61    "skin",
62    // sensory
63    "eye",
64    // skeletal
65    "pelvis",
66    // reproductive (model-specific — each reference body matches only its own organs)
67    "prostate",
68    "uterus",
69    "ovary",
70    "vagina",
71    "fallopian-tube",
72];
73
74/// A discovered organ: its CCF filename and its normalised base token.
75#[derive(Debug, Clone, Serialize)]
76pub struct DiscoveredOrgan {
77    pub filename: String,
78    pub token: String,
79}
80
81/// Discover every reference organ for a model (filename + normalised token).
82/// Useful for curating [`CURATED_ORGAN_TOKENS`] against what the HRA actually
83/// serves.
84pub fn discover_model_organs(model: AnatomyModel) -> Result<Vec<DiscoveredOrgan>, String> {
85    let all =
86        discover_ref_organs(HRA_SPARQL_ENDPOINT).map_err(|e| format!("SPARQL discovery: {e}"))?;
87    Ok(organs_for_model(&all, model)
88        .into_iter()
89        .map(|o| DiscoveredOrgan {
90            token: normalize_organ_key(&o.filename),
91            filename: o.filename,
92        })
93        .collect())
94}
95
96/// The result of building a pack — honest about what packed and what curated
97/// organ was not found/failed.
98#[derive(Debug, Clone, Serialize)]
99pub struct PackReport {
100    pub model: String,
101    pub out_path: String,
102    pub organs_packed: usize,
103    pub total_10d_bytes: usize,
104    pub bundle_bytes: usize,
105    /// Curated tokens that were requested but not discovered for this model.
106    pub curated_not_found: Vec<String>,
107    /// (filename, error) for organs that failed to fetch or compile.
108    pub failed: Vec<(String, String)>,
109    /// Organ keys packed, in order.
110    pub packed_keys: Vec<String>,
111    /// Size in bytes of the pack-level `.q42` provenance/semantics graph (carried in the
112    /// bundle as `body.q42` and written beside the bundle as a linkable sidecar).
113    pub q42_graph_bytes: usize,
114    /// Number of quins (facts) in the pack `.q42` graph.
115    pub q42_quins: usize,
116    /// Path the `.q42` sidecar was written to.
117    pub q42_sidecar_path: String,
118}
119
120/// `male` or `female`. Anything else is refused.
121pub fn model_from_token(token: &str) -> Result<AnatomyModel, String> {
122    match token {
123        "male" => Ok(AnatomyModel::Male),
124        "female" => Ok(AnatomyModel::Female),
125        _ => Err("model must be male or female".into()),
126    }
127}
128
129/// Build a curated `.hmc` pack for `model` and write it to `out_path`.
130///
131/// `curated` is the set of normalised base tokens to include (defaults to
132/// [`CURATED_ORGAN_TOKENS`] when `None`). Blocking network I/O.
133pub fn build_anatomy_pack(
134    model: AnatomyModel,
135    out_path: impl AsRef<Path>,
136    curated: Option<&[&str]>,
137) -> Result<PackReport, String> {
138    let out_path = out_path.as_ref();
139
140    // Discover every reference organ for this model.
141    let all =
142        discover_ref_organs(HRA_SPARQL_ENDPOINT).map_err(|e| format!("SPARQL discovery: {e}"))?;
143    let model_organs = organs_for_model(&all, model);
144
145    // `Some(list)` selects a curated subset by normalised token; `None` builds the COMPLETE body —
146    // every discovered reference organ for the model (skin, vasculature, and all). Since the renderer
147    // now places organs by their true shared-space coordinates, no per-organ position curation is needed.
148    let (selected, curated_not_found): (Vec<_>, Vec<String>) = match curated {
149        Some(list) => {
150            let sel: Vec<_> = model_organs
151                .iter()
152                .filter(|o| {
153                    let key = normalize_organ_key(&o.filename);
154                    list.iter().any(|t| key.as_str() == *t)
155                })
156                .cloned()
157                .collect();
158            let found: std::collections::BTreeSet<String> = sel
159                .iter()
160                .map(|o| normalize_organ_key(&o.filename))
161                .collect();
162            let missing: Vec<String> = list
163                .iter()
164                .filter(|t| !found.contains(**t))
165                .map(|t| (*t).to_string())
166                .collect();
167            (sel, missing)
168        }
169        None => (model_organs.clone(), Vec::new()),
170    };
171
172    if selected.is_empty() {
173        return Err(format!(
174            "no reference organs discovered for {}",
175            model.as_str()
176        ));
177    }
178
179    // Fetch each selected GLB.
180    eprintln!(
181        "atlas {}: {} reference organs",
182        model.as_str(),
183        selected.len()
184    );
185    let mut fetched: Vec<(String, Vec<u8>)> = Vec::new();
186    let mut failed: Vec<(String, String)> = Vec::new();
187    for organ in &selected {
188        match fetch_glb(&organ.glb_url) {
189            Ok(bytes) => fetched.push((organ.filename.clone(), bytes)),
190            Err(e) => failed.push((organ.filename.clone(), format!("fetch: {e}"))),
191        }
192        let done = fetched.len() + failed.len();
193        if done == selected.len() || done % 25 == 0 {
194            eprintln!(
195                "atlas {}: fetched {done}/{} ({} failed)",
196                model.as_str(),
197                selected.len(),
198                failed.len()
199            );
200        }
201    }
202
203    // Compile the fetched GLBs to sealed `.10d`.
204    let compiled = compile_body(model, &fetched);
205    for (k, e) in &compiled.failed {
206        failed.push((k.clone(), format!("compile: {e}")));
207    }
208    for organ_key in &compiled.unmapped {
209        failed.push((organ_key.clone(), "unmapped: no body-system mapping".into()));
210    }
211
212    // Pack each compiled organ as a `.10d` entry with its render meta.
213    let mut writer = BundleWriter::new();
214    let mut total_10d_bytes = 0usize;
215    let mut packed_keys: Vec<String> = Vec::new();
216    for organ in &compiled.organs {
217        // All systems this organ participates in (primary first) — so the pack supports colouring by the
218        // primary system OR blending across memberships, and a condition on any member system lights it.
219        let systems: Vec<String> = system_memberships_for_organ(&organ.organ_key)
220            .into_iter()
221            .map(|(s, _)| s.to_string())
222            .collect();
223        let meta = AnatomyOrganMeta {
224            system: organ.system_id.clone(),
225            label: normalize_organ_key(&organ.organ_key), // "3d-vh-m-heart.glb" → "heart"
226            systems,
227            position: position_for(&organ.organ_key),
228            rgba: palette_for(&organ.system_id),
229        };
230        let bytes = organ.asset.container_10d.clone();
231        total_10d_bytes += bytes.len();
232        writer
233            .add_file(organ.organ_key.clone(), "10d", bytes, Some(meta.to_cbor()))
234            .map_err(|e| format!("bundle add {}: {e}", organ.organ_key))?;
235        packed_keys.push(organ.organ_key.clone());
236    }
237
238    // Pack-level `.q42`: the body's provenance + organ→system semantic graph. It is the
239    // growing semantic spine the copyright panel links to, and to which disease↔organ links
240    // and — privately, client-side — the person's own conditions are later appended. Built
241    // from the SAME hypermedia containers the desktop uses, so the pack's semantics are the
242    // product's semantics (not a demo aside). Its source citations use the real CCF/HRA CDN
243    // URLs each GLB was fetched from.
244    let source_urls: HashMap<String, String> = selected
245        .iter()
246        .map(|o| (o.filename.clone(), o.glb_url.clone()))
247        .collect();
248    let (q42_bytes, q42_quins) = build_pack_q42(compiled.model, &compiled.organs, &source_urls);
249    let q42_graph_bytes = q42_bytes.len();
250    // Carried INSIDE the bundle (one attestable unit alongside the `.10d` meshes).
251    writer
252        .add_file("body.q42", "q42", q42_bytes.clone(), None)
253        .map_err(|e| format!("bundle add body.q42: {e}"))?;
254
255    let bundle = writer.build().map_err(|e| format!("bundle build: {e}"))?;
256    if let Some(parent) = out_path.parent() {
257        std::fs::create_dir_all(parent).map_err(|e| format!("create out dir: {e}"))?;
258    }
259    std::fs::write(out_path, &bundle).map_err(|e| format!("write {}: {e}", out_path.display()))?;
260
261    // Also write the same `.q42` as a standalone sidecar next to the bundle (e.g.
262    // `anatomy-male.q42`) — a directly-linkable provenance/semantics file for the web demo,
263    // byte-identical to the bundle's `body.q42` entry (one graph, two carriers, no drift).
264    let q42_sidecar = out_path.with_extension("q42");
265    std::fs::write(&q42_sidecar, &q42_bytes)
266        .map_err(|e| format!("write {}: {e}", q42_sidecar.display()))?;
267
268    Ok(PackReport {
269        model: compiled.model.as_str().to_string(),
270        out_path: out_path.display().to_string(),
271        organs_packed: compiled.compiled_count(),
272        total_10d_bytes,
273        bundle_bytes: bundle.len(),
274        curated_not_found,
275        failed,
276        packed_keys,
277        q42_graph_bytes,
278        q42_quins,
279        q42_sidecar_path: q42_sidecar.display().to_string(),
280    })
281}
282
283/// Aggregate the compiled organs into a single pack-level `.q42` graph volume: each organ
284/// becomes a hypermedia container (its sealed `.10d` ⊕ its CCF/HRA source with licence +
285/// creator ⊕ topic/system/depiction descriptors), bundled into one **body** container. The
286/// returned bytes are a valid unified v3 `.q42` (object-sorted blocks) carrying the full
287/// provenance + organ→system semantics — the same graph the desktop builds. Returns the
288/// bytes and the number of quins (facts) in the graph.
289fn build_pack_q42(
290    model: AnatomyModel,
291    organs: &[CompiledOrgan],
292    source_urls: &HashMap<String, String>,
293) -> (Vec<u8>, usize) {
294    let containers: Vec<_> = organs
295        .iter()
296        .map(|o| organ_container(o, model, source_urls.get(&o.organ_key).map(String::as_str)))
297        .collect();
298    let body = body_container(model, &containers);
299    let quins = body.quins.len();
300    (q42_bytes_from_graph(&body.quins, &body.lexicon), quins)
301}
302
303/// Serialise a quin graph + object-lexicon into unified v3 `.q42` bytes. Quins are sorted by
304/// `object` and chunked into [`QUINS_PER_BLOCK`]-sized SuperBlocks so the volume's BIDX (which
305/// the header advertises as object-sorted) is truthful and object-hash lookups resolve.
306fn q42_bytes_from_graph(quins: &[NQuin], lexicon: &HashMap<u64, String>) -> Vec<u8> {
307    let mut sorted = quins.to_vec();
308    sorted.sort_by_key(|q| q.object);
309    let mut builder = UnifiedVolumeBuilder::with_lex_map(lexicon)
310        .expect("body Q42 lexicon entries fit the current Q42LEX format");
311    for (seq, chunk) in sorted.chunks(QUINS_PER_BLOCK).enumerate() {
312        builder
313            .push_block(seq as u64, chunk)
314            .expect("body Q42 graph is object-sorted");
315    }
316    builder.finish_to_bytes()
317}
318
319/// The shipped default linear RGBA for a body system (the person's σ-derived burden colour overrides it
320/// at runtime). Delegates to the [`wellfare_core::anatomy`] **system registry** — the single source of
321/// truth for the system palette — so a registered extension system carries its own colour into the pack
322/// and no colour table drifts. Unknown/unregistered systems get the neutral swatch.
323fn palette_for(system: &str) -> [f32; 4] {
324    wellfare_core::anatomy::default_registry().color_of(system)
325}
326
327/// An approximate anatomical position `[x, y, z]` in 0..1 body space (x=right,
328/// y=up, z=front) for assembling the whole body. Approximate placement — a
329/// future pass can use real CCF spatial-placement transforms. Laterality
330/// (`-l`/`-r`) nudges x so paired organs don't overlap.
331fn position_for(filename: &str) -> [f32; 3] {
332    let token = normalize_organ_key(filename);
333    let [x, y, z] = match token.as_str() {
334        "brain" => [0.50, 0.93, 0.50],
335        "spinal-cord" => [0.50, 0.70, 0.44],
336        "trachea" => [0.50, 0.74, 0.55],
337        "thymus" => [0.50, 0.66, 0.55],
338        "heart" => [0.50, 0.60, 0.55],
339        "lung" => [0.42, 0.62, 0.50],
340        "liver" => [0.57, 0.53, 0.52],
341        "stomach" => [0.44, 0.52, 0.52],
342        "spleen" => [0.60, 0.52, 0.44],
343        "pancreas" => [0.50, 0.50, 0.46],
344        "gallbladder" => [0.56, 0.51, 0.55],
345        "kidney" => [0.50, 0.47, 0.40],
346        "small-intestine" => [0.50, 0.42, 0.55],
347        "large-intestine" => [0.50, 0.42, 0.60],
348        "urinary-bladder" => [0.50, 0.33, 0.55],
349        "larynx" => [0.50, 0.77, 0.55],
350        "main-bronchus" => [0.50, 0.66, 0.50],
351        "mouth" => [0.50, 0.85, 0.56],
352        "ureter" => [0.50, 0.40, 0.42],
353        "lymph-node" => [0.44, 0.68, 0.50],
354        "eye" => [0.50, 0.90, 0.57],
355        "pelvis" => [0.50, 0.35, 0.50],
356        "skin" => [0.50, 0.50, 0.50],
357        "prostate" => [0.50, 0.31, 0.50],
358        "uterus" => [0.50, 0.34, 0.50],
359        "ovary" => [0.50, 0.37, 0.45],
360        "vagina" => [0.50, 0.29, 0.50],
361        "fallopian-tube" => [0.50, 0.38, 0.45],
362        _ => [0.50, 0.50, 0.50],
363    };
364    // Laterality nudge for paired organs (kidney-l/-r, lung-l/-r, …).
365    let lower = filename.to_ascii_lowercase();
366    let x = if lower.contains("-l.") || lower.contains("-left") {
367        x - 0.09
368    } else if lower.contains("-r.") || lower.contains("-right") {
369        x + 0.09
370    } else {
371        x
372    };
373    [x, y, z]
374}
375
376#[cfg(test)]
377mod tests {
378    use super::*;
379
380    /// The pack-level `.q42` must carry the real provenance (licence + source citation) and the
381    /// organ→system semantics — and open as a valid unified volume whose facts are queryable.
382    /// This is the growing semantic spine the copyright panel links to.
383    #[test]
384    fn pack_q42_carries_provenance_and_system_semantics() {
385        use qualia_core_db::q42_volume::{Q42Volume, Q42_MAGIC};
386
387        // Compile two organs whose systems are covered by the map (real GLB parsing is proven in
388        // render::assets; a stand-in OBJ triangle exercises the pack graph, not the GLB decoder).
389        const TRI_OBJ: &[u8] = b"v 0 0 0\nv 1 0 0\nv 0 1 0\nf 1 2 3\n";
390        let organs = vec![
391            ("3d-vh-m-lung.obj".to_string(), TRI_OBJ.to_vec()),
392            (
393                "3d-vh-m-blood-vasculature.obj".to_string(),
394                TRI_OBJ.to_vec(),
395            ),
396        ];
397        let body = compile_body(AnatomyModel::Male, &organs);
398        assert_eq!(body.organs.len(), 2, "both organs mapped to a system");
399
400        let mut urls = HashMap::new();
401        urls.insert(
402            "3d-vh-m-lung.obj".to_string(),
403            "https://cdn.humanatlas.io/hra/lung.glb".to_string(),
404        );
405        let (q42, quin_count) = build_pack_q42(AnatomyModel::Male, &body.organs, &urls);
406        assert!(quin_count > 0, "the graph has facts");
407        assert!(q42.starts_with(&Q42_MAGIC), "produced a Q42 volume");
408
409        // It opens as a valid unified volume and every fact round-trips.
410        let tmp = tempfile::NamedTempFile::new().unwrap();
411        std::fs::write(tmp.path(), &q42).unwrap();
412        let vol = Q42Volume::open(tmp.path()).unwrap();
413        let quins = vol.read_all_quins().unwrap();
414        assert_eq!(
415            quins.len(),
416            quin_count,
417            "every fact recoverable from the .q42"
418        );
419
420        // Resolve the string-valued objects through the embedded lexicon.
421        let lex = vol.lex_view().unwrap();
422        let vals: Vec<String> = quins
423            .iter()
424            .filter_map(|q| lex.lookup_owned(q.object))
425            .collect();
426        // Provenance: the licence and the real CDN source URL are in the graph.
427        assert!(
428            vals.iter().any(|v| v == "CC-BY-4.0"),
429            "licence fact present: {vals:?}"
430        );
431        assert!(
432            vals.iter().any(|v| v.contains("humanatlas.io")),
433            "source citation present: {vals:?}"
434        );
435        // Organ→system: lung→respiratory and blood-vasculature→circulatory are both bound.
436        assert!(
437            vals.iter().any(|v| v == "respiratory"),
438            "lung system present"
439        );
440        assert!(
441            vals.iter().any(|v| v == "circulatory"),
442            "vasculature system present"
443        );
444    }
445
446    #[test]
447    fn laterality_nudges_paired_organs_apart() {
448        let l = position_for("3d-vh-f-kidney-l.glb");
449        let r = position_for("3d-vh-f-kidney-r.glb");
450        assert!(
451            l[0] < r[0],
452            "left kidney is left of right kidney: {l:?} {r:?}"
453        );
454        // Unpaired organ is centred.
455        assert_eq!(position_for("3d-vh-m-heart.glb")[0], 0.50);
456    }
457
458    #[test]
459    fn palette_covers_systems_with_neutral_fallback() {
460        // Canonical ids from wellfare_core::anatomy::systems get real colours…
461        assert_eq!(palette_for("circulatory")[0], 0.80);
462        assert_eq!(palette_for("immune_lymphatic")[1], 0.82);
463        // …and every organ we actually pack resolves to a non-default colour.
464        for sys in [
465            "nervous",
466            "circulatory",
467            "respiratory",
468            "digestive",
469            "urinary",
470            "immune_lymphatic",
471        ] {
472            assert_ne!(
473                palette_for(sys),
474                [0.62, 0.66, 0.72, 1.0],
475                "{sys} should have a colour"
476            );
477        }
478        // Unknown system falls back to neutral.
479        assert_eq!(palette_for("unknown-system"), [0.62, 0.66, 0.72, 1.0]);
480    }
481}