@id-sdk/projection

📽 Projection class for converting between Lon/Lat (λ,φ) and Cartesian (x,y) coordinates

The default projection wraps a d3.geoMercatorRaw projection, but works in degrees instead of radians, and skips several features:

Antimeridian clipping
Spherical rotation
Resampling

Installing

npm install @id-sdk/projection

This library is distributed in ESM format only. It cannot be require()'d from CommonJS. For more, please read Sindre Sorhus’s FAQ.

import { Projection } from '@id-sdk/projection';

Contributing

This project is just getting started! 🌱

We're not able to support external contributors at this time, but check back in a bit when things have matured.

API Reference

Methods

new Projection(x?: number, y?: number, k?: number) constructor
project(p: Vec2): Vec2
invert(p: Vec2): Vec2
scale(val?: number): number | Projection
translate(val?: Vec2): Vec2 | Projection
dimensions(val?: Vec2[]): Vec2[] | Projection
transform(obj?: Transform): Transform | Projection
getStream(): any

Types

Vec2: [number, number]
Transform: { x: number, y: number, k: number }

Methods

# new Projection(x?: number, y?: number, k?: number) <>

Constructs a new Projection. The default values are: x = 0, y = 0, k = 256 / Math.PI Which corresponds to the world at zoom 1 and centered on "Null Island" [0, 0].

const p1 = new Projection();
const p2 = new Projection(20, 30, 512 / Math.PI);

# project(p: Vec2): Vec2 <>

Projects from given Lon/Lat (λ,φ) to Cartesian (x,y) coordinates.

const p = new Projection();
p.project([0, 0]);                  // returns [0, 0]
p.project([180, -85.0511287798]);   // returns [256, 256]
p.project([-180, 85.0511287798]);   // returns [-256, -256]

# invert(p: Vec2): Vec2 <>

Inverse projects from given Cartesian (x,y) to Lon/Lat (λ,φ) coordinates.

const p = new Projection();
p.invert([0, 0]);         // returns [0, 0]
p.invert([256, 256]);     // returns [180, -85.0511287798]
p.invert([-256, -256]);   // returns [-180, 85.0511287798]

# scale(val?: number): number | Projection <>

When passed a numeric argument, sets the scale factor and returns this for method chaining.

When passed no argument, returns the scale factor.

const p = new Projection().scale(512 / Math.PI);   // sets scale
p.scale();   // gets scale - returns 512 / Math.PI;

# translate(val?: Vec2): Vec2 | Projection <>

When passed a Vec2 argument, sets the x,y translation values and returns this for method chaining.

When passed no argument, returns the x,y translation values.

const p = new Projection().translate([20, 30]);    // sets translation
p.translate();   // gets translation - returns [20, 30]

# dimensions(val?: Vec2[]): Vec2[] | Projection <>

When passed a Vec2[2] argument, sets the viewport min/max dimensions and returns this for method chaining.

When passed no argument, returns the viewport min/max dimensions.

const p = new Projection().dimensions([[0, 0], [800, 600]]);    // sets viewport dimensions
p.dimensions();   // gets viewport dimensions - returns [[0, 0], [800, 600]]

# transform(obj?: Transform): Transform | Projection <>

When passed a Transform argument, sets x,y,k from the Transform and returns this for method chaining.

When passed no argument, returns a Transform object containing the current x,y,k values.

const t = { x: 20, y: 30, k: 512 / Math.PI };
const p = new Projection().transform(t);    // sets `x`,`y`,`k` from given Transform object
p.transform();   // gets transform - returns { x: 20, y: 30, k: 512 / Math.PI }

# getStream(): any <>

Returns a d3.geoTransform stream that uses this Projection to project geometry points.

const proj = new Projection();
let s = proj.getStream();
let p;

s.stream = {
  point: (x, y) => {
    p = [x, y];
  }
};
s.point(-180, 85.0511287798);  // returns [256, 256]

Types

# Vec2

An array of two numbers.

[number, number]

# Transform

An Object containing x, y, k numbers.

{ x: number, y: number, k: number }