# pixel-projection

**Repository Path**: proj4js/pixel-projection

## Basic Information

- **Project Name**: pixel-projection
- **Description**: pixel-projection
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-28
- **Last Updated**: 2025-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pixel Projection

**Pixel Projection** 是一个用于地理坐标投影和像素坐标转换的 TypeScript 库。它支持多种坐标参考系统（CRS），例如 `EPSG:3857` 和 `EPSG:4326`，并提供了高效的瓦片地图投影工具。通过这个库，开发者可以轻松地在地理坐标与像素坐标之间进行转换。

## 特性

- **支持多种坐标参考系统**：内置支持 `EPSG:3857`（Web Mercator）和 `EPSG:4326`（WGS84）。
- **动态数组类型切换**：支持 `Float32Array`、`Float64Array` 和普通数组。
- **瓦片地图投影**：提供基于瓦片大小和楼层级别的像素坐标计算。
- **轻量级设计**：无外部依赖，专注于核心功能。
- **TypeScript 支持**：完全用 TypeScript 编写，提供类型安全性和更好的开发者体验。

## 安装

安装 **Pixel Projection**，运行以下命令：

```bash
npm install pixel-projection
```

或者使用 Yarn：

```bash
yarn add pixel-projection
```

## 使用方法

### 基本示例

以下是如何使用 **Pixel Projection** 将地理坐标投影到像素坐标，并反向投影的示例：

```typescript
import { InvertedPyramid, setArrayType } from 'pixel-projection';
import { Float32Array } from 'types';

// 设置数组类型为 Float32Array
setArrayType(Float32Array);

// 创建一个 InvertedPyramid 实例，默认使用 EPSG:3857 投影
const pyramid = new InvertedPyramid(256);

// 地理坐标（纬度和经度）
const latlng = [39.9042, 116.4074]; // 北京的地理坐标

// 投影到像素坐标（第 10 层）
const pixel = pyramid.project(latlng, 10);
console.log(`像素坐标: [${pixel[0]}, ${pixel[1]}]`);

// 反向投影回地理坐标
const unprojectedLatLng = pyramid.unproject(pixel, 10);
console.log(`反向投影的地理坐标: [${unprojectedLatLng[0]}, ${unprojectedLatLng[1]}]`);
```

### 自定义 CRS

您也可以自定义坐标参考系统（CRS）。例如，使用 `EPSG:4326`：

```typescript
import { InvertedPyramid } from 'pixel-projection';
import { EPSG4326 } from 'pixel-projection/src/epsg/EPSG4326';

// 创建一个 InvertedPyramid 实例，使用 EPSG:4326 投影
const pyramid = new InvertedPyramid(256, 0, 20, new EPSG4326());

// 地理坐标
const latlng = [39.9042, 116.4074];

// 投影到像素坐标（第 10 层）
const pixel = pyramid.project(latlng, 10);
console.log(`像素坐标: [${pixel[0]}, ${pixel[1]}]`);
```

## API 参考

### 核心类

#### `InvertedPyramid`

用于地理坐标与像素坐标之间的投影和反向投影。

- **构造函数**
  ```typescript
  constructor(tilesize: number, minFloor: number = 0, maxFloor: number = 20, crs: CRS = new EPSG3857())
  ```
  - `tilesize`: 瓦片大小，默认为 `256`。
  - `minFloor`: 最小楼层级别，默认为 `0`。
  - `maxFloor`: 最大楼层级别，默认为 `20`。
  - `crs`: 坐标参考系统，默认为 `EPSG3857`。

- **方法**
  - `project(latlng: ArrayType, floor: number): ArrayType`
    - 将地理坐标投影到像素坐标。
    - 参数：
      - `latlng`: 地理坐标 `[纬度, 经度]`。
      - `floor`: 地图的楼层级别。
    - 返回值：投影后的像素坐标 `[x, y]`。

  - `unproject(pixel: ArrayType, floor: number): ArrayType`
    - 将像素坐标反向投影为地理坐标。
    - 参数：
      - `pixel`: 像素坐标 `[x, y]`。
      - `floor`: 地图的楼层级别。
    - 返回值：反向投影的地理坐标 `[纬度, 经度]`。

#### `CRS`

坐标参考系统的接口定义。

- **属性**
  - `code: string` - 坐标参考系统的代码（如 `"EPSG:3857"`）。
  - `transform: Float32Array` - 转换矩阵，格式为 `[a, b, c, d, 1/a, 1/c]`。

- **方法**
  - `project(latlng: ArrayType): ArrayType`
    - 将地理坐标投影到二维平面坐标。
    - 参数：
      - `latlng`: 地理坐标 `[纬度, 经度]`。
    - 返回值：投影后的二维平面坐标 `[x, y]`。

  - `unproject(point: ArrayType): ArrayType`
    - 将二维平面坐标反向投影为地理坐标。
    - 参数：
      - `point`: 二维平面坐标 `[x, y]`。
    - 返回值：反向投影的地理坐标 `[纬度, 经度]`。

### 工具函数

- `setArrayType(type: any)`
  - 动态设置底层数组类型。
  - 参数：
    - `type`: 目标数组类型（如 `Float32Array`、`Float64Array` 或普通数组）。

## 坐标参考系统（CRS）

### EPSG:3857

Web Mercator 投影，适用于大多数在线地图服务（如 Google Maps、OpenStreetMap）。

### EPSG:4326

WGS84 地理坐标系，直接使用纬度和经度表示。

## 性能优化

- **缓存机制**：通过预先计算瓦片宽度及其倒数，减少运行时计算开销。
- **动态数组类型切换**：根据性能需求选择合适的数组类型。

## 贡献

欢迎贡献！如果您发现问题或有改进建议，请提交问题或拉取请求。

## 许可证
MIT