warpvas
Version:
This JavaScript library enables fast and efficient image distortion transformations using Canvas 2D.
211 lines (161 loc) • 6.74 kB
Markdown
# Warpvas
[English](README.md) | [中文](README.cn.md)
## Introduction
> Warpvas is inspired by the combination of "warped" and "canvas", meaning a distorted canvas.
This JavaScript library helps you efficiently implement 3D-like image distortion effects on `Canvas 2D`. Using specific strategies, you can achieve various effects such as perspective, convex/concave lens effects.
## Installation
```shell
npm install warpvas
# or
pnpm add warpvas
```
## Features
- **Grid Split Strategy**: Supports custom grid splitting algorithms to achieve perspective/wave/curved surface distortion effects through different strategies.
- **Boundary Curve Control**: Fine-tune boundary distortion effects through Bezier curve control points.
- **Auxiliary Display Effects**: Provides options to add split lines and split points on the distorted image to assist in observing the distortion effects.
- **Input/Output Limitations**: Provides options to control the input and output dimensions of distorted images for better quality and efficiency control, also preventing performance issues from oversized images.
- **Multiple Rendering Engines**: Switch freely between WebGL (high performance) and Canvas2D (high compatibility) rendering modes.
- **Safe Rendering Mode**: Automatically falls back to Canvas2D rendering when WebGL rendering fails, ensuring basic functionality.
- **State Serialization**: Supports serializing distortion states to base64 strings for easy saving/restoring of complex distortion states.
## Usage
### 1. Create a New Warpvas Instance
```typescript
// Create using an image
const img = new Image();
img.src = 'example.jpg';
img.onload = () => new Warpvas(img);
// Create using canvas with a 2x2 grid
const canvas = document.createElement('canvas');
const warpvas = new Warpvas(canvas, 2, 2);
```
### 2. Update Vertex Coordinates
```typescript
// Move the top-left vertex of region (0,0) to (50,50)
const warpvas = new Warpvas(canvas);
warpvas.updateVertexCoord(
0, // row index
0, // column index
'tl', // vertex position (top-left)
{ x: 50, y: 50 }, // new position
true // recalculate curve
);
```
### 3. Update Boundary Curve Coordinates
```typescript
// Create an arc-shaped bottom boundary
const warpvas = new Warpvas(canvas);
warpvas.updateRegionBoundCoords(
0, // row index
0, // column index
'bottom', // direction
[
{ x: 0, y: canvas.height }, // start point
{ x: canvas.width / 3, y: canvas.height / 2 }, // control point 1
{ x: (canvas.width / 3) * 2, y: canvas.height / 2 }, // control point 2
{ x: canvas.width, y: canvas.height }, // end point
]
);
```
### 4. Add Split Points to Divide Regions
```typescript
// Add a split point at the center of the first region (0,0) with 10% tolerance
const warpvas = new Warpvas(canvas);
const region = warpvas.originalRegions[0][0];
warpvas.splitRegionByPoint(
0, // row index
0, // column index
{
x: (region.tl.x + region.br.x) / 2, // region center X coordinate
y: (region.tl.y + region.br.y) / 2, // region center Y coordinate
},
0.1 // 10% tolerance
);
```
### 5. Remove a Specific Distortion Region
```typescript
// Remove the region at row 1, column 1
const warpvas = new Warpvas(canvas);
warpvas.removeRegion({
row: 1,
column: 1
});
```
### 6. Warpvas Rendering Configuration Options
```typescript
// Control rendering effects and debug view display
const warpvas = new Warpvas(canvas);
warpvas.setRenderingConfig({
// padding: 10, // Set 10px padding
// enableAntialias: true, // Enable anti-aliasing
// enableSafeRendering: true, // Enable safe rendering mode
// enableContentDisplay: true, // Show distorted content
enableGridDisplay: true, // Show distortion grid
enableGridVertexDisplay: true, // Show grid vertices
gridColor: { r: 206, g: 102, b: 91, a: 1 } // Use coral red grid
});
```
### 7. Set Maximum Grid Subdivision Ratio
```typescript
// Set sparse grid to improve performance
const warpvas = new Warpvas(canvas);
warpvas
.setSplitUnit(0.2)
.setRenderingConfig({
enableGridDisplay: true,
gridColor: { r: 206, g: 102, b: 91, a: 1 }
});
```
### 8. Set Grid Split Point Calculation Strategy
To apply perspective mode, you need to install the warpvas-perspective package separately.
```typescript
import WarpvasPerspective from 'warpvas-perspective';
const warpvas = new Warpvas(canvas);
warpvas.setSplitStrategy({
name: 'custom',
execute: (warpvas) => {
// Use default strategy calculation result
// return Warpvas.strategy(warpvas);
// Use perspective strategy calculation result
return WarpvasPerspective.strategy(warpvas);
}
});
```
### 9. Set Input Canvas Size Limit
When processing large images, you can use this method to limit the maximum size of the input canvas. The system will automatically scale the image proportionally within the limits to improve performance and reduce memory usage.
```typescript
const warpvas = new Warpvas(canvas);
// Limit input height to 100px, width scales proportionally
warpvas.setInputLimitSize({
height: 100
});
```
### 10. Set Output Canvas Size Limit
Limit the maximum size of the distorted output canvas. When distortion results in an oversized canvas, the system will automatically scale the result proportionally within limits to prevent rendering failures due to memory constraints.
```typescript
const warpvas = new Warpvas(canvas);
// Limit output height to 100px, width scales proportionally
warpvas.setOutputLimitSize({
height: 100
});
```
### 11. Set Rendering Engine Type
```typescript
const warpvas = new Warpvas(canvas);
// Enable Canvas2D rendering
warpvas.setRenderingContext('2d');
// Enable WebGL rendering
warpvas.setRenderingContext('webgl');
```
### 12. Generate Distorted Canvas Asynchronously with Web Worker
```typescript
const canvas = document.createElement('canvas');
const warpvas = new Warpvas(canvas);
await warpvas.renderWithWorker();
```
Check out the project's [online demo](https://huanjinliu.github.io/warpvas/) or directly view the [project API documentation](docs/api/README.md).
### License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
### Contact
huanjinliu - [huanjin.liu@foxmail.com](mailto:huanjin.liu@foxmail.com)