# 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** is a TypeScript library for projecting geographic coordinates to pixel coordinates and vice versa. It supports multiple Coordinate Reference Systems (CRS), such as `EPSG:3857` and `EPSG:4326`, and provides efficient tools for tile-based map projections. With this library, developers can easily convert between geographic and pixel coordinates.

## Features

- **Support for Multiple CRS**: Built-in support for `EPSG:3857` (Web Mercator) and `EPSG:4326` (WGS84).
- **Dynamic Array Type Switching**: Supports `Float32Array`, `Float64Array`, and plain JavaScript arrays.
- **Tile Map Projection**: Provides pixel coordinate calculations based on tile size and zoom levels.
- **Lightweight Design**: No external dependencies, focusing on core functionality.
- **TypeScript Support**: Fully written in TypeScript for enhanced type safety and developer experience.

## Installation

To install **Pixel Projection**, run the following command:

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

Or using Yarn:

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

## Usage

### Basic Example

Below is an example of how to use **Pixel Projection** to project geographic coordinates to pixel coordinates and then reverse the projection:

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

// Set the array type to Float32Array
setArrayType(Float32Array);

// Create an InvertedPyramid instance with the default EPSG:3857 projection
const pyramid = new InvertedPyramid(256);

// Geographic coordinates (latitude and longitude)
const latlng = [39.9042, 116.4074]; // Beijing's geographic coordinates

// Project to pixel coordinates (zoom level 10)
const pixel = pyramid.project(latlng, 10);
console.log(`Pixel Coordinates: [${pixel[0]}, ${pixel[1]}]`);

// Reverse project back to geographic coordinates
const unprojectedLatLng = pyramid.unproject(pixel, 10);
console.log(`Reversed Geographic Coordinates: [${unprojectedLatLng[0]}, ${unprojectedLatLng[1]}]`);
```
## API Reference

### Core Classes

#### `InvertedPyramid`

Used for projecting between geographic and pixel coordinates.

- **Constructor**
  ```typescript
  constructor(tilesize: number, minFloor: number = 0, maxFloor: number = 20, crs: CRS = new EPSG3857())
  ```
  - `tilesize`: Tile size, defaults to `256`.
  - `minFloor`: Minimum zoom level, defaults to `0`.
  - `maxFloor`: Maximum zoom level, defaults to `20`.
  - `crs`: Coordinate reference system, defaults to `EPSG3857`.

- **Methods**
  - `project(latlng: ArrayType, floor: number): ArrayType`
    - Projects geographic coordinates to pixel coordinates.
    - Parameters:
      - `latlng`: Geographic coordinates `[latitude, longitude]`.
      - `floor`: Map zoom level.
    - Returns: Projected pixel coordinates `[x, y]`.

  - `unproject(pixel: ArrayType, floor: number): ArrayType`
    - Reverse projects pixel coordinates to geographic coordinates.
    - Parameters:
      - `pixel`: Pixel coordinates `[x, y]`.
      - `floor`: Map zoom level.
    - Returns: Reversed geographic coordinates `[latitude, longitude]`.

#### `CRS`

Interface definition for Coordinate Reference Systems.

- **Properties**
  - `code: string` - The code for the coordinate reference system (e.g., `"EPSG:3857"`).
  - `transform: Float32Array` - Transformation matrix, format `[a, b, c, d, 1/a, 1/c]`.

- **Methods**
  - `project(latlng: ArrayType): ArrayType`
    - Projects geographic coordinates to 2D plane coordinates.
    - Parameters:
      - `latlng`: Geographic coordinates `[latitude, longitude]`.
    - Returns: Projected 2D plane coordinates `[x, y]`.

  - `unproject(point: ArrayType): ArrayType`
    - Reverse projects 2D plane coordinates to geographic coordinates.
    - Parameters:
      - `point`: 2D plane coordinates `[x, y]`.
    - Returns: Reversed geographic coordinates `[latitude, longitude]`.

### Utility Functions

- `setArrayType(type: any)`
  - Dynamically sets the underlying array type.
  - Parameters:
    - `type`: Target array type (e.g., `Float32Array`, `Float64Array`, or plain array).

## Coordinate Reference Systems (CRS)

### EPSG:3857

Web Mercator projection, suitable for most online map services (e.g., Google Maps, OpenStreetMap).

### EPSG:4326

WGS84 geographic coordinate system, directly using latitude and longitude.

## Performance Optimization

- **Caching Mechanism**: Precomputes tile widths and their reciprocals to reduce runtime computation overhead.
- **Dynamic Array Type Switching**: Choose the appropriate array type based on performance requirements.

## Contribution

Contributions are welcome! If you find any issues or have improvement suggestions, please submit an issue or pull request.

## License
MIT