@somakine/vue

A Vue 3 component for the Somakine 3D anatomy viewer.

npm install @somakine/vue vue three

vue and three are peer dependencies and must be installed by the host application.

<script setup lang="ts">
import { ref } from "vue";
import { SomakineViewer, type SomakineViewerHandle } from "@somakine/vue";
import { musculoskeletalBasic } from "@somakine/musculoskeletal-basic";

const viewer = ref<SomakineViewerHandle>();
</script>

<template>
  <SomakineViewer
    ref="viewer"
    :dataset="musculoskeletalBasic"
    accessible-label="Interactive body model"
    style="height: 32rem"
    @selection="(selection) => console.log(selection.label)"
    @state-change="(state) => console.log(state.phase, state.message)"
    @structure-transform-change="(change) => console.log(change.structureId, change.offset)"
  />
</template>

The component owns the host element and the viewer's lifecycle (creation and disposal). The viewer owns the canvas, scene, semantic events, verified loading, and resource disposal. The host application still owns controls, navigation, labels, panels, and educational content.

Props

| Prop | Type | Notes | | --- | --- | --- | | dataset | DataPack | Required. Validated Somakine data pack. | | accessible-label | string | Required. Canvas aria-label. | | locale | string | Initial label language. Default "en". | | background | string \| null | Clear colour, or null for transparent. | | initial-view-direction | [number, number, number] | Initial camera direction. | | initial-view-up | [number, number, number] | Camera up axis. | | initial-visible-structure-ids | readonly StructureId[] | Initial semantic subset; with loading.mode: "visible", only this subset loads initially. | | loading | ViewerLoadingOptions | Demand-driven mode and asset concurrency. | | asset-resolver | AssetResolver | Custom GLB byte resolver. |

class and style are inherited by the host element automatically (Vue's default attribute fallthrough).

Events

| Event | Payload | Fires | | --- | --- | --- | | selection | ViewerSelection | When exactly one structure is selected. | | selection-group | readonly ViewerSelection[] | For every selection change. | | state-change | ViewerState | Lifecycle state transitions. | | asset-progress | ViewerAssetProgress | Per-asset loading phases and aggregate progress. | | structure-transform-change | StructureTransformChange | Structure offset changes from host calls or move-mode gestures. | | error | unknown | Creation failure (not unmount). |

Creation-time props (dataset, background, initial-view-*, initial-visible-structure-ids, loading, asset-resolver, locale) are read when the viewer is created. To change them, remount the component — for example with a :key.

Imperative handle

A template ref exposes the viewer's imperative methods. They are no-ops until the viewer is ready (after state-change reports phase: "ready").

viewer.value?.setLocale("zh-CN");
viewer.value?.setInteractionMode("pan");
viewer.value?.selectStructure("somakine:structure:femur");
viewer.value?.focusRegion("somakine:region:knee");
viewer.value?.setExplode(0.5, { types: ["muscle"] });
viewer.value?.setInteractionMode("move");
viewer.value?.setLayerStyle("muscle", { opacity: 0.2, transparent: true });
viewer.value?.setLayerVisibility("muscle", false); // hide without reframing
function inspectPoint(clientX: number, clientY: number) {
  return viewer.value?.pickAt(clientX, clientY) ?? [];
}
await viewer.value?.preloadStructures(["somakine:structure:femur"]);
viewer.value?.reset(); // restore the complete creation-time scene state
viewer.value?.resetView(); // preserve the current semantic visibility

The handle also supports shared layer ghosting through setLayerStyle and occlusion-aware deep picking through pickAt. pickAt returns an empty array until the viewer is ready. setLayerVisibility hides a layer without loading or changing the camera, and restores only the current semantic visible subset. Hidden structures are excluded from normal picking, pickAt, and move-mode dragging.

setLayer, setVisible, focusRegion, and showBody clear highlighting without emitting a selection event. reset and resetView clear highlighting and emit an empty selection-group event. focusStructure is the selection-oriented exception: it isolates the target and emits its resolved selection.

API reference: docs/api/vue.md