Plane Transformer

A TypeScript implementation of homography-based transformation between 2D planes. This library provides functionality to compute and apply projective transformations between two 2D coordinate systems.

Features

- Plane class for representing 2D coordinate systems
- PlaneTransformer class for computing and applying homography transformations
- Support for 4 or more point correspondences
- Error calculation and validation
- TypeScript type definitions included

Installation

``bash
npm install
`

Usage

Here's a basic example of how to use the library:

`typescript
import { Plane, Point } from './Plane';
import { PlaneTransformer, PointPair } from './PlaneTransformer';

// Create two planes
const sourcePlane = new Plane(1080, 1920); // e.g., mobile screen
const targetPlane = new Plane(640, 480); // e.g., camera image

// Define corresponding points
const pointPairs: PointPair[] = [
{ source: { x: 0, y: 0 }, target: { x: 0, y: 0 } },
{ source: { x: 1080, y: 0 }, target: { x: 640, y: 0 } },
{ source: { x: 0, y: 1920 }, target: { x: 0, y: 480 } },
{ source: { x: 1080, y: 1920 }, target: { x: 640, y: 480 } }
];

// Create transformer
const transformer = new PlaneTransformer(sourcePlane, targetPlane, pointPairs);

// Transform a point
const sourcePoint: Point = { x: 100, y: 200 };
const transformedPoint = transformer.transform(sourcePoint);

// Check transformation error
const error = transformer.getTransformationError();
`

Development

- Build the project: npm run build
- Run tests: npm test
- Run example: npm run example

Implementation Details

The implementation uses the following approach:

1. Computes the homography matrix using SVD (Singular Value Decomposition)
2. Requires at least 4 point correspondences
3. Supports additional points for better accuracy using least squares
4. Validates points are within plane boundaries
5. Provides error metrics for transformation quality

Dependencies

- numeric.js` for matrix operations
- TypeScript for type safety
- Jest for testing

License

MIT