Deca-image-tools NPM

deca-image-tools

A lightweight TypeScript library for image processing operations, offering a variety of filters, transformations including edge detection, blur effects, color manipulation, and image transformations.

Installation

npm install deca-image-tools

Features

Edge detection using Sobel operators
Gaussian blur filter
Image sharpening
Brightness adjustment
Image colorization
Color inversion
Image rotation
Image skewing
Image file saving
TypeScript support out of the box
Zero dependencies
Fully typed API

Usage

Edge Detection

The edgeDetect function applies Sobel edge detection to an image, converting it to grayscale and highlighting edges:

import { edgeDetect } from 'deca-image-tools';

// Assuming you have an ImageData object from a canvas
const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d');
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);

// Apply edge detection
const edgedImage = edgeDetect(imageData);

// Draw the result back to canvas
ctx.putImageData(edgedImage, 0, 0);

Gaussian Blur

The gaussianBlur function applies a Gaussian blur effect to smooth the image:

import { gaussianBlur } from 'deca-image-tools';

// Apply Gaussian blur with default radius
const blurredImage = gaussianBlur(imageData);

// Or specify a custom radius
const customBlurredImage = gaussianBlur(imageData, 2);

Color Manipulation

The library provides several color manipulation functions:

import { colorize, invertColors, adjustBrightness } from 'deca-image-tools';

// Apply a red tint
const color = { r: 255, g: 0, b: 0 };
const colorizedImage = colorize(imageData, color);

// Invert colors
const invertedImage = invertColors(imageData);

// Adjust brightness (factor > 1 brightens, < 1 darkens)
const brightenedImage = adjustBrightness(imageData, 1.5);

Image Transformations

The library includes functions for geometric transformations:

import { rotateImage, skewImage } from 'deca-image-tools';

// Rotate image by 45 degrees
const rotatedImage = rotateImage(imageData, 45);

// Skew image horizontally and vertically
const skewedImage = skewImage(imageData, 0.2, 0.1);

Saving Images

The library provides functionality to save processed images:

import { saveImage } from 'deca-image-tools';

// Save the processed image to a file
await saveImage(imageData, 'output.png');

API Reference

edgeDetect(imageData: ImageData): ImageData

Detects edges in an image using the Sobel operator.

Parameters:

imageData: ImageData object containing the source image

Returns:

New ImageData object containing the edge-detected image

gaussianBlur(imageData: ImageData, radius?: number): ImageData

Applies a Gaussian blur effect to the image.

Parameters:

imageData: ImageData object containing the source image
radius: Optional blur radius (default: 1)

Returns:

New ImageData object containing the blurred image

sharpen(imageData: ImageData): ImageData

Applies a sharpening filter to the image.

Parameters:

imageData: ImageData object containing the source image

Returns:

New ImageData object containing the sharpened image

adjustBrightness(imageData: ImageData, factor: number): ImageData

Adjusts the brightness of an image.

Parameters:

imageData: ImageData object containing the source image
factor: Brightness adjustment factor (>1 brightens, <1 darkens)

Returns:

New ImageData object with adjusted brightness

colorize(imageData: ImageData, color: { r: number; g: number; b: number }): ImageData

Applies a color tint to an image.

Parameters:

imageData: ImageData object containing the source image
color: Object containing RGB values (0-255) for the tint color

Returns:

New ImageData object containing the colorized image

invertColors(imageData: ImageData): ImageData

Inverts the colors of an image.

Parameters:

imageData: ImageData object containing the source image

Returns:

New ImageData object with inverted colors

rotateImage(imageData: ImageData, degrees: number): ImageData

Rotates an image by the specified angle.

Parameters:

imageData: ImageData object containing the source image
degrees: Rotation angle in degrees

Returns:

New ImageData object containing the rotated image

skewImage(imageData: ImageData, skewX: number, skewY: number): ImageData

Applies horizontal and vertical skewing to an image.

Parameters:

imageData: ImageData object containing the source image
skewX: Horizontal skew factor
skewY: Vertical skew factor

Returns:

New ImageData object containing the skewed image

saveImage(imageData: ImageData, filePath: string): Promise

Saves an image to a file.

Parameters:

imageData: ImageData object to save
filePath: Path where the image should be saved

Returns:

Promise that resolves when the image has been saved

Technical Details

The edge detection algorithm uses Sobel operators for gradient calculation
Gaussian blur uses a 3x3 kernel with customizable radius
Sharpening uses a 3x3 kernel matrix
Rotation uses bilinear interpolation for smooth results
All operations create new ImageData objects, leaving the original unchanged
Alpha channel is preserved in all operations
Image saving requires Node.js environment with 'canvas' package

Project Structure

deca-image-tools/
├── src/
│   └── index.ts          # Main source code
├── dist/                 # Compiled output
│   ├── index.js
│   └── index.d.ts
├── package.json          # Package configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # Documentation

Development

Setup

Clone the repository:

git clone https://github.com/yourusername/deca-image-tools.git
cd deca-image-tools

Install dependencies:

npm install

Available Scripts

npm run build - Compiles the TypeScript code
npm test - Runs the test suite
npm run lint - Runs ESLint for code quality
npm run format - Formats code using Prettier

Requirements

Modern browser with Canvas API support
TypeScript 4.0+ (for TypeScript users)
Node.js 14+ (for development)
Node.js canvas package (for image saving functionality)

Browser Support

The package supports all modern browsers that implement the Canvas API:

Chrome 60+
Firefox 55+
Safari 11+
Edge 79+

Performance Considerations

Image processing operations are performed on the CPU and may be computationally intensive for large images
Consider downscaling large images before processing
All operations are synchronous and will block the main thread
The Gaussian blur and rotation operations may be particularly intensive on large images
Transformation operations may cause some quality loss due to interpolation

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please make sure to:

Update tests as appropriate
Follow the existing code style
Update documentation for any new features

License

MIT

Author

Tom Tarpey (decagondev)

Changelog

1.0.2

Added image rotation support
Added image skewing support
Added image saving functionality
Performance improvements for transformation operations

1.0.1

Gaussian blur filter
Image sharpening
Brightness adjustment
Color inversion support

1.0.0

Initial release
Edge detection implementation
Image colorization

Acknowledgments

This package implements several fundamental image processing algorithms including the Sobel edge detection algorithm, Gaussian blur, and various geometric transformations

Support

For support, please open an issue in the GitHub repository or contact the maintainers.

image-processing edge-detection colorize gaussian-blur image-sharpening brightness-adjustment color-inversion typescript canvas sobel

8 months ago

8 months ago

8 months ago