# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

AnySurface is an ES6 module collection for projected surface interactions. The main entry point is `Surface.js`, which orchestrates camera-projector correspondence mapping, laser pointer detection, 3D scanning, and synthetic mouse event generation.

## Development Commands

This project uses Yarn for dependency management:
- `yarn install` - Install dependencies
- No build process required (pure ES6 modules served directly)
- Testing is done via HTML files in `/tests/` directory (open in browser)
  - Main test: `tests/basic.html` - Camera interface examples and basic functionality

## Code Style

Uses Prettier with: no semicolons, single quotes, 4-space tabs, trailing commas (ES5 style).

## Architecture

### Core Components

**Surface.js** - Main orchestrator class that:
- Initializes and coordinates all subsystems
- Manages camera interface and projector parameters  
- Handles gray code scanning for camera-projector correspondence
- Controls laser detection and synthetic event generation

**Key Subsystems:**
- **GrayScan** (`lib/GrayScan.js`) - Gray code pattern projection and camera correspondence mapping
- **InputSimulator** (`lib/Laser/InputSimulator.js`) - Converts laser positions to synthetic DOM events
- **Align** (`lib/Align.js`) - Camera alignment visualization
- **ShutterEstimate** (`lib/ShutterEstimate.js`) - Automatic camera exposure optimization

### Camera System Architecture

The camera system uses a polymorphic interface pattern:

```
CameraInterface
├── ImageLoader (gets images)
│   ├── IPImageLoader (for IP/GeniCam cameras)
│   ├── USBImageLoader (for UVC webcams)
│   ├── WebRTCImageLoader
│   └── DummyImageLoader
└── SettingsInterface (controls camera parameters)
    ├── IPLaserServerSettings (for laser-server)
    ├── UVCServerSettings (for UVC server)
    ├── BrowserUSBSettings (browser native)
    └── DummyCameraSettingsInterface
```

### Laser Detection Pipeline

1. Camera captures image
2. Background subtraction (optional) 
3. Brightest point detection (runs in web worker for performance)
4. Position mapping through correspondence table
5. Synthetic mouse event generation

### 3D Scanning Flow

1. `flatScan()` - Capture baseline correspondence with flat surface
2. `calibrationMoundScan(x0,y0,x1,y1)` - Learn height differences with known mound
3. `moundScan()` - Generate height maps of current surface

## Module System

- Pure ES6 modules with explicit imports/exports
- Single external dependency: `simple-statistics` (ckmeans clustering for scan analysis)
- Import maps configured in HTML files for `@simple-statistics/`
- Web workers used for computationally intensive image processing
- Internal utilities in `lib/utils/` (e.g., Evented class for pub/sub)

## Camera Compatibility

- **UVC (USB webcams)**: Full browser support varies by platform
  - Mac browsers: can stream video but cannot control camera settings (use UVC server as fallback)
  - Windows/Android Chrome: full support including settings
  - Linux: partial settings support
- **IP cameras**: Via laser-server (Python) on port 8080
- **Axis cameras**: Direct IP interface
- **GeniCam**: Via laser-server integration

## External Servers

- **laser-server**: Python server for GeniCam/PointGrey cameras (port 8080) - https://github.com/RedfishGroup/laser-server/
- **uvcc-webserver**: Node.js server for USB camera settings on Mac (port 3456) - https://github.com/RedfishGroup/uvcc-webserver
  - Required on Mac where browsers cannot control camera settings
  - API: `/get/:device/:control`, `/set/:device/:control/:value`, `/devices`, `/controls/:device`

## Deployment

CircleCI deploys branches to `https://dev.simtable.com/anysurface/{branch}/demo.html`. The `config.js` file is modified during deployment to inject build metadata.

## Configuration

- `config.js` - Build-time configuration (modified by deploy system)
- `lib/Projectors.js` - Default camera/projector parameter presets
- Settings persisted to Firebase and localStorage per device

## Key Files to Understand

- `lib/Surface.js:23` - Main initialization method
- `lib/Calibration/LaserCalibrator/webComponent/LaserThresholdCalibrator.js` - Main calibration UI
- `lib/Laser/findBrightestPoint.js` - Core laser detection algorithm
- `lib/Scan/Correspondence.js` - Camera-projector coordinate mapping