marimo-cad 0.1.0__tar.gz

marimo_cad-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Build JS bundle
+        run: |
+          cd js
+          npm install
+          npm run build
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

marimo_cad-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv/
+venv/
+ENV/
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+src/marimo_cad/static/widget.js
+src/marimo_cad/static/widget.css
+
+# Playwright
+test-results/
+playwright-report/
+blob-report/
+.playwright/
+
+# Marimo cache
+**/__marimo__/
+
+# Keep sample files but ignore generated exports
+!notebooks/sample_part.step

marimo_cad-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cemrehan Cavdar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

marimo_cad-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: marimo-cad
+Version: 0.1.0
+Summary: Reactive Parametric CAD for marimo notebooks
+Project-URL: Homepage, https://github.com/cemrehancavdar/marimo-cad
+Project-URL: Repository, https://github.com/cemrehancavdar/marimo-cad
+Project-URL: Issues, https://github.com/cemrehancavdar/marimo-cad/issues
+Author-email: Cemrehan Cavdar <cemrehancavdar@hotmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: 3d,anywidget,build123d,cad,marimo,parametric
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: anywidget>=0.9.0
+Requires-Dist: build123d>=0.10.0
+Requires-Dist: marimo>=0.9.0
+Requires-Dist: ocp-tessellate>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: gears
+Requires-Dist: bd-warehouse>=0.1.0; extra == 'gears'
+Description-Content-Type: text/markdown
+
+# marimo-cad
+
+**Reactive Parametric CAD** for [marimo](https://marimo.io) notebooks.
+
+Build interactive 3D CAD models with sliders that update in real-time without losing your camera position.
+
+![Parametric Bookshelf Demo](assets/demo.gif)
+
+## Why marimo-cad?
+
+| Use Case | Native build123d | marimo-cad |
+|----------|------------------|------------|
+| Quick visualization | Just return the object | Overkill |
+| **Parametric design with sliders** | Camera resets on every change | Camera preserved |
+| Named multi-part assemblies | No | Yes, with tree view |
+| Export (STL/STEP/GLTF) | Manual | Built-in |
+
+## Installation
+
+```bash
+uv add marimo-cad
+```
+
+## Quick Start
+
+```python
+import marimo as mo
+from build123d import Box
+import marimo_cad as cad
+
+size = mo.ui.slider(10, 50, value=20, label="Size")
+viewer = cad.Viewer()
+
+box = Box(size.value, size.value, size.value)
+viewer.render(box)
+
+mo.vstack([size, viewer])
+```
+
+## Examples
+
+See [notebooks/](notebooks/) for complete examples:
+- `bookshelf.py` - Parametric bookshelf
+- `vase.py` - Parametric vase with STL export
+
+## Viewer Features
+
+- **Mouse**: Rotate (drag), pan (right-drag), zoom (scroll)
+- **Tree view**: Toggle part visibility
+- **Clipping planes**: Slice along X/Y/Z
+- **Measurement**: Distance and angles
+
+## Limitations
+
+- Large models (>100k triangles) may be slow to tessellate
+- Selection events not yet exposed to Python
+
+## Development
+
+```bash
+uv sync && cd js && npm install && npm run build && cd ..
+uv run pytest tests/           # 34 tests
+uv run ruff check src/ --fix   # Lint
+```
+
+---
+
+## API Reference
+
+### Viewer
+
+```python
+viewer = cad.Viewer(width="100%", height=600)
+viewer.render(shapes)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `width` | `str \| int` | `"100%"` | CSS width or pixels |
+| `height` | `int` | `600` | Height in pixels |
+
+**render(shapes)** - Render shapes, preserving camera position.
+
+```python
+# Single shape
+viewer.render(box)
+
+# Multiple shapes
+viewer.render([box, cylinder])
+
+# Named parts with colors
+viewer.render([
+    {"shape": base, "name": "Base", "color": "blue"},
+    {"shape": top, "name": "Top", "color": "red", "alpha": 0.8},
+])
+```
+
+### PartSpec
+
+Dict for specifying parts with metadata:
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `shape` | `Shape` | Yes | build123d object |
+| `name` | `str` | No | Display name |
+| `color` | `str` | No | Color name or hex |
+| `alpha` | `float` | No | Opacity 0.0-1.0 |
+
+### COLORS
+
+Available named colors: `blue`, `red`, `green`, `yellow`, `orange`, `purple`, `cyan`, `pink`, `gray`, `white`, `black`
+
+```python
+{"shape": box, "color": "blue"}      # Named
+{"shape": box, "color": "#ff6600"}   # Hex
+```
+
+### Export Functions
+
+```python
+from marimo_cad import export_stl, export_step, export_gltf
+
+export_stl(obj, "part.stl")                    # 3D printing
+export_stl(obj, "fine.stl", tolerance=0.0001)  # Higher resolution
+export_step(obj, "part.step")                  # CAD interchange (lossless)
+export_gltf(obj, "part.glb")                   # Web viewers
+```
+
+| Function | Parameters | Description |
+|----------|------------|-------------|
+| `export_stl` | `obj, filename, tolerance=0.001, angular_tolerance=0.1` | Tessellated mesh |
+| `export_step` | `obj, filename` | Exact geometry |
+| `export_gltf` | `obj, filename` | Web-ready format |
+
+All return `Path` to exported file.
+
+### How It Works
+
+1. **Tessellate**: build123d → triangle meshes (ocp-tessellate)
+2. **Transport**: Mesh data → JavaScript (anywidget)
+3. **Render**: Three.js via three-cad-viewer
+4. **Update**: `render()` updates geometry, camera preserved
+
+## License
+
+MIT

marimo_cad-0.1.0/README.md

@@ -0,0 +1,146 @@
+# marimo-cad
+
+**Reactive Parametric CAD** for [marimo](https://marimo.io) notebooks.
+
+Build interactive 3D CAD models with sliders that update in real-time without losing your camera position.
+
+![Parametric Bookshelf Demo](assets/demo.gif)
+
+## Why marimo-cad?
+
+| Use Case | Native build123d | marimo-cad |
+|----------|------------------|------------|
+| Quick visualization | Just return the object | Overkill |
+| **Parametric design with sliders** | Camera resets on every change | Camera preserved |
+| Named multi-part assemblies | No | Yes, with tree view |
+| Export (STL/STEP/GLTF) | Manual | Built-in |
+
+## Installation
+
+```bash
+uv add marimo-cad
+```
+
+## Quick Start
+
+```python
+import marimo as mo
+from build123d import Box
+import marimo_cad as cad
+
+size = mo.ui.slider(10, 50, value=20, label="Size")
+viewer = cad.Viewer()
+
+box = Box(size.value, size.value, size.value)
+viewer.render(box)
+
+mo.vstack([size, viewer])
+```
+
+## Examples
+
+See [notebooks/](notebooks/) for complete examples:
+- `bookshelf.py` - Parametric bookshelf
+- `vase.py` - Parametric vase with STL export
+
+## Viewer Features
+
+- **Mouse**: Rotate (drag), pan (right-drag), zoom (scroll)
+- **Tree view**: Toggle part visibility
+- **Clipping planes**: Slice along X/Y/Z
+- **Measurement**: Distance and angles
+
+## Limitations
+
+- Large models (>100k triangles) may be slow to tessellate
+- Selection events not yet exposed to Python
+
+## Development
+
+```bash
+uv sync && cd js && npm install && npm run build && cd ..
+uv run pytest tests/           # 34 tests
+uv run ruff check src/ --fix   # Lint
+```
+
+---
+
+## API Reference
+
+### Viewer
+
+```python
+viewer = cad.Viewer(width="100%", height=600)
+viewer.render(shapes)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `width` | `str \| int` | `"100%"` | CSS width or pixels |
+| `height` | `int` | `600` | Height in pixels |
+
+**render(shapes)** - Render shapes, preserving camera position.
+
+```python
+# Single shape
+viewer.render(box)
+
+# Multiple shapes
+viewer.render([box, cylinder])
+
+# Named parts with colors
+viewer.render([
+    {"shape": base, "name": "Base", "color": "blue"},
+    {"shape": top, "name": "Top", "color": "red", "alpha": 0.8},
+])
+```
+
+### PartSpec
+
+Dict for specifying parts with metadata:
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `shape` | `Shape` | Yes | build123d object |
+| `name` | `str` | No | Display name |
+| `color` | `str` | No | Color name or hex |
+| `alpha` | `float` | No | Opacity 0.0-1.0 |
+
+### COLORS
+
+Available named colors: `blue`, `red`, `green`, `yellow`, `orange`, `purple`, `cyan`, `pink`, `gray`, `white`, `black`
+
+```python
+{"shape": box, "color": "blue"}      # Named
+{"shape": box, "color": "#ff6600"}   # Hex
+```
+
+### Export Functions
+
+```python
+from marimo_cad import export_stl, export_step, export_gltf
+
+export_stl(obj, "part.stl")                    # 3D printing
+export_stl(obj, "fine.stl", tolerance=0.0001)  # Higher resolution
+export_step(obj, "part.step")                  # CAD interchange (lossless)
+export_gltf(obj, "part.glb")                   # Web viewers
+```
+
+| Function | Parameters | Description |
+|----------|------------|-------------|
+| `export_stl` | `obj, filename, tolerance=0.001, angular_tolerance=0.1` | Tessellated mesh |
+| `export_step` | `obj, filename` | Exact geometry |
+| `export_gltf` | `obj, filename` | Web-ready format |
+
+All return `Path` to exported file.
+
+### How It Works
+
+1. **Tessellate**: build123d → triangle meshes (ocp-tessellate)
+2. **Transport**: Mesh data → JavaScript (anywidget)
+3. **Render**: Three.js via three-cad-viewer
+4. **Update**: `render()` updates geometry, camera preserved
+
+## License
+
+MIT

marimo_cad-0.1.0/js/ARCHITECTURE.md

@@ -0,0 +1,214 @@
+# JS Architecture: three-cad-viewer Wrapper
+
+## Overview
+
+This document explains the JavaScript wrapper layer we built over `three-cad-viewer` to enable reactive CAD visualization in marimo notebooks.
+
+## The Problem
+
+`three-cad-viewer` is a powerful CAD viewer, but it has several quirks that make reactive updates difficult:
+
+1. **Full re-render resets camera** - Calling `viewer.render()` rebuilds everything and resets camera position
+2. **Internal API confusion** - `ObjectGroup` extends `THREE.Group` directly, so position/quaternion are on the group itself (not `group.group`)
+3. **Path-based group keys** - Parts are stored with paths like `/shapes/assembly/Left` not just `Left`
+4. **Tree view coupling** - The tree UI is built during render and doesn't update when parts change
+5. **No exported TreeView** - The `TreeView` class is internal, making tree updates tricky
+
+## Solution Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     index.js (Widget)                        │
+│  - Creates Display and LiveViewer                           │
+│  - Handles model.on('change:shapes_data') events            │
+│  - Calls viewer.syncParts() for updates                     │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 LiveViewer (extends Viewer)                  │
+│  - render() - initial render, builds PartManager            │
+│  - syncParts() - smart update (add/remove/update parts)     │
+│  - _rebuildTreeView() - updates tree when parts change      │
+│  - Exposes parts: PartManager for direct manipulation       │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      PartManager                             │
+│  - get(id) → PartHandle                                     │
+│  - add(partData) → PartHandle                               │
+│  - remove(id)                                               │
+│  - update(id, partData)                                     │
+│  - sync(partsArray) → { added, updated, removed }           │
+│  - buildFromViewer() - maps viewer's groups to handles      │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       PartHandle                             │
+│  - setPosition(x, y, z)                                     │
+│  - setQuaternion(x, y, z, w)                                │
+│  - setTransform(loc) - from [[pos], [quat]] format          │
+│  - updateGeometry(vertices, normals, triangles)             │
+│  - updateEdges(edgeData)                                    │
+│  - dispose()                                                │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│              three-cad-viewer (external library)             │
+│  - Viewer: base viewer class                                │
+│  - Display: UI container (tree, toolbar, canvas)            │
+│  - THREE.js scene management                                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Key Files
+
+### `js/src/part-manager.js`
+
+**PartHandle** - Clean interface to a single part:
+- Abstracts away three-cad-viewer's ObjectGroup quirks
+- Provides simple `setPosition()`, `updateGeometry()` methods
+- Handles buffer reuse for efficient geometry updates
+
+**PartManager** - Manages all parts:
+- Tracks parts by ID with a Map
+- `sync()` method does intelligent diffing: only adds new, removes old, updates existing
+- `buildFromViewer()` maps three-cad-viewer's internal groups to PartHandles
+- Handles path-based key lookup (finds `Left` in `/shapes/assembly/Left`)
+
+### `js/src/live-viewer.js`
+
+**LiveViewer** - Extends `three-cad-viewer.Viewer`:
+- Overrides `render()` to initialize PartManager after scene builds
+- `syncParts()` - main update method, preserves camera
+- `_rebuildTreeView()` - reconstructs tree UI when parts change
+- `_buildTreeFromParts()` - creates tree data structure from parts array
+
+### `js/src/index.js`
+
+**Widget entry point**:
+- Creates Display and LiveViewer
+- Listens for `change:shapes_data` traitlet events
+- First render uses `viewer.render()`, subsequent updates use `viewer.syncParts()`
+
+## How It Works
+
+### Initial Render
+```javascript
+// First time - full render
+viewer.render(shapesData, renderOptions, viewerOptions);
+// This:
+// 1. Builds THREE.js scene with all parts
+// 2. Creates tree view
+// 3. Sets up camera, lights, controls
+// 4. PartManager.buildFromViewer() maps groups to handles
+```
+
+### Subsequent Updates
+```javascript
+// When slider changes - smart sync
+viewer.syncParts(newShapesData);
+// This:
+// 1. PartManager.sync() diffs old vs new parts
+// 2. Removes parts not in new data
+// 3. Updates existing parts (geometry + transform)
+// 4. Adds new parts
+// 5. If parts added/removed, rebuilds tree view
+// 6. Camera position preserved!
+```
+
+### Tree View Rebuild
+```javascript
+// When parts added or removed
+_rebuildTreeView(partsData) {
+  // 1. Build tree structure: { shapes: { "PartName": [1,1], ... } }
+  const newTree = this._buildTreeFromParts(partsData);
+  
+  // 2. Update viewer's internal tree properties
+  this.tree = this.expandedTree = this.compactTree = newTree;
+  
+  // 3. Get TreeView class from existing instance (not exported)
+  const TreeViewClass = this.treeview.constructor;
+  
+  // 4. Dispose old, create new
+  this.treeview.dispose();
+  this.treeview = new TreeViewClass(this.tree, ...callbacks);
+  
+  // 5. Render new tree
+  this.display.clearCadTree();
+  this.display.addCadTree(this.treeview.create());
+  this.treeview.render();
+}
+```
+
+## three-cad-viewer Quirks Handled
+
+### ObjectGroup is a THREE.Group
+```javascript
+// WRONG - group.group is undefined
+group.group.position.set(x, y, z);
+
+// CORRECT - ObjectGroup extends THREE.Group
+group.position.set(x, y, z);
+```
+
+### Path-based Keys
+```javascript
+// Groups are stored with paths
+const groups = viewer.nestedGroup.groups;
+// Keys: "/shapes/assembly/Left", "/shapes/assembly/Right", etc.
+
+// PartManager handles lookup
+_findViewerGroup(id) {
+  for (const [path, group] of Object.entries(groups)) {
+    if (path === id || path.endsWith('/' + id)) {
+      return { path, group };
+    }
+  }
+}
+```
+
+### Tree Structure Format
+```javascript
+// three-cad-viewer expects this format:
+{
+  "shapes": {
+    "Left Side": [1, 1],   // [shape_visible, edges_visible]
+    "Right Side": [1, 1],
+    "Top": [1, 1],
+    // ...
+  }
+}
+```
+
+## Usage Example
+
+```javascript
+// In marimo widget
+const viewer = new LiveViewer(display, options, callback);
+
+// Initial render
+viewer.render(shapesData, renderOptions, viewerOptions);
+
+// When data changes (slider moved)
+model.on("change:shapes_data", () => {
+  const newData = model.get("shapes_data");
+  viewer.syncParts(newData);  // Camera preserved, tree updated
+});
+
+// Direct part manipulation (if needed)
+const part = viewer.getPart("Left Side");
+part.setPosition(10, 0, 0);
+viewer.update(true);
+```
+
+## Benefits
+
+1. **Clean API** - No need to understand three-cad-viewer internals
+2. **Reactive updates** - `syncParts()` handles add/remove/update intelligently
+3. **Camera preserved** - No jarring resets when parameters change
+4. **Tree updates** - Tree view reflects current parts
+5. **Efficient** - Reuses geometry buffers when sizes match