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

$3

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

$3

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

$3

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

$3

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

$3

- 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

$3

`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');
}
`

$3

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

$3

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

$3

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

$3

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)
};
`

$3

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.