pointcloud-zernike/README.md

A high-performance JavaScript library for Zernike polynomial decomposition of point cloud data

<div align="center">
  <img src="https://webassembly.org/css/webassembly.svg" alt="WebAssembly" width="100" height="100">
</div>

# pointcloud-zernike

**A specialized metrology tool for optical surface analysis from non-regular measurement data.**

Modern optical surface metrology instruments like LiDAR systems, laser trackers, and scanning profilers generate non-regular grid point clouds that pose significant challenges for traditional analysis methods. Conventional approaches require heavy interpolation to convert irregular data into regular grids, introducing artifacts and computational overhead. This library solves that problem by providing direct Zernike polynomial decomposition on raw point cloud data, enabling precise optical surface characterization without interpolation losses.

Our solution processes irregular measurement data directly from various sources:
- **LiDAR systems** - 3D laser scanning with non-uniform point distributions
- **Laser trackers** - High-precision coordinate measurements with sparse sampling
- **Scanning profilers** - Linear and area scanning with variable point density
- **Coordinate measuring machines (CMM)** - Discrete point measurements

The library delivers comprehensive 28-term Zernike analysis directly on point clouds, providing industry-standard optical surface characterization for manufacturing quality control, precision optics testing, and surface metrology applications.

## Features

### **Ultra High Performance**
- **100M+ data points** tested and verified for large-scale metrology applications
- **WebAssembly-powered** computation engine for maximum speed
- **JavaScript integration** with seamless browser compatibility

### **Real-time Visualization**
- **WebGL 2.0 rendering** for high-speed interactive visualization
- **Real-time surface analysis** with instant feedback
- **Hardware-accelerated** graphics for smooth performance

### **Web-Based Solution**
- **Browser-only** deployment - no desktop software required
- **Cross-platform** compatibility (Windows, macOS, Linux)
- **Zero installation** for end users - just open in browser

### **Extensible Architecture**
- **Modular design** for custom metrology applications
- **Plugin-ready** framework for specialized analysis tools
- **API-first** approach for integration with existing workflows

### **Advanced Analysis**
- **28-term Zernike polynomial decomposition** (Z1-Z28) for comprehensive surface analysis
- **Surface reconstruction** from Zernike coefficients with sub-nanometer precision
- **Residual analysis** for fit quality assessment and validation
- **Comprehensive error handling** and robust data validation

## Installation

```bash
npm install pointcloud-zernike
```

## Usage

### Basic Example

```javascript
import ZernikeDecomposer from 'pointcloud-zernike';

// Create decomposer instance
const decomposer = new ZernikeDecomposer();

// Prepare your point cloud data
const surfaceData = {
    x: [/* array of x coordinates */],
    y: [/* array of y coordinates */],
    z: [/* array of z coordinates */]
};

// Perform decomposition
const result = await decomposer.decompose(surfaceData, {
    numTerms: 28,
    wavelength_nm: 632.8,
    progressCallback: (progress) => {
        console.log(`Progress: ${progress.progress}% - ${progress.message}`);
    }
});

if (result.success) {
    console.log('Decomposition completed!');
    console.log('Coefficients:', result.coefficients);
    console.log('Residual RMS:', result.residualAnalysis.rms);
    console.log('Processing time:', result.metadata.processingTime_ms, 'ms');
}
```

### Surface Reconstruction

```javascript
// Reconstruct surface from coefficients
const reconstructed = decomposer.reconstructSurface(
    originalX, 
    originalY, 
    result.metadata.radius, 
    result.coefficients
);
```

### Results Output Modes

The library provides 4 different output modes for results:

```javascript
// Mode 0: Background computing (structured JSON)
const jsonResult = await decomposer.dumpResults(result, { mode: 0 });
console.log('RMS:', jsonResult.rms, 'PV:', jsonResult.pv);

// Mode 1: Command line information (formatted console output)
await decomposer.dumpResults(result, { mode: 1 });

// Mode 2: Generate coefficients table file
await decomposer.dumpResults(result, { 
    mode: 2, 
    outputFile: 'coefficients.txt' 
});

// Mode 3: Generate table and residual surface PLY
await decomposer.dumpResults(result, { 
    mode: 3, 
    outputFile: 'coefficients.txt',
    plyFile: 'residual_surface.ply',
    surfaceData: originalSurfaceData
});
```

## API Reference

### `ZernikeDecomposer`

#### Constructor
```javascript
const decomposer = new ZernikeDecomposer();
```

#### Methods

##### `decompose(surfaceData, options)`
Performs Zernike polynomial decomposition on point cloud data.

**Parameters:**
- `surfaceData` (Object): Surface data with `x`, `y`, `z` coordinate arrays
- `options` (Object): Optional configuration
  - `numTerms` (number): Number of Zernike terms (default: 28)
  - `wavelength_nm` (number): Wavelength in nanometers (default: 632.8)
  - `progressCallback` (function): Progress callback function

**Returns:** Promise resolving to decomposition results

##### `reconstructSurface(x, y, radius, coeffs)`
Reconstructs surface from Zernike coefficients.

**Parameters:**
- `x` (Array): X coordinates
- `y` (Array): Y coordinates  
- `radius` (number): Normalization radius
- `coeffs` (Array): Zernike coefficients

**Returns:** Array of reconstructed Z coordinates

##### `getZernikeName(index)`
Gets the name of a Zernike term by index.

**Parameters:**
- `index` (number): Zero-based index

**Returns:** String name of the Zernike term

##### `dumpResults(result, options)`
Generates formatted output of decomposition results in various modes.

**Parameters:**
- `result` (Object): Decomposition result object
- `options` (Object): Output configuration
  - `mode` (number): Output mode (0-3, default: 1)
  - `precision` (number): Decimal precision (default: 6)
  - `wavelength_nm` (number): Wavelength in nanometers (default: 632.8)
  - `outputFile` (string): Output file path (modes 2-3)
  - `plyFile` (string): PLY file path (mode 3)
  - `surfaceData` (Object): Original surface data (mode 3)

**Output Modes:**
- **Mode 0**: Background computing - Returns structured JSON data
- **Mode 1**: Command line - Formatted console output
- **Mode 2**: Generate table - Writes coefficients table to file
- **Mode 3**: Generate table + PLY - Writes table and residual surface PLY

**Returns:** Promise resolving to output result object

### Data Format

Input surface data should be an object with three arrays:

```javascript
const surfaceData = {
    x: [1.0, 2.0, 3.0, ...],  // X coordinates
    y: [1.0, 2.0, 3.0, ...],  // Y coordinates  
    z: [0.1, 0.2, 0.3, ...]   // Z coordinates (heights)
};
```

### Result Format

The decomposition result contains:

```javascript
{
    success: true,
    coefficients: [
        { term: "Piston", coeff: 0.123, index: 1 },
        { term: "Tip", coeff: 0.045, index: 2 },
        // ... more coefficients
    ],
    residualAnalysis: {
        rms: 0.001,
        pv: 0.005,
        reconstructedZ: [/* reconstructed surface */],
        residualZ: [/* residual errors */]
    },
    metadata: {
        numPoints: 1000,
        numTerms: 28,
        wavelength_nm: 632.8,
        radius: 10.0,
        mean: 0.001,
        processingTime_ms: 150
    }
}
```

## Zernike Terms

The library supports 28 Zernike polynomial terms:

| Index | Term | Description |
|-------|------|-------------|
| Z1 | Piston | Constant offset |
| Z2 | Tip | X-Tilt |
| Z3 | Tilt | Y-Tilt |
| Z4 | Defocus | Defocus |
| Z5 | Astigmatism (45°) | Oblique Astigmatism |
| Z6 | Astigmatism (0°) | Vertical Astigmatism |
| Z7 | Coma (Y) | Vertical Coma |
| Z8 | Coma (X) | Horizontal Coma |
| Z9 | Spherical | Spherical Aberration |
| ... | ... | ... |
| Z28 | Tertiary Trefoil | Tertiary Trefoil (Oblique) |

## Performance

The library is optimized for large datasets:
- Efficient memory usage with chunked processing
- Numerical stability with regularization
- Progress callbacks for long-running operations
- Handles datasets with millions of points

## Error Handling

The library includes comprehensive error handling:
- Input validation for coordinate arrays
- NaN and infinity detection
- Numerical stability checks
- Graceful degradation for ill-conditioned data

## Testing

Run the included test:

```bash
npm test
```

## License

MIT License

## Applications

This library is particularly useful for:
- **Optical surface analysis** - Characterizing mirrors, lenses, and other optical components
- **Precision machining** - Analyzing surface quality in manufacturing
- **Metrology** - Surface form measurement and analysis
- **Research** - Wavefront analysis and optical system design

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.