geometryview 0.1.2 → 0.3.0

package/web/import-queue.js

@@ -0,0 +1,168 @@
+// The order in which files are imported and drawn: the browser's copy of the Mac's library::Queue
+// (Engine/library/queue.h). Both run the cases in Tests/data/gallery-queue.json, so a gallery
+// fills in the same order everywhere. Pure policy: who runs a job, and how, is the caller's.
+//
+// What is wanted is replaced whole as the view moves: each job has a band (a file being opened, one
+// in view, one near the view, or one prefetched while nothing else waits) and an order within its
+// band. Jobs start best first while slots are free. A job no longer wanted is dropped before it
+// starts; once running it runs on, since its result is kept, unless a job in view needs its slot.
+// Only a file being opened or one in view ever cancels a running job, and only one in a lower band.
+
+export const Bands = Object.freeze({ open: 0, visible: 1, near: 2, prefetch: 3 });
+
+/** Files larger than this are never prefetched: they are imported only when in view. */
+export const kMaxPrefetchBytes = 300_000_000;
+
+const kStale = 4; // a running job no longer wanted ranks below every band
+
+export class ImportQueue {
+  #slots;
+  #prefetch;
+  #jobs = new Map(); // id -> { band, order, bytes, position, wanted, running, cancelling }
+  #waiting = []; // ids, best first
+  #running = 0;
+
+  constructor({ slots = 1, prefetch = true } = {}) {
+    this.#slots = slots;
+    this.#prefetch = prefetch;
+  }
+
+  /**
+   * Replaces what is wanted: jobs as { id, band, order, bytes }, band a name from Bands. A waiting
+   * job not wanted is dropped; a running one runs on, stale. A job is started again only if it is
+   * wanted after it finished.
+   */
+  want(jobs) {
+    for (const job of this.#jobs.values()) job.wanted = false;
+    jobs.forEach(({ id, band, order = 0, bytes = 0 }, position) => {
+      const rank = Bands[band];
+      if (rank === undefined) throw new Error(`No band named ${band}`);
+      const job = this.#jobs.get(id);
+      if (job) {
+        Object.assign(job, { band: rank, order, bytes, position, wanted: true });
+      } else {
+        this.#jobs.set(id, { band: rank, order, bytes, position, wanted: true, running: false, cancelling: false });
+      }
+    });
+    for (const [id, job] of this.#jobs) {
+      if (!job.wanted && !job.running) this.#jobs.delete(id);
+    }
+    this.#sortWaiting();
+  }
+
+  /** Starts the best waiting job, if a slot is free and one may start, and returns its id, or null. */
+  next() {
+    if (this.#running >= this.#slots) return null;
+    for (let i = 0; i < this.#waiting.length; i++) {
+      const id = this.#waiting[i];
+      const job = this.#jobs.get(id);
+      if (job.band === Bands.prefetch) {
+        if (!this.#prefetch) break; // prefetched jobs come last
+        if (job.bytes > kMaxPrefetchBytes) continue;
+      }
+      this.#waiting.splice(i, 1);
+      job.running = true;
+      this.#running++;
+      return id;
+    }
+    return null;
+  }
+
+  /** A running job completed, or failed: it is done with. */
+  finish(id) {
+    const job = this.#jobs.get(id);
+    if (!job?.running) return;
+    this.#running--;
+    this.#jobs.delete(id);
+  }
+
+  /** A running job stopped before completing, as when cancelled: if still wanted it waits again. */
+  stopped(id) {
+    const job = this.#jobs.get(id);
+    if (!job?.running) return;
+    this.#running--;
+    if (!job.wanted) {
+      this.#jobs.delete(id);
+      return;
+    }
+    job.running = false;
+    job.cancelling = false;
+    this.#sortWaiting();
+  }
+
+  /**
+   * Running jobs to cancel now, worst first, so that waiting jobs in view can start. Each is
+   * returned once, and keeps its slot until it has stopped.
+   */
+  toCancel() {
+    let available = Math.max(0, this.#slots - this.#running);
+    const candidates = [];
+    for (const [id, job] of this.#jobs) {
+      if (!job.running) continue;
+      if (job.cancelling) {
+        available++;
+        continue;
+      }
+      candidates.push({ id, rank: job.wanted ? job.band : kStale, order: job.order, position: job.position });
+    }
+    candidates.sort((a, b) => compare(b, a)); // worst first
+    const cancelled = [];
+    for (const id of this.#waiting) {
+      const band = this.#jobs.get(id).band;
+      if (band > Bands.visible) break;
+      if (available > 0) {
+        available--;
+        continue;
+      }
+      const worse = candidates.findIndex((c) => c.rank > band);
+      if (worse < 0) break; // later jobs are in the same band or lower, and can cancel no more
+      cancelled.push(candidates[worse].id);
+      candidates.splice(worse, 1);
+    }
+    for (const id of cancelled) this.#jobs.get(id).cancelling = true;
+    return cancelled;
+  }
+
+  /** Fewer slots, as memory runs short, start nothing new until running jobs fall below them. */
+  setSlots(slots) {
+    this.#slots = slots;
+  }
+  get slots() {
+    return this.#slots;
+  }
+  /** Whether prefetched jobs may start. */
+  setPrefetch(allowed) {
+    this.#prefetch = allowed;
+  }
+
+  waiting() {
+    return [...this.#waiting];
+  }
+  running() {
+    return [...this.#jobs]
+      .filter(([, job]) => job.running)
+      .sort(([a, x], [b, y]) => compare({ id: a, rank: x.band, ...x }, { id: b, rank: y.band, ...y }))
+      .map(([id]) => id);
+  }
+  get idle() {
+    return this.#waiting.length === 0 && this.#running === 0;
+  }
+  /** A job's band, by name, if the queue holds it. */
+  bandOf(id) {
+    const job = this.#jobs.get(id);
+    return job ? Object.keys(Bands).find((name) => Bands[name] === job.band) : undefined;
+  }
+
+  #sortWaiting() {
+    this.#waiting = [...this.#jobs]
+      .filter(([, job]) => !job.running)
+      .map(([id, job]) => ({ id, rank: job.band, order: job.order, position: job.position }))
+      .sort(compare)
+      .map((job) => job.id);
+  }
+}
+
+// Best first: band, then order, then where it was wanted, then id, as the Mac's queue keys jobs.
+function compare(a, b) {
+  return a.rank - b.rank || a.order - b.order || a.position - b.position || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}

package/web/import-worker.js

@@ -13,13 +13,25 @@
 // A STEP file's source is kept beside its cache, so its definitions can be imported again, finer,
 // when the view comes close: a refinement, whose segments the page adds to the open document.
 //
-// Messages in:  { type: "import", file, kind: "step" | "stl", name, workers, threads, progressive }
+// A cache file is kept under its key (kept.js); a file the page can read again from a connected
+// folder keeps no source.
+//
+// Messages in:  { type: "import", file, kind: "step" | "stl", name, key, keepSource, workers,
+//                 threads, progressive }
 //               { type: "refine", file, level, definitions, workers }
-// Messages out: { type: "progress", done, total } and, if progressive or refining,
-//               { type: "segment", bytes } as each is written; then { type: "done", ... } or
-//               { type: "failed", message }
+//               { type: "structure", file }: a STEP file's model alone, as one segment, for an
+//                 estimated box while it waits to import; nothing is kept
+//               { type: "cancel" }: the import or refinement running stops after the slices out
+// Messages out: { type: "progress", done, total } and, if progressive, refining or reading
+//               structure, { type: "segment", bytes } as each is written; then
+//               { type: "done", ... } or { type: "failed", message, cancelled }
 
 import createStepImporter from "./occt/geometryview-step-web.mjs";
+import { keepImport, keepSource as keepSourceByKey } from "./kept.js";
+
+// Set by a cancel message, which arrives while an import awaits its slices.
+let cancelled = false;
+const kCancelled = "The import was cancelled.";
 
 // Some browsers refuse a worker that starts another worker by URL. Claude Desktop's built-in
 // browser is one: the nested worker fails at once, with no message and no request sent. A module
@@ -130,6 +142,14 @@ function mesh(step, slots, progressive) {
     let closed = false;
 
     const pump = () => {
+      if (cancelled && !closed) {
+        // No more slices: once those out are answered, the import stops.
+        if (busy === 0) {
+          closed = true;
+          Promise.all(replacing).then(() => reject(new Error(kCancelled)));
+        }
+        return;
+      }
       while (!closed && idle.length > 0) {
         const id = step._step_next();
         if (id === -2) {
@@ -255,6 +275,7 @@ async function readInto(step, file) {
 // Imports some of a STEP file's definitions again at a finer level, posting each segment as it is
 // written; they hold geometry only, for the page to add to the document already open.
 async function refine(data) {
+  cancelled = false;
   try {
     const step = await supervisor(false);
     await readInto(step, data.file);
@@ -271,7 +292,27 @@ async function refine(data) {
     self.postMessage({ type: "done", triangles: stats[11], faces: stats[10], failedFaces: stats[12],
                        crashedWorkers: stats[14], coarserFaces: stats[16] });
   } catch (error) {
-    self.postMessage({ type: "failed", message: String(error.message ?? error) });
+    failed(error);
+  }
+}
+
+function failed(error) {
+  const message = String(error.message ?? error);
+  self.postMessage({ type: "failed", message, cancelled: message === kCancelled });
+}
+
+// Reads a STEP file's structure alone and posts its model, with each body's box estimated, as one
+// segment: what a gallery lays a file out from while it waits to import. Nothing is kept, and no
+// OCCT worker is needed.
+async function structure(data) {
+  try {
+    const step = await supervisor(false);
+    await readInto(step, data.file);
+    if (step._step_begin() !== 0) throw new Error(step.UTF8ToString(step._step_error()));
+    postSegments(step);
+    self.postMessage({ type: "done", structure: true });
+  } catch (error) {
+    failed(error);
   }
 }
 
@@ -289,11 +330,20 @@ async function readPieces(step, file) {
 }
 
 self.onmessage = async ({ data }) => {
+  if (data.type === "cancel") {
+    cancelled = true;
+    return;
+  }
   if (data.type === "refine") {
     await refine(data);
     return;
   }
+  if (data.type === "structure") {
+    await structure(data);
+    return;
+  }
   if (data.type !== "import") return;
+  cancelled = false;
   const started = performance.now();
   try {
     const step = await supervisor(data.threads && self.crossOriginIsolated);
@@ -319,11 +369,15 @@ self.onmessage = async ({ data }) => {
                      coarserFaces: stats[16], slices,
                      importMs: Math.round(performance.now() - started), cacheBytes: blob.length,
                      supervisorMB: Math.round(step.HEAPU8.length / 2 ** 20) };
-    await keep(data.name, blob, { name: data.name, size: data.file.size,
-                                  lastModified: data.file.lastModified, importedAt: Date.now(), ...result });
+    const note = { name: data.name, size: data.file.size, lastModified: data.file.lastModified,
+                   importedAt: Date.now(), ...result };
+    if (data.key) await keepImport(data.key, blob, note);
+    else await keep(data.name, blob, note);
     self.postMessage({ type: "done", ...result });
-    if (data.kind === "step") await keepSource(data.name, data.file).catch(() => {});
+    if (data.kind === "step" && data.keepSource !== false) {
+      await (data.key ? keepSourceByKey(data.key, data.file) : keepSource(data.name, data.file)).catch(() => {});
+    }
   } catch (error) {
-    self.postMessage({ type: "failed", message: String(error.message ?? error) });
+    failed(error);
   }
 };

package/web/importers.js

@@ -0,0 +1,140 @@
+// Runs the page's imports through ImportQueue, in two lanes: what a person opens, and what the
+// gallery wants. What a person opens never waits behind the gallery: on a desktop the gallery has
+// an importer of its own, which starts nothing new while anything is being opened; on a phone, one
+// importer is shared, so the gallery's running job is cancelled for an open and waits again.
+//
+// The live lane's jobs are files being opened ("open"), in the order asked, and refinements of what
+// is open ("visible"): a file being opened cancels a refinement running, which is not tried again;
+// the engine asks anew. Who runs a job, and how, is the caller's: `run(signal)` returns a promise,
+// and stops early, rejecting or not, once `signal` aborts.
+
+import { ImportQueue } from "./import-queue.js";
+
+export class Importers {
+  #live = new ImportQueue({ slots: 1 });
+  #liveWants = [];
+  #gallery;
+  #shared;
+  #jobs = new Map(); // id -> { lane, run, resolve, reject, controller }
+  #sequence = 0;
+
+  /** `shared`: one importer for both lanes, as on a phone, where prefetching is off too. */
+  constructor({ shared = false, gallerySlots = 1 } = {}) {
+    this.#shared = shared;
+    this.#gallery = new ImportQueue({ slots: gallerySlots, prefetch: !shared });
+  }
+
+  /** Runs a live job: a file being opened (band "open") or a refinement ("visible"). */
+  live(id, run, { band = "open" } = {}) {
+    return new Promise((resolve, reject) => {
+      this.#jobs.set(id, { lane: "live", run, resolve, reject, controller: null });
+      this.#liveWants.push({ id, band, order: this.#sequence++ });
+      this.#live.want(this.#liveWants);
+      this.#pump();
+    });
+  }
+
+  /** Stops a live job: dropped if it waits, aborted if it runs. */
+  cancel(id) {
+    const job = this.#jobs.get(id);
+    if (!job) return;
+    if (job.controller) {
+      job.controller.abort();
+    } else {
+      this.#dropLive(id);
+      this.#jobs.delete(id);
+      job.resolve({ type: "cancelled" });
+      this.#pump();
+    }
+  }
+
+  /**
+   * Replaces what the gallery wants: [{ id, band, order, bytes, run }]. A job not wanted any more
+   * is dropped before it starts and runs on once started, unless a job in view needs its slot.
+   * Each job's result goes to `onDone(id, result)`; its failure to `onFailed(id, error)`.
+   */
+  want(jobs, { onDone = () => {}, onFailed = () => {} } = {}) {
+    this.#onDone = onDone;
+    this.#onFailed = onFailed;
+    for (const job of jobs) {
+      const known = this.#jobs.get(job.id);
+      if (!known) this.#jobs.set(job.id, { lane: "gallery", run: job.run, controller: null });
+      else if (known.lane === "gallery") known.run = job.run;
+    }
+    this.#gallery.want(jobs.map(({ id, band, order, bytes }) => ({ id, band, order, bytes })));
+    for (const [id, job] of this.#jobs) {
+      if (job.lane === "gallery" && !job.controller && !this.#gallery.bandOf(id)) this.#jobs.delete(id);
+    }
+    this.#pump();
+  }
+  #onDone = () => {};
+  #onFailed = () => {};
+
+  setPrefetch(allowed) {
+    this.#gallery.setPrefetch(allowed && !this.#shared);
+    this.#pump();
+  }
+
+  /** Whether anything is being opened, waiting or running. */
+  get opening() {
+    return this.#live.waiting().length > 0 || this.#live.running().length > 0;
+  }
+
+  /** Ids running now, by lane, for checks. */
+  running() {
+    return { live: this.#live.running(), gallery: this.#gallery.running() };
+  }
+
+  #pump() {
+    for (const id of this.#live.toCancel()) this.#jobs.get(id)?.controller?.abort();
+    for (let id = this.#live.next(); id !== null; id = this.#live.next()) this.#start("live", id);
+
+    if (this.opening) {
+      // One importer for both: the gallery's running job makes way, and waits again.
+      if (this.#shared) for (const id of this.#gallery.running()) this.#jobs.get(id)?.controller?.abort();
+      return;
+    }
+    for (const id of this.#gallery.toCancel()) this.#jobs.get(id)?.controller?.abort();
+    for (let id = this.#gallery.next(); id !== null; id = this.#gallery.next()) this.#start("gallery", id);
+  }
+
+  #dropLive(id) {
+    this.#liveWants = this.#liveWants.filter((want) => want.id !== id);
+    this.#live.want(this.#liveWants);
+  }
+
+  #start(lane, id) {
+    const job = this.#jobs.get(id);
+    const queue = lane === "live" ? this.#live : this.#gallery;
+    if (!job) {
+      queue.finish(id);
+      return;
+    }
+    const controller = new AbortController();
+    job.controller = controller;
+    Promise.resolve()
+      .then(() => job.run(controller.signal))
+      .then((result) => ({ result }), (error) => ({ error }))
+      .then(({ result, error }) => {
+        job.controller = null;
+        const aborted = controller.signal.aborted;
+        if (lane === "live") {
+          queue.finish(id);
+          this.#dropLive(id);
+          this.#jobs.delete(id);
+          if (aborted) job.resolve({ type: "cancelled" });
+          else if (error) job.reject(error);
+          else job.resolve(result);
+        } else if (aborted) {
+          queue.stopped(id); // waits again, if still wanted
+          if (!queue.bandOf(id)) this.#jobs.delete(id);
+        } else {
+          queue.finish(id);
+          this.#jobs.delete(id);
+          if (error) this.#onFailed(id, error);
+          else this.#onDone(id, result);
+        }
+        this.#pump();
+      });
+  }
+}

package/web/index.html

@@ -8,6 +8,7 @@
 <link rel="icon" href="icons/icon-32.png" sizes="32x32" type="image/png">
 <link rel="apple-touch-icon" href="icons/icon-180.png">
 <link rel="stylesheet" href="viewer.css">
+<link rel="stylesheet" href="gallery.css">
 </head>
 <body>
 <canvas id="viewport"></canvas>