Overview

Sketch3D is a browser-based 3D design tool built with Three.js and Vite. It uses a face-and-edge surface modeling approach inspired by SketchUp — there are no solid objects, only independent Face and Edge primitives that can be drawn, split, extruded, swept, and painted.

The entire application runs client-side with no backend required. Projects can be persisted to GitHub via Device Flow OAuth.

Architecture

The application is organized into six core modules, wired together in main.js:

Data Flow

Every user action follows the same path:

1. Input — Mouse/keyboard event dispatched to the active tool
2. Command — Tool creates a Command object (e.g. ExtrudeFaceCommand)
3. Execute — UndoManager.executeCommand(cmd) runs cmd.execute() and pushes to the undo stack
4. Kernel — Command calls GeometryKernel methods to create/modify/delete geometry
5. Render — Engine's animation loop renders the updated scene

Quick Start

# Clone and run
git clone https://github.com/user/sketch3d.git
cd sketch3d
npm install
npm run dev        # http://localhost:3000

# Build for production
npm run build      # outputs to dist/

Project Structure

sketch3d/
├── app/index.html      # App shell (canvas + toolbar HTML)
├── index.html          # Landing page
├── docs/index.html     # This documentation
├── src/
│   ├── main.js         # Bootstrap & wiring
│   ├── engine.js       # Three.js setup
│   ├── geometry.js     # Face, Edge, Group, GeometryKernel
│   ├── tools.js        # All tool implementations
│   ├── history.js      # Command classes & UndoManager
│   ├── inference.js    # Snapping engine
│   ├── export.js       # OBJ/STL export
│   ├── ui.js           # Toolbar, panels, milestones
│   ├── github.js       # GitHub OAuth & API client
│   ├── styles.css      # All app styles
│   └── examples.js     # Demo scene builder
└── vite.config.js      # Vite MPA config

Engine

src/engine.js — Three.js wrapper providing scene setup, camera controls, and raycasting utilities.

Constructor

Creates the renderer (WebGL, antialiased), perspective camera (45° FOV), orbit controls (middle=pan, right=orbit, scroll=zoom), lighting (ambient + directional + hemisphere), grid (100×100 at Y=0), and colored axes.

Key Methods

Geometry Kernel

src/geometry.js — Central manager for all geometric data. Contains Face, Edge, Group classes and the GeometryKernel.

Constructor

Properties

Face Operations

Create a new face, add it to the kernel, wire boundary edges, add mesh to scene.

Split a face by cutting a hole with innerVerts. Returns the inner face (filling the hole) and the outer face (frame with hole). Inner face uses polygonOffsetFactor: 2 to avoid z-fighting.

Extrude face along its normal by distance. Creates bottom, top, and side faces as independent Face objects.

Sweep a 2D profile along a 3D path using parallel-transport frames. Creates side quads and cap faces. Used by FollowMeTool.

Revolve a profile around an axis to create a surface of revolution. Handles on-axis vertices by collapsing quads to triangles. 24 steps default.

Compute polygon offset using angle bisectors. Positive = inward, negative = outward.

Edge Operations

Reuse an existing edge matching endpoints (within eps=0.01) or create a new one. Core deduplication mechanism.

Auto-detect closed loops formed by a new edge. Uses leftmost-turn cycle detection with intersection splitting. Creates faces for all discovered coplanar cycles.

Intersection

Compute all overlaps between two face sets, chain segments into paths/loops, and split faces. Handles both non-coplanar (line-plane intersection + clipping) and coplanar (Sutherland-Hodgman) cases.

Serialization

Serialize all faces, edges, groups, and camera state to a JSON-compatible object.

Clear all geometry and restore from JSON. Resets undo history.

Face

The primary geometric primitive. A planar polygon with optional holes.

Constructor

Properties

Key Methods

Edge

First-class edge primitive. All edges (standalone lines and face boundaries) are Edge objects stored in the kernel's edges map.

Constructor

Properties

Edges are deduplicated via findOrCreateEdge(a, b) with epsilon 0.01. When a face is created, _createBoundaryEdges(face) wires bidirectional references between the face and its edges.

Group

Named collection of faces. Groups are excluded from auto-intersection and can be moved/rotated as a unit.

Properties

Tool System

src/tools.js — All user-facing tools extend the base Tool class. ToolManager handles activation and switching.

Base Class

class Tool {
  constructor(engine, geometry, inference, history) { ... }
  activate() {}    // Called when tool becomes active
  deactivate() {}  // Called when switching away
  onMouseDown(event) {}
  onMouseMove(event) {}
  onMouseUp(event) {}
  onKeyDown(event) {}
}

ToolManager

Deactivates the current tool and activates the named tool. Dispatches a toolChanged custom event.

Helper Functions

Undo / Redo

src/history.js — Command pattern. Every user action creates a Command with execute() and undo() methods.

UndoManager

Creating a Custom Command

class MyCommand extends Command {
  constructor(kernel, params) {
    super();
    this.kernel = kernel;
    this.params = params;
    this._createdFace = null;
  }

  execute() {
    this._createdFace = this.kernel.createFaceFromPoints(
      this.params.points, this.params.normal
    );
  }

  undo() {
    if (this._createdFace) {
      this.kernel.deleteFace(this._createdFace);
      this._createdFace = null;
    }
  }
}

Snapping (Inference Engine)

src/inference.js — SketchUp-style snapping with visual feedback indicators.

Snap Priority

1. Endpoint (green) — Existing face/edge vertices
2. Midpoint (blue) — Edge midpoints
3. Axis alignment (red/green/blue) — Cardinal alignment from reference point
4. Grid (orange) — 0.5-unit grid fallback

Usage

const result = inference.snap(worldPoint);
// result = { point: Vector3, type: 'endpoint'|'midpoint'|'axis'|'grid', color: hex }

inference.setReferencePoint(lastClickPoint);  // for axis alignment
inference.showIndicator(result);              // display snap sphere
inference.hideIndicator();                    // clear feedback

Export (OBJ / STL)

src/export.js — Static export methods with vertex deduplication and proper triangulation.

Wavefront OBJ format. Handles faces with holes by extracting pre-triangulated geometry from ShapeGeometry. Simple faces exported as n-gons. Vertex deduplication with eps=0.0001.

ASCII STL format. Extracts triangles from ShapeGeometry for faces with holes, uses fan triangulation for simple faces.

Trigger browser file download.

Serialization

Projects are serialized as a single JSON object stored in sketch3d.json.

JSON Format

{
  "faces": [
    {
      "vertices": [[x, y, z], ...],
      "normal": [nx, ny, nz],
      "holes": [[[x, y, z], ...], ...],
      "color": 13421772,
      "metalness": 0,
      "roughness": 0.8,
      "opacity": 1,
      "textureId": null,
      "visible": true,
      "groupId": null
    }
  ],
  "edges": [
    { "points": [[x, y, z], ...], "color": 0 }
  ],
  "groups": [
    { "id": "group_1", "name": "Box", "faceIndices": [0, 1, 2, 3, 4, 5] }
  ],
  "camera": {
    "position": [15, 20, 15],
    "target": [0, 0, 0]
  }
}

GitHub Integration

src/github.js — Device Flow OAuth for GitHub authentication. Projects are stored as sketch3d.json in private repos. Each save creates a commit — commits serve as "milestones" that can be browsed and restored.

Flow

1. startDeviceFlow() → Get user code + verification URL
2. User visits GitHub URL, enters code
3. pollForToken() → Receive access token
4. validateToken() → Fetch username and avatar
5. createRepo(name) → Private repo for project
6. saveProject(repo, json, message) → Commit sketch3d.json
7. listMilestones(repo) → Browse commit history
8. getProjectAtCommit(repo, sha) → Restore any version

Sharing

Public repos can be loaded via /app/?gh=owner/repo. The fetchProject() and listPublicMilestones() methods work without authentication for public repos.

Command Reference

All commands in src/history.js extend the base Command class.

Tool Reference

Keyboard Shortcuts