homography-transform/README.md

A robust TypeScript implementation of homography-based transformation between 2D planes, ideal for computer vision and image mapping

# 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