@harpern/edu-modelhub-viewer-core 0.1.0-beta.0

package/dist/markers.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Annotation markers.
+ *
+ * Two presentations, one numbering. Sprites live in the 3D scene and follow
+ * the model; projected screen positions let a host draw real HTML buttons
+ * over the canvas, which is the accessible option because a sprite cannot be
+ * focused or read by a screen reader.
+ *
+ * Numbers always follow reading order, so what a sighted user sees and what a
+ * screen reader announces cannot disagree.
+ */
+import { Sprite, Vector3 } from "three";
+import type { Camera, Object3D } from "three";
+import type { MarkerAnchor } from "./normalize.js";
+/** Colours for a marker's circle and number. */
+export interface MarkerColors {
+    fill?: string;
+    text?: string;
+    textStroke?: string;
+}
+/** Default unselected marker colour. */
+export declare const MARKER_FILL = "#2196f3";
+/** Default selected marker colour. */
+export declare const MARKER_FILL_ACTIVE = "#ff5722";
+/**
+ * Draw a numbered marker: a filled circle, a white ring, and the number.
+ * Rendered at 256px so it stays crisp when the camera is close.
+ */
+export declare function drawMarkerCanvas(value: number | string, colors?: MarkerColors): HTMLCanvasElement;
+/**
+ * A numbered sprite for the 3D scene.
+ *
+ * `depthTest` is off so a marker is never swallowed by the geometry it sits
+ * on; occlusion, when a viewer wants it, is decided explicitly in
+ * `occlusion.ts` rather than by the depth buffer.
+ */
+export declare function createMarkerSprite(value: number | string, scale?: number, colors?: MarkerColors): Sprite;
+/** Redraw a sprite's texture in a new colour, disposing the old one. */
+export declare function setMarkerSpriteColor(sprite: Sprite, value: number | string, fill: string): void;
+/**
+ * Add one sprite per marker anchor, parented to the model so they inherit
+ * its centring and scaling. Returns the sprites in reading order.
+ */
+export declare function createMarkerSprites(model: Object3D, anchors: readonly MarkerAnchor[], scale?: number, colors?: MarkerColors): Sprite[];
+/** Where one marker landed on screen, and how to draw it. */
+export interface MarkerScreenPosition {
+    x: number;
+    y: number;
+    /** Perspective scale relative to the camera's distance to its target. */
+    scale: number;
+    /** Nearer markers stack above farther ones; occluded ones sink below both. */
+    zIndex: number;
+    /** False when the marker is behind the camera or outside the frame. */
+    inView: boolean;
+    occluded: boolean;
+}
+/** Inputs for {@link projectMarkers}. */
+export interface ProjectMarkersOptions {
+    camera: Camera;
+    model: Object3D;
+    anchors: readonly MarkerAnchor[];
+    width: number;
+    height: number;
+    /** Camera-to-target distance, so marker size tracks zoom. */
+    referenceDistance?: number;
+    /** Optional occlusion test; see `occlusion.ts`. */
+    isOccluded?: (world: Vector3, distance: number) => boolean;
+}
+/**
+ * Project every marker anchor into canvas pixel space.
+ *
+ * Call after each render. Depth survives two ways: stacking order, so a near
+ * marker covers a far one, and a scale factor, so distance reads visually.
+ */
+export declare function projectMarkers(options: ProjectMarkersOptions): Record<string, MarkerScreenPosition>;

package/dist/metadata.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Getting a model's metadata, from whichever source has it.
+ *
+ * The spec sets a precedence: a valid embedded `EDU_modelhub` extension wins;
+ * otherwise a `<model>.modelhub.json` sidecar beside the file; otherwise the
+ * viewer fails closed with an accessible error rather than quietly rendering
+ * a bare model as though nothing were missing.
+ *
+ * The GLB is fetched exactly once and the same bytes are returned for the
+ * caller's own loader, so the scene and the metadata can never disagree about
+ * which file they came from. Nothing here touches a renderer or the DOM.
+ */
+import { GlbParseError, type EduModelHub, type ValidationResult } from "@osuecampus/edu-modelhub-extractor";
+/** Where a payload came from. `"none"` is the fail-closed case. */
+export type MetadataSource = "embedded" | "sidecar" | "none";
+/** Result of a metadata load. */
+export interface MetadataResult {
+    /** The payload, or `null` when no source had one. */
+    payload: EduModelHub | null;
+    /** Which source supplied it. */
+    source: MetadataSource;
+    /** Validator findings for the payload; empty when there is none. */
+    findings: ValidationResult[];
+    /**
+     * Human-readable reason the load failed closed, suitable for an error
+     * region. `null` whenever a payload was found.
+     */
+    problem: string | null;
+}
+/** A metadata load plus the bytes it was read from. */
+export interface LoadedModel extends MetadataResult {
+    /** The GLB bytes, for the caller's own loader. */
+    bytes: ArrayBuffer;
+}
+/** Options for {@link loadModel}. */
+export interface LoadOptions {
+    /** Injected for tests and non-browser hosts. Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Set false to skip the sidecar request entirely. */
+    sidecar?: boolean;
+    /** Resolve a sidecar URL yourself, for hosts with rewriting asset paths. */
+    sidecarUrl?: (glbUrl: string) => string | null;
+}
+/** Only `error` findings block use; warnings are advisory. */
+export declare function errorsOf(findings: ValidationResult[]): ValidationResult[];
+/**
+ * The sidecar URL for a GLB URL: the same basename with `.modelhub.json`.
+ * Returns `null` when the URL is not a `.glb`, so there is nothing to try.
+ */
+export declare function sidecarUrlFor(glbUrl: string): string | null;
+/**
+ * The directory a GLB was fetched from, so a loader can resolve any relative
+ * URIs inside it, such as external textures.
+ *
+ * `blob:` and `data:` URLs have no directory, and neither do self-contained
+ * files, so both get an empty path, which is what loaders expect.
+ */
+export declare function resourcePathFor(url: string, base?: string): string;
+/** Fetch a URL as bytes. Works for http(s), `blob:` and `data:` alike. */
+export declare function fetchBytes(url: string, fetchImpl?: typeof fetch): Promise<ArrayBuffer>;
+/**
+ * Read the embedded payload out of GLB bytes and validate it.
+ *
+ * `parseGlb` checks the GLB header and chunk bounds and strips
+ * prototype-polluting keys, so the result is safe to spread. A malformed
+ * container throws `GlbParseError`; a well-formed one with no extension
+ * returns a `"none"` result so the caller can try the sidecar.
+ */
+export declare function readEmbedded(bytes: ArrayBuffer): MetadataResult;
+/**
+ * Load a model's metadata, trying the embedded extension and then a sidecar.
+ *
+ * Resolves rather than throws for a model with no metadata: that is a state
+ * the UI must render, not an exception. A malformed GLB container does throw,
+ * because the file itself is unusable.
+ *
+ * @throws {GlbParseError} If the GLB container is malformed.
+ */
+export declare function loadModel(url: string, options?: LoadOptions): Promise<LoadedModel>;
+/**
+ * Print validator findings compactly, so authoring mistakes surface during
+ * development without any UI. Errors warn, warnings inform.
+ */
+export declare function logFindings(findings: ValidationResult[], label?: string, console_?: Pick<Console, "warn" | "info">): void;
+export { GlbParseError };

package/dist/normalize.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Turning a raw payload into the shapes a UI can bind to.
+ *
+ * A viewer should never hand a raw `EDU_modelhub` payload straight to its
+ * components. Ids may be missing or duplicated, reading order may be absent,
+ * and marker positions may need converting. Normalizing once, here, keeps
+ * every consumer agreeing about what "annotation 3" means.
+ */
+import type { Annotation, EduModelHub, Region } from "@osuecampus/edu-modelhub-extractor";
+import { type Vec3 } from "./coordinates.js";
+/** An annotation whose id is guaranteed unique and non-empty. */
+export type IdentifiedAnnotation = Annotation & {
+    id: string;
+};
+/** A marker annotation with its position already in renderer space. */
+export interface MarkerAnchor {
+    annotation: IdentifiedAnnotation;
+    /** Position in renderer (glTF Y-up) space. */
+    position: Vec3;
+    /** Authored camera, converted to renderer space, when the payload has one. */
+    camera?: {
+        eye: Vec3;
+        target: Vec3;
+        fov?: number;
+    };
+}
+/** One run of annotation body text, optionally a link. */
+export interface BodySegment {
+    text: string;
+    url?: string;
+}
+/** Everything a UI needs, derived once from a payload. */
+export interface NormalizedModel {
+    payload: EduModelHub;
+    regions: Region[];
+    regionsById: Map<string, Region>;
+    annotations: IdentifiedAnnotation[];
+    annotationsById: Map<string, IdentifiedAnnotation>;
+    annotationsByRegion: Map<string, IdentifiedAnnotation[]>;
+    markerAnchors: MarkerAnchor[];
+    hiddenRegionIds: Set<string>;
+}
+/**
+ * Give every annotation a stable, unique id.
+ *
+ * Repeats keep storage order rather than reading order, so re-ordering a tour
+ * later never renames a pin. Bilateral labels ("Transverse process" left and
+ * right) commonly share an id in Sketchfab-era exports, and without this they
+ * would collapse onto one marker.
+ */
+export declare function normalizeAnnotationIds(annotations: readonly Annotation[] | undefined): IdentifiedAnnotation[];
+/**
+ * Annotations sorted by `readingOrder`, ties and absences keeping storage
+ * order. This is the order markers are numbered in, the order the list is
+ * rendered in, and the order a tour steps through, so they cannot disagree.
+ */
+export declare function annotationsInReadingOrder(payload: EduModelHub): IdentifiedAnnotation[];
+/** Regions sorted by `order`, ties keeping storage order. */
+export declare function regionsInOrder(payload: EduModelHub): Region[];
+/** Display name for a region, falling back to its id. */
+export declare function regionLabel(region: Region | undefined): string;
+/**
+ * Split an annotation body into plain-text and link segments.
+ *
+ * Bodies are untrusted text that may carry markdown links. Returning
+ * segments lets a UI render real anchors without ever putting payload text
+ * through `innerHTML`, which is what the spec requires.
+ */
+export declare function parseBodySegments(body: string | undefined): BodySegment[];
+/**
+ * Build every index a UI needs from one payload.
+ *
+ * Marker positions and authored cameras come out already in renderer space,
+ * so no consumer has to remember the coordinate rule.
+ */
+export declare function normalizeModel(payload: EduModelHub): NormalizedModel;

package/dist/occlusion.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Deciding whether a marker is behind the model.
+ *
+ * Markers draw on top of everything so they are never swallowed by geometry,
+ * which leaves a marker on the far side of a skull looking like it is on the
+ * near side. Testing each marker against the mesh lets a viewer dim the ones
+ * that are actually hidden.
+ *
+ * A ray per marker per frame against a few hundred thousand triangles is far
+ * too slow unmodified, so this uses `three-mesh-bvh` when the host has it.
+ * The dependency is optional: without it, `createOcclusionIndex` resolves to
+ * an index that reports nothing occluded, and markers simply all stay bright.
+ */
+import { Vector3 } from "three";
+import type { Camera, Object3D } from "three";
+/**
+ * Markers sit on, or a hair inside, the surface they label, so the ray to an
+ * unoccluded marker still hits its own mesh at about the marker's distance.
+ * Anything nearer than this margin counts as geometry in front. Expressed in
+ * normalized model units, where the longest axis is 2.
+ */
+export declare const OCCLUSION_BIAS = 0.03;
+/** Tests whether a world-space point is hidden behind geometry. */
+export interface OcclusionIndex {
+    /** True when the index can actually answer; false when it is a no-op. */
+    readonly enabled: boolean;
+    isOccluded(camera: Camera, point: Vector3, distance: number): boolean;
+    dispose(): void;
+}
+/**
+ * Build an occlusion index for a loaded model.
+ *
+ * Resolves to a no-op index when `three-mesh-bvh` is not installed or the
+ * acceleration has not been patched onto three's prototypes by the host.
+ * Skinned meshes are indexed in their bind pose, so occlusion is approximate
+ * while an animation plays.
+ */
+export declare function createOcclusionIndex(root: Object3D): Promise<OcclusionIndex>;

package/dist/regions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Binding regions to geometry.
+ *
+ * Region membership is not stored in the extension payload. Each glTF mesh
+ * primitive that belongs to a region carries `extras.modelhubRegionId`, so
+ * the binding has to be read from the loaded scene, not from the metadata.
+ *
+ * Three lookups are tried in turn, because exporters differ in what survives
+ * into the loaded scene: the extras three.js copies onto geometry userData,
+ * the raw glTF JSON when the host still has it, and finally an object whose
+ * name is itself a region id.
+ */
+import type { Mesh, Object3D, Material } from "three";
+import type { Region } from "@osuecampus/edu-modelhub-extractor";
+/** Region id to the meshes that make it up. */
+export type RegionMeshMap = Map<string, Mesh[]>;
+/** The parts of a glTF JSON this module reads. */
+export interface GltfJsonLike {
+    meshes?: {
+        name?: string;
+        primitives?: {
+            extras?: Record<string, unknown>;
+        }[];
+    }[];
+    nodes?: {
+        name?: string;
+        mesh?: number;
+    }[];
+}
+/**
+ * Build the region-to-geometry map for a loaded scene.
+ *
+ * @param root - The loaded model root (`gltf.scene`).
+ * @param gltfJson - Raw glTF JSON, when available (`gltf.parser.json`).
+ * @param regions - Payload regions, used only for the name-matching fallback.
+ */
+export declare function buildRegionMeshMap(root: Object3D, gltfJson?: GltfJsonLike, regions?: readonly Region[]): RegionMeshMap;
+/** How many meshes each region resolved to, for diagnostics and UI badges. */
+export declare function regionBindingCounts(map: RegionMeshMap): Record<string, number>;
+/** Show or hide every mesh bound to one region. */
+export declare function setRegionVisible(map: RegionMeshMap, regionId: string, visible: boolean): void;
+/**
+ * Apply each region's `visibilityDefault` on load.
+ *
+ * Required by the spec and implemented by neither viewer before this package:
+ * a region authored as hidden was showing up anyway.
+ */
+export declare function applyVisibilityDefaults(map: RegionMeshMap, hiddenRegionIds: ReadonlySet<string>): void;
+/** Swap in a highlight material, remembering what was there before. */
+export declare function highlightRegion(map: RegionMeshMap, regionId: string, material: Material): void;
+/** Put a region's authored material back. */
+export declare function clearRegionHighlight(map: RegionMeshMap, regionId: string): void;

package/dist/transcript.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Markdown transcript of everything a model says.
+ *
+ * A linear, offline-readable equivalent of the whole viewer experience, for
+ * screen reader and braille users who want the content without driving a 3D
+ * scene. Pure string building: no DOM, so it runs in Node and in tests.
+ */
+import type { EduModelHub } from "@osuecampus/edu-modelhub-extractor";
+/** Options for {@link buildTranscript}. */
+export interface TranscriptOptions {
+    /** Heading for the summary section. */
+    summaryHeading?: string;
+}
+/**
+ * Build a Markdown transcript for a payload.
+ *
+ * Sections are omitted when the payload has nothing to put in them, so a
+ * sparse model produces a short document rather than a page of "not
+ * specified".
+ *
+ * @param payload - The EDU_modelhub payload.
+ * @returns Markdown text.
+ */
+export declare function buildTranscript(payload: EduModelHub, options?: TranscriptOptions): string;
+/** Filename a transcript should download as, without a path. */
+export declare function transcriptFileName(payload: EduModelHub): string;

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@harpern/edu-modelhub-viewer-core",
+  "version": "0.1.0-beta.0",
+  "description": "Framework-agnostic viewer core for EDU_modelhub models: metadata loading, normalization, region binding, annotation markers, and camera behaviour shared by every conforming viewer",
+  "license": "Apache-2.0",
+  "author": "Oregon State University Ecampus",
+  "contributors": [
+    {
+      "name": "Nick Harper",
+      "email": "nick.harper@oregonstate.edu"
+    }
+  ],
+  "keywords": [
+    "gltf",
+    "glb",
+    "edu_modelhub",
+    "3d",
+    "threejs",
+    "accessibility",
+    "viewer"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/osuecampus/3d-model-hub.git",
+    "directory": "packages/edu-modelhub-viewer-core"
+  },
+  "homepage": "https://github.com/osuecampus/3d-model-hub/tree/main/packages/edu-modelhub-viewer-core#readme",
+  "bugs": {
+    "url": "https://github.com/osuecampus/3d-model-hub/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json --emitDeclarationOnly --declarationDir dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@osuecampus/edu-modelhub-extractor": "^0.1.0-beta.0"
+  },
+  "peerDependencies": {
+    "three": ">=0.160.0",
+    "three-mesh-bvh": ">=0.7.0"
+  },
+  "peerDependenciesMeta": {
+    "three-mesh-bvh": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/three": "^0.180.0",
+    "three": "^0.180.0",
+    "typescript": "^5.4.0",
+    "vite": "^6.4.3",
+    "vitest": "^4.1.10"
+  }
+}