ocp-viewer-core 1.0.0

package/src/notify.js

@@ -0,0 +1,112 @@
+/**
+ * Reporting viewer changes back to Python.
+ *
+ * three-cad-viewer calls a notification callback with `{key: {old, new}}` for
+ * whatever changed. This turns that into the message a host sends, and keeps a
+ * running picture of the viewer's state so a host can answer `status()` out of
+ * memory instead of asking the browser.
+ *
+ * The names here are the renderer's own notification names, which are
+ * snake_case - `clip_intersection`, `zebra_count`, `relative_time`. So nothing
+ * is translated on the way back: the renderer already emits what Python
+ * speaks, and the camelCase conversion is one-directional by the renderer's own
+ * choice rather than by ours.
+ */
+
+/*
+   Copyright 2026 Bernhard Walter
+
+   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.
+*/
+
+/**
+ * Keys that report that something happened, as opposed to what something is.
+ *
+ * These must never be accumulated into a status snapshot. An accumulated
+ * `selectedShapeIDs` replays a selection the user made minutes ago into the
+ * next measurement, against a model that may not even contain those ids.
+ *
+ * The distinction is not "does it change often". It is whether re-applying the
+ * last value to a different model still means anything.
+ */
+export const EVENT_KEYS = new Set([
+  "selectedShapeIDs",
+  "selected",
+  "lastPick",
+  "activeTool",
+  "relative_time",
+]);
+
+/**
+ * Create the notification callback.
+ *
+ * The message sent is the *delta* - only what this change carried - rather than
+ * a snapshot accumulated across every change so far. `viewer.html` accumulates
+ * into one long-lived object, which is what lets a stale event key ride along
+ * with an unrelated update. The accumulated picture still exists here, as
+ * `status`, but it holds state keys only and is never what goes on the wire.
+ *
+ * @param viewer  the viewer, read for tree states
+ * @param send    (message) => void, the host's transport
+ * @param debug   optional (label, value) => void
+ * @returns `{ notify, status }` - `notify` is the callback to hand the viewer,
+ *          `status` is the live picture to answer a status request from
+ */
+export function createNotifier({ viewer, send, debug }) {
+  const status = {};
+  let lastStatesJson = null;
+
+  function notify(change) {
+    if (debug) {
+      debug("notify", change);
+    }
+
+    const message = {};
+    let changed = false;
+
+    for (const key of Object.keys(change)) {
+      const value = change[key] == null ? undefined : change[key].new;
+      if (value === undefined) {
+        continue;
+      }
+      message[key] = value;
+      changed = true;
+      if (!EVENT_KEYS.has(key)) {
+        status[key] = value;
+      }
+    }
+
+    // Tree state is not part of the change set - the viewer reports it
+    // separately - so it is read and compared. Serialising is also how it gets
+    // cloned: `getStates()` hands back the tree's own live arrays, so keeping
+    // the reference would compare an object against itself and never report a
+    // change.
+    if (viewer != null && viewer.treeview != null) {
+      const json = JSON.stringify(viewer.treeview.getStates());
+      if (lastStatesJson == null || lastStatesJson !== json) {
+        const states = JSON.parse(json);
+        message.states = states;
+        status.states = states;
+        lastStatesJson = json;
+        changed = true;
+      }
+    }
+
+    if (changed) {
+      send(message);
+    }
+    return changed ? message : null;
+  }
+
+  return { notify, status };
+}

package/src/options.js

@@ -0,0 +1,272 @@
+/**
+ * Assembling the three option objects `Viewer.render` and `new Display` take.
+ *
+ * Which option belongs to which object is three-cad-viewer's fact rather than
+ * Python's, so the lists live here in renderer names. The config arrives in
+ * those names, Python having converted once at the boundary; no name is
+ * translated here. A key still in snake_case is a host that has not converted,
+ * and it will miss its entry and fall back to a default rather than be renamed
+ * into something plausible.
+ */
+
+/*
+   Copyright 2026 Bernhard Walter
+
+   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.
+*/
+
+// The defaults themselves, not only the key lists. They describe
+// three-cad-viewer, so every client should start from the same numbers and
+// override only what is genuinely its own - a viewer whose ambient light or
+// whose metalness differs from another's for no stated reason is a difference
+// nobody chose.
+
+/** Defaults for `Viewer.render`'s second argument. */
+export const RENDER_DEFAULTS = {
+  ambientIntensity: 1.0,
+  directIntensity: 1.1,
+  metalness: 0.3,
+  roughness: 0.65,
+  // A CSS colour rather than 0x707070. The renderer takes either, but Python
+  // always sends this form - `Color(...).web_color` - and a host that mirrors
+  // what the renderer reports back into a string-typed setting cannot take the
+  // number. One representation across the ecosystem, and it is this one.
+  edgeColor: "#707070",
+  defaultOpacity: 0.5,
+  normalLen: 0,
+  angularTolerance: 0.2,
+  deviation: 0.1,
+  defaultColor: "#e8b024",
+};
+
+/** Defaults for `Viewer.render`'s third argument. */
+export const VIEWER_DEFAULTS = {
+  timeit: false,
+  zoom: 1.0,
+  position: null,
+  quaternion: null,
+  target: null,
+  centerGrid: false,
+  gridFontSize: 12,
+  newTreeBehavior: true,
+  studioEnvironment: "studio",
+  studioEnvIntensity: 1.0,
+  studioEnvRotation: 0,
+  studioBackground: "environment",
+  studioToneMapping: "neutral",
+  studioExposure: 1.0,
+  studioShadowIntensity: 0.5,
+  studioShadowSoftness: 0.2,
+  studioAOIntensity: 0.5,
+  studioTextureMapping: "parametric",
+  studio4kEnvMaps: false,
+};
+
+/**
+ * Defaults for `new Display(container, options)`.
+ *
+ * `cadWidth`, `height` and `treeWidth` are here for completeness and are always
+ * replaced by the geometry the host measures. The tool flags say which tools
+ * exist in this surface at all, which is a host's decision - these are the
+ * common answer, not the only one.
+ */
+export const DISPLAY_DEFAULTS = {
+  cadWidth: 730,
+  height: 525,
+  treeWidth: 240,
+  glass: false,
+  tools: true,
+  theme: "browser",
+  pinning: false,
+  newTreeBehavior: true,
+  keymap: {
+    shift: "shiftKey",
+    ctrl: "ctrlKey",
+    meta: "metaKey",
+    alt: "altKey",
+  },
+  measureTools: true,
+  selectTool: true,
+  explodeTool: true,
+  // Stated here rather than left to the renderer's own default, which is
+  // `true`: a host passing `studioTool: false` to hide the Studio tab was
+  // silently keeping it, because `display.ts` tests `=== false` and the key
+  // never arrived to be tested.
+  studioTool: true,
+  zebraTool: true,
+  zscaleTool: false,
+  externalMeasurementBackend: true,
+};
+
+/** Options `Viewer.render` takes as its second argument. */
+export const RENDER_OPTION_KEYS = [
+  "ambientIntensity",
+  "directIntensity",
+  "metalness",
+  "roughness",
+  "edgeColor",
+  "defaultOpacity",
+  "normalLen",
+];
+
+/** Options `Viewer.render` takes as its third argument. */
+export const VIEWER_OPTION_KEYS = [
+  "axes",
+  "axes0",
+  // A state key `ViewerState._update` accepts and the tree builder reads on
+  // every render (`viewer.ts:1343`, `:3446`). Without it here the setting had
+  // no route at all in the two page hosts: it is not in either one's splash
+  // config, so the Display and Viewer were built with the logo config's
+  // `true`, later shows computed it and `page.js` dropped it because the
+  // Display already existed, and `apply.js` has no setter for it. Jupyter
+  // CadQuery is the contrast that proves it - there `viewer_args` carries it
+  // and it works.
+  "newTreeBehavior",
+  "blackEdges",
+  "grid",
+  "collapse",
+  "ortho",
+  "ticks",
+  "centerGrid",
+  "gridFontSize",
+  "timeit",
+  "tools",
+  "glass",
+  "up",
+  "transparent",
+  "control",
+  "panSpeed",
+  "zoomSpeed",
+  "rotateSpeed",
+  "clipSlider0",
+  "clipSlider1",
+  "clipSlider2",
+  "clipNormal0",
+  "clipNormal1",
+  "clipNormal2",
+  "clipIntersection",
+  "clipPlaneHelpers",
+  "clipObjectColors",
+  "zebraCount",
+  "zebraOpacity",
+  "zebraDirection",
+  "zebraColorScheme",
+  "zebraMappingMode",
+  "studioEnvironment",
+  "studioEnvIntensity",
+  "studioEnvRotation",
+  "studioBackground",
+  "studioToneMapping",
+  "studioExposure",
+  "studioShadowIntensity",
+  "studioShadowSoftness",
+  "studioAOIntensity",
+  "studioTextureMapping",
+  "studio4kEnvMaps",
+];
+
+/**
+ * The config's value for a key, or the fallback.
+ *
+ * `null` and `undefined` both mean "not given": a host that sends an explicit
+ * null is asking for the default, not for null. Every other falsy value -
+ * `false`, `0`, `""` - is a value the caller meant, so the test is against null
+ * rather than truthiness. Getting that wrong turns `axes: false` into `axes:
+ * true` wherever the default is on.
+ */
+export function preset(config, key, fallback) {
+  return config == null || config[key] == null ? fallback : config[key];
+}
+
+/** Pick a list of keys out of the config, defaulting each. */
+function pick(keys, config, defaults) {
+  const options = {};
+  for (const key of keys) {
+    const value = preset(config, key, defaults == null ? undefined : defaults[key]);
+    // A key nobody has a value for is left out rather than passed as
+    // undefined. The two are not the same to the renderer: an option that is
+    // present is applied, and applying undefined resets whatever it names -
+    // which for a camera key means the viewer reports null back, and a host
+    // whose settings are typed refuses it.
+    //
+    // It matters most for a host whose config comes from what a user has set
+    // rather than from a stored workspace, where most keys are legitimately
+    // absent.
+    if (value !== undefined) {
+      options[key] = value;
+    }
+  }
+  return options;
+}
+
+// Each builder starts from the core's defaults and lets a host override the
+// ones that are genuinely its own. A host that passes nothing gets the shared
+// answer, which is the point: the numbers describe three-cad-viewer, so a
+// client differing from another for no stated reason is a difference nobody
+// chose.
+
+export function buildRenderOptions(config, overrides) {
+  return pick(RENDER_OPTION_KEYS, config, { ...RENDER_DEFAULTS, ...overrides });
+}
+
+export function buildViewerOptions(config, overrides) {
+  return pick(VIEWER_OPTION_KEYS, config, { ...VIEWER_DEFAULTS, ...overrides });
+}
+
+/**
+ * The display options, which are what `new Display(container, options)` reads
+ * and what seeds the viewer's state.
+ *
+ * `geometry` is the host's: only it knows the size of the surface it is drawing
+ * on and what to subtract for its own chrome. It supplies `cadWidth`, `height`
+ * and `treeWidth` already normalised.
+ *
+ * `theme` arrives as "light", "dark" or "browser" and is passed through: it is
+ * one word in every language here, and the renderer resolves "browser" itself.
+ * The boolean `dark` it replaced is gone from the vocabulary - it had not been
+ * on the wire since 2025, because each host converted it to `theme` before
+ * answering a config request.
+ */
+export function buildDisplayOptions(config, overrides, geometry) {
+  const defaults = { ...DISPLAY_DEFAULTS, ...overrides };
+  const fromConfig = pick(["glass", "tools", "keymap", "newTreeBehavior"], config, defaults);
+
+  const theme = preset(config, "theme", defaults.theme);
+
+  return {
+    ...fromConfig,
+    theme,
+    cadWidth: geometry.cadWidth,
+    height: geometry.height,
+    treeWidth: geometry.treeWidth,
+
+    // Capability flags the host owns: whether a tool exists in this surface at
+    // all is not something a document can ask for.
+    //
+    // `pinning` and `studioTool` were merged into `defaults` above and then
+    // left out of this hand-written list, so they never reached the renderer.
+    // `display.ts` reads `options.pinning` in its constructor, which is why
+    // cad-viewer-widget's pin-as-PNG button could not appear in any cell
+    // viewer, `pinning=True` asked for or defaulted. Nothing was said: an
+    // option the renderer does not receive is indistinguishable from one it
+    // was never given.
+    pinning: defaults.pinning,
+    studioTool: defaults.studioTool,
+    measureTools: defaults.measureTools,
+    selectTool: defaults.selectTool,
+    explodeTool: defaults.explodeTool,
+    zscaleTool: defaults.zscaleTool,
+    zebraTool: defaults.zebraTool,
+    externalMeasurementBackend: defaults.externalMeasurementBackend,
+  };
+}