---
name: spatial-planning
description: Interactive 3D spatial planning tools using Three.js — room layout visualization, furniture placement, material/color specification, and 板材 (sheet goods) optimization for woodworking and interior design projects.
version: 1.0.0
author: Hermes Agent
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [threejs, 3d, spatial-planning, interior-design, layout, furniture, woodworking, 交互式3D, 空间规划]
    related_skills: [claude-design, p5js, sketch, architecture-diagram]
---

# Spatial Planning with Three.js

Use when the user wants to **visualize, plan, or iterate on a physical space** — a room, studio, workshop, garage, office — as an interactive 3D model they can manipulate. Covers: room geometry from real dimensions, furniture libraries, material specification, interaction (drag/rotate/delete), and cost/板材 optimization for woodworking projects.

## When to use

- User wants to "see" or "model" a space before building/furnishing it
- Room dimensions provided or estimable from photos
- Involves furniture layout, shelving, workbench design, studio setup
- Has woodworking /板材 component (desks, shelves, cabinets from sheet goods)
- Needs to optimize for standard material sizes to reduce waste/cost

## When NOT to use

- Pure generative art or data visualization → `p5js`
- 2D floor plan or architectural diagram → `architecture-diagram` or `excalidraw`
- Design mockups / UI screens → `claude-design` or `sketch`
- Detailed architectural CAD → dedicated CAD tool

## Core Workflow

```
尺寸提取 → Three.js房间建模 → 家具库 → 材质定义 → 交互放置 → 板材优化
```

### 1. 尺寸提取

From user input or image analysis (use mmx vision):
- Wall width, depth, height in meters
- Door/window positions (affects furniture placement)
- Special features (beams, pipes, slopes)

Default furniture heights:
- Standard desk: 740mm
- Standard shelf: 800mm (5-level), 1800mm (tall)
- Chair seat: 450mm

### 2. Three.js 房间建模

Essential components per room:

```javascript
// Room constants (in meters, convert from mm)
const RW = 2.45, RD = 5.0, RH = 2.45;

// 1. Floor + ceiling
const floor = new THREE.Mesh(
  new THREE.PlaneGeometry(RW, RD),
  new THREE.MeshStandardMaterial({ color: 0x333333, roughness: 0.95 })
);
floor.rotation.x = -Math.PI/2;
scene.add(floor);

// 2. Four walls (brick = 0x8b4513, back wall darker)
const wallMat = new THREE.MeshStandardMaterial({ color: 0x8b4513, roughness: 0.95 });

// 3. 木梁/桁架 (roof trusses as beams)
[-0.8, 0, 0.8].forEach(x => {
  const beam = new THREE.Mesh(new THREE.BoxGeometry(0.09, 0.11, RD), beamMat);
  beam.position.set(x, RH - 0.06, 0);
  scene.add(beam);
});

// 4. Directional light (sun) + ambient
const sun = new THREE.DirectionalLight(0xfff5e0, 1.2);
sun.position.set(4, 8, 3);
sun.castShadow = true;
scene.add(sun);
```

### 3. 家具库

**Material: 复合板/颗粒板**
```javascript
const mComp  = new THREE.MeshStandardMaterial({ color: 0xd4b896, roughness: 0.9, metalness: 0.0 });
const mCompD = new THREE.MeshStandardMaterial({ color: 0xc4a882, roughness: 0.9, metalness: 0.0 }); // 侧板，稍深
```

**工作桌 (desk)**
- Desktop: thin flat box (0.026m = 26mm board)
- Side panels: full-height boxes
- Braces: horizontal boxes for structure
- Standard: 2000×600×740mm (桌面60cm深，适合2.45m宽空间)
- Wide: 1500×500×740mm

**货架 (shelf)**
- Top/bottom panels: flat boxes
- Side panels: full-height boxes
- Interior shelves: flat boxes at intervals
- 矮货架: 1200×380×800mm (380mm深 = 1220÷3=406, 取380)
- 高货架: 800×380×1800mm (800mm长 = 2440÷3段，整除)

### 4. 交互系统

Standard interaction pattern:
- **Raycasting** for mouse picking (intersectObjects on furniture group)
- **OrbitControls** for camera (right-drag rotate, scroll zoom)
- **Drag plane** (y=0 plane) for furniture movement
- **Keyboard**: `Delete` to remove, `R` to rotate 45°
- **Selection highlight**: emissive color change on hover/select

```javascript
// Selection + drag pattern
raycaster.setFromCamera(mouse, camera);
const hit = raycaster.intersectObjects(furniture, true)
  .find(h => furniture.includes(h.object));

// Drag: clamp to room bounds
item.position.x = THREE.MathUtils.clamp(
  newX, -RW/2 + halfWidth, RW/2 - halfWidth
);
```

### 5. 板材 (Sheet Goods) 优化参考

2440×1220mm standard颗粒板/复合板:

| 成品尺寸 | 切割方式 | 出材率 |
|----------|----------|--------|
| 桌面 2000×600 | 长向切1块 | ~82% |
| 货架侧板 800×380 | 1220宽÷380=3块，2440长÷800=3段 | ~93% |
| 货架侧板 800×300 | 1220宽÷300=4块，2440长÷800=3段 | ~95% |
| 隔板 1200×380 | 长向切2块 | ~98% |

**优化原则:**
- 深度统一 380mm 或 300mm（1220宽的因数）
- 长度统一 800mm（2440的因数）
- 高货架每层800mm长，5层=4000mm → 2440板接板

### 6. 输出

- Single self-contained HTML file at `~/hermes-space-model.html` or user's home
- Open via `open` (macOS), `xdg-open` (Linux), or share IP:port for remote access
- Tell user exact path and how to open it

## 材质速查

复合板/颗粒板颜色梯度:
- 浅: `0xd4b896` (暖白木色)
- 中: `0xc4a882` (侧板/深色件)
- 深: `0xb4946a` (厚重感)

金属腿/支架: `0x888899` roughness:0.4, metalness:0.7

## 文件位置

交互式3D空间规划工具默认保存在: `/home/kuhnn/hermes-space-model.html`

## 参考资料

- `references/sheet-goods.md` — 板材（2440×1220mm）切割方案、尺寸优化、出材率计算