# box-filter

**Repository Path**: cesiumjs/box-filter

## Basic Information

- **Project Name**: box-filter
- **Description**: High-performance box filter implementation for image processing in TypeScript
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-19
- **Last Updated**: 2025-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Box Filter

Box Filter 是一个高效的图像处理库，支持对 `ImageData`、`Uint8ClampedArray` 和二维数组进行盒式滤波操作。它提供了多种优化实现，以满足不同场景下的性能需求。

## 目录结构

```plaintext
.
├── src
│   ├── internal
│   │   └── utils.ts          # 工具函数（如边界处理、平均值计算等）
│   ├── batchProcessing.ts    # 批量处理功能
│   ├── benchmark.ts          # 基准测试模块
│   ├── borderType.ts         # 边界处理类型的定义
│   ├── boxFilterArray.ts     # 二维数组滤波实现
│   ├── boxFilterImageData.ts # ImageData 滤波实现
│   ├── boxFilterUint8.ts     # Uint8ClampedArray 滤波实现
│   ├── index.ts              # 主入口文件
│   └── types.ts              # 类型定义
├── package.json              # 项目依赖和脚本配置
└── tsup.config.json          # 构建工具配置
```

---

## 功能特性

1. **高性能滤波**：
   - 支持对 `ImageData`、`Uint8ClampedArray` 和二维数组进行快速盒式滤波。
   - 使用滑动窗口算法和循环展开技术优化性能。

2. **灵活的边界处理**：
   - 提供多种边界处理方式（如复制边界、零填充等），通过 `BorderType` 枚举定义。

3. **批量处理支持**：
   - 提供批量滤波功能，支持对多个半径或选项进行高效处理。

4. **基准测试**：
   - 内置基准测试模块，用于评估不同数据类型和滤波实现的性能。

5. **跨平台兼容**：
   - 基于 TypeScript 实现，适用于 Node.js 和浏览器环境。

---

## 安装与使用

### 安装

通过 npm 安装：

```bash
npm install box-filter
```

### 使用示例

#### 对 `ImageData` 进行滤波

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

const imageData = new ImageData(1920, 1080); // 示例 ImageData 对象
const options = {
  radius: 5,
  borderType: BorderType.REPLICATE,
};

const filteredImageData = boxFilterImageData(imageData, options);
```

#### 对 `Uint8ClampedArray` 进行滤波

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

const data = new Uint8ClampedArray(1920 * 1080 * 4); // 示例像素数据
const width = 1920;
const height = 1080;
const radius = 5;

const filteredData = boxFilterUint8(data, width, height, radius, BorderType.REPLICATE);
```

#### 对二维数组进行滤波

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

const array = Array.from({ length: 1080 }, () => Array(1920).fill(0)); // 示例二维数组
const options = {
  radius: 5,
  borderType: BorderType.REPLICATE,
};

const filteredArray = boxFilterArray(array, options);
```

---

## 基准测试

运行基准测试以评估不同实现的性能：

```bash
npm run benchmark
```

输出示例：

```plaintext
Running benchmarks...
Image size: 1920x1080, radius: 5, iterations: 10
2D Array average time: 12.34ms
ImageData average time: 8.76ms
Uint8ClampedArray average time: 4.56ms
Performance ratio (Array/Uint8): 2.7x
```

---

## API 文档

### `boxFilterImageData`

对 `ImageData` 应用盒式滤波。

```typescript
function boxFilterImageData(
  imageData: ImageData,
  options: BoxFilterOptions
): ImageData;
```

- **参数**：
  - `imageData`: 输入的 `ImageData` 对象。
  - `options`: 滤波选项，包含以下字段：
    - `radius`: 滤波半径（非负整数）。
    - `borderType`: 边界处理方式（可选，默认为 `BorderType.REPLICATE`）。

- **返回值**：滤波后的 `ImageData` 对象。

---

### `boxFilterUint8`

对 `Uint8ClampedArray` 应用盒式滤波。

```typescript
function boxFilterUint8(
  data: Uint8ClampedArray,
  width: number,
  height: number,
  radius: number,
  borderType?: BorderType
): Uint8ClampedArray;
```

- **参数**：
  - `data`: 输入的像素数据（RGBA 格式）。
  - `width`: 图像宽度。
  - `height`: 图像高度。
  - `radius`: 滤波半径（非负整数）。
  - `borderType`: 边界处理方式（可选，默认为 `BorderType.REPLICATE`）。

- **返回值**：滤波后的 `Uint8ClampedArray`。

---

### `boxFilterArray`

对二维数组应用盒式滤波。

```typescript
function boxFilterArray(
  data: number[][],
  options: BoxFilterOptions
): number[][];
```

- **参数**：
  - `data`: 输入的二维数组。
  - `options`: 滤波选项，包含以下字段：
    - `radius`: 滤波半径（非负整数）。
    - `borderType`: 边界处理方式（可选，默认为 `BorderType.REPLICATE`）。

- **返回值**：滤波后的二维数组。

---

## 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库。
2. 创建新的分支（`git checkout -b feature/your-feature-name`）。
3. 提交更改（`git commit -m "Add some feature"`）。
4. 推送分支（`git push origin feature/your-feature-name`）。
5. 创建 Pull Request。

---

## 许可证

本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。