@yandex/ymaps3-world-utils

Utility package for coordinate transformations in Yandex Maps 3.0.

Usage

ES Modules

npm install @yandex/ymaps3-world-utils

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:

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:

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

License

Apache-2.0