geometryview 0.1.2 → 0.4.0

package/README.md

@@ -1,9 +1,9 @@
 # GeometryView
 
-**See inside your CAD models, fast.** Open STEP and STL files in your browser, and let your AI apps
-open, inspect and picture them.
+**See inside your CAD models, and a whole folder of them at once.** STEP and STL, in your browser,
+on a Mac, on your phone, and from your AI apps.
 
-<img src="https://raw.githubusercontent.com/atharvaaalok/geometryview/main/Docs/media/styles.jpg" alt="A drive cut open, in six drawing styles" width="600">
+<img src="https://raw.githubusercontent.com/atharvaaalok/geometryview/v0.4.0/Docs/media/fig1-light.webp" width="680" alt="A turbofan cut along its axis, six stages numbered, in a drafting frame">
 
 ## View a model
 
@@ -13,26 +13,35 @@ npx geometryview               # the viewer, with your folders and recent files
 ```
 
 The viewer is served from your computer only (127.0.0.1), and your files never leave it. It needs a
-browser with WebGPU: Chrome or Edge, or Safari 26 or later. Or use the hosted copy, with sample
-models: [atharvaaalok.github.io/geometryview](https://atharvaaalok.github.io/geometryview/).
+browser with WebGPU: Chrome or Edge, or Safari 26 or later; on Linux it opens a Chrome window of its
+own, with Vulkan on. Or use the hosted copy:
+[atharvaaalok.github.io/geometryview](https://atharvaaalok.github.io/geometryview/).
 
-## Use it from your AI app
+Connect a folder and every part in it is drawn to scale, five ways: Plates, Sheet, Ladders, Atlas and
+Catalogue.
 
-`geometryview --mcp` is a tool server (MCP) with four tools:
+<img src="https://raw.githubusercontent.com/atharvaaalok/geometryview/v0.4.0/Docs/media/plates-light.webp" width="680" alt="A folder of 124 parts as a poster, fifteen families each at its own scale">
 
-- `open_model` opens a file and sums it up.
-- `get_structure` lists its assemblies and parts.
-- `render_view` returns a picture: any view, any of six styles, sections, parts alone.
-- `open_in_viewer` shows it to you, live.
+## Use it from your AI app
 
 ```sh
 claude mcp add geometryview -- npx -y geometryview --mcp     # Claude Code
 codex mcp add geometryview -- npx -y geometryview --mcp      # Codex
 ```
 
-Other apps take the same command, `npx -y geometryview --mcp`, in their MCP settings. Claude
-Desktop can also install it in one click from the `.mcpb` in the
+Other apps take the same command, `npx -y geometryview --mcp`, in their MCP settings. Claude Desktop
+installs it in one click from the `.mcpb` in the
 [latest release](https://github.com/atharvaaalok/geometryview/releases/latest).
 
-More, including the Mac app and the iPhone: [github.com/atharvaaalok/geometryview](https://github.com/atharvaaalok/geometryview).
-MIT licensed.
+- `open_model` opens a file and sums it up.
+- `get_structure` lists its assemblies and parts.
+- `render_view` returns a picture: any view, any of six styles, sections, parts alone.
+- `open_in_viewer` shows it to you, live.
+- `view_folder` pictures a whole folder on one contact sheet. It needs the native engine: the Claude
+  Desktop extension for Mac, or a build from source.
+
+Your files stay on your computer. The pictures, part names and structure the tools return go to
+your AI app, and from it to its provider.
+
+More, including the Mac app and the iPhone:
+[github.com/atharvaaalok/geometryview](https://github.com/atharvaaalok/geometryview). MIT licensed.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "geometryview",
-  "version": "0.1.2",
-  "description": "View STEP and STL models in your browser, and let AI apps open, inspect and picture them (MCP).",
+  "version": "0.4.0",
+  "description": "See inside STEP and STL models, and whole folders of them, in your browser; and let AI apps open, inspect and picture them (MCP).",
   "keywords": [
     "step",
     "stl",
@@ -14,7 +14,7 @@
     "mcp",
     "model-context-protocol"
   ],
-  "homepage": "https://github.com/atharvaaalok/geometryview#readme",
+  "homepage": "https://atharvaaalok.github.io/geometryview/",
   "bugs": {
     "url": "https://github.com/atharvaaalok/geometryview/issues"
   },
@@ -39,6 +39,7 @@
   },
   "scripts": {
     "test": "node --test test/*.test.mjs",
-    "prepack": "node scripts/web.mjs"
+    "prepack": "node scripts/web.mjs",
+    "prepublishOnly": "node scripts/readme.mjs --check"
   }
 }

package/src/mcp.mjs

@@ -4,7 +4,7 @@
 
 import { createInterface } from "node:readline";
 
-const SERVER = { name: "geometryview", version: "0.1.2" };
+const SERVER = { name: "geometryview", version: "0.4.0" };
 const LATEST_PROTOCOL = "2025-06-18";
 
 /// Serves `tools` until standard input closes. Each tool is { name, description, inputSchema,

package/src/native.mjs

@@ -2,11 +2,11 @@
 // read its assembly tree and statistics, and render it to a PNG. The universal WebAssembly engine
 // will take this module's place on other machines.
 
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
-import { homedir, release, tmpdir } from "node:os";
+import { mkdir, open, readdir, readFile, rename, rm, stat, utimes } from "node:fs/promises";
+import { cpus, homedir, release, tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
@@ -63,6 +63,66 @@ function binaries() {
 
 const cacheDirectory = join(homedir(), "Library/Caches/geometryview");
 
+// Imports and renders at once: a third of the cores, at most four, so a folder's worth of files
+// leaves the machine usable (ADR 0016).
+const slots = Math.max(1, Math.min(4, Math.floor(cpus().length / 3)));
+let busy = 0;
+const queued = [];
+
+/// Runs `work` once a slot is free.
+export async function withSlot(work) {
+  if (busy >= slots) await new Promise((resolve) => queued.push(resolve));
+  busy += 1;
+  try {
+    return await work();
+  } finally {
+    busy -= 1;
+    queued.shift()?.();
+  }
+}
+
+// Imports under way, by cache file, so the same file asked for twice is imported once.
+const importing = new Map();
+
+// The cache's budget: GEOMETRYVIEW_CACHE_BYTES, else 4 GB. Past it, the files used longest ago go,
+// down to 80% of it, in a sweep run 30 s after the last import; a cache file's time is its last use.
+// Partial files left by an import that died go once they are an hour old.
+const kCacheBudget = Number(process.env.GEOMETRYVIEW_CACHE_BYTES) || 4 * 1024 ** 3;
+let sweepTimer = null;
+
+function scheduleSweep() {
+  clearTimeout(sweepTimer);
+  sweepTimer = setTimeout(() => sweepCache().catch(() => {}), 30_000);
+  sweepTimer.unref?.();
+}
+
+/// Keeps the cache within `budget` bytes, sparing files used in the last minute. Returns the bytes
+/// it holds after.
+export async function sweepCache(directory = cacheDirectory, budget = kCacheBudget, now = Date.now()) {
+  const names = await readdir(directory).catch(() => []);
+  const files = [];
+  for (const name of names) {
+    const path = join(directory, name);
+    const info = await stat(path).catch(() => null);
+    if (!info?.isFile()) continue;
+    if (name.endsWith(".partial")) {
+      if (now - info.mtimeMs > 3600_000) await rm(path, { force: true });
+      continue;
+    }
+    if (name.endsWith(".geoblob")) files.push({ path, bytes: info.size, used: info.mtimeMs });
+  }
+  let total = files.reduce((sum, file) => sum + file.bytes, 0);
+  if (total <= budget) return total;
+  files.sort((a, b) => a.used - b.used);
+  for (const file of files) {
+    if (total <= budget * 0.8) break;
+    if (now - file.used < 60_000) continue;
+    await rm(file.path, { force: true });
+    total -= file.bytes;
+  }
+  return total;
+}
+
 /// Imports `path` unless an import of the same file, unchanged, is cached. Returns the cache file.
 // The cache file version gcli writes and reads, from Import/format/blob.h.
 export const kCacheVersion = 5;
@@ -96,23 +156,95 @@ export async function importModel(path) {
     .slice(0, 32);
   const blob = join(cacheDirectory, `${key}.geoblob`);
   if (existsSync(blob)) {
-    // One in an older format is made again: gcli reads only its own.
-    if (await isCurrent(blob)) return { blob, source, fromCache: true };
+    // One in an older format is made again: gcli reads only its own. Its time marks its use.
+    if (await isCurrent(blob)) {
+      const now = new Date();
+      await utimes(blob, now, now).catch(() => {});
+      return { blob, source, fromCache: true };
+    }
     await rm(blob, { force: true });
   }
-  await mkdir(cacheDirectory, { recursive: true });
-  const { gcli, worker } = binaries();
-  const partial = `${blob}.${process.pid}.partial`;
-  try {
-    await run(gcli, ["import", source, partial, worker], { maxBuffer: 1 << 20 });
-  } catch (error) {
-    await rm(partial, { force: true });
-    throw new Error(`Could not import ${basename(source)}: ${(error.stderr || error.message).trim()}`);
+  if (!importing.has(blob)) {
+    const work = withSlot(async () => {
+      await mkdir(cacheDirectory, { recursive: true });
+      const { gcli, worker } = binaries();
+      const partial = `${blob}.${process.pid}.partial`;
+      try {
+        await run(gcli, ["import", source, partial, worker], { maxBuffer: 1 << 20 });
+      } catch (error) {
+        await rm(partial, { force: true });
+        throw new Error(`Could not import ${basename(source)}: ${(error.stderr || error.message).trim()}`);
+      }
+      await rename(partial, blob);
+      scheduleSweep();
+    }).finally(() => importing.delete(blob));
+    importing.set(blob, work);
   }
-  await rename(partial, blob);
+  await importing.get(blob);
   return { blob, source, fromCache: false };
 }
 
+/// The STEP and STL files in `folder`, and with `recursive` in its folders too, hidden ones left
+/// out: at most 20,000, 32 folders deep.
+export async function listModels(folder, { recursive = false } = {}) {
+  const root = resolve(folder);
+  const info = await stat(root).catch(() => {
+    throw new Error(`There is no folder at ${root}.`);
+  });
+  if (!info.isDirectory()) throw new Error(`${root} is not a folder.`);
+  const found = [];
+  const walk = async (directory, depth) => {
+    const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      if (found.length >= 20000 || entry.name.startsWith(".")) continue;
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (recursive && depth < 32) await walk(path, depth + 1);
+      } else if (entry.isFile() && /\.(step|stp|stl)$/i.test(entry.name)) {
+        found.push(path);
+      }
+    }
+  };
+  await walk(root, 0);
+  return found;
+}
+
+/// A cache file's facts: its box in millimetres, parts, bodies, faces, triangles and the name
+/// inside it (scene::Facts).
+export async function readFacts(blob) {
+  const { gcli } = binaries();
+  const { stdout } = await run(gcli, ["facts", blob], { maxBuffer: 1 << 20 });
+  return JSON.parse(stdout);
+}
+
+/// Draws cache files on one contact sheet, as the gallery draws them: `tiles` are { blob, label,
+/// sub }. Returns the PNG's bytes and, for each tile, its cell and any error.
+export async function contactSheet(tiles, { cell = 192, columns, style = "illustration", colour = "parts",
+                                            sameScale = false, title } = {}) {
+  const { gcli, shaders } = binaries();
+  const png = join(tmpdir(), `geometry-view-sheet-${process.pid}-${Date.now()}.png`);
+  const args = ["sheet", shaders, png, "--cell", String(cell), "--style", String(style),
+                "--colour", String(colour)];
+  if (columns) args.push("--columns", String(columns));
+  if (sameScale) args.push("--same-scale");
+  if (title) args.push("--title", title);
+  try {
+    const stdout = await withSlot(() => new Promise((resolve, reject) => {
+      const child = spawn(gcli, args, { stdio: ["pipe", "pipe", "pipe"] });
+      let out = "", err = "";
+      child.stdout.on("data", (chunk) => { out += chunk; });
+      child.stderr.on("data", (chunk) => { err += chunk; });
+      child.on("error", reject);
+      child.on("close", (code) => (code === 0 ? resolve(out) : reject(new Error(err.trim() || `gcli sheet failed (${code})`))));
+      child.stdin.end(tiles.map((tile) => JSON.stringify(tile)).join("\n") + "\n");
+    }));
+    const placed = stdout.split("\n").filter(Boolean).map((line) => JSON.parse(line));
+    return { png: await readFile(png), tiles: placed };
+  } finally {
+    await rm(png, { force: true });
+  }
+}
+
 /// The assembly tree: one node per entry, depth-first, with parent, kind, name and body range.
 export async function readTree(blob) {
   const { gcli } = binaries();
@@ -142,7 +274,7 @@ export async function render(blob, view) {
     (view.isolate ?? []).join(","),
   ];
   try {
-    await run(gcli, args, { maxBuffer: 1 << 20 });
+    await withSlot(() => run(gcli, args, { maxBuffer: 1 << 20 }));
     return await readFile(png);
   } catch (error) {
     throw new Error((error.stderr || error.message).trim());

package/src/tools.mjs

@@ -1,8 +1,8 @@
 // The tools an AI app can call: open a model, read its parts, picture it, and show it to the user.
 
-import { basename } from "node:path";
-import { importModel, nativeAvailable, openInViewer, readStats, readTree, render,
-         viewerApplication } from "./native.mjs";
+import { basename, relative, resolve } from "node:path";
+import { contactSheet, importModel, listModels, nativeAvailable, openInViewer, readFacts, readStats,
+         readTree, render, viewerApplication } from "./native.mjs";
 import { linkToPage, openInPage, pageRender, pageTree, showInPage, viewerServer } from "./page.mjs";
 
 export const instructions =
@@ -14,8 +14,10 @@ export const instructions =
   "studio). To study a part, pass names from get_structure as isolate, and use section to cut " +
   "through the model. open_in_viewer shows the model to the user, live: in the GeometryView app, " +
   "in their browser, or, when they want to see it inside this chat app, as a link to open in " +
-  "the app's own browser (where: link). Where this computer has no native engine, the viewer " +
-  "opens in the user's browser and the pictures come from it, so the user sees what you look at.";
+  "the app's own browser (where: link). view_folder pictures a whole folder of models on one " +
+  "contact sheet with a numbered index, to survey a library or find a part by eye. Where this " +
+  "computer has no native engine, the viewer opens in the user's browser and the pictures come " +
+  "from it, so the user sees what you look at.";
 
 const STYLES = ["illustration", "metal", "clay", "blueprint", "technical", "studio"];
 const COLOURS = ["material", "parts", "mono", "file"];
@@ -27,6 +29,35 @@ const VIEWS = {
 
 const path = { type: "string", description: "Absolute path to a .step, .stp or .stl file." };
 
+// How long view_folder waits for imports before drawing what it has; the rest keep importing, so
+// asking again shows them.
+const kFolderDeadline = 90_000;
+
+const naturalOrder = new Intl.Collator("en", { numeric: true, sensitivity: "base" }).compare;
+
+/// A box's sides in millimetres, as the gallery writes them: 40 × 30 × 26.
+function sides(facts) {
+  if (!Array.isArray(facts?.min) || !Array.isArray(facts?.max)) return "";
+  return facts.max.map((high, axis) => {
+    const value = high - facts.min[axis];
+    return value >= 100 ? String(Math.round(value)) : String(Number(value.toPrecision(3)));
+  }).join(" × ");
+}
+
+function largestSide(facts) {
+  if (!Array.isArray(facts?.min) || !Array.isArray(facts?.max)) return Infinity;
+  return Math.max(...facts.max.map((high, axis) => high - facts.min[axis]));
+}
+
+/// Waits for `work`, or rejects with `kLate` once `deadline` passes; the work carries on.
+const kLate = Symbol("late");
+function byDeadline(work, deadline) {
+  work.catch(() => {});
+  return Promise.race([work, new Promise((_, reject) => {
+    setTimeout(() => reject(kLate), Math.max(0, deadline - Date.now())).unref?.();
+  })]);
+}
+
 // ---- The tree as an outline ---------------------------------------------------------------------
 
 function annotate(nodes) {
@@ -215,6 +246,105 @@ export const tools = [
       ];
     },
   },
+  {
+    name: "view_folder",
+    description: "Pictures a folder of 3D CAD models (STEP and STL files) on one contact sheet, " +
+                 "each part drawn over its name and number, for you to look at, with a numbered " +
+                 "index of the files: their paths, sizes in millimetres, parts and triangles. Use it " +
+                 "to survey a library, find a part by eye, or compare sizes (same_scale). Files are " +
+                 "taken in name order, max_files of them; those still importing after 90 seconds " +
+                 "are listed, and asking again shows them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute path to a folder." },
+        recursive: { type: "boolean", default: false, description: "Include the folders inside." },
+        max_files: { type: "integer", minimum: 1, maximum: 144, default: 36 },
+        filter: { type: "string", description: "Only files whose path inside the folder contains this." },
+        sort: { type: "string", enum: ["name", "size"], default: "name",
+                description: "Order on the sheet: by path, or smallest to largest measured size." },
+        style: { type: "string", enum: STYLES, default: "illustration" },
+        colour: { type: "string", enum: COLOURS, default: "parts" },
+        same_scale: { type: "boolean", default: false,
+                      description: "Draw every part at one scale, so sizes compare." },
+        cell: { type: "integer", minimum: 96, maximum: 384, default: 192,
+                description: "Each picture's size in points." },
+        columns: { type: "integer", minimum: 1, maximum: 12 },
+      },
+      required: ["path"],
+    },
+    async call(args) {
+      if (!nativeAvailable()) {
+        throw new Error("view_folder needs GeometryView's native engine, on a Mac with Apple silicon " +
+                        "and macOS 26 or later. Use render_view to picture files one by one.");
+      }
+      const folder = resolve(args.path);
+      const max = Math.min(144, Math.max(1, args.max_files ?? 36));
+      const filter = (args.filter ?? "").toLowerCase();
+      const found = (await listModels(folder, { recursive: args.recursive ?? false }))
+        .map((file) => ({ file, path: relative(folder, file) }))
+        .filter(({ path: inside }) => !filter || inside.toLowerCase().includes(filter))
+        .sort((a, b) => naturalOrder(a.path, b.path));
+      const where = `${folder}${args.recursive ? " and its folders" : ""}`;
+      if (found.length === 0) {
+        return [{ type: "text", text: `No STEP or STL files${filter ? ` matching "${args.filter}"` : ""} in ${where}.` }];
+      }
+      const chosen = found.slice(0, max);
+      // Imported a few at a time, by the deadline.
+      const deadline = Date.now() + kFolderDeadline;
+      const done = await Promise.all(chosen.map(async (entry) => {
+        try {
+          const read = (async () => {
+            const { blob } = await importModel(entry.file);
+            return { blob, facts: await readFacts(blob) };
+          })();
+          return { ...entry, ...(await byDeadline(read, deadline)) };
+        } catch (error) {
+          return error === kLate ? { ...entry, late: true } : { ...entry, error: String(error.message ?? error) };
+        }
+      }));
+      const drawn = done.filter((entry) => entry.blob);
+      if (args.sort === "size") drawn.sort((a, b) => largestSide(a.facts) - largestSide(b.facts));
+      const lines = [];
+      let png = null;
+      if (drawn.length > 0) {
+        const tiles = drawn.map((entry, index) => ({
+          blob: entry.blob,
+          label: basename(entry.path).replace(/\.(step|stp|stl)$/i, ""),
+          sub: [`#${index + 1}`, sides(entry.facts)].filter(Boolean).join(" · "),
+        }));
+        const sheet = await contactSheet(tiles, {
+          cell: args.cell ?? 192, columns: args.columns, style: args.style ?? "illustration",
+          colour: args.colour ?? "parts", sameScale: args.same_scale ?? false, title: basename(folder),
+        });
+        png = sheet.png;
+        drawn.forEach((entry, index) => {
+          const f = entry.facts ?? {};
+          const failed = sheet.tiles[index]?.error;
+          const parts = f.parts ? `${f.parts} part${f.parts === 1 ? "" : "s"}` : null;
+          const size = sides(f) ? `${sides(f)} mm` : null;
+          const triangles = f.triangles ? `${f.triangles.toLocaleString("en-US")} triangles` : null;
+          const name = f.name && f.name !== basename(entry.path).replace(/\.[^.]+$/, "") ? `"${f.name}"` : null;
+          lines.push(`${index + 1}. ${entry.path}: ${[size, parts, triangles, name, failed && `not drawn: ${failed}`]
+            .filter(Boolean).join(", ")}`);
+        });
+      }
+      const late = done.filter((entry) => entry.late).map((entry) => entry.path);
+      const failed = done.filter((entry) => entry.error);
+      const header = `${drawn.length} of ${found.length} STEP and STL files in ${where}` +
+        (filter ? ` matching "${args.filter}"` : "") +
+        `, ${args.style ?? "illustration"} style, ${args.sort === "size" ? "smallest to largest" : "by name"}` +
+        (args.same_scale ? ", at one scale" : "") + ". Numbered in reading order, as on the sheet.";
+      const text = [header, "", ...lines];
+      if (found.length > chosen.length) text.push("", `${found.length - chosen.length} more not shown: raise max_files (up to 144) or use filter.`);
+      if (late.length) text.push("", `Still importing, not drawn yet (ask again to see them): ${late.join(", ")}.`);
+      if (failed.length) text.push("", "Could not be read:", ...failed.map((entry) => `- ${entry.path}: ${entry.error}`));
+      const content = [];
+      if (png) content.push({ type: "image", data: png.toString("base64"), mimeType: "image/png" });
+      content.push({ type: "text", text: text.join("\n") });
+      return content;
+    },
+  },
   {
     name: "open_in_viewer",
     description: "Shows a STEP or STL model to the user, live, where they can turn it, select " +

package/web/NOTICES.md

@@ -3,6 +3,9 @@
 GeometryView is MIT licensed (see [LICENSE](LICENSE)). It builds on the work below, each under its
 own license. Versions are pinned in [ThirdParty/manifest.toml](ThirdParty/manifest.toml).
 
+The showcase models ([`Tools/showcase`](Tools/showcase), and the folder and sample files made from
+them) and the README's pictures are GeometryView's own, under the same MIT license.
+
 ## Shipped in the app, the browser viewer and the launcher
 
 | Project | License | How it is used |
@@ -47,3 +50,4 @@ SOFTWARE.
 |---|---|
 | [doctest](https://github.com/doctest/doctest) 2.4.12 | MIT; vendored with its [license](ThirdParty/doctest/LICENSE.txt) |
 | [Dawn](https://dawn.googlesource.com/dawn) (native) | BSD-3-Clause; the WebGPU test harness on the Mac |
+| [build123d](https://github.com/gumyr/build123d) 0.13 and [OCP](https://github.com/CadQuery/OCP) 8.0.1 | Apache-2.0; they write the showcase models' STEP files |