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

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to `@osuecampus/edu-modelhub-viewer-core` are documented
+here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Metadata loading with the spec's source precedence: embedded extension,
+  then `.modelhub.json` sidecar, then a fail-closed result carrying a reason.
+  The GLB is fetched once and its bytes returned for the host's own loader.
+- Payload normalization: unique annotation ids, reading order, lookups by id
+  and by region, regions in display order, and marker anchors with positions
+  already converted to renderer space.
+- Coordinate handling, where a payload with no `coordinateSpace` is glTF Y-up
+  and only an explicit `"blender"` is converted.
+- Region-to-geometry binding from `primitive.extras.modelhubRegionId`, with
+  highlight and restore, and `visibilityDefault` applied on load.
+- Annotation markers as numbered sprites, or projected to screen positions so
+  a host can draw focusable HTML buttons over the canvas.
+- Optional marker occlusion through `three-mesh-bvh`, degrading to a no-op
+  when the host has not installed it.
+- Model framing that measures skinned meshes through their bind-pose bounds,
+  so rigged models no longer frame several times too small.
+- Camera placement preferring an authored camera, with an eased flight that
+  becomes a jump cut under reduced motion.
+- A spoken model summary, a throttled announcer, and a Markdown transcript.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on behalf
+      of the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Oregon State University
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,88 @@
+# @osuecampus/edu-modelhub-viewer-core
+
+The parts of an EDU_modelhub viewer that should not be written twice.
+
+This package holds the behaviour two viewers of the same model must agree on:
+how metadata is found, what happens when it is missing, how annotations are
+numbered, where markers sit, which geometry a region owns, and where the
+camera goes when someone selects an annotation.
+
+It renders nothing and owns no scene. Bring your own three.js renderer and
+your own interface.
+
+## Why it exists
+
+Two viewers of the same models drifted apart until each was correct about its
+own content and wrong about the other's. The costly divergences were not
+visual: they were a coordinate rule, a metadata precedence order, and an
+annotation numbering scheme. Those belong in one place.
+
+## Install
+
+The official package is not yet on npm. Publishing under the `@osuecampus`
+scope waits on the same npm org access that holds up the extractor. Once it
+lands:
+
+```sh
+yarn add @osuecampus/edu-modelhub-viewer-core three
+```
+
+Until then it is published under the maintainer’s personal scope. It is this
+exact build with the same API:
+
+```sh
+yarn add @harpern/edu-modelhub-viewer-core@beta three
+```
+
+When the official package appears, change the package name in your install
+and import lines; nothing else changes. The `@harpern` package will be
+deprecated at that point with a message pointing at the new name, so your
+package manager tells you when to switch.
+
+`three` is a peer dependency. `three-mesh-bvh` is an optional peer: install
+it to get marker occlusion, leave it out and markers simply never dim.
+
+## What it does
+
+**Metadata, with the precedence the spec requires.** One fetch, embedded
+extension first, `.modelhub.json` sidecar second, and a fail-closed result
+carrying a reason when neither has anything. The same bytes come back for your
+own loader, so the scene and the metadata can never disagree about which file
+they came from.
+
+```js
+import { loadModel, normalizeModel } from "@osuecampus/edu-modelhub-viewer-core";
+
+const { payload, source, bytes, problem } = await loadModel(url);
+if (!payload) showAccessibleError(problem);
+const model = normalizeModel(payload);
+```
+
+**Normalization.** `normalizeModel` returns regions in display order,
+annotations in reading order with unique ids, lookups by id and by region, and
+marker anchors whose positions are already in renderer space.
+
+**Coordinate space.** A payload is glTF Y-up unless it explicitly says
+`"blender"`. Reading a Blender-authored file into a Y-up renderer without
+converting is the most common integration bug in this format, and silence
+used to mean the opposite, so this rule is enforced in one function.
+
+**Regions bound to geometry.** Built from `primitive.extras.modelhubRegionId`,
+which three.js copies onto the geometry's `userData` rather than the mesh's.
+`applyVisibilityDefaults` honours a region authored as hidden.
+
+**Markers.** Numbered from reading order, so the visual order and the
+announced order cannot disagree. Use sprites in the scene, or project anchors
+to screen positions and draw real HTML buttons, which is the accessible
+option because a sprite cannot be focused.
+
+**Camera.** `computeTourPlacement` prefers an authored camera and falls back
+to a computed standoff. `flyCamera` eases, or cuts straight there when the
+viewer prefers reduced motion.
+
+**Text.** A spoken model summary, a throttled announcer so held keys do not
+flood a live region, and a Markdown transcript of everything the model says.
+
+## Licence
+
+Apache-2.0.

package/dist/announce.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What the viewer says out loud.
+ *
+ * Screen reader announcements are part of the interface, not decoration, so
+ * the wording lives here rather than being retyped in each app. Camera moves
+ * are throttled: a held arrow key would otherwise flood the live region and
+ * drown out everything else.
+ */
+import type { EduModelHub } from "@osuecampus/edu-modelhub-extractor";
+/** Default gap between camera announcements, in milliseconds. */
+export declare const CAMERA_ANNOUNCE_INTERVAL = 500;
+/** A one-line summary spoken when a model finishes loading. */
+export declare function modelSummary(payload: EduModelHub | null): string;
+/** What to say when an annotation becomes the active one. */
+export declare function annotationSummary(title: string | undefined, index: number, total: number): string;
+/**
+ * Rate-limit announcements to one per `interval`.
+ *
+ * The most recent message wins: when keys are held down, what the user wants
+ * to hear is where the camera ended up, not every step along the way.
+ */
+export declare function createAnnouncer(emit: (message: string) => void, interval?: number, now?: () => number): {
+    announce: (message: string) => void;
+    flush: () => void;
+};

package/dist/backgrounds.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Viewer background colours.
+ *
+ * Which background a model sits on changes how readable it is: a pale bone
+ * specimen disappears on white and reads clearly on dark grey. Offering the
+ * same choices in every viewer means an instructor who picked one for a
+ * collection gets it wherever the model is shown.
+ */
+/** One background choice. */
+export interface BackgroundOption {
+    id: string;
+    label: string;
+    /** Canonical `#rrggbb`. */
+    hex: string;
+    /** True when the colour is light enough that dark overlays read better. */
+    light: boolean;
+}
+/**
+ * The standard swatches. Dark grey is the reference background, and gallery
+ * thumbnails are captured against it.
+ */
+export declare const BACKGROUND_OPTIONS: readonly BackgroundOption[];
+/** The swatch used when nothing else is chosen. */
+export declare const DEFAULT_BACKGROUND = "dark-grey";
+/**
+ * Accept `#rgb` or `#rrggbb`, with or without the hash, and return canonical
+ * `#rrggbb`. Anything else returns an empty string, so a viewer falls back to
+ * a known swatch rather than handing an invalid colour to the renderer.
+ */
+export declare function normalizeHexColor(value: unknown): string;
+/** Perceived brightness, 0 to 1, using the usual luma weights. */
+export declare function luminance(hex: string): number;
+/**
+ * The background actually in force.
+ *
+ * A custom colour, typically chosen per collection or per model, wins over
+ * the named swatch, and its `light` flag is measured rather than declared so
+ * overlays stay readable on a colour nobody anticipated.
+ */
+export declare function resolveBackground(backgroundId?: string, custom?: string): BackgroundOption;

package/dist/camera.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Moving the camera to an annotation.
+ *
+ * Two jobs: work out where the camera should be for a given annotation, and
+ * get it there. They are separate because the placement is worth testing on
+ * its own, while the movement is a render loop.
+ *
+ * Authored cameras win. When a payload carries one, the camera flies to the
+ * exact eye the author framed. Sources like Sketchfab encode the look
+ * direction as a point right beside the eye, so the raw target is useless as
+ * an orbit pivot: the pivot is placed at the anchor's depth along the
+ * authored direction instead, which keeps orbiting sane after the flight.
+ */
+import { Vector3 } from "three";
+import type { Object3D, PerspectiveCamera } from "three";
+import type { MarkerAnchor } from "./normalize.js";
+/** Where the camera should sit to view one annotation. */
+export interface CameraPlacement {
+    position: Vector3;
+    target: Vector3;
+    /** Vertical field of view in degrees, when the annotation authored one. */
+    fov?: number;
+}
+/** Tuning for the computed fallback placement. */
+export interface TourPlacementOptions {
+    /**
+     * `true` puts the camera between the model centre and the annotation,
+     * looking outward, which suits interior walkthrough scenes. `false` puts it
+     * beyond the annotation looking back at the centre, which suits a single
+     * specimen and needs a real standoff or the camera lands inside the mesh.
+     */
+    outward?: boolean;
+    outwardDistance?: number;
+    inwardDistance?: number;
+}
+/** Default standoffs, in normalized model units (longest axis 2). */
+export declare const TOUR_DISTANCE_OUTWARD = 0.5;
+export declare const TOUR_DISTANCE_INWARD = 1.5;
+/**
+ * Work out where to put the camera for one annotation.
+ *
+ * @param anchor - The marker anchor, positions already in renderer space.
+ * @param model - The loaded model, for its world transform.
+ */
+export declare function computeTourPlacement(anchor: MarkerAnchor, model: Object3D, options?: TourPlacementOptions): CameraPlacement;
+/** Minimal orbit-controls surface this module drives. */
+export interface ControlsLike {
+    target: Vector3;
+    update(): void;
+}
+/** Options for {@link flyCamera}. */
+export interface FlyOptions {
+    camera: {
+        position: Vector3;
+    };
+    controls: ControlsLike;
+    to: CameraPlacement;
+    /** Jump straight there instead of animating. */
+    reducedMotion?: boolean;
+    durationMs?: number;
+    /** Called after each step so the host can request a render. */
+    onFrame?: () => void;
+    /** Called once the move finishes or is cancelled. */
+    onDone?: () => void;
+}
+/** Handle for an in-flight camera move. */
+export interface Flight {
+    cancel(): void;
+}
+/**
+ * Move the camera to a placement, easing unless the user prefers reduced
+ * motion, in which case it cuts straight there. Returns a handle so a new
+ * move, or a teardown, can cancel one already running.
+ */
+export declare function flyCamera(options: FlyOptions): Flight;
+/** Apply a placement's field of view, or fall back to the viewer default. */
+export declare function applyFov(camera: PerspectiveCamera, fov: number | undefined, defaultFov: number): void;

package/dist/coordinates.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Coordinate space handling.
+ *
+ * EDU_modelhub payloads store marker and camera positions in one of two
+ * spaces, named by the root `coordinateSpace` field. Web renderers are Y-up,
+ * Blender is Z-up, and getting this wrong puts every annotation marker in the
+ * wrong place, which is the single most common integration bug.
+ *
+ * The rule: a payload is glTF Y-up unless it explicitly says `"blender"`.
+ * Silence used to mean Blender Z-up, on the assumption that an undeclared
+ * file was an old one. The published content says otherwise, so an
+ * undeclared payload is now read as Y-up and only an explicit marker is
+ * converted.
+ */
+import type { EduModelHub } from "@osuecampus/edu-modelhub-extractor";
+/** A position as stored in a payload, or as handed to a renderer. */
+export type Vec3 = [number, number, number];
+/** True when `value` is three finite numbers. */
+export declare function isVec3(value: unknown): value is Vec3;
+/**
+ * Whether a payload's positions need converting before a Y-up renderer uses
+ * them. Only an explicit `"blender"` does.
+ */
+export declare function needsConversion(coordinateSpace: EduModelHub["coordinateSpace"]): boolean;
+/**
+ * Convert one stored position into renderer (glTF Y-up) space.
+ *
+ * Returns `null` when `position` is not three finite numbers, rather than
+ * throwing: a payload that failed validation can still reach a viewer, and
+ * one bad marker must not take down every other marker with it.
+ *
+ * @param position - Position as stored in the payload.
+ * @param coordinateSpace - The payload's root `coordinateSpace`.
+ */
+export declare function toViewerPosition(position: unknown, coordinateSpace?: EduModelHub["coordinateSpace"]): Vec3 | null;
+/**
+ * Convert a position from renderer space back to the payload's space, for
+ * tools that write positions rather than read them.
+ */
+export declare function fromViewerPosition(position: unknown, coordinateSpace?: EduModelHub["coordinateSpace"]): Vec3 | null;

package/dist/dispose.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Freeing a model.
+ *
+ * Switching models without disposing leaks GPU memory a frame at a time until
+ * the context is lost, which on a gallery of hundreds of models happens well
+ * inside one session.
+ */
+import type { Object3D } from "three";
+/** Free every geometry, material, and texture under `root`. */
+export declare function disposeSceneGraph(root: Object3D | null | undefined): void;

package/dist/framing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Fitting a model into view.
+ *
+ * Models arrive at wildly different scales, so every viewer normalizes them
+ * to a known size and centres them at the origin. Doing it the same way in
+ * both apps means an authored camera means the same thing in each.
+ */
+import { Box3 } from "three";
+import type { Object3D } from "three";
+/** Size the longest axis is normalized to. */
+export declare const NORMALIZED_SIZE = 2;
+/**
+ * World bounding box of a model as it will actually render.
+ *
+ * `Box3.setFromObject` measures raw geometry, which for a skinned mesh
+ * ignores the armature's bone transforms. A rigged model carrying a scaled
+ * armature then measures several times wrong and frames far too small, so
+ * skinned meshes are measured through their own bind-pose bounds instead.
+ */
+export declare function computeDisplayBox(root: Object3D): Box3;
+/**
+ * Scale a model so its longest axis is `size`, then centre it at the origin.
+ * Mutates the model's transform and returns the scale factor applied.
+ */
+export declare function frameModel(root: Object3D, size?: number): number;
+/**
+ * Camera distance that frames a normalized model at a given vertical field of
+ * view. Narrow fields of view need to sit much further back, which is why a
+ * fixed distance looks wrong as soon as a model overrides the default.
+ */
+export declare function distanceForFov(fovDegrees: number, margin?: number): number;

package/dist/index.cjs

@@ -0,0 +1,21 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const h=require("@osuecampus/edu-modelhub-extractor"),m=require("three");function R(e){return e.filter(t=>t.severity==="error")}function v(e){const[t,i=""]=e.split("?",2);if(!/\.glb$/i.test(t))return null;const n=t.replace(/\.glb$/i,".modelhub.json");return i?`${n}?${i}`:n}function K(e,t){var o;if(!e||e.startsWith("blob:")||e.startsWith("data:"))return"";const i=t??((o=globalThis.location)==null?void 0:o.href),n=i?new URL(e,i).href:e,r=n.lastIndexOf("/");return r===-1?"":n.slice(0,r+1)}async function $(e,t=fetch){const i=await t(e);if(!i.ok)throw new Error(`Failed to fetch ${e} (HTTP ${i.status}).`);return i.arrayBuffer()}function _(e){const t=h.parseGlb(e);if(!t)return{payload:null,source:"none",findings:[],problem:"This model carries no EDU_modelhub metadata."};const i=h.validate(t);return{payload:t,source:"embedded",findings:i,problem:null}}async function q(e,t={}){const i=t.fetchImpl??fetch,n=await $(e,i),r=_(n);if(r.payload)return{...r,bytes:n};if(t.sidecar===!1)return{...r,bytes:n};const s=(t.sidecarUrl??v)(e);if(!s)return{...r,bytes:n};try{const c=await i(s);if(c.ok){const u=h.adaptSidecar(await c.json());return{payload:u,source:"sidecar",findings:h.validate(u),problem:null,bytes:n}}}catch{}return{payload:null,source:"none",findings:[],problem:"This model has no EDU_modelhub metadata, either embedded in the file or in a sidecar beside it.",bytes:n}}function j(e,t="EDU_modelhub",i=console){if(!(e!=null&&e.length))return;const n=R(e),r=e.filter(o=>o.severity!=="error");n.length&&i.warn(`${t}: ${n.length} validation error(s)`,n),r.length&&i.info(`${t}: ${r.length} validation warning(s)`,r)}function T(e){return Array.isArray(e)&&e.length===3&&e.every(t=>typeof t=="number"&&Number.isFinite(t))}function A(e){return e==="blender"}function x(e,t){if(!T(e))return null;const[i,n,r]=e;return A(t)?[i,r,-n]:[i,n,r]}function Z(e,t){if(!T(e))return null;const[i,n,r]=e;return A(t)?[i,-r,n]:[i,n,r]}function C(e){if(!Array.isArray(e))return[];const t=new Set;return e.map((i,n)=>{const o=(typeof(i==null?void 0:i.id)=="string"?i.id.trim():"")||`annotation-${n+1}`;let s=o,c=2;for(;t.has(s);)s=`${o}-${c++}`;return t.add(s),{...i??{},id:s}})}function M(e){const t=C(e==null?void 0:e.annotations),i=n=>Number.isFinite(n.readingOrder)?n.readingOrder:Number.MAX_SAFE_INTEGER;return t.map((n,r)=>({annotation:n,index:r})).sort((n,r)=>i(n.annotation)-i(r.annotation)||n.index-r.index).map(n=>n.annotation)}function S(e){return(Array.isArray(e==null?void 0:e.regions)?e.regions:[]).map((i,n)=>({region:i,index:n})).sort((i,n)=>(i.region.order??Number.MAX_SAFE_INTEGER)-(n.region.order??Number.MAX_SAFE_INTEGER)||i.index-n.index).map(i=>i.region)}function I(e){var t;return e?((t=e.label)==null?void 0:t.trim())||e.id||"Unnamed region":"Unknown region"}function X(e){if(!e)return[];const t=[],i=/\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g;let n=0,r;for(;(r=i.exec(e))!==null;)r.index>n&&t.push({text:e.slice(n,r.index)}),t.push({text:r[1],url:r[2]}),n=r.index+r[0].length;return n<e.length&&t.push({text:e.slice(n)}),t.filter(o=>o.text.trim()||o.url)}function Q(e){const t=e==null?void 0:e.coordinateSpace,i=S(e),n=M(e),r=new Map(i.map(a=>[a.id,a])),o=new Map(n.map(a=>[a.id,a])),s=new Map;for(const a of n){const l=a.regionId;if(!l)continue;const d=s.get(l);d?d.push(a):s.set(l,[a])}const c=[];for(const a of n){const l=a.anchor;if(!l||l.type!=="marker")continue;const d=x(l.position,t);if(!d)continue;const f=a.camera,p=f?x(f.eye,t):null,g=f?x(f.target,t):null;c.push({annotation:a,position:d,...p&&g?{camera:{eye:p,target:g,...f!=null&&f.fov?{fov:f.fov}:{}}}:{}})}const u=new Set(i.filter(a=>a.visibilityDefault==="hidden").map(a=>a.id));return{payload:e,regions:i,regionsById:r,annotations:n,annotationsById:o,annotationsByRegion:s,markerAnchors:c,hiddenRegionIds:u}}function Y(e){return e.isMesh===!0}function J(e,t,i=[]){var u;const n=new Map,r=new Map,o=new Map,s=new Map;for(const[a,l]of((t==null?void 0:t.meshes)??[]).entries())for(const d of l.primitives??[]){const f=(u=d.extras)==null?void 0:u.modelhubRegionId;typeof f=="string"&&f&&(s.set(a,f),l.name&&r.set(l.name,f))}for(const a of(t==null?void 0:t.nodes)??[]){if(a.mesh===void 0||!a.name)continue;const l=s.get(a.mesh);l&&o.set(a.name,l)}const c=new Set(i.map(a=>a.id));return e.traverse(a=>{var p,g;if(!Y(a))return;const l=(g=(p=a.geometry)==null?void 0:p.userData)==null?void 0:g.modelhubRegionId,d=typeof l=="string"&&l||o.get(a.name)||r.get(a.name)||(c.has(a.name)?a.name:void 0);if(!d)return;const f=n.get(d);f?f.push(a):n.set(d,[a]),a.userData.modelhubOriginalMaterial===void 0&&(a.userData.modelhubOriginalMaterial=a.material)}),n}function ee(e){const t={};for(const[i,n]of e)t[i]=n.length;return t}function B(e,t,i){for(const n of e.get(t)??[])n.visible=i}function te(e,t){for(const i of e.keys())B(e,i,!t.has(i))}function ne(e,t,i){for(const n of e.get(t)??[])n.material=i}function ie(e,t){for(const i of e.get(t)??[]){const n=i.userData.modelhubOriginalMaterial;n&&(i.material=n)}}const k="#2196f3",re="#ff5722";function N(e,t={}){const{fill:i=k,text:n="#ffffff",textStroke:r="rgba(0, 0, 0, 0.45)"}=t,o=256,s=document.createElement("canvas");s.width=o,s.height=o;const c=s.getContext("2d");return c&&(c.beginPath(),c.arc(o/2,o/2,o/2-4,0,Math.PI*2),c.fillStyle=i,c.fill(),c.strokeStyle="#ffffff",c.lineWidth=8,c.stroke(),c.fillStyle=n,c.strokeStyle=r,c.lineWidth=10,c.font="bold 132px Arial, sans-serif",c.textAlign="center",c.textBaseline="middle",c.strokeText(String(e),o/2,o/2),c.fillText(String(e),o/2,o/2)),s}function D(e,t=.2,i){const n=new m.SpriteMaterial({map:new m.CanvasTexture(N(e,i)),transparent:!0,depthTest:!1}),r=new m.Sprite(n);return r.scale.set(t,t,1),r.renderOrder=999,r}function oe(e,t,i){var r;const n=e.material;(r=n.map)==null||r.dispose(),n.map=new m.CanvasTexture(N(t,{fill:i})),n.needsUpdate=!0}function se(e,t,i=.2,n){return t.map((r,o)=>{const s=D(o+1,i,n);return s.position.set(...r.position),s.name=`modelhub_marker_${r.annotation.id}`,s.userData.annotationId=r.annotation.id,s.userData.displayNumber=o+1,e.add(s),s})}function ae(e){const{camera:t,model:i,anchors:n,width:r,height:o,isOccluded:s}=e,c=e.referenceDistance??1,u=new m.Vector3,a={};i.updateMatrixWorld();for(const l of n){u.set(...l.position).applyMatrix4(i.matrixWorld);const d=u.distanceTo(t.position),f=s?s(u,d):!1,p=u.clone().project(t);a[l.annotation.id]={x:(p.x*.5+.5)*r,y:(-p.y*.5+.5)*o,scale:Math.min(1.6,Math.max(.55,c/Math.max(d,.001))),zIndex:Math.max(1,Math.round((1-p.z)*1e5))+(f?0:2e5),inView:p.z<1&&p.x>-1.05&&p.x<1.05&&p.y>-1.05&&p.y<1.05,occluded:f}}return a}const L=.03,ce={enabled:!1,isOccluded:()=>!1,dispose:()=>{}};async function le(e){var o;let t=[],i=[];if(e.traverse(s=>{if(!s.isMesh)return;const c=s.geometry;c!=null&&c.computeBoundsTree&&(t.push(c),i.push(s))}),!t.length)return ce;for(const s of t)s.boundsTree||(o=s.computeBoundsTree)==null||o.call(s,{maxLeafTris:8});const n=new m.Raycaster;n.firstHitOnly=!0;const r=new m.Vector3;return{enabled:!0,isOccluded(s,c,u){return r.subVectors(c,s.position).normalize(),n.set(s.position,r),n.near=0,n.far=Math.max(0,u-L),n.camera=s,n.intersectObjects(i,!1).length>0},dispose(){var s;for(const c of t)(s=c.disposeBoundsTree)==null||s.call(c);t=[],i=[]}}}const y={headlight:{ambient:.7,lights:[{color:[1,1,1],intensity:.9,position:[4,8,6]},{color:[1,1,1],intensity:2.4,position:[0,0,0],attach:!0,spot:!0}]},studio:{ambient:.85,lights:[{color:[.78,.8,1],intensity:1.45,position:[1.35,6.75,-7.26]},{color:[1,.88,.71],intensity:1.5,position:[-5.71,3.5,7.43]},{color:[.42,.74,1],intensity:.25,position:[7.23,6.78,1.29]}]},"dual-cam":{ambient:.6,lights:[{color:[.6,.48,.3],intensity:1.6,position:[-1,0,1],attach:!0},{color:[.42,.42,.6],intensity:1.6,position:[1,0,1],attach:!0}]},"studio-cam":{ambient:.7,lights:[{color:[.78,.8,1],intensity:1.35,position:[-1,.3,1],attach:!0},{color:[1,.88,.71],intensity:1.4,position:[1,.3,1],attach:!0},{color:[.42,.74,1],intensity:.25,position:[7.23,6.78,1.29]}]}},U="headlight";function ue(){return Object.keys(y)}function de(e){var t;(t=e.parent)==null||t.remove(e)}function fe(e){var c;const{scene:t,camera:i,exposure:n=1}=e;(c=e.previous)==null||c.remove();const r=y[e.preset??""]??y[U],o=[],s=new m.AmbientLight(16777215,r.ambient*n);t.add(s),o.push(s);for(const u of r.lights){let a;if(u.spot){const d=new m.SpotLight(new m.Color(...u.color));d.angle=.5,d.penumbra=.9,d.decay=0,a=d}else a=new m.DirectionalLight(new m.Color(...u.color));a.intensity=u.intensity,a.position.set(...u.position);const l=a.target;u.attach?(l==null||l.position.set(0,0,u.spot?-1:0),i.add(a),l&&i.add(l)):(t.add(a),l&&t.add(l)),o.push(a),l&&o.push(l)}return{lights:o,remove(){for(const u of o)de(u);o.length=0}}}const b=[{id:"white",label:"White",hex:"#ffffff",light:!0},{id:"light-grey",label:"Light grey",hex:"#d4d4d4",light:!0},{id:"medium-grey",label:"Medium grey",hex:"#808080",light:!1},{id:"dark-grey",label:"Dark grey",hex:"#252525",light:!1},{id:"black",label:"Black",hex:"#000000",light:!1}],F="dark-grey";function V(e){if(typeof e!="string")return"";const t=e.trim().replace(/^#/,"");return/^[0-9a-f]{6}$/i.test(t)?`#${t.toLowerCase()}`:/^[0-9a-f]{3}$/i.test(t)?`#${[...t].map(i=>i+i).join("").toLowerCase()}`:""}function P(e){const t=Number.parseInt(e.replace("#",""),16);return Number.isFinite(t)?(.299*(t>>16&255)+.587*(t>>8&255)+.114*(t&255))/255:0}function me(e,t){const i=V(t);return i?{id:"custom",label:"Custom",hex:i,light:P(i)>.5}:b.find(n=>n.id===e)??b.find(n=>n.id===F)??b[0]}const G=2;function w(e){e.updateMatrixWorld(!0);const t=new m.Box3,i=new m.Box3;return e.traverse(n=>{const r=n,o=n;r.isSkinnedMesh?(r.computeBoundingBox(),r.boundingBox&&(i.copy(r.boundingBox).applyMatrix4(r.matrixWorld),t.union(i))):o.isMesh&&o.geometry&&(o.geometry.boundingBox||o.geometry.computeBoundingBox(),o.geometry.boundingBox&&(i.copy(o.geometry.boundingBox).applyMatrix4(o.matrixWorld),t.union(i)))}),t.isEmpty()?new m.Box3().setFromObject(e):t}function pe(e,t=G){const n=w(e).getSize(new m.Vector3),r=Math.max(n.x,n.y,n.z)||1,o=t/r;e.scale.multiplyScalar(o);const s=w(e);return e.position.sub(s.getCenter(new m.Vector3)),o}function ge(e,t=1.3){return t/Math.tan(e*Math.PI/360)}const z=.5,W=1.5;function he(e,t,i={}){t.updateMatrixWorld();const n=new m.Vector3(...e.position).applyMatrix4(t.matrixWorld);if(e.camera){const u=new m.Vector3(...e.camera.eye).applyMatrix4(t.matrixWorld),l=new m.Vector3(...e.camera.target).applyMatrix4(t.matrixWorld).clone().sub(u);l.lengthSq()<1e-10&&l.copy(n).sub(u),l.normalize();const d=Math.max(n.distanceTo(u),.2);return{position:u,target:u.clone().addScaledVector(l,d),...e.camera.fov?{fov:e.camera.fov}:{}}}const r=i.outward??!0,o=new m.Vector3(n.x,0,n.z);o.lengthSq()<1e-8&&o.set(0,0,1),o.normalize();const s=r?-(i.outwardDistance??z):i.inwardDistance??W,c=n.clone().addScaledVector(o,s);return c.y=n.y,{position:c,target:n}}const xe={cancel:()=>{}};function be(e){const{camera:t,controls:i,to:n,onFrame:r,onDone:o}=e,s=()=>{r==null||r(),o==null||o()};if(e.reducedMotion)return t.position.copy(n.position),i.target.copy(n.target),i.update(),s(),xe;const c=e.durationMs??900,u=t.position.clone(),a=i.target.clone(),l=performance.now();let d=null;const f=p=>{const g=Math.min((p-l)/c,1),O=g*(2-g);t.position.lerpVectors(u,n.position,O),i.target.lerpVectors(a,n.target,O),i.update(),r==null||r(),g<1?d=requestAnimationFrame(f):(d=null,o==null||o())};return d=requestAnimationFrame(f),{cancel(){d!==null&&cancelAnimationFrame(d),d=null}}}function ye(e,t,i){const n=t||i;e.fov!==n&&(e.fov=n,e.updateProjectionMatrix())}const H=500;function Me(e){var r,o,s;if(!e)return"Model loaded, but it carries no educational metadata.";const t=[];(r=e.model)!=null&&r.title&&t.push(`${e.model.title} loaded`),(o=e.model)!=null&&o.altText&&t.push(e.model.altText);const i=((s=e.regions)==null?void 0:s.length)??0,n=M(e).length;return i&&t.push(`${i} labelled ${i===1?"region":"regions"}`),n&&t.push(`${n} ${n===1?"annotation":"annotations"}`),t.map(c=>c.replace(/\.$/,"")).join(". ")+"."}function Ie(e,t,i){return`Annotation ${t+1} of ${i}: ${e||"Untitled"}.`}function we(e,t=H,i=()=>Date.now()){let n=-1/0,r=null,o=null;const s=a=>{n=i(),r=null,e(a)};return{announce:a=>{const l=i()-n;if(l>=t){s(a);return}r=a,o||(o=setTimeout(()=>{o=null,r!==null&&s(r)},t-l))},flush:()=>{o&&(clearTimeout(o),o=null),r!==null&&s(r)}}}function E(e,t){return`## ${e}
+${t}
+
+`}function Te(e,t={}){const i=e.model??{},n=S(e),r=M(e);let o=`# ${i.title||"Untitled model"}
+
+`;if(i.altText&&(o+=E(t.summaryHeading??"Summary",i.altText)),i.longDescription&&(o+=E("Full description",i.longDescription)),n.length){o+=`## Regions (${n.length})
+
+`;for(const s of n)o+=`### ${I(s)}
+${s.description||"No description."}
+
+`}return r.length&&(o+=`## Annotations (${r.length})
+
+`,r.forEach((s,c)=>{const u=s.regionId?` (${I(n.find(l=>l.id===s.regionId))})`:"",a=`${c+1}. ${s.title||"Untitled"}${u}`;o+=`### ${a}
+${s.body||"No description."}
+
+`})),o+=`## Licensing
+`,o+=`- **License:** ${i.license||"Not specified"}
+`,o+=`- **Attribution:** ${i.attribution||"Not specified"}
+`,o+=`- **Creator:** ${i.creator||"Not specified"}
+`,o+=`- **Source:** ${i.source||"Not specified"}
+`,o}function Ae(e){var i;return`${(((i=e.model)==null?void 0:i.title)||"model").trim().replace(/[^\w\-. ]+/g,"").replace(/\s+/g,"_")||"model"}_transcript.md`}function Se(e){e&&e.traverse(t=>{var o,s;const i=t,n=i.geometry;n&&(n.boundsTree&&n.disposeBoundsTree&&n.disposeBoundsTree(),(o=n.dispose)==null||o.call(n));const r=[].concat(i.material??[]);for(const c of r)if(c){for(const u of Object.values(c)){const a=u;a&&a.isTexture&&a.dispose()}(s=c.dispose)==null||s.call(c)}})}Object.defineProperty(exports,"GlbParseError",{enumerable:!0,get:()=>h.GlbParseError});exports.BACKGROUND_OPTIONS=b;exports.CAMERA_ANNOUNCE_INTERVAL=H;exports.DEFAULT_BACKGROUND=F;exports.DEFAULT_LIGHTING=U;exports.LIGHTING_PRESETS=y;exports.MARKER_FILL=k;exports.MARKER_FILL_ACTIVE=re;exports.NORMALIZED_SIZE=G;exports.OCCLUSION_BIAS=L;exports.TOUR_DISTANCE_INWARD=W;exports.TOUR_DISTANCE_OUTWARD=z;exports.annotationSummary=Ie;exports.annotationsInReadingOrder=M;exports.applyFov=ye;exports.applyLighting=fe;exports.applyVisibilityDefaults=te;exports.buildRegionMeshMap=J;exports.buildTranscript=Te;exports.clearRegionHighlight=ie;exports.computeDisplayBox=w;exports.computeTourPlacement=he;exports.createAnnouncer=we;exports.createMarkerSprite=D;exports.createMarkerSprites=se;exports.createOcclusionIndex=le;exports.disposeSceneGraph=Se;exports.distanceForFov=ge;exports.drawMarkerCanvas=N;exports.errorsOf=R;exports.fetchBytes=$;exports.flyCamera=be;exports.frameModel=pe;exports.fromViewerPosition=Z;exports.highlightRegion=ne;exports.isVec3=T;exports.lightingPresetNames=ue;exports.loadModel=q;exports.logFindings=j;exports.luminance=P;exports.modelSummary=Me;exports.needsConversion=A;exports.normalizeAnnotationIds=C;exports.normalizeHexColor=V;exports.normalizeModel=Q;exports.parseBodySegments=X;exports.projectMarkers=ae;exports.readEmbedded=_;exports.regionBindingCounts=ee;exports.regionLabel=I;exports.regionsInOrder=S;exports.resolveBackground=me;exports.resourcePathFor=K;exports.setMarkerSpriteColor=oe;exports.setRegionVisible=B;exports.sidecarUrlFor=v;exports.toViewerPosition=x;exports.transcriptFileName=Ae;

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @osuecampus/edu-modelhub-viewer-core
+ *
+ * The parts of an EDU_modelhub viewer that should not be written twice:
+ * loading metadata and failing closed without it, normalizing a payload into
+ * the shapes a UI binds to, binding regions to geometry, numbering and
+ * placing annotation markers, and moving the camera to them.
+ *
+ * Nothing here renders or owns a scene. A host brings its own three.js
+ * renderer and its own UI; this package supplies the behaviour underneath so
+ * two viewers of the same model agree about what it says.
+ */
+export { GlbParseError, errorsOf, fetchBytes, loadModel, logFindings, readEmbedded, resourcePathFor, sidecarUrlFor, type LoadOptions, type LoadedModel, type MetadataResult, type MetadataSource } from "./metadata.js";
+export { fromViewerPosition, isVec3, needsConversion, toViewerPosition, type Vec3 } from "./coordinates.js";
+export { annotationsInReadingOrder, normalizeAnnotationIds, normalizeModel, parseBodySegments, regionLabel, regionsInOrder, type BodySegment, type IdentifiedAnnotation, type MarkerAnchor, type NormalizedModel } from "./normalize.js";
+export { applyVisibilityDefaults, buildRegionMeshMap, clearRegionHighlight, highlightRegion, regionBindingCounts, setRegionVisible, type GltfJsonLike, type RegionMeshMap } from "./regions.js";
+export { MARKER_FILL, MARKER_FILL_ACTIVE, createMarkerSprite, createMarkerSprites, drawMarkerCanvas, projectMarkers, setMarkerSpriteColor, type MarkerColors, type MarkerScreenPosition, type ProjectMarkersOptions } from "./markers.js";
+export { OCCLUSION_BIAS, createOcclusionIndex, type OcclusionIndex } from "./occlusion.js";
+export { DEFAULT_LIGHTING, LIGHTING_PRESETS, applyLighting, lightingPresetNames, type LightSpec, type LightingHandle, type LightingOptions, type LightingPreset } from "./lighting.js";
+export { BACKGROUND_OPTIONS, DEFAULT_BACKGROUND, luminance, normalizeHexColor, resolveBackground, type BackgroundOption } from "./backgrounds.js";
+export { NORMALIZED_SIZE, computeDisplayBox, distanceForFov, frameModel } from "./framing.js";
+export { TOUR_DISTANCE_INWARD, TOUR_DISTANCE_OUTWARD, applyFov, computeTourPlacement, flyCamera, type CameraPlacement, type ControlsLike, type Flight, type FlyOptions, type TourPlacementOptions } from "./camera.js";
+export { CAMERA_ANNOUNCE_INTERVAL, annotationSummary, createAnnouncer, modelSummary } from "./announce.js";
+export { buildTranscript, transcriptFileName, type TranscriptOptions } from "./transcript.js";
+export { disposeSceneGraph } from "./dispose.js";