@thatopen/services 0.2.0 → 0.3.0

package/src/cli/templates/app/src/setups/styles.ts

@@ -0,0 +1,375 @@
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+
+/**
+ * STYLES tool — a typed, generic descriptor over the viewer's visual settings so
+ * a UI (the bottom-left helper panel) can render controls without poking the
+ * postproduction renderer internals.
+ *
+ * Every entry reads/writes LIVE: the deferred composite re-reads its `settings`
+ * each frame, the AO/FXAA flags are read per-frame, and `renderScale` /
+ * `adaptiveResolution` apply on assignment — so no rebuild or lib change is
+ * needed. Mutating a setting takes effect on the next rendered frame.
+ *
+ * NOTE on presets: setting `Style preset` runs the engine's
+ * `_applyDeferredStyle`, which overwrites `Surface color`, `Edges` and
+ * `Ambient occlusion` to the preset's combination. After changing the preset,
+ * re-read all settings to refresh the panel.
+ */
+export type StyleSetting =
+  | {
+      key: string;
+      label: string;
+      group: string;
+      type: "bool";
+      default: boolean;
+      get(): boolean;
+      set(v: boolean): void;
+    }
+  | {
+      key: string;
+      label: string;
+      group: string;
+      type: "number";
+      default: number;
+      min: number;
+      max: number;
+      step: number;
+      get(): number;
+      set(v: number): void;
+    }
+  | {
+      key: string;
+      label: string;
+      group: string;
+      type: "color"; // value is a "#rrggbb" hex string
+      default: string;
+      get(): string;
+      set(v: string): void;
+    }
+  | {
+      key: string;
+      label: string;
+      group: string;
+      type: "enum";
+      default: string | number;
+      options: { label: string; value: string | number }[];
+      get(): string | number;
+      set(v: string | number): void;
+    };
+
+const hex = (c: THREE.Color) => `#${c.getHexString()}`;
+
+// Background state is MODULE-scoped so it survives styles() re-creation (the
+// graphics panel rebuilds the descriptor on every refresh — a per-instance
+// `lastBg` re-clobbered a user-picked background to 0x202020 one frame after the
+// pick, #30). `stylesLastBg` is the remembered OPAQUE colour: it persists even
+// while transparent mode zeroes the renderer's clear colour, so toggling back to
+// opaque restores the picked hue. The 0x202020 default is applied to the
+// renderer exactly once.
+let stylesBgInitialized = false;
+const stylesLastBg = new THREE.Color(0x202020);
+
+export const styles = (
+  components: OBC.Components,
+  world: OBC.World,
+): { settings: StyleSetting[] } => {
+  const renderer = world.renderer as OBF.PostproductionRenderer;
+
+  // Lazy accessors — resolved at call time so they always hit the live objects
+  // (the deferred pipeline is allocated once postproduction is up).
+  const pp = () => renderer.postproduction;
+  const deferred = () => renderer.postproduction.deferred;
+  const composite = () => renderer.postproduction.deferred.composite.settings;
+  const grid = () => components.get(OBC.Grids).list.get(world.uuid);
+  const scene = world.scene.three as THREE.Scene;
+  const three = () => renderer.three as THREE.WebGLRenderer;
+
+  // Background is driven through the RENDERER CLEAR colour/alpha, not
+  // scene.background. Under the deferred pen pipeline the composite passes the
+  // captured clear straight through for background pixels, so the clear colour IS
+  // the viewport background; setting scene.background to a THREE.Color instead
+  // makes three force-clear the capture G-buffer mid-pass and the whole model
+  // vanishes (#30). Keep scene.background null and own the clear here.
+  scene.background = null;
+  // Apply the default background ONCE (never on a rebuild — that was the #30
+  // reset). Default is TRANSPARENT (clear alpha 0) to match the
+  // `transparentBackground` setting's default:true, so on load the viewport shows
+  // whatever is behind it instead of an opaque black. The remembered hue lives in
+  // the module-scoped `stylesLastBg` for when transparency is toggled off.
+  if (!stylesBgInitialized) {
+    stylesBgInitialized = true;
+    three().setClearColor(0x000000, 0);
+  }
+
+  const A = OBF.PostproductionAspect;
+
+  const settings: StyleSetting[] = [
+    // ── Preset ──────────────────────────────────────────────────────
+    {
+      key: "preset",
+      label: "Style preset",
+      group: "Preset",
+      type: "enum",
+      default: A.COLOR_PEN_SHADOWS,
+      options: [
+        { label: "Color + edges + shadows", value: A.COLOR_PEN_SHADOWS },
+        { label: "Color", value: A.COLOR },
+        { label: "Color + edges", value: A.COLOR_PEN },
+        { label: "Color + shadows", value: A.COLOR_SHADOWS },
+        { label: "Pen (edges only)", value: A.PEN },
+        { label: "Pen + shadows", value: A.PEN_SHADOWS },
+      ],
+      get: () => pp().style,
+      set: (v) => {
+        pp().style = v as OBF.PostproductionAspect;
+      },
+    },
+    {
+      key: "postproductionEnabled",
+      label: "Postproduction",
+      group: "Preset",
+      type: "bool",
+      default: true,
+      get: () => pp().enabled,
+      set: (v) => {
+        pp().enabled = v;
+      },
+    },
+
+    // ── Edges (contour) ─────────────────────────────────────────────
+    {
+      key: "edges",
+      label: "Edges",
+      group: "Edges",
+      type: "bool",
+      default: true,
+      get: () => composite().contourEnabled,
+      set: (v) => {
+        composite().contourEnabled = v;
+      },
+    },
+    {
+      key: "edgeColor",
+      label: "Edge color",
+      group: "Edges",
+      type: "color",
+      default: "#000000",
+      get: () => hex(composite().edgeColor),
+      set: (v) => composite().edgeColor.set(v),
+    },
+    {
+      key: "edgeStrength",
+      label: "Edge strength",
+      group: "Edges",
+      type: "number",
+      default: 0.8,
+      min: 0,
+      max: 1,
+      step: 0.05,
+      get: () => composite().edgeStrength,
+      set: (v) => {
+        composite().edgeStrength = v;
+      },
+    },
+
+    // ── Shading ─────────────────────────────────────────────────────
+    {
+      key: "surfaceColor",
+      label: "Surface color (off = paper)",
+      group: "Shading",
+      type: "bool",
+      default: true,
+      get: () => composite().colorEnabled,
+      set: (v) => {
+        composite().colorEnabled = v;
+      },
+    },
+    {
+      key: "ao",
+      label: "Ambient occlusion",
+      group: "Shading",
+      type: "bool",
+      default: true,
+      get: () => deferred().settings.aoEnabled,
+      set: (v) => {
+        deferred().settings.aoEnabled = v;
+      },
+    },
+    {
+      key: "aoStrength",
+      label: "AO strength",
+      group: "Shading",
+      type: "number",
+      default: 1.0,
+      min: 0,
+      max: 2,
+      step: 0.05,
+      get: () => composite().aoStrength,
+      set: (v) => {
+        composite().aoStrength = v;
+      },
+    },
+    {
+      key: "tonalShading",
+      label: "Tonal shading",
+      group: "Shading",
+      type: "bool",
+      default: true,
+      get: () => composite().tonalShadingEnabled,
+      set: (v) => {
+        composite().tonalShadingEnabled = v;
+      },
+    },
+    {
+      key: "tonalFloor",
+      label: "Tonal floor",
+      group: "Shading",
+      type: "number",
+      default: 0.7,
+      min: 0,
+      max: 1,
+      step: 0.05,
+      get: () => composite().tonalFloor,
+      set: (v) => {
+        composite().tonalFloor = v;
+      },
+    },
+
+    // ── Scene ───────────────────────────────────────────────────────
+    {
+      key: "transparentBackground",
+      label: "Transparent background",
+      group: "Scene",
+      type: "bool",
+      default: true,
+      // Transparent === clear alpha 0 (page/scene behind shows through).
+      get: () => three().getClearAlpha() === 0,
+      set: (v) => {
+        scene.background = null;
+        if (v) {
+          // TRUE transparency: zero the RGB too, not just alpha. The composite
+          // passes the clear straight through and the canvas composites
+          // premultiplied, so a non-zero rgb at alpha 0 ADDS that colour over the
+          // page (the picked colour bled through as a tint). (0,0,0,0) = clean
+          // page-through with no tint. The hue is remembered in stylesLastBg.
+          three().setClearColor(0x000000, 0);
+        } else {
+          three().setClearColor(stylesLastBg, 1);
+        }
+      },
+    },
+    {
+      key: "backgroundColor",
+      label: "Background color",
+      group: "Scene",
+      type: "color",
+      // Reflect the remembered hue even while transparent (clear rgb is zeroed).
+      default: `#${stylesLastBg.getHexString()}`,
+      get: () => hex(stylesLastBg),
+      set: (v) => {
+        stylesLastBg.set(v);
+        scene.background = null;
+        // Choosing a colour means you want to SEE it → make the background
+        // opaque (alpha 1). The Transparent toggle re-reads alpha on refresh and
+        // flips off to match.
+        three().setClearColor(stylesLastBg, 1);
+      },
+    },
+    {
+      key: "grid",
+      label: "Grid",
+      group: "Scene",
+      type: "bool",
+      default: true,
+      get: () => grid()?.config.visible ?? false,
+      set: (v) => {
+        const g = grid();
+        if (g) g.config.visible = v;
+      },
+    },
+    {
+      key: "gridColor",
+      label: "Grid color",
+      group: "Scene",
+      type: "color",
+      default: "#d3d3d3",
+      get: () => {
+        const g = grid();
+        return g ? hex(g.config.color) : "#d3d3d3";
+      },
+      set: (v) => {
+        const g = grid();
+        if (g) g.config.color = new THREE.Color(v);
+      },
+    },
+
+    // ── Quality / performance ───────────────────────────────────────
+    {
+      key: "fxaa",
+      label: "Anti-aliasing (FXAA)",
+      group: "Quality",
+      type: "bool",
+      default: true,
+      get: () => deferred().settings.fxaaEnabled,
+      set: (v) => {
+        deferred().settings.fxaaEnabled = v;
+      },
+    },
+    {
+      key: "renderScale",
+      label: "Render scale",
+      group: "Quality",
+      type: "number",
+      default: 1.0,
+      min: 0.25,
+      max: 1,
+      step: 0.05,
+      get: () => deferred().renderScale,
+      set: (v) => {
+        deferred().renderScale = v;
+      },
+    },
+    {
+      key: "adaptiveResolution",
+      label: "Adaptive resolution",
+      group: "Quality",
+      type: "bool",
+      default: true,
+      get: () => renderer.adaptiveResolution,
+      set: (v) => {
+        renderer.adaptiveResolution = v;
+      },
+    },
+    {
+      key: "targetFps",
+      label: "Target FPS",
+      group: "Quality",
+      type: "number",
+      default: 60,
+      min: 24,
+      max: 120,
+      step: 5,
+      get: () => renderer.adaptiveTargetFps,
+      set: (v) => {
+        renderer.adaptiveTargetFps = v;
+      },
+    },
+    {
+      key: "highResOutline",
+      label: "High-res selection outline",
+      group: "Quality",
+      type: "bool",
+      default: true,
+      // false → render the selection outline at half resolution (cheaper when a
+      // selection covers much of the screen, slightly softer); true → full res.
+      get: () => components.get(OBF.Outliner).resolutionScale >= 1,
+      set: (v) => {
+        components.get(OBF.Outliner).resolutionScale = v ? 1 : 0.5;
+      },
+    },
+  ];
+
+  return { settings };
+};

package/src/cli/templates/app/src/setups/tool-mode-manager.ts

@@ -0,0 +1,150 @@
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+
+/**
+ * Central single-active-tool manager (explicit-state discipline per the grimoire
+ * interaction-editing/modal-tools/state-machine-discipline): exactly ONE modal
+ * tool (Section / Measure / future walkthrough …) is active at a time, and while
+ * ANY tool is active the viewer's passive interactions — the Hoverer overlay and
+ * the Highlighter (hover + click-select) — are suppressed so they don't fight the
+ * tool's own picking. Both are restored when the last tool exits.
+ *
+ * A tool registers a {@link ManagedTool} and calls {@link setActive} on enter /
+ * {@link clearActive} on exit. When another tool takes over, the manager calls
+ * the previous tool's {@link ManagedTool.onDeactivate} (LOCAL teardown only — it
+ * must not call back into the manager, to avoid re-entrancy).
+ *
+ * Reachable as a per-Components singleton via {@link toolModeManager} so panels
+ * (and later walkthrough/others) can route through the same instance. (Flagging:
+ * a plain memoised singleton, not an OBC.Component — say if you'd rather it be
+ * components.get()-able and I'll wrap it.)
+ */
+export interface ManagedTool {
+  readonly id: string;
+  /**
+   * Human-readable description of what the user is doing while this tool is
+   * active (e.g. "Drawing clipping plane", "Measuring length"). Surfaced by the
+   * active-tool HUD — which only reads this, so any future tool that registers a
+   * label shows up there with no HUD changes. May be a function for tools whose
+   * label varies while active (call {@link ToolModeManager.refresh} to update).
+   */
+  readonly label: string | (() => string);
+  /** Optional mdi icon name (e.g. "mdi:scissors-cutting") shown next to the label. */
+  readonly icon?: string;
+  /** Called when another tool takes over; do LOCAL teardown only (no manager calls). */
+  onDeactivate(): void;
+}
+
+export class ToolModeManager {
+  // Always a real tool — the resting default is `selectTool` (never null), so
+  // SELECT is a first-class state: reflected by the HUD, and entered via the same
+  // setActive() exclusivity path as every other tool (so clicking Select
+  // deactivates whatever modal tool was active, just like clip↔measure).
+  private _active: ManagedTool;
+  private _suppressed = false;
+  private _prevHovererEnabled = true;
+  private _prevHighlighterEnabled = true;
+
+  /** Fires whenever the active tool changes (carries the new active tool, which
+   *  is `selectTool` in the default mode). `| null` kept for HUD back-compat. */
+  readonly onActiveChanged = new OBC.Event<ManagedTool | null>();
+
+  /**
+   * The default SELECT tool — plain object hover + click-select. It is the
+   * resting active tool (on load and after any modal tool exits) and is the ONE
+   * tool that does NOT suppress viewer interaction (Select IS that mode).
+   */
+  private readonly selectTool: ManagedTool = {
+    id: ToolModeManager.SELECT_ID,
+    label: "Select",
+    icon: "mdi:cursor-default",
+    onDeactivate: () => {},
+  };
+
+  constructor(private readonly components: OBC.Components) {
+    this._active = this.selectTool;
+  }
+
+  /**
+   * Id of the implicit default mode: idle / plain object-selection. Active on load
+   * and whenever no modal tool is engaged. The Select toolbar button maps to it,
+   * and the HUD reflects it as the resting state.
+   */
+  static readonly SELECT_ID = "select";
+
+  get active(): ManagedTool {
+    return this._active;
+  }
+
+  /** The active tool's id ({@link ToolModeManager.SELECT_ID} in the default mode). */
+  getActiveId(): string {
+    return this._active.id;
+  }
+
+  /** True in the default object-selection mode (no modal tool active). */
+  get isSelectMode(): boolean {
+    return this._active === this.selectTool;
+  }
+
+  /**
+   * Return to SELECT (the default): exit whatever modal tool is active so the
+   * viewer is back to idle hover + click-select. No-op if already in select. The
+   * Select toolbar button calls this; individual tools still exit via clearActive.
+   */
+  selectMode() {
+    this.setActive(this.selectTool);
+  }
+
+  /** Make `tool` the single active tool, deactivating the previous one. */
+  setActive(tool: ManagedTool) {
+    if (this._active === tool) return;
+    this._active.onDeactivate(); // tear down the previous tool (selectTool: no-op)
+    this._active = tool;
+    // Suppress passive hover/select for MODAL tools only — selectTool IS that mode.
+    this._applySuppression(tool !== this.selectTool);
+    this.onActiveChanged.trigger(this._active);
+  }
+
+  /** Exit `tool` back to the default SELECT tool (no-op unless it's the active one). */
+  clearActive(tool: ManagedTool) {
+    if (this._active !== tool) return;
+    this.setActive(this.selectTool);
+  }
+
+  /**
+   * Re-emit the current active tool without changing it — for a tool whose
+   * dynamic {@link ManagedTool.label} changed while it stayed active (e.g. the
+   * measurement tool switching length → area), so the HUD re-reads the label.
+   */
+  refresh() {
+    this.onActiveChanged.trigger(this._active);
+  }
+
+  private _applySuppression(suppress: boolean) {
+    if (suppress === this._suppressed) return; // only act on a real transition
+    const hoverer = this.components.get(OBF.Hoverer);
+    const highlighter = this.components.get(OBF.Highlighter);
+    if (suppress) {
+      this._prevHovererEnabled = hoverer.enabled;
+      this._prevHighlighterEnabled = highlighter.enabled;
+      hoverer.enabled = false;
+      highlighter.enabled = false;
+    } else {
+      hoverer.enabled = this._prevHovererEnabled;
+      highlighter.enabled = this._prevHighlighterEnabled;
+    }
+    this._suppressed = suppress;
+  }
+}
+
+const instances = new WeakMap<OBC.Components, ToolModeManager>();
+
+/** Per-Components singleton accessor. */
+export const toolModeManager = (components: OBC.Components): ToolModeManager => {
+  let manager = instances.get(components);
+  if (!manager) {
+    manager = new ToolModeManager(components);
+    instances.set(components, manager);
+  }
+  return manager;
+};

package/src/cli/templates/app/src/setups/tool-mode.ts

@@ -0,0 +1,23 @@
+/**
+ * Controller returned by each toolbar mode-tool setup (`clipper`,
+ * `lengthMeasurement`, `areaMeasurement`, …). The toolbar — owned by Worker 2 —
+ * calls {@link activate} to enter the tool's mode and {@link deactivate} to exit
+ * it, and guarantees only one mode is active at a time (mutual exclusion).
+ *
+ * Contract:
+ *  - `activate()`   — enable the tool's pointer/keyboard listeners + cursor.
+ *  - `deactivate()` — remove those listeners and drop any transient in-progress
+ *                     state. It must NOT discard finished results (e.g. existing
+ *                     section planes / measurements persist across mode switches).
+ *  Both are idempotent.
+ */
+export interface ModeTool {
+  /** Human label, used for the toolbar button tooltip. */
+  label: string;
+  /** Iconify icon name, e.g. "mdi:scissors-cutting". */
+  icon: string;
+  /** Enter the tool's mode. */
+  activate(): void;
+  /** Exit the tool's mode and clean up transient state. */
+  deactivate(): void;
+}