# Getting Started with AnySurface

AnySurface is an ES6 module collection for projected surface interactions. It provides camera-projector correspondence mapping, laser pointer detection, 3D surface scanning, and synthetic mouse event generation.

## Installation

```bash
yarn add anysurface
# or
npm install anysurface
```

AnySurface has one runtime dependency: `simple-statistics` (for scan data clustering).

## Basic Import

```js
import { Surface, CameraInterface } from 'anysurface'
```

Or import specific subsystems:

```js
import {
    Surface,
    CameraInterface,
    Correspondence,
    InputSimulator,
    PointerDetectorClient,
    initWorker,
} from 'anysurface'
```

## Quick Start

### 1. Set Up Canvases

AnySurface requires HTML canvas elements for its subsystems:

```html
<canvas id="pointer"></canvas>
<canvas id="scan"></canvas>
<canvas id="align"></canvas>
<canvas id="shutter"></canvas>
```

### 2. Initialize Surface

```js
import { Surface, initWorker } from 'anysurface'

// If using the bundled worker, point to its location
initWorker('./build/anysurface.worker.js')

const surface = new Surface()

await surface.init({
    pointerCanvas: document.getElementById('pointer'),
    scanCanvas: document.getElementById('scan'),
    alignCanvas: document.getElementById('align'),
    shutterCanvas: document.getElementById('shutter'),
}, {
    trackingOn: true,
})

surface.on('initialized', () => {
    console.log('AnySurface ready')
})
```

### 3. Detect a Camera

```js
// USB camera (browser webcam)
const found = await surface.detectCamera('USB Camera')

// IP camera via laser-server
const found = await surface.detectCamera('GeniCam', 'http://localhost:8080')
```

### 4. Auto-Detect Exposure

```js
await surface.findAndSetShutterValue(
    (value) => console.log('Optimal shutter:', value),
    (err) => console.error('Failed:', err)
)
```

### 5. Run a Gray Code Scan

The scan establishes the camera-projector correspondence mapping:

```js
// The scan projects gray code patterns and captures camera images
// This happens on the scanCanvas
```

After scanning, retrieve the mapping:

```js
const rasters = surface.getAllRasters()
// rasters.cameraRaster  - camera pixel -> projector cell
// rasters.projectorRaster - projector cell -> camera pixel
```

### 6. Enable Laser Tracking

With a correspondence mapping loaded, laser pointer positions are automatically converted to synthetic mouse events on DOM elements:

```js
surface.backgroundSubtract = true
// Laser pointer events now fire as mouseover, mousedown, mousemove, mouseup, click
```

## Using Individual Components

You don't need to use the `Surface` orchestrator. Components work independently:

```js
import { CameraInterface, PointerDetectorClient } from 'anysurface'

const camera = new CameraInterface()
await camera.detectCamera('USB Camera')

const detector = new PointerDetectorClient(camera, 100)
detector.on('laser-on', ({u, v, i}) => {
    console.log(`Laser at (${u}, ${v}) intensity ${i}`)
})
detector.on('laser-move', ({u, v}) => {
    console.log(`Laser moved to (${u}, ${v})`)
})
detector.on('laser-off', () => {
    console.log('Laser lost')
})

await detector.start()
```

## Web Worker Setup

For best performance, laser detection runs in a web worker. Initialize it with the correct path to the bundled worker:

```js
import { initWorker } from 'anysurface'

// Point to wherever you serve the worker file
initWorker('./path/to/anysurface.worker.js')
```

If the worker fails to load (e.g., CSP restrictions), detection falls back to the main thread automatically.

## Camera Compatibility

| Camera Type | Loader | Settings | Notes |
|-------------|--------|----------|-------|
| USB webcam (Windows/Android) | `USBImageLoader` | `BrowserUSBSettings` | Full browser support |
| USB webcam (Mac) | `USBImageLoader` | `UVCServerSettings` | Requires uvcc-webserver on port 3456 |
| USB webcam (Linux) | `USBImageLoader` | `BrowserUSBSettings` | Partial settings support |
| IP / GeniCam | `IPImageLoader` | `IPLaserServerSettings` | Requires laser-server on port 8080 |
| Axis | `AxisLoader` | `AxisSettings` | Direct IP interface |

## Next Steps

- [API Reference](./API.md) - Complete API documentation
- [Architecture](./ARCHITECTURE.md) - System design overview
- [Bundling](./BUNDLING.md) - How to consume the bundle