nettika/mattercontrol
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
mattercontrol/TODO.md
Nettika 128bfde8c0
Add perspective toggles
2026-01-29 00:04:05 -08:00

14 KiB
Raw Blame History

MatterControl Web Port - Development Checklist

A step-by-step checklist for porting MatterControl's design features to a Vue + TypeScript + three.js web application.

Phase 1: Project Foundation

Development Environment

  • Create flake.nix with Node.js and pnpm
  • Add Rust toolchain to flake.nix (for later WASM work)
  • Add flake.lock and verify nix develop works
  • Create Justfile with dev, build, test, lint, format recipes

Vue Project Scaffold

  • Initialize Vue 3 project with Vite and TypeScript
  • Add ESLint and Prettier configuration
  • Create folder structure (components/, composables/, stores/, types/)
  • Add Pinia for state management

Testing Infrastructure

  • Add Vitest for unit testing
  • Create first placeholder test
  • Add test script to Justfile

Phase 2: 3D Viewport Foundation

three.js Setup

  • Install three.js and @types/three
  • Create Viewport.vue component with canvas element
  • Initialize three.js Scene, Camera, and Renderer
  • Add resize observer for responsive canvas
  • Implement render loop with requestAnimationFrame
  • Add basic lighting (ambient + two directional)

Scene Helpers

  • Add ground grid helper (XZ plane)
  • Add axis helper (RGB arrows for X/Y/Z)
  • Add option to toggle grid visibility
  • Add option to toggle axis visibility

Camera Controls

  • Install and configure OrbitControls (zoom, pan, orbit)
  • Add "fit to selection" camera function
  • Add "reset view" function (home position)
  • Add view presets (front, back, top, bottom, left, right)
  • Add orthographic/perspective toggle

Scene State Management

  • Create useScene composable for scene state
  • Define SceneObject interface (id, name, mesh, visible, locked)
  • Implement addObject() function
  • Implement removeObject() function
  • Implement clearScene() function
  • Add scene object list to Pinia store

Phase 3: Core UI Layout

Application Shell

  • Create AppLayout.vue with CSS Grid layout
  • Add header area with app title
  • Add left sidebar container (tools panel)
  • Add right sidebar container (properties panel)
  • Add center viewport area
  • Add bottom status bar

Theme System

  • Define CSS custom properties for colors
  • Define CSS custom properties for spacing
  • Define CSS custom properties for typography
  • Create dark theme color palette
  • Apply theme to all components

Sidebar Behavior

  • Create collapsible sidebar component
  • Add toggle buttons for left/right sidebars
  • Persist sidebar state to localStorage
  • Handle responsive layout for narrow screens

Phase 4: Selection System

Object Picking

  • Add Raycaster for mouse picking
  • Implement click-to-select single object
  • Implement click-on-empty to deselect
  • Add selectedObjects array to Pinia store
  • Implement Shift+click for multi-select
  • Implement Ctrl+click to toggle selection
  • Add "Select All" (Ctrl+A) shortcut

Selection Visualization

  • Add selection outline effect (OutlinePass or custom)
  • Add hover highlight on mouseover
  • Distinguish single vs multi-selection visually

Context Menu

  • Create right-click context menu component
  • Show context menu on object right-click
  • Add "Delete" option to context menu
  • Add "Duplicate" option to context menu
  • Add "Group" option to context menu
  • Close menu on click outside

Phase 5: Transform Tools

Transform Gizmos

  • Install three.js TransformControls
  • Attach gizmo to selected object(s)
  • Implement translate mode
  • Implement rotate mode
  • Implement scale mode
  • Hide gizmo when nothing selected

Tool Switching

  • Create toolbar with tool buttons (Select, Move, Rotate, Scale)
  • Add keyboard shortcuts (Q=Select, W=Move, E=Rotate, R=Scale)
  • Show active tool indicator
  • Add Escape to switch to Select tool

Transform Options

  • Add snap-to-grid toggle for translate
  • Add grid size input (1, 0.5, 0.1, etc.)
  • Add angle snap toggle for rotate
  • Add angle snap size (15°, 45°, 90°)

Phase 6: Properties Panel

Panel Structure

  • Create PropertiesPanel.vue component
  • Show "No selection" state when empty
  • Show "Multiple objects" state for multi-select
  • Add collapsible sections

Object Properties

  • Display and edit object name
  • Display and edit position (X, Y, Z)
  • Display and edit rotation (X, Y, Z in degrees)
  • Display and edit scale (X, Y, Z)
  • Add uniform scale toggle (lock aspect ratio)

Object State

  • Add visibility toggle (eye icon)
  • Add lock toggle (lock icon)
  • Reflect visibility in viewport
  • Prevent selection/transform of locked objects

Mesh Info

  • Display vertex count
  • Display face count
  • Display bounding box dimensions

Phase 7: Undo/Redo System

Command Infrastructure

  • Define Command interface (execute, undo)
  • Create useHistory composable
  • Implement undo stack with max depth (50)
  • Implement redo stack
  • Clear redo stack on new action

Core Commands

  • Implement AddObjectCommand
  • Implement RemoveObjectCommand
  • Implement TransformCommand
  • Implement RenameCommand
  • Implement GroupCommand

Integration

  • Wrap all scene modifications in commands
  • Wire Ctrl+Z to undo
  • Wire Ctrl+Y / Ctrl+Shift+Z to redo
  • Add undo/redo buttons to toolbar
  • Disable buttons when stack empty

Phase 8: File Import/Export

STL Support

  • Add three.js STLLoader
  • Create file input component for import
  • Parse STL and add mesh to scene
  • Add three.js STLExporter
  • Implement "Export as STL" function
  • Add binary/ASCII export option

OBJ Support

  • Add three.js OBJLoader
  • Parse OBJ and add mesh to scene
  • Add three.js OBJExporter
  • Implement "Export as OBJ" function

Export Options

  • Create export dialog component
  • Add "Export Selected" option
  • Add "Export All" option
  • Remember last export settings

Drag and Drop

  • Add drag-and-drop zone overlay
  • Detect file type from extension
  • Route to appropriate loader
  • Show loading indicator during import
  • Handle import errors with toast message

Phase 9: Primitives (MVP)

Primitive Generation

  • Create usePrimitives composable
  • Implement Box primitive
  • Implement Sphere primitive
  • Implement Cylinder primitive
  • Auto-select newly created primitives
  • Place primitives at scene origin (or selection center)

Primitives Panel

  • Create primitives panel in left sidebar
  • Add clickable primitive icons/buttons
  • Show primitive name on hover

Parametric Editing

  • Store primitive parameters in object metadata
  • Show parameters in properties panel for primitives
  • Update mesh when parameters change
  • Add "Convert to Mesh" to bake parameters

Phase 10: Clipboard & Grouping

Clipboard Operations

  • Implement Copy (Ctrl+C) - serialize to clipboard
  • Implement Cut (Ctrl+X) - copy then delete
  • Implement Paste (Ctrl+V) - deserialize and add
  • Offset pasted objects slightly to show difference
  • Implement Duplicate (Ctrl+D) - copy + paste in one action

Object Grouping

  • Implement Group command (Ctrl+G)
  • Create Group object that contains children
  • Select group selects all children
  • Transform group transforms all children
  • Implement Ungroup command (Ctrl+Shift+G)
  • Allow entering group to edit children

Phase 11: Persistence (IndexedDB)

Database Setup

  • Install idb library (IndexedDB wrapper)
  • Define database schema version 1
  • Create projects object store
  • Create settings object store
  • Implement database open/migration

Project Storage

  • Define Project interface (id, name, created, modified)
  • Implement saveProject() - serialize scene
  • Implement loadProject() - deserialize scene
  • Implement listProjects() - get all projects
  • Implement deleteProject()

Scene Serialization

  • Serialize mesh geometry (positions, normals, indices)
  • Serialize object transforms and metadata
  • Serialize group hierarchy
  • Handle large meshes efficiently (binary format)

Unsaved Changes

  • Track "dirty" state when scene modified
  • Show unsaved indicator in header
  • Warn before closing with unsaved changes
  • Warn before "New Project" with unsaved changes

Auto-Save

  • Add debounced auto-save on scene changes
  • Store current project ID in localStorage
  • Load last project on app start

Phase 12: Project Management UI

Toolbar Actions

  • Add "New" button - create empty project
  • Add "Open" button - show project browser
  • Add "Save" button - save current project
  • Add "Save As" button - save with new name
  • Add "Export" button - open export dialog

Project Browser

  • Create project browser dialog
  • Display projects as list with name and date
  • Add delete button per project
  • Add rename option per project
  • Double-click to open project

Recent Projects

  • Track recently opened projects
  • Add recent projects to File menu
  • Limit to last 5-10 projects

Phase 13: Extended Primitives

Additional Shapes

  • Implement Cone primitive
  • Implement Torus primitive
  • Implement Plane/Quad primitive
  • Implement Wedge/Prism primitive
  • Add parameter UI for each shape

Text Primitive

  • Add font loading (Google Fonts or bundled)
  • Implement 3D extruded text
  • Add text content input
  • Add font size parameter
  • Add extrusion depth parameter
  • Add font family selector

Phase 14: Basic Mesh Operations

Transform Operations

  • Implement "Center to Origin"
  • Implement "Align to Ground" (bottom at Z=0)
  • Implement "Mirror X"
  • Implement "Mirror Y"
  • Implement "Mirror Z"

Array/Pattern

  • Implement linear array (count + spacing)
  • Implement grid array (X count × Y count)
  • Create array objects as group

Mesh Utilities

  • Implement "Flip Normals"
  • Implement "Recompute Normals" (flat/smooth)
  • Implement "Merge Vertices" (weld by distance)

Phase 15: Boolean Operations (CSG)

CSG Setup

  • Research and select CSG library (manifold.js recommended)
  • Install and test CSG library
  • Create Web Worker for CSG operations
  • Create useBooleans composable

Boolean Operations

  • Implement Union (combine meshes)
  • Implement Subtract (cut mesh from mesh)
  • Implement Intersect (keep overlap)
  • Validate: require exactly 2 objects selected
  • Handle CSG errors gracefully

Boolean UI

  • Add Boolean section to toolbar or menu
  • Show progress indicator for slow operations
  • Add operation to undo history

Phase 16: Advanced Mesh Operations

Mesh Modification

  • Implement mesh simplification (decimate)
  • Add target face count or ratio input
  • Implement subdivision smooth
  • Add subdivision level input

Mesh Analysis

  • Detect non-manifold edges
  • Highlight non-manifold edges in red
  • Detect holes (boundary edges)
  • Implement "Fill Holes" repair

Phase 17: Library Browser

Library Panel

  • Create LibraryPanel.vue in left sidebar
  • Display saved projects as cards
  • Show project name and modified date
  • Add search/filter input

Thumbnails

  • Generate thumbnail on project save
  • Render scene to off-screen canvas
  • Store thumbnail as data URL in IndexedDB
  • Display thumbnail in library card

Phase 18: Polish & UX

User Feedback

  • Add toast notification system
  • Show success toast on save
  • Show error toast on failures
  • Add loading spinner component
  • Show loading during imports

Confirmations

  • Add confirmation dialog component
  • Confirm before delete objects
  • Confirm before delete project
  • Confirm before clear scene

Keyboard Shortcuts Help

  • Create keyboard shortcuts modal
  • Add "?" key to open shortcuts help
  • List all available shortcuts

Phase 19: Performance

Render Optimization

  • Profile render loop performance
  • Implement frustum culling
  • Add level-of-detail for distant objects
  • Throttle property panel updates

Large Scenes

  • Test with 100+ objects
  • Optimize scene tree rendering
  • Lazy-render off-screen UI
  • Profile memory usage

Phase 20: Rust + WASM Migration

Rust Project Setup

  • Create crates/mesh-ops/ directory
  • Initialize Cargo workspace
  • Add wasm-bindgen dependency
  • Add nalgebra dependency
  • Configure wasm-pack build
  • Update just wasm recipe

Mesh Data in Rust

  • Define Mesh struct (vertices, indices, normals)
  • Implement mesh creation from JS arrays
  • Implement mesh export to JS arrays
  • Add tests for mesh operations

Port Operations to Rust

  • Port "Merge Vertices" to Rust
  • Port "Compute Normals" to Rust
  • Port mesh simplification to Rust
  • Port CSG operations to Rust (or wrap manifold)

Integration

  • Create TypeScript wrapper for WASM module
  • Replace JS implementations with WASM calls
  • Benchmark performance improvement
  • Add WASM loading fallback for old browsers

Future Considerations (Out of Scope)

  • Additional file formats (3MF, AMF, STEP)
  • Measurement tools (distance, angle)
  • Section view / clipping planes
  • Multi-user collaboration
  • Plugin/extension system
  • Mobile/touch support
  • Offline PWA support