box-filter

Box Filter

Box Filter is a high-performance image processing library that supports box filtering operations on ImageData, Uint8ClampedArray, and two-dimensional arrays. It provides multiple optimized implementations to meet performance requirements in various scenarios.

Directory Structure

.
├── src
│   ├── internal
│   │   └── utils.ts          # Utility functions (e.g., border handling, averaging)
│   ├── batchProcessing.ts    # Batch processing functionality
│   ├── benchmark.ts          # Benchmark module
│   ├── borderType.ts         # Border type definitions
│   ├── boxFilterArray.ts     # Two-dimensional array filtering implementation
│   ├── boxFilterImageData.ts # ImageData filtering implementation
│   ├── boxFilterUint8.ts     # Uint8ClampedArray filtering implementation
│   ├── index.ts              # Main entry file
│   └── types.ts              # Type definitions
├── package.json              # Project dependencies and script configuration
└── tsup.config.json          # Build tool configuration

Features

• High-Performance Filtering:

  • Supports fast box filtering for ImageData, Uint8ClampedArray, and two-dimensional arrays.
  • Optimized using sliding window algorithms and loop unrolling techniques.

• Flexible Border Handling:

  • Provides multiple border handling methods (e.g., replicate border, zero padding) defined via the BorderType enumeration.

• Batch Processing Support:

  • Offers batch filtering capabilities to efficiently handle multiple radii or options.

• Benchmarking:

  • Includes a built-in benchmarking module to evaluate the performance of different data types and filtering implementations.

• Cross-Platform Compatibility:

  • Implemented in TypeScript, suitable for both Node.js and browser environments.

Installation and Usage

Installation

Install via npm:

npm install box-filter

Usage Examples

Filtering ImageData

import { boxFilterImageData, BorderType } from 'box-filter';

const imageData = new ImageData(1920, 1080); // Example ImageData object
const options = {
  radius: 5,
  borderType: BorderType.REPLICATE,
};

const filteredImageData = boxFilterImageData(imageData, options);

Filtering Uint8ClampedArray

import { boxFilterUint8, BorderType } from 'box-filter';

const data = new Uint8ClampedArray(1920 * 1080 * 4); // Example pixel data
const width = 1920;
const height = 1080;
const options = {
  radius: 5,
  borderType: BorderType.ZERO_PADDING,
};

const filteredData = boxFilterUint8(data, width, height, options);

Filtering Two-Dimensional Arrays

import { boxFilterArray, BorderType } from 'box-filter';

const array = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9],
];
const options = {
  radius: 1,
  borderType: BorderType.WRAP,
};

const filteredArray = boxFilterArray(array, options);

Benchmarking

The library includes a benchmarking module to measure the performance of different filtering implementations. To run benchmarks:

npm run benchmark

Example output:

Benchmark Results:
- boxFilterImageData: 12.5ms
- boxFilterUint8: 9.8ms
- boxFilterArray: 15.2ms

Contributing

We welcome contributions! Please follow these steps:

• Fork the repository.
• Create a new branch (git checkout -b feature/your-feature-name).
• Commit your changes (git commit -m "Add some feature").
• Push the branch (git push origin feature/your-feature-name).
• Open a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

If you encounter any issues or have suggestions for improvement, feel free to open an issue or contact us.