or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

clipping.mdgeographic-calculations.mdindex.mdpath.mdprojections.mdshapes.mdtransformations.md
tile.json

tessl/npm-d3-geo

Shapes and calculators for spherical coordinates.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/d3-geo@3.1.x

To install, run

npx @tessl/cli install tessl/npm-d3-geo@3.1.0

index.mddocs/

d3-geo

D3-geo provides comprehensive functionality for geographic projections, spherical geometry calculations, and GeoJSON manipulation. It handles map projections including common ones like Mercator and Albers, performs spherical calculations like area and distance, and offers advanced features like clipping algorithms and path generation for cartographic applications.

Package Information

  • Package Name: d3-geo
  • Package Type: npm
  • Language: JavaScript (ES modules)
  • Installation: npm install d3-geo

Core Imports

import * as d3 from "d3-geo";
// or specific imports:
import { geoMercator, geoPath, geoArea, geoDistance } from "d3-geo";

For CommonJS:

const d3 = require("d3-geo");
// or specific imports:
const { geoMercator, geoPath, geoArea, geoDistance } = require("d3-geo");

Basic Usage

import { geoMercator, geoPath, geoArea, geoDistance } from "d3-geo";

// Create a map projection
const projection = geoMercator()
  .scale(150)
  .translate([480, 250]);

// Create a path generator
const path = geoPath(projection);

// Calculate geographic measurements
const feature = {
  type: "Polygon",
  coordinates: [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]]
};

const area = geoArea(feature); // Spherical area in steradians
const distance = geoDistance([0, 0], [1, 1]); // Great-arc distance in radians

// Generate SVG path data
const pathData = path(feature);

Architecture

d3-geo is built around several key components:

  • Geographic Calculations: Core spherical geometry functions for area, bounds, centroid, distance, and length calculations
  • Map Projections: Comprehensive collection of cartographic projections with configurable parameters
  • Clipping System: Advanced clipping algorithms for antimeridian, extent, and circle boundaries
  • Path Generation: SVG/Canvas path generation with projection integration
  • Streaming Interface: Memory-efficient geometry processing through streaming transforms
  • GeoJSON Support: Full compatibility with GeoJSON specification for geographic features

Capabilities

Geographic Calculations

Core spherical geometry functions for measuring and analyzing geographic features on the sphere. Essential for geographic analysis and cartographic applications.

function geoArea(object: GeoJSON.Feature | GeoJSON.Geometry): number;
function geoBounds(object: GeoJSON.Feature | GeoJSON.Geometry): [[number, number], [number, number]];
function geoCentroid(object: GeoJSON.Feature | GeoJSON.Geometry): [number, number];
function geoDistance(a: [number, number], b: [number, number]): number;
function geoLength(object: GeoJSON.Feature | GeoJSON.Geometry): number;
function geoContains(object: GeoJSON.Feature | GeoJSON.Geometry, point: [number, number]): boolean;
function geoInterpolate(a: [number, number], b: [number, number]): (t: number) => [number, number];

Geographic Calculations

Map Projections

Comprehensive collection of cartographic projections for transforming spherical coordinates to planar coordinates. Includes azimuthal, conic, cylindrical, and specialized projections.

function geoMercator(): MercatorProjection;
function geoAlbers(): AlbersProjection;
function geoOrthographic(): Projection;
function geoAzimuthalEqualArea(): Projection;
function geoProjection(project: ProjectionFunction): Projection;

interface Projection {
  (point: [number, number]): [number, number] | null;
  invert?(point: [number, number]): [number, number] | null;
  scale(scale?: number): this | number;
  translate(translate?: [number, number]): this | [number, number];
  center(center?: [number, number]): this | [number, number];
  rotate(rotate?: [number, number, number?]): this | [number, number, number];
  clipAngle(angle?: number): this | number | null;
  clipExtent(extent?: [[number, number], [number, number]] | null): this | [[number, number], [number, number]] | null;
  precision(precision?: number): this | number;
  fitExtent(extent: [[number, number], [number, number]], object: GeoJSON.Feature | GeoJSON.Geometry): this;
  fitSize(size: [number, number], object: GeoJSON.Feature | GeoJSON.Geometry): this;
  fitWidth(width: number, object: GeoJSON.Feature | GeoJSON.Geometry): this;
  fitHeight(height: number, object: GeoJSON.Feature | GeoJSON.Geometry): this;
  stream(stream: Transform): Transform;
}

Map Projections

Path Generation

SVG and Canvas path generation for rendering GeoJSON features with integrated projection support. Essential for creating interactive maps and geographic visualizations.

function geoPath(projection?: Projection | null, context?: CanvasRenderingContext2D | null): Path;

interface Path {
  (object: GeoJSON.Feature | GeoJSON.Geometry): string | null;
  area(object: GeoJSON.Feature | GeoJSON.Geometry): number;
  bounds(object: GeoJSON.Feature | GeoJSON.Geometry): [[number, number], [number, number]];
  centroid(object: GeoJSON.Feature | GeoJSON.Geometry): [number, number];
  measure(object: GeoJSON.Feature | GeoJSON.Geometry): number;
  projection(projection?: Projection | null): this | Projection | null;
  context(context?: CanvasRenderingContext2D | null): this | CanvasRenderingContext2D | null;
  pointRadius(radius?: number | ((object: any, ...args: any[]) => number)): this | number | ((object: any, ...args: any[]) => number);
  digits(digits?: number | null): this | number | null;
}

Path Generation

Clipping

Advanced clipping algorithms for constraining geometry to specific boundaries. Includes antimeridian handling, extent clipping, and circular clipping.

function geoClipAntimeridian(stream: Transform): Transform;
function geoClipCircle(radius: number): (stream: Transform) => Transform;
function geoClipExtent(extent: [[number, number], [number, number]]): (stream: Transform) => Transform;
function geoClipRectangle(x0: number, y0: number, x1: number, y1: number): (stream: Transform) => Transform;

Clipping

Geometric Shapes

Generation of geometric shapes like circles and graticules for cartographic applications and map overlays.

function geoCircle(): Circle;
function geoGraticule(): Graticule;
const geoGraticule10: GeoJSON.MultiLineString;

interface Circle {
  (): GeoJSON.Polygon;
  center(center?: [number, number]): this | [number, number];
  radius(radius?: number): this | number;
  precision(precision?: number): this | number;
}

interface Graticule {
  (): GeoJSON.MultiLineString;
  lines(): GeoJSON.LineString[];
  outline(): GeoJSON.Polygon;
  extent(extent?: [[number, number], [number, number]]): this | [[number, number], [number, number]];
  extentMajor(extent?: [[number, number], [number, number]]): this | [[number, number], [number, number]];
  extentMinor(extent?: [[number, number], [number, number]]): this | [[number, number], [number, number]];
  step(step?: [number, number]): this | [number, number];
  stepMajor(step?: [number, number]): this | [number, number];
  stepMinor(step?: [number, number]): this | [number, number];
  precision(precision?: number): this | number;
}

Geometric Shapes

Transformations

Low-level transformation functions for rotation, streaming, and coordinate system manipulation.

function geoRotation(angles: [number, number, number?]): Rotation;
function geoStream(object: GeoJSON.Feature | GeoJSON.Geometry, stream: Transform): void;
function geoTransform(methods: TransformMethods): Transform;

interface Rotation {
  (point: [number, number]): [number, number];
  invert(point: [number, number]): [number, number];
}

interface Transform {
  point?(x: number, y: number): void;
  lineStart?(): void;
  lineEnd?(): void;
  polygonStart?(): void;
  polygonEnd?(): void;
  sphere?(): void;
}

Transformations

Types

type ProjectionFunction = (lambda: number, phi: number) => [number, number];

interface TransformMethods {
  point?(x: number, y: number): void;
  lineStart?(): void;
  lineEnd?(): void;
  polygonStart?(): void;
  polygonEnd?(): void;
  sphere?(): void;
}

interface MercatorProjection extends Projection {
  // Inherits all Projection methods
}

interface AlbersProjection extends Projection {
  parallels(parallels?: [number, number]): this | [number, number];
}