From fe1e25f4ba9b816a54982ebb313332b7e85a149e Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 26 Apr 2026 00:14:56 +0000 Subject: [PATCH 1/2] docs(OpenGeometry): add Core/Scene groups and fix orphaned pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add api/core/opengeometry.mdx — documents the OpenGeometry class (create, version, instance, enableDebug) extracted from index.ts - Add api/core/vector3.mdx — documents the wasm-backed Vector3 type - Add api/scene/spot-label.mdx — documents the SpotLabel CSS2D marker - Add OUTLINE_TYPE type definition to api/export/projection.mdx - Remove bogus demo link from api/export/ifc.mdx (no demo exists) - Fix broken internal links in api/scene/scene-management.mdx (missing /OpenGeometry/ product prefix) - Add projection, scene-management, spot-label, opengeometry, vector3 to docs.json navigation; add "Scene" and "Core" groups - Sync .atlas-analysis.json with current API surface and nav structure https://claude.ai/code/session_01LfFsmHz67gxarN59GMQYSt --- OpenGeometry/.atlas-analysis.json | 91 +++++++------- OpenGeometry/api/core/opengeometry.mdx | 126 ++++++++++++++++++++ OpenGeometry/api/core/vector3.mdx | 91 ++++++++++++++ OpenGeometry/api/export/ifc.mdx | 8 +- OpenGeometry/api/export/projection.mdx | 8 ++ OpenGeometry/api/scene/scene-management.mdx | 14 +-- OpenGeometry/api/scene/spot-label.mdx | 66 ++++++++++ docs.json | 17 ++- 8 files changed, 367 insertions(+), 54 deletions(-) create mode 100644 OpenGeometry/api/core/opengeometry.mdx create mode 100644 OpenGeometry/api/core/vector3.mdx create mode 100644 OpenGeometry/api/scene/spot-label.mdx diff --git a/OpenGeometry/.atlas-analysis.json b/OpenGeometry/.atlas-analysis.json index 641a9c2..b2da8ad 100644 --- a/OpenGeometry/.atlas-analysis.json +++ b/OpenGeometry/.atlas-analysis.json @@ -4,17 +4,17 @@ "projectDescription": "A high-performance CAD kernel for the web, providing 2D/3D geometric primitives and CAD operations via WebAssembly.", "theme": "almond", "primaryColor": "#4460FF", - "lightColor": null, - "darkColor": null, + "lightColor": "#4460FF", + "darkColor": "#4460FF", "navigation": { "tabs": [ { "tab": "Documentation", "groups": [ { - "group": "Get Started", + "group": "Introduction", "pages": [ - "introduction", + "what-is-opengeometry", "installation", "quickstart" ] @@ -23,15 +23,11 @@ "group": "Core Concepts", "pages": [ "concepts/architecture", - "concepts/brep", - "concepts/scene-graph" - ] - }, - { - "group": "Integration", - "pages": [ - "integration/threejs", - "integration/examples" + "concepts/primitives-and-shapes", + "concepts/operations", + "concepts/booleans", + "concepts/exports", + "concepts/brep" ] } ] @@ -57,7 +53,8 @@ "api/shapes/cuboid", "api/shapes/sphere", "api/shapes/wedge", - "api/shapes/sweep" + "api/shapes/sweep", + "api/shapes/opening" ] }, { @@ -66,15 +63,32 @@ "api/operations/extrude", "api/operations/offset", "api/operations/sweep", - "api/operations/triangulate" + "api/operations/triangulate", + "api/operations/boolean-operations" ] }, { - "group": "Scene & Export", + "group": "Export (Experimental)", + "pages": [ + "api/export/stl", + "api/export/ifc", + "api/export/pdf", + "api/export/step", + "api/export/projection" + ] + }, + { + "group": "Scene", "pages": [ "api/scene/scene-management", - "api/export/projection", - "api/export/pdf" + "api/scene/spot-label" + ] + }, + { + "group": "Core", + "pages": [ + "api/core/opengeometry", + "api/core/vector3" ] } ] @@ -84,29 +98,26 @@ "keyFeatures": [ "WebAssembly-powered geometric kernel written in Rust", "2D primitives: lines, arcs, rectangles, polylines, curves", - "3D shapes: polygons, cylinders, cuboids, spheres, wedges", - "CAD operations: extrusion, offset, sweep, triangulation", + "3D shapes: polygons, cylinders, cuboids, spheres, wedges, sweep, openings", + "CAD operations: extrusion, offset, sweep, triangulate, boolean operations", "BREP (Boundary Representation) data structure", - "Scene graph management for complex models", - "Export to PDF with projection support", - "Three.js integration layer" + "Scene management via OGSceneManager", + "3D-to-2D projection with hidden line removal", + "Export to STL, STEP, IFC, PDF", + "Three.js integration layer with CSS2D markup support" ], "publicApiSurface": [ - "OGLine", - "OGArc", - "OGRectangle", - "OGPolyline", - "OGCurve", - "OGPolygon", - "OGCylinder", - "OGCuboid", - "OGSphere", - "OGWedge", - "OGScene", - "Brep", - "extrude_polygon_by_buffer_geometry", - "offset_polygon", - "sweep_operation", - "triangulate_polygon" - ] + "OpenGeometry", + "OpenGeometryOptions", + "Vector3", + "OGSceneManager", + "SpotLabel", + "OUTLINE_TYPE", + "OGStlExportResult", + "OGStepExportResult", + "OGIfcExportResult" + ], + "extractedAt": "2026-04-26T00:10:00.661Z", + "sourceRef": "HEAD", + "entryFile": "main/opengeometry-three/index.ts" } diff --git a/OpenGeometry/api/core/opengeometry.mdx b/OpenGeometry/api/core/opengeometry.mdx new file mode 100644 index 0000000..c4dd570 --- /dev/null +++ b/OpenGeometry/api/core/opengeometry.mdx @@ -0,0 +1,126 @@ +--- +title: OpenGeometry +description: The runtime entrypoint that initializes the WebAssembly module and provides the singleton instance +icon: rocket +--- + +## Overview + +`OpenGeometry` is the top-level class you initialize before using any kernel-backed API. It loads and caches the WebAssembly binary, exposes version information, and provides an optional debug mode. + +**Use cases:** +- Bootstrap the wasm runtime once at application startup. +- Gate geometry construction behind `await OpenGeometry.create(...)` to guarantee the wasm module is ready. +- Enable debug rendering to inspect face normals and geometry orientation during development. + +## Initialization + +`OpenGeometry` is a singleton — call `create` once and reuse the returned instance. + +```ts +import { OpenGeometry } from "opengeometry"; + +const og = await OpenGeometry.create({ + wasmURL: "/opengeometry_bg.wasm", +}); +``` + +## `OpenGeometry.create` (static) + +Asynchronously initializes the wasm runtime. Subsequent calls return the cached singleton without re-initializing. + +```ts +static async create(options: OpenGeometryOptions): Promise +``` + +Call this before constructing `Vector3` or any kernel-backed wrapper. + +### Parameters + + + Configuration object for the runtime. All fields are optional. + + + + URL to the `opengeometry_bg.wasm` binary. When omitted, the module resolves the wasm file from a default relative path. + + + + Enable debug mesh overlays for visualizing internal geometry structures. + + +## Properties + + + The current version of the `opengeometry` package. Static read-only property — access as `OpenGeometry.version`. + + + + The cached singleton set after the first successful `create` call. `null` before initialization. Static property. + + + + Enables or disables debug rendering mode. When `true`: + + - Geometry renders with a semi-transparent material. + - Each face is colored randomly for visual distinction. + - Face normals are shown as overlays. + + Setting this to `true` also logs `"OpenGeometry Debug Mode Enabled"` to the console. Readable and settable after initialization. + + +## Code examples + +### Basic setup + +```ts +import { OpenGeometry, Vector3 } from "opengeometry"; + +await OpenGeometry.create({ wasmURL: "/opengeometry_bg.wasm" }); + +// Vector3 and all shape wrappers are now safe to use +const origin = new Vector3(0, 0, 0); +``` + +### Using the cached singleton + +```ts +import { OpenGeometry } from "opengeometry"; + +// First call — loads the wasm binary +const og = await OpenGeometry.create({ wasmURL: "/opengeometry_bg.wasm" }); + +// Subsequent calls return the same instance immediately +const same = await OpenGeometry.create(); +console.log(og === same); // true +``` + +### Enabling debug mode + +```ts +import { OpenGeometry } from "opengeometry"; + +const og = await OpenGeometry.create({ wasmURL: "/opengeometry_bg.wasm" }); + +og.enableDebug = true; +// All subsequently rendered shapes show normals and random face colors +``` + +### Checking the version at runtime + +```ts +import { OpenGeometry } from "opengeometry"; + +console.log(OpenGeometry.version); // e.g. "2.0.3" +``` + +## See also + + + + The wasm-backed 3D vector used throughout the API + + + Managing collections of geometry entities with OGSceneManager + + diff --git a/OpenGeometry/api/core/vector3.mdx b/OpenGeometry/api/core/vector3.mdx new file mode 100644 index 0000000..fcb71d8 --- /dev/null +++ b/OpenGeometry/api/core/vector3.mdx @@ -0,0 +1,91 @@ +--- +title: Vector3 +description: The wasm-backed 3D vector used as the coordinate type throughout the OpenGeometry API +icon: cube +--- + +## Overview + +`Vector3` is the shared coordinate type used across all OpenGeometry primitives, shapes, and operations. It is backed by the WebAssembly kernel, so the wasm module must be initialized with `OpenGeometry.create(...)` before you construct any `Vector3` instance. + +**Use cases:** +- Supplying start, end, center, or direction coordinates to primitive and shape constructors. +- Passing position arguments to `OGSceneManager` projection and export methods. + + +Constructing `Vector3` before `await OpenGeometry.create(...)` resolves will throw a wasm initialization error. Always await initialization first. + + +## Constructor + +```ts +new Vector3(x: number, y: number, z: number) +``` + +### Parameters + + + The X component of the vector. + + + + The Y component of the vector. + + + + The Z component of the vector. + + +## Code examples + +### Creating vectors after initialization + +```ts +import { OpenGeometry, Vector3 } from "opengeometry"; + +await OpenGeometry.create({ wasmURL: "/opengeometry_bg.wasm" }); + +const origin = new Vector3(0, 0, 0); +const tip = new Vector3(10, 0, 0); +``` + +### Using Vector3 with a primitive + +```ts +import { OpenGeometry, Vector3, Line } from "opengeometry"; + +await OpenGeometry.create({ wasmURL: "/opengeometry_bg.wasm" }); + +const line = new Line({ + start: new Vector3(0, 0, 0), + end: new Vector3(5, 5, 0), + color: 0x000000, +}); +``` + +### Using Vector3 with a 3D shape + +```ts +import { OpenGeometry, Vector3, Cuboid } from "opengeometry"; + +await OpenGeometry.create({ wasmURL: "/opengeometry_bg.wasm" }); + +const box = new Cuboid({ + center: new Vector3(0, 0.5, 0), + width: 2, + height: 1, + depth: 1, + color: 0x10b981, +}); +``` + +## See also + + + + Initialize the runtime before constructing Vector3 + + + A simple line primitive defined by two Vector3 points + + diff --git a/OpenGeometry/api/export/ifc.mdx b/OpenGeometry/api/export/ifc.mdx index b70dc93..24f1928 100644 --- a/OpenGeometry/api/export/ifc.mdx +++ b/OpenGeometry/api/export/ifc.mdx @@ -150,11 +150,7 @@ Native-only builds also expose `exportSceneToIfcFile(...)` (not available in bro ## Related -- [Exports](/OpenGeometry/concepts/exports) for an overview of available exporters and runtime constraints +- [Exports](/OpenGeometry/concepts/exports) — Overview of available exporters and runtime constraints - [STL export](/OpenGeometry/api/export/stl) - [STEP export](/OpenGeometry/api/export/step) (experimental) -- [Scene Management](/OpenGeometry/api/scene/scene-management) - Organizing geometry entities -## Live demo - -There is no dedicated IFC export demo page yet. Start from the demo index: -[OpenGeometry demos](https://demo.opengeometry.io/). +- [Scene management](/OpenGeometry/api/scene/scene-management) — Organizing geometry entities diff --git a/OpenGeometry/api/export/projection.mdx b/OpenGeometry/api/export/projection.mdx index de205a3..73ec3ee 100644 --- a/OpenGeometry/api/export/projection.mdx +++ b/OpenGeometry/api/export/projection.mdx @@ -13,6 +13,14 @@ an exporter limitation or confusing output, reach out on [Discord](https://discord.gg/cZY2Vm6E). +## OUTLINE_TYPE + +```ts +type OUTLINE_TYPE = "front" | "side" | "top"; +``` + +A convenience string-literal type that names the three standard orthographic views. Use it to label or select the view direction when building multi-view drawings. + ## Key Concepts ### Projection Modes diff --git a/OpenGeometry/api/scene/scene-management.mdx b/OpenGeometry/api/scene/scene-management.mdx index 6a34b70..868ff82 100644 --- a/OpenGeometry/api/scene/scene-management.mdx +++ b/OpenGeometry/api/scene/scene-management.mdx @@ -268,12 +268,12 @@ manager.setCurrentScene(analysisScene); ## Related -- [Projection](/api/export/projection) - Converting 3D scenes to 2D drawings -- [PDF Export](/api/export/pdf) - Exporting scenes to PDF format +- [Projection](/OpenGeometry/api/export/projection) — Converting 3D scenes to 2D drawings +- [PDF export](/OpenGeometry/api/export/pdf) — Exporting scenes to PDF format +- [Line](/OpenGeometry/api/primitives/line) — Basic 2D geometry that can be added to scenes -### Live Demo +### Live demo - - Try Scene Management in the browser - -- [Line Primitive](/api/primitives/line) - Basic 2D geometry that can be added to scenes \ No newline at end of file + + Try scene management in the browser + \ No newline at end of file diff --git a/OpenGeometry/api/scene/spot-label.mdx b/OpenGeometry/api/scene/spot-label.mdx new file mode 100644 index 0000000..8e80ed9 --- /dev/null +++ b/OpenGeometry/api/scene/spot-label.mdx @@ -0,0 +1,66 @@ +--- +title: SpotLabel +description: A Three.js CSS2D marker for annotating points on geometry in the scene +icon: hand-pointer +--- + +## Overview + +`SpotLabel` is a lightweight markup component that renders a small square dot on top of 3D geometry using the Three.js `CSS2DRenderer`. It extends `CSS2DObject` and is positioned in world space like any Three.js object. + +**Use cases:** +- Annotating a specific vertex or point of interest on a shape. +- Displaying a visual pick indicator during interactive selection workflows. + +## Constructor + +```ts +new SpotLabel() +``` + +`SpotLabel` takes no arguments. The DOM element (a 3×3 px bordered square) is created internally. + +## Code examples + +### Adding a spot label to a scene + +```ts +import { OpenGeometry, Vector3, SpotLabel } from "opengeometry"; +import { CSS2DRenderer } from "three/examples/jsm/renderers/CSS2DRenderer.js"; + +await OpenGeometry.create({ wasmURL: "/opengeometry_bg.wasm" }); + +// Set up CSS2DRenderer alongside your WebGLRenderer +const labelRenderer = new CSS2DRenderer(); +labelRenderer.setSize(window.innerWidth, window.innerHeight); +document.body.appendChild(labelRenderer.domElement); + +// Create and position the label +const label = new SpotLabel(); +label.position.set(2, 1, 0); // world-space coordinates + +scene.add(label); + +// Render both in your animation loop +function animate() { + requestAnimationFrame(animate); + renderer.render(scene, camera); + labelRenderer.render(scene, camera); +} +animate(); +``` + + +`SpotLabel` requires a `CSS2DRenderer` alongside your `WebGLRenderer`. The label is a DOM element that the `CSS2DRenderer` projects into screen space each frame. + + +## See also + + + + Managing geometry entities with OGSceneManager + + + Initialize the runtime before constructing wasm-backed objects + + diff --git a/docs.json b/docs.json index 8929a25..a0cb217 100644 --- a/docs.json +++ b/docs.json @@ -114,7 +114,22 @@ "OpenGeometry/api/export/stl", "OpenGeometry/api/export/ifc", "OpenGeometry/api/export/pdf", - "OpenGeometry/api/export/step" + "OpenGeometry/api/export/step", + "OpenGeometry/api/export/projection" + ] + }, + { + "group": "Scene", + "pages": [ + "OpenGeometry/api/scene/scene-management", + "OpenGeometry/api/scene/spot-label" + ] + }, + { + "group": "Core", + "pages": [ + "OpenGeometry/api/core/opengeometry", + "OpenGeometry/api/core/vector3" ] } ] From 41393f6058a1c259174b9337779a8289d85ea860 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 26 Apr 2026 00:15:27 +0000 Subject: [PATCH 2/2] chore: add .gitignore to exclude node_modules https://claude.ai/code/session_01LfFsmHz67gxarN59GMQYSt --- .gitignore | 1 + 1 file changed, 1 insertion(+) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c2658d7 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +node_modules/