@thatopen/services 0.3.6 → 0.3.8

package/src/built-in/ClashesManager/example.ts

@@ -0,0 +1,285 @@
+/* MD
+  ## ClashesManager
+  ---
+  Structural engineers and BIM coordinators routinely detect geometric clashes
+  between disciplines — structural steel penetrating ductwork, pipes clashing
+  with slabs — and need to track the status of each issue through resolution
+  without leaving their BIM environment.
+
+  ClashesManager is the platform-side component that owns clash data: it loads and
+  persists jobs, runs, and clashes; launches cloud-based clash detection in a Web
+  Worker; and exposes the events and methods needed to build review workflows on
+  top of it.
+
+  This tutorial covers initializing the manager from the platform client; the
+  recommended `clashes-panel` UI that works out of the box once `init` has been
+  called; defining queries and detection matrices for fine-grained control;
+  launching a detection run and tracking progress; updating clash status
+  programmatically; and rendering sphere markers and element highlights without
+  the built-in panel.
+
+  By the end, you'll understand every public surface of ClashesManager and know
+  which parts are handled automatically by `clashes-panel` so you can decide how
+  much of the stack you need for your use case.
+*/
+
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as FRAGS from "@thatopen/fragments";
+import * as BUI from "@thatopen/ui";
+import { PlatformClient } from "thatopen-services";
+import clashesManagerDef from "./index";
+
+const ClashesManager = clashesManagerDef.componentDefinition;
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: ClashesManager.uuid },
+)) as { components: OBC.Components };
+
+/* MD
+  ### 🚀 Initializing the manager
+
+  `init(client)` is the only call required before using the manager. It:
+
+  - Loads all persisted clash data (jobs, runs, clashes, queries, matrices) from
+    the project's cloud storage into memory.
+  - Registers `save` and `reload` callbacks so writes are debounced to storage
+    automatically and the manager can refresh its data after a run completes.
+  - Reads any in-flight cloud executions so that a page reload mid-run doesn't
+    lose track of the job.
+  - Resolves the engine's active `World` in the background — if no world exists
+    yet, it waits until one is created, so the order of initialization does not
+    matter.
+
+  After `init` resolves, `manager.ready` is `true` and all data properties
+  (`jobs`, `runs`, `clashes`, `queries`, `matrices`) are populated.
+*/
+
+const manager = components.get(ClashesManager);
+await manager.init(client);
+
+console.log(
+  `Loaded ${manager.jobs.length} jobs, ` +
+  `${manager.runs.length} runs, ` +
+  `${manager.clashes.length} clashes.`,
+);
+
+/* MD
+  ### 🖥️ Adding the built-in panel (recommended)
+
+  Once `init` has been called, the `<clashes-panel>` web component is the
+  recommended way to interact with `ClashesManager`. It covers the full
+  review workflow — detection matrix, clash table, sphere markers, status
+  filters, run progress — with zero additional wiring.
+
+  `clashes-panel` is registered when `UIManager` is included in the platform
+  setup call. See the **clashes-panel** tutorial for the complete setup and a
+  detailed breakdown of everything the panel manages automatically.
+
+  The sections below are for cases where you need direct control: building a
+  custom UI, integrating clash data into your own panels, or automating status
+  updates from outside the panel.
+*/
+
+/* MD
+  ### 📐 Queries and matrices
+
+  A `ClashQuery` defines a named set of model elements: which files to scan and,
+  optionally, which IFC categories or attribute conditions to match. Queries have
+  no detection logic of their own — they are inputs to a matrix.
+
+  A `ClashMatrix` pairs queries in an upper-triangle grid. Each active cell
+  corresponds to one `ClashJob` that the cloud worker will execute. The matrix
+  also carries the clash type (`hard` or `clearance`) and, for clearance checks,
+  the tolerance in metres.
+
+  Assigning to `manager.queries` or `manager.matrices` triggers a debounced
+  auto-save (2 s). Call `await manager.flush()` to persist immediately before
+  navigating away.
+*/
+
+const structuralFileId = "file-id-of-structural-model";
+const mepFileId        = "file-id-of-mep-model";
+
+manager.queries = [
+  {
+    id:           "q-structural",
+    name:         "Structural",
+    modelFileIds: [structuralFileId],
+    query:        { categories: ["IFCBEAM", "IFCCOLUMN", "IFCSLAB"] },
+  },
+  {
+    id:           "q-mep",
+    name:         "MEP",
+    modelFileIds: [mepFileId],
+    // Omitting `query` matches all elements with geometry in the listed files.
+  },
+];
+
+// The matrix below defines a single hard-clash job between Structural and MEP.
+// `activePairs` lists the upper-triangle cell keys (queryAId:queryBId).
+// `jobIds` is managed by the platform when the matrix is saved; leave it empty
+// on first creation and the backend fills it after the first save.
+manager.matrices = [
+  {
+    id:          "matrix-main",
+    name:        "Structural vs MEP",
+    queryIds:    ["q-structural", "q-mep"],
+    activePairs: ["q-structural:q-mep"],
+    jobIds:      [],
+    jobType:     "hard",
+  },
+];
+
+await manager.flush();
+
+/* MD
+  ### ▶️ Running clash detection
+
+  `run(jobId)` launches a Web Worker that calls the cloud clash-detection
+  endpoint. It returns immediately — all feedback arrives through events.
+
+  | Event | Payload | When |
+  |-------|---------|------|
+  | `onRunProgress` | `{ message, progress }` | Periodically while the worker runs |
+  | `onRunComplete` | `{ runId, clashCount }` | Worker finished successfully |
+  | `onRunError`    | `{ code?, message }`    | Worker or cloud error |
+  | `onRunningJobsChanged` | `Set<string>` | A job starts or finishes |
+  | `onReloadingChanged`   | `boolean`     | Data reload after a successful run |
+
+  If the page is reloaded while a run is in progress, `init` re-reads the
+  in-flight execution from storage and populates `runningJobIds`. Call
+  `reconnectIfRunning(jobId)` to resume receiving progress events for that job.
+*/
+
+manager.onRunProgress.add(({ message, progress }) => {
+  console.log(`[${progress}%] ${message}`);
+});
+
+manager.onRunComplete.add(({ runId, clashCount }) => {
+  console.log(`Run ${runId} complete — ${clashCount} clash(es) found.`);
+});
+
+manager.onRunError.add(({ code, message }) => {
+  console.error(`Run failed (${code ?? "unknown"}): ${message}`);
+});
+
+manager.onReloadingChanged.add((reloading) => {
+  // Use this flag to show a loading state in a custom UI while fresh data
+  // is fetched from storage after the run. clashes-panel handles this automatically.
+  console.log(reloading ? "Reloading clash data…" : "Clash data ready.");
+});
+
+// Guard: only run if the manager is ready and the job is not already running.
+const jobToRun = manager.jobs[0];
+if (jobToRun && manager.ready && !manager.runningJobIds.has(jobToRun.id)) {
+  manager.run(jobToRun.id);
+}
+
+// If a run was already in progress before this page loaded, reconnect to it.
+for (const jobId of manager.runningJobIds) {
+  manager.reconnectIfRunning(jobId);
+}
+
+/* MD
+  ### ✅ Updating clash status
+
+  Each clash starts with status `"new"`. Reviewers move clashes through a
+  workflow by calling `updateClash`. Valid statuses are:
+
+  - `"new"` — detected, not yet reviewed
+  - `"active"` — under investigation
+  - `"acknowledged"` — known issue, not blocking
+  - `"resolved"` — fixed and verified
+
+  Status changes and comments are persisted automatically via the same
+  auto-save mechanism as queries and matrices.
+
+  `runsForJob(jobId)` and `clashesForRun(runId)` let you navigate the history:
+  a clash's `firstSeenRunId` / `lastSeenRunId` span shows across which runs it
+  was present, so you can determine whether a resolution actually closed it.
+*/
+
+manager.onClashStatusChanged.add((allClashes) => {
+  const open = allClashes.filter(c => c.status === "new" || c.status === "active");
+  console.log(`Open clashes: ${open.length}`);
+});
+
+const clashToAcknowledge = manager.clashes[0];
+if (clashToAcknowledge) {
+  manager.updateClash(clashToAcknowledge.id, {
+    status:   "acknowledged",
+    comments: "Coordination with MEP team scheduled for next sprint.",
+  });
+}
+
+// Navigate run history for the first job.
+const firstJob = manager.jobs[0];
+if (firstJob) {
+  const runs = manager.runsForJob(firstJob.id);    // newest first
+  const latestRun = runs[0];
+  if (latestRun) {
+    const clashesInRun = manager.clashesForRun(latestRun.id);
+    console.log(`Latest run has ${clashesInRun.length} active clash(es).`);
+  }
+}
+
+/* MD
+  ### 📍 Visualization without the built-in panel
+
+  If you are building a custom UI and not using `clashes-panel`, you can drive
+  the visualization layer directly.
+
+  **Sphere markers** — `showMarkers` places colored 3D spheres at clash
+  locations in the viewer. Call `hideMarkers` to remove them and re-enable
+  hover highlighting. Points are automatically transformed from IFC world space
+  to Three.js viewer space using `FragmentsManager.baseCoordinationMatrix`.
+
+  **Element highlights** — `highlightAllClashes` colors element A (green) and
+  element B (red) for every new/active clash in the provided list.
+  `clearClashHighlight` removes both styles. For single-clash focus, use
+  `highlightClash` and pair it with `ghostClashes` to dim everything else.
+
+  **Clustering** — `cluster(clashes, threshold)` groups spatially close clashes
+  into a single marker. Pass `threshold = 0` to show one sphere per clash.
+  `toViewerPoint` converts a raw IFC point to viewer space if you need to
+  position custom objects.
+*/
+
+const jobClashes = manager.clashes.filter(c => c.jobId === firstJob?.id);
+
+// Show one marker per clash, colored by status.
+manager.showMarkers(
+  jobClashes.map(c => ({ id: c.id, point: c.point, count: 1, status: c.status })),
+);
+
+// Highlight all open clashes across both element sets.
+manager.highlightAllClashes(jobClashes);
+
+// --- Clustered view ---
+// Group clashes within 2 m of each other into a single sphere.
+const clusters = manager.cluster(jobClashes, 2);
+manager.showMarkers(
+  clusters.map(group => ({
+    point:  group[0].point,
+    count:  group.length,
+    status: group[0].status,
+  })),
+);
+
+// Focus on a single clash: ghost everything else and zoom in.
+const focusClash = jobClashes[0];
+if (focusClash) {
+  manager.clearClashHighlight();
+  manager.highlightClash(focusClash);
+  await manager.ghostClash(focusClash);
+}
+
+// Restore full scene when done.
+manager.hideMarkers();
+manager.clearClashHighlight();
+await manager.clearGhostClash();

package/src/built-in/UIManager/src/clashes-panel/example.ts

@@ -0,0 +1,164 @@
+/* MD
+  ## clashes-panel
+  ---
+  BIM coordinators need a dedicated review environment where they can see all
+  detected clashes, filter by status, navigate to each issue in the 3D viewer,
+  and mark items as resolved — without writing any UI code themselves.
+
+  `clashes-panel` is a ready-made web component that delivers exactly that. It
+  connects to `ClashesManager` automatically and manages the entire review
+  workflow: the detection matrix, the clash table with status filters, sphere
+  markers and element highlights in the viewer, run controls with live progress,
+  and a loading skeleton while fresh data reloads after a run completes.
+
+  This tutorial covers the prerequisites before mounting the panel; dropping it
+  into a `top-app` layout alongside a 3D viewer; and a detailed breakdown of
+  everything the panel handles automatically so you know what you do not need to
+  implement yourself.
+
+  By the end, you'll have a fully working clash-review environment running in
+  your application with a single line of markup.
+*/
+
+import { html } from "lit";
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as FRAGS from "@thatopen/fragments";
+import * as BUI from "@thatopen/ui";
+import { PlatformClient } from "thatopen-services";
+import uiManagerDef from "../../../index";
+import clashesManagerDef from "../../../ClashesManager/index";
+import type { App } from "../app/index";
+
+const UIManager      = uiManagerDef.componentDefinition;
+const ClashesManager = clashesManagerDef.componentDefinition;
+
+/* MD
+  ### ✅ Prerequisites
+
+  Two conditions must be met before the panel mounts:
+
+  1. **`UIManager` must be in the setup call.** It registers all platform web
+     components, including `<clashes-panel>` itself. Without it the element is
+     unknown to the browser and renders as an empty box.
+
+  2. **`ClashesManager.init(client)` must have resolved.** The panel reads all
+     its initial data from the manager in `connectedCallback`. If `init` has not
+     finished, the panel mounts into an empty state and never catches up because
+     it only subscribes to change events — it does not poll.
+
+  Both conditions are naturally satisfied when you call `init` before appending
+  `top-app` to the document, which is the pattern shown below.
+*/
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: UIManager.uuid },
+  { uuid: ClashesManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+// init must resolve before top-app (and therefore clashes-panel) mounts.
+await components.get(ClashesManager).init(client);
+
+/* MD
+  ### 🖥️ Wiring the panel
+
+  Add `clashes-panel` as a named area in `app.elements` and reference it in your
+  layout template. A side-by-side layout with the 3D viewer is the most natural
+  arrangement — the panel controls markers and highlights directly in the scene.
+*/
+
+const app = document.createElement("top-app") as unknown as App;
+
+app.setup = (waitUntil) => {
+  waitUntil(
+    (async () => {
+      const fragments = components.get(OBC.FragmentsManager);
+      const workerUrl = await FRAGS.FragmentsModels.getWorker();
+      fragments.init(await FRAGS.toClassicWorker(workerUrl), { classicWorker: true });
+    })(),
+    "Fragments Core",
+  );
+
+  waitUntil(
+    (async () => {
+      const loader = components.get(OBC.IfcLoader);
+      await loader.setup();
+    })(),
+    "IFC Loader",
+  );
+
+  return { components, client };
+};
+
+app.elements = {
+  viewer:  () => html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
+  clashes: () => html`<clashes-panel></clashes-panel>`,
+};
+
+app.layouts = {
+  main: {
+    label:    "Main",
+    icon:     "solar:3d-square-bold",
+    template: `"viewer clashes" 1fr / 1fr 22rem`,
+  },
+};
+
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";
+
+/* MD
+  ### 🤖 What the panel manages automatically
+
+  Once mounted, `clashes-panel` takes ownership of the following without any
+  further code from you:
+
+  **Data synchronization** — the panel subscribes to every `ClashesManager`
+  event (`onJobsChanged`, `onRunsChanged`, `onClashesChanged`,
+  `onClashStatusChanged`, `onQueriesChanged`, `onRunningJobsChanged`) and keeps
+  its tables in sync. Changes made programmatically through the manager API are
+  reflected in the panel immediately.
+
+  **Run lifecycle** — a progress callout appears as soon as a run starts
+  (`onRunProgress`), updates its percentage and message in real time, and
+  disappears when the run completes or errors. If a run was already in progress
+  when the page loaded, the panel calls `reconnectIfRunning` automatically when
+  the user opens that job.
+
+  **Post-run reload skeleton** — after a successful run the manager reloads clash
+  data from storage. During that window (`onReloadingChanged = true`) the panel
+  replaces its entire content with an animated skeleton so the user is never left
+  looking at stale results that appear final.
+
+  **Sphere markers** — entering a job view places colored spheres in the 3D scene
+  at each clash location, transformed from IFC world space to viewer space.
+  Selecting a clash in the table zooms the camera, ghosts unrelated elements, and
+  re-focuses the markers on the selection. Leaving the job view removes all
+  markers and restores the full scene.
+
+  **Element highlights** — element A is highlighted green and element B red for
+  every new or active clash in the current job. Selecting a single clash refines
+  the highlight to that pair only. Clearing the selection or changing status
+  restores the full job highlight.
+
+  **Model awareness** — the panel tracks which fragment models are currently
+  loaded in the scene. Markers and highlights are activated only when the relevant
+  models are present, and are cleaned up automatically if a model is disposed
+  while the panel is open.
+
+  **Save indicator** — a subtle indicator appears while auto-save is in progress
+  (`onSaveStart`) and disappears once the write confirms (`onSaveComplete`), so
+  users know their status changes and query edits are persisted.
+
+  **Disconnection cleanup** — when the panel is removed from the DOM it calls
+  `hideMarkers` and `clearClashHighlight` on the manager, leaving the 3D scene
+  clean regardless of what was selected at the time.
+*/

package/src/built-in/UIManager/src/models-list/example.ts

@@ -0,0 +1,120 @@
+/* MD
+  ## top-models-list
+  ---
+  top-models-list is the project files panel: it lists the project's files, uploads new ones, converts IFC to fragments, and loads `.frag` models into the 3D scene. Its loaders are PLUGGABLE — the panel owns the UI and the orchestration (progress, refresh, association), but the HOST decides how each file format is loaded, so you can teach it new formats without forking the built-in.
+
+  This tutorial covers the two extension points. First, registering a custom loader for a file extension — either imperatively with `registerLoader(ext, fn)` or up front via the `loaders` property; a loader receives `(fileId, ctx)` where `ctx` carries the engine (`components`), the platform `client`, and per-file alignment persistence. A format with no registered loader simply hides its load action. Second, overriding the IFC to fragments `converter` — omit it to use the built-in default (which drives the project's IfcFragmenter cloud component), or provide one to run conversion elsewhere.
+
+  By the end you'll have a files panel that knows how to load a custom format and how to run a custom IFC conversion, with the panel's UI untouched.
+*/
+
+import { html } from "lit";
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as FRAGS from "@thatopen/fragments";
+import * as BUI from "@thatopen/ui";
+import { PlatformClient } from "thatopen-services";
+import uiManagerDef from "../../index";
+import type { App } from "../app/index";
+import type { ModelsList } from "./index";
+
+const UIManager = uiManagerDef.componentDefinition;
+
+const client = PlatformClient.fromPlatformContext();
+
+// UIManager registers every platform web component (top-app, top-viewer,
+// top-models-list, …) before the DOM renders.
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: UIManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+const app = document.createElement("top-app") as unknown as App;
+
+app.setup = (waitUntil) => {
+  waitUntil(
+    (async () => {
+      const fragments = components.get(OBC.FragmentsManager);
+      const workerUrl = await FRAGS.FragmentsModels.getWorker();
+      fragments.init(await FRAGS.toClassicWorker(workerUrl), {
+        classicWorker: true,
+      });
+    })(),
+    "Fragments Core",
+  );
+  return { components, client };
+};
+
+// One stable <top-models-list>, kept by reference so re-rendering top-app reuses
+// it. The loaders are read LIVE, so registration can happen at any time.
+const modelsList = document.createElement("top-models-list") as ModelsList;
+
+// ── Extension point 1: a custom loader, keyed by file extension ──────────────
+// A ModelLoader is `(fileId, ctx) => void | Promise<void>`. The panel calls it
+// when the user loads a file whose extension matches. `ctx` gives you everything
+// you need: { name, ext, components, client, getAlignment, setAlignment }. Do
+// whatever it takes to put the file in the scene — fetch it via the client,
+// parse it, and add geometry to a world from `components`.
+modelsList.registerLoader("xyz", async (fileId, ctx) => {
+  // const buffer = await ctx.client
+  //   .downloadFile(fileId)
+  //   .then((r: Response) => r.arrayBuffer());
+  // ...parse `buffer` and add it to the world here...
+  // Persist/restore a placement matrix across reloads via the panel's app-data:
+  //   const saved = ctx.getAlignment(fileId);
+  //   ctx.setAlignment(fileId, matrix.toArray());
+  console.log(`[xyz loader] would load "${ctx.name}" (${fileId})`, ctx.components);
+});
+
+// Equivalent declarative form — hand the whole registry over at once:
+//   modelsList.loaders = { xyz: async (fileId, ctx) => { ... } };
+//
+// Registering a loader for an extension is also what makes that format's files
+// APPEAR in the list (recognition follows the loaders registry). For a
+// CONVERT-style action — e.g. a PLY that runs a PLY→3D-tiles cloud component
+// then views the result — register a RICH entry so the button reads correctly:
+//   modelsList.registerLoader("ply", {
+//     label: "Generate 3D tiles",
+//     icon: "mdi:cube-scan",
+//     fn: async (fileId, ctx) => {
+//       // const { executionId } = await ctx.client.executeComponent(...);
+//       // ...poll until done, then open the produced tileset...
+//     },
+//   });
+
+// ── Extension point 2: override the IFC → fragments converter ────────────────
+// OMIT this to keep the built-in default (drives the project's IfcFragmenter
+// cloud component via the platform client). Provide it to run conversion
+// elsewhere / differently — the panel keeps the progress bar, reload-survival,
+// association and refresh; your converter just `start`s and is `poll`ed.
+modelsList.converter = {
+  async start(fileId) {
+    // kick off your conversion; return an execution id to poll
+    return `exec-${fileId}`;
+  },
+  async poll(executionId) {
+    // report progress; when done, hand back the produced .frag id
+    return { done: true, ok: true, fragId: "demo-frag", message: "Converted" };
+  },
+};
+
+// Mount the panel into a one-area layout. (In a real app it sits beside a
+// top-viewer so loaded models have a world to render into.)
+app.elements = {
+  files: () => html`${modelsList}`,
+};
+app.layouts = {
+  main: {
+    label: "Files",
+    icon: "mdi:folder-multiple-outline",
+    template: `"files" 1fr / 1fr`,
+  },
+};
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";