homography-transform v1.0.0

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

npm install

Usage

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

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