# @yandex/ymaps3-world-utils

Utility package for coordinate transformations in Yandex Maps 3.0.

## Usage

### ES Modules

```bash
npm install @yandex/ymaps3-world-utils
```

```javascript
import { worldToPixels, pixelsToWorld } from '@yandex/ymaps3-world-utils';

// Convert world coordinates to pixels
const pixels = worldToPixels({ x: 0.5, y: 0.5 }, 10);
console.log(pixels); // { x: 196608, y: 65536 }

// Convert pixels back to world coordinates
const world = pixelsToWorld({ x: 196608, y: 65536 }, 10);
console.log(world); // { x: 0.5, y: 0.5 }
```

## API Reference

### Coordinate Systems

The package works with two coordinate systems:

- **WorldCoordinates** - Normalized coordinates in the range `[-1, 1]`
  - Center: `(0, 0)`
  - Bottom-left corner: `(-1, -1)`
  - Top-right corner: `(1, 1)`

- **PixelCoordinates** - Global pixel coordinates
  - World size depends on zoom level: `2^(zoom + 8) × 2^(zoom + 8)` pixels
  - At zoom 0: 256×256 pixels
  - At zoom 10: 262,144×262,144 pixels
  - Top-left corner: `(0, 0)`
  - Bottom-right corner: `(2^(zoom + 8), 2^(zoom + 8))`

### Functions

#### `worldToPixels(coordinates: WorldCoordinates, zoom: number): PixelCoordinates`

Converts world coordinates to pixel coordinates.

**Parameters:**
- `coordinates` - World coordinates object with `x` and `y` properties
- `zoom` - Zoom level (integer)

**Returns:** Pixel coordinates object with `x` and `y` properties

**Example:**
```javascript
const pixels = worldToPixels({ x: 0, y: 0 }, 10);
// Returns: { x: 131072, y: 131072 } - center of the world at zoom 10
```

---

#### `pixelsToWorld(pixels: PixelCoordinates, zoom: number): WorldCoordinates`

Converts pixel coordinates to world coordinates.

**Parameters:**
- `pixels` - Pixel coordinates object with `x` and `y` properties
- `zoom` - Zoom level (integer)

**Returns:** World coordinates object with `x` and `y` properties

**Example:**
```javascript
const world = pixelsToWorld({ x: 131072, y: 131072 }, 10);
// Returns: { x: 0, y: 0 } - center of the world
```

## License

Apache-2.0