# 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

## 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
- Import maps configured for external dependencies (`@redfish-util/`, etc.)
- Web workers used for computationally intensive image processing

## Camera Compatibility

- **UVC (USB webcams)**: Full browser support varies by platform (Mac lacks settings control)
- **IP cameras**: Via laser-server (Python) on port 8080
- **Axis cameras**: Direct IP interface
- **GeniCam**: Via laser-server integration

## 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