A high-performance JavaScript library for Zernike polynomial decomposition of point cloud data
npm install pointcloud-zernikebash
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
``