# MyClients.md

This file documents how client applications utilize the AnySurface library and their specific needs.

## Simtable2/AnyHazard - Augmented Reality Emergency Management System

**Location**: `../Simtable2/`
**Branch Used**: `ft-claude-in-mix`

### Overview
Simtable2 is an AR sandtable system for emergency management and wildfire simulation that transforms physical sand surfaces into interactive GIS environments. AnySurface serves as the **core enabling technology** - the entire application architecture is built around AnySurface capabilities.

### How They Use AnySurface

#### 1. Core Integration Pattern
```javascript
// Surface wrapper (src/surface.js)
import { Surface } from '../node_modules/anysurface/lib/Surface.js'
export var surface = new Surface()

// Event-driven initialization
surface.on('initialized', async () => {
    await initializeSurfaceCamera()
    // Connect laser calibration UI
})
```

#### 2. Hardware Interface Requirements
- **Camera Support**: Industrial GenICAM cameras via `http://127.0.0.1:8080` (laser-server)
- **USB Camera Support**: Consumer webcams and Point Grey/FLIR cameras
- **Settings Management**: Camera exposure, gain, white balance stored in Firebase
- **Device Profiles**: Multiple projector/camera hardware combinations

#### 3. Physical Interaction Pipeline
```
Laser Pointer → AnySurface Detection → Surface Coordinates →
Geographic Coordinates → Model Parameters → Simulation Updates → Projector Output
```

#### 4. Critical Dependencies on AnySurface Components

**A. Surface Class (`lib/Surface.js`)**
- Main orchestrator for all subsystems
- Status events for UI feedback
- API methods: `findAndSetShutterValue()`, `align.start()`

**B. Camera Interface (`lib/CameraInterface.js`)**
- Hardware abstraction for different camera types
- Automatic parameter optimization via shutter estimation
- Real-time frame processing

**C. Graycode Scanning (`lib/GrayScan.js`)**
- Structured light surface mapping
- Persistent calibration storage
- Surface geometry detection

**D. Laser Detection (`lib/Laser/`)**
- Sub-pixel accuracy tracking
- Web worker processing (`brightestPoint_webWorker.js`)
- Background subtraction and adaptive thresholding

**E. Input Simulation (`lib/Laser/InputSimulator.js`)**
- Mouse event synthesis from laser coordinates
- Coordinate system transformations
- Event filtering to prevent jitter

**F. Alignment System (`lib/Align.js`)**
- Interactive projector calibration
- Distortion correction
- Transform matrix generation

**G. Shutter Estimation (`lib/ShutterEstimate.js`)**
- Automatic exposure optimization (1-100ms in 3ms increments)
- Brightness analysis (1/4 pixels > 400 RGB threshold)
- Progress feedback for UI

### Client-Specific Needs

#### 1. Real-Time Performance Requirements
- Web worker architecture for non-blocking laser detection
- Coordinate transformations must not impact simulation performance
- Sub-pixel accuracy for precise GIS interactions

#### 2. Hardware Flexibility
- Support for various projector/camera combinations
- Automatic hardware detection and configuration
- Field-deployable calibration procedures

#### 3. Coordinate System Integration
- Physical surface coordinates → Camera pixels → Projector pixels → Geographic coordinates
- Integration with Proj4 for spatial reference transformations
- Multi-resolution support for different hardware capabilities

#### 4. Data Persistence
- Firebase integration for device settings and calibration data
- LocalForage for offline operation
- Scenario storage and multi-device collaboration

#### 5. UI Integration Points
- Angular 1.3 service bridge (`surfaceSvc.js`)
- Leaflet mapping library integration
- Mouse/laser interaction layer (`mouseLayer.js`)
- Real-time status feedback and progress indicators

### Architecture Dependencies

**System Architecture Flow**:
1. AnySurface initialization → Camera detection
2. Surface mapping → Correspondence table generation
3. Input simulation startup → Laser pointer interaction enabled
4. Continuous coordinate transformation → GIS model integration

**Critical Role**: AnySurface IS the physical interface layer. Without it, Simtable2 would be just a regular computer application. The entire system - fire simulations, GIS interactions, layer management, and emergency response tools - depends on AnySurface to translate physical gestures into digital commands.

**Performance Impact**: The system requires real-time response for emergency management scenarios, making AnySurface's web worker architecture and efficient coordinate transformations essential.

### Current Development
The `ft-claude-in-mix` branch suggests active development integrating AI/ML capabilities, potentially for:
- Improved laser detection algorithms
- Automatic calibration procedures
- Intelligent surface mapping
- Enhanced gesture recognition

### Integration Lessons
- Event-driven architecture works well for complex initialization sequences
- Firebase integration for settings persistence is crucial for field deployment
- Web worker architecture is essential for real-time performance
- Hardware abstraction layer enables wide device compatibility
- Coordinate system bridging is the most critical architectural component