@types/d3-geo
Version:
TypeScript definitions for d3-geo
1,093 lines (977 loc) • 62.2 kB
TypeScript
// Last module patch version validated against: 3.0.1
import * as GeoJSON from "geojson";
// ----------------------------------------------------------------------
// Shared Interfaces and Types
// ----------------------------------------------------------------------
/**
* A basic geometry for a sphere, which is supported by d3-geo
* beyond the GeoJSON geometries.
*/
export interface GeoSphere {
/**
* Sphere geometry type
*/
type: "Sphere";
}
/**
* Type Alias for GeoJSON Geometry Object and GeoSphere additional
* geometry supported by d3-geo
*/
export type GeoGeometryObjects = GeoJSON.GeometryObject | GeoSphere;
/**
* A GeoJSON-style GeometryCollection which supports GeoJSON geometry objects
* and additionally GeoSphere.
*
* The generic refers to the type(s) of d3-geo geometry objects contained in the collection.
*/
export interface ExtendedGeometryCollection<GeometryType extends GeoGeometryObjects = GeoGeometryObjects> {
type: string;
bbox?: number[] | undefined;
crs?: {
type: string;
properties: any;
} | undefined;
geometries: GeometryType[];
}
/**
* A GeoJSON-style Feature which support features built on GeoJSON GeometryObjects
* or GeoSphere.
*
* The first generic refers to the type(s) of d3-geo geometry objects underlying the ExtendedFeature.
* Unless explicitly ruled out, the geometry value is nullable.
*
* The second generic refers to the data type of the properties of the ExtendedFeature. Unless explicitly ruled out,
* the properties value is nullable.
*/
export interface ExtendedFeature<
GeometryType extends GeoGeometryObjects | null = GeoGeometryObjects | null,
Properties extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties,
> extends GeoJSON.GeoJsonObject {
geometry: GeometryType;
properties: Properties;
id?: string | number | undefined;
}
/**
* A GeoJSON-style FeatureCollection which supports GeoJSON features
* and features built on GeoSphere
*
* The generic refers to the type of ExtendedFeature contained in the ExtendedFeatureCollection.
*/
export interface ExtendedFeatureCollection<FeatureType extends ExtendedFeature = ExtendedFeature>
extends GeoJSON.GeoJsonObject
{
features: FeatureType[];
}
/**
* Type Alias for permissible objects which can be used with d3-geo
* methods
*/
export type GeoPermissibleObjects =
| GeoGeometryObjects
| ExtendedGeometryCollection
| ExtendedFeature
| ExtendedFeatureCollection;
// ----------------------------------------------------------------------
// Spherical Math
// ----------------------------------------------------------------------
/**
* Returns the spherical area of the specified GeoJSON object in steradians.
* This is the spherical equivalent of path.area.
*/
export function geoArea(
object: ExtendedFeature | ExtendedFeatureCollection | GeoGeometryObjects | ExtendedGeometryCollection,
): number;
/**
* Returns the spherical bounding box for the specified GeoJSON object.
* The bounding box is represented by a two-dimensional array: [[left, bottom], [right, top]],
* where left is the minimum longitude, bottom is the minimum latitude, right is maximum longitude, and top is the maximum latitude.
* All coordinates are given in degrees.
* (Note that in projected planar coordinates, the minimum latitude is typically the maximum y-value, and the maximum latitude is typically the minimum y-value.)
* This is the spherical equivalent of path.bounds.
*/
export function geoBounds(
object: ExtendedFeature | ExtendedFeatureCollection | GeoGeometryObjects | ExtendedGeometryCollection,
): [[number, number], [number, number]];
/**
* Returns the spherical centroid of the specified GeoJSON object.
* This is the spherical equivalent of path.centroid.
*/
export function geoCentroid(
object: ExtendedFeature | ExtendedFeatureCollection | GeoGeometryObjects | ExtendedGeometryCollection,
): [number, number];
/**
* Returns true if and only if the specified GeoJSON object contains the specified point, or false if the object does not contain the point.
* The point must be specified as a two-element array [longitude, latitude] in degrees.
* For Point and MultiPoint geometries, an exact test is used; for a Sphere, true is always returned; for other geometries, an epsilon threshold is applied.
*/
export function geoContains(
object: ExtendedFeature | ExtendedFeatureCollection | GeoGeometryObjects | ExtendedGeometryCollection,
point: [number, number],
): boolean;
/**
* Returns the great-arc distance in radians between the two points a and b.
* Each point must be specified as a two-element array [longitude, latitude] in degrees.
*
* @param a Point specified as a two-element array [longitude, latitude] in degrees.
* @param b Point specified as a two-element array [longitude, latitude] in degrees.
*/
export function geoDistance(a: [number, number], b: [number, number]): number;
/**
* Returns the great-arc length of the specified GeoJSON object in radians.
* For polygons, returns the perimeter of the exterior ring plus that of any interior rings.
* This is the spherical equivalent of path.measure.
*/
export function geoLength(
object: ExtendedFeature | ExtendedFeatureCollection | GeoGeometryObjects | ExtendedGeometryCollection,
): number;
/**
* Returns an interpolator function given two points a and b.
* Each point must be specified as a two-element array [longitude, latitude] in degrees.
*
* @param a Point specified as a two-element array [longitude, latitude] in degrees.
* @param b Point specified as a two-element array [longitude, latitude] in degrees.
*/
export function geoInterpolate(a: [number, number], b: [number, number]): (t: number) => [number, number];
/**
* A Geo Rotation
*/
export interface GeoRotation {
/**
* Returns a new array [longitude, latitude] in degrees representing the rotated point of the given point.
*
* @param point The point must be specified as a two-element array [longitude, latitude] in degrees.
*/
(point: [number, number]): [number, number];
/**
* Returns a new array [longitude, latitude] in degrees representing the point of the given rotated point; the inverse of rotation.
*
* @param point The rotated point must be specified as a two-element array [longitude, latitude] in degrees.
*/
invert(point: [number, number]): [number, number];
}
/**
* Returns a rotation function for the given angles.
*
* @param angles A two- or three-element array of numbers [lambda, phi, gamma] specifying the rotation angles in degrees about each spherical axis.
* (These correspond to yaw, pitch and roll.) If the rotation angle gamma is omitted, it defaults to 0.
*/
export function geoRotation(angles: [number, number] | [number, number, number]): GeoRotation;
// ----------------------------------------------------------------------
// Spherical Shapes
// ----------------------------------------------------------------------
// geoCircle ============================================================
/**
* A new circle generator
*
* The first generic corresponds to the "this"-context within which the geo circle generator will be invoked.
*
* The second generic corresponds to the type of the Datum which will be passed into the geo circle generator.
*/
export interface GeoCircleGenerator<This = any, Datum = any> {
/**
* Returns a new GeoJSON geometry object of type “Polygon” approximating a circle on the surface of a sphere,
* with the current center, radius and precision. Any arguments are passed to the accessors.
*/
(this: This, d?: Datum, ...args: any[]): GeoJSON.Polygon;
/**
* Returns the current center accessor, which defaults to a function returning [0, 0].
*/
center(): (this: This, d: Datum, ...args: any[]) => [number, number];
/**
* Sets the circle center to the specified point [longitude, latitude] in degrees, and returns this circle generator.
* The center may also be specified as a function; this function will be invoked whenever a circle is generated, being passed any arguments passed to the circle generator.
*/
center(center: [number, number] | ((this: This, d: Datum, ...args: any[]) => [number, number])): this;
/**
* Returns the current radius accessor, which defaults to a function returning 90.
*/
radius(): (this: This, d: Datum, ...args: any[]) => number;
/**
* Sets the circle radius to the specified angle in degrees, and returns this circle generator.
* The radius may also be specified as a function; this function will be invoked whenever a circle is generated, being passed any arguments passed to the circle generator.
*/
radius(radius: number | ((this: This, d: Datum, ...args: any[]) => number)): this;
/**
* Returns the current precision accessor, which defaults to a function returning 6.
*/
precision(): (this: This, d: Datum, ...args: any[]) => number;
/**
* Sets the circle precision to the specified angle in degrees, and returns this circle generator.
* The precision may also be specified as a function; this function will be invoked whenever a circle is generated, being passed any arguments passed to the circle generator.
*/
precision(precision: number | ((this: This, d: Datum, ...args: any[]) => number)): this;
}
/**
* Returns a new geo circle generator
*/
export function geoCircle(): GeoCircleGenerator;
/**
* Returns a new geo circle generator
*
* The generic corresponds to the data type of the first argument passed into the geo circle generator and its accessor functions.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function geoCircle<Datum>(): GeoCircleGenerator<any, Datum>;
/**
* Returns a new geo circle generator
*
* The first generic corresponds to the "this" context within which the geo circle generator and its accessors will be invoked.
*
* The second generic corresponds to the data type of the first argument passed into the geo circle generator and its accessor functions.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function geoCircle<This, Datum>(): GeoCircleGenerator<This, Datum>;
// geoGraticule ============================================================
/**
* A Feature generator for graticules: a uniform grid of meridians and parallels for showing projection distortion.
* The default graticule has meridians and parallels every 10° between ±80° latitude; for the polar regions, there are meridians every 90°.
*/
export interface GeoGraticuleGenerator {
/**
* Returns a GeoJSON MultiLineString geometry object representing all meridians and parallels for this graticule.
*/
(): GeoJSON.MultiLineString;
/**
* Returns an array of GeoJSON LineString geometry objects, one for each meridian or parallel for this graticule.
*/
lines(): GeoJSON.LineString[];
/**
* Returns a GeoJSON Polygon geometry object representing the outline of this graticule, i.e. along the meridians and parallels defining its extent.
*/
outline(): GeoJSON.Polygon;
/**
* Returns the current minor extent, which defaults to ⟨⟨-180°, -80° - ε⟩, ⟨180°, 80° + ε⟩⟩.
*/
extent(): [[number, number], [number, number]];
/**
* Sets the major and minor extents of this graticule.
*
* @param extent Extent to use for major and minor extent of graticule.
*/
extent(extent: [[number, number], [number, number]]): this;
/**
* Returns the current major extent, which defaults to ⟨⟨-180°, -90° + ε⟩, ⟨180°, 90° - ε⟩⟩.
*/
extentMajor(): [[number, number], [number, number]];
/**
* Sets the major extent of this graticule.
*
* @param extent Major extent of graticule.
*/
extentMajor(extent: [[number, number], [number, number]]): this;
/**
* Returns the current minor extent, which defaults to ⟨⟨-180°, -80° - ε⟩, ⟨180°, 80° + ε⟩⟩.
*/
extentMinor(): [[number, number], [number, number]];
/**
* Sets the minor extent of this graticule.
*
* @param extent Minor extent of graticule.
*/
extentMinor(extent: [[number, number], [number, number]]): this;
/**
* Returns the current minor step, which defaults to ⟨10°, 10°⟩.
*/
step(): [number, number];
/**
* Sets the major and minor step for this graticule
*
* @param step Major and minor step to use for this graticule.
*/
step(step: [number, number]): this;
/**
* Returns the current major step, which defaults to ⟨90°, 360°⟩.
*/
stepMajor(): [number, number];
/**
* Sets the major step for this graticule.
*
* @param step Major step.
*/
stepMajor(step: [number, number]): this;
/**
* Returns the current major step, which defaults to ⟨10°, 10°⟩.
*/
stepMinor(): [number, number];
/**
* Sets the minor step for this graticule.
*
* @param step Minor step.
*/
stepMinor(step: [number, number]): this;
/**
* Returns the current precision, which defaults to 2.5°.
*/
precision(): number;
/**
* Sets the precision for this graticule, in degrees.
*
* @param angle Precision in degrees.
*/
precision(angle: number): this;
}
/**
* Constructs a feature generator for creating graticules: a uniform grid of meridians and parallels for showing projection distortion.
* The default graticule has meridians and parallels every 10° between ±80° latitude; for the polar regions, there are meridians every 90°.
*/
export function geoGraticule(): GeoGraticuleGenerator;
/**
* A convenience method for directly generating the default 10° global graticule as a GeoJSON MultiLineString geometry object.
*/
export function geoGraticule10(): GeoJSON.MultiLineString;
// ----------------------------------------------------------------------
// Projections
// ----------------------------------------------------------------------
/**
* A D3 geo stream. D3 transforms geometry using a sequence of function calls, rather than materializing intermediate representations, to minimize overhead.
* Streams must implement several methods to receive input geometry. Streams are inherently stateful; the meaning of a point depends on whether the point is inside of a line,
* and likewise a line is distinguished from a ring by a polygon. Despite the name “stream”, these method calls are currently synchronous.
*/
export interface GeoStream {
/**
* Indicates the end of a line or ring. Within a polygon, indicates the end of a ring.
* Unlike GeoJSON, the redundant closing coordinate of a ring is not indicated via point, and instead is implied via lineEnd within a polygon.
*/
lineEnd(): void;
/**
* Indicates the start of a line or ring. Within a polygon, indicates the start of a ring. The first ring of a polygon is the exterior ring, and is typically clockwise.
* Any subsequent rings indicate holes in the polygon, and are typically counterclockwise.
*/
lineStart(): void;
/**
* Indicates a point with the specified coordinates x and y (and optionally z). The coordinate system is unspecified and implementation-dependent;
* for example, projection streams require spherical coordinates in degrees as input. Outside the context of a polygon or line,
* a point indicates a point geometry object (Point or MultiPoint). Within a line or polygon ring, the point indicates a control point.
*
* @param x x-coordinate of point.
* @param y y-coordinate of point.
* @param z Optional z-coordinate of point.
*/
point(x: number, y: number, z?: number): void;
/**
* Indicates the end of a polygon.
*/
polygonEnd(): void;
/**
* Indicates the start of a polygon. The first line of a polygon indicates the exterior ring, and any subsequent lines indicate interior holes.
*/
polygonStart(): void;
/**
* Indicates the sphere (the globe; the unit sphere centered at ⟨0,0,0⟩).
*/
sphere?(): void;
}
// geoStream(...) =======================================================
/**
* Streams the specified GeoJSON object to the specified projection stream.
* While both features and geometry objects are supported as input, the stream interface only describes the geometry, and thus additional feature properties are not visible to streams.
*/
export function geoStream(
object: ExtendedFeature | ExtendedFeatureCollection | GeoGeometryObjects | ExtendedGeometryCollection,
stream: GeoStream,
): void;
// ----------------------------------------------------------------------
// Projections
// ----------------------------------------------------------------------
/**
* Raw projections are point transformation functions that are used to implement custom projections; they typically passed to d3.geoProjection or d3.geoProjectionMutator.
* They are exposed here to facilitate the derivation of related projections.
* Raw projections take spherical coordinates [lambda, phi] in radians (not degrees!) and return a point [x, y], typically in the unit square centered around the origin.
*/
export interface GeoRawProjection {
/**
* Projects the specified point [lambda, phi] in radians, returning a new point [x, y] in unitless coordinates.
* @param lambda Spherical lambda coordinate in radians.
* @param phi Spherical phi coordinate in radians.
*/
(lambda: number, phi: number): [number, number];
/**
* Inverts the projected point [x, y] in unitless coordinates, returning an unprojected point in spherical coordinates [lambda, phi] in radians.
* @param x x-coordinate (unitless).
* @param y y-coordinate (unitless).
*/
invert?(x: number, y: number): [number, number];
}
/**
* An object implementing a stream method
*/
export interface GeoStreamWrapper {
/**
* Returns a projection stream for the specified output stream. Any input geometry is projected before being streamed to the output stream.
* A typical projection involves several geometry transformations: the input geometry is first converted to radians, rotated on three axes,
* clipped to the small circle or cut along the antimeridian, and lastly projected to the plane with adaptive resampling, scale and translation.
*
* @param stream An input stream
*/
stream(stream: GeoStream): GeoStream;
}
/**
* A Geographic Projection to transform spherical polygonal geometry to planar polygonal geometry.
* D3 provides implementations of several classes of standard projections:
*
* - Azimuthal
* - Composite
* - Conic
* - Cylindrical
*
* For many more projections, see d3-geo-projection. You can implement custom projections using d3.geoProjection or d3.geoProjectionMutator.
*/
export interface GeoProjection extends GeoStreamWrapper {
/**
* Returns a new array [x, y] (typically in pixels) representing the projected point of the given point.
* The point must be specified as a two-element array [longitude, latitude] in degrees.
* May return null if the specified point has no defined projected position, such as when the point is outside the clipping bounds of the projection.
*
* @param point A point specified as a two-dimensional array [longitude, latitude] in degrees.
*/
(point: [number, number]): [number, number] | null;
/**
* Returns a new array [longitude, latitude] in degrees representing the unprojected point of the given projected point.
* May return null if the specified point has no defined projected position, such as when the point is outside the clipping bounds of the projection.
*
* @param point The projected point, specified as a two-element array [x, y] (typically in pixels).
*/
invert?(point: [number, number]): [number, number] | null;
/**
* Returns the current spherical clipping function.
* Pre-clipping occurs in geographic coordinates. Cutting along the antimeridian line,
* or clipping along a small circle are the most common strategies.
*/
preclip(): (stream: GeoStream) => GeoStream;
/**
* Sets the projection’s spherical clipping to the specified function and returns the projection.
* Pre-clipping occurs in geographic coordinates. Cutting along the antimeridian line, or clipping along a small circle are the most common strategies.
*
* @param preclip A spherical clipping function. Clipping functions are implemented as transformations of a projection stream.
* Pre-clipping operates on spherical coordinates, in radians.
*/
preclip(preclip: (stream: GeoStream) => GeoStream): this;
/**
* Returns the current cartesian clipping function.
* Post-clipping occurs on the plane, when a projection is bounded to a certain extent such as a rectangle.
*/
postclip(): (stream: GeoStream) => GeoStream;
/**
* Sets the projection’s cartesian clipping to the specified function and returns the projection.
*
* @param postclip A cartesian clipping function. Clipping functions are implemented as transformations of a projection stream.
* Post-clipping operates on planar coordinates, in pixels.
*/
postclip(postclip: (stream: GeoStream) => GeoStream): this;
/**
* Returns the current clip angle which defaults to null.
*
* null switches to antimeridian cutting rather than small-circle clipping.
*/
clipAngle(): number | null;
/**
* Sets the projection’s clipping circle radius to the specified angle in degrees and returns the projection.
* If angle is null, switches to antimeridian cutting rather than small-circle clipping.
*/
clipAngle(angle: null | number): this;
/**
* Returns the current viewport clip extent which defaults to null.
*/
clipExtent(): [[number, number], [number, number]] | null;
/**
* Sets the projection’s viewport clip extent to the specified bounds in pixels and returns the projection.
* The extent bounds are specified as an array [[x₀, y₀], [x₁, y₁]], where x₀ is the left-side of the viewport, y₀ is the top, x₁ is the right and y₁ is the bottom.
* If extent is null, no viewport clipping is performed.
*/
clipExtent(extent: null | [[number, number], [number, number]]): this;
/**
* Returns the current scale factor; the default scale is projection-specific.
*
* The scale factor corresponds linearly to the distance between projected points; however, absolute scale factors are not equivalent across projections.
*/
scale(): number;
/**
* Sets the projection’s scale factor to the specified value and returns the projection.
* The scale factor corresponds linearly to the distance between projected points; however, absolute scale factors are not equivalent across projections.
*
* @param scale Scale factor to be used for the projection; the default scale is projection-specific.
*/
scale(scale: number): this;
/**
* Returns the current translation offset which defaults to [480, 250] and places ⟨0°,0°⟩ at the center of a 960×500 area.
* The translation offset determines the pixel coordinates of the projection’s center.
*/
translate(): [number, number];
/**
* Sets the projection’s translation offset to the specified two-element array [tx, ty] and returns the projection.
* The translation offset determines the pixel coordinates of the projection’s center. The default translation offset places ⟨0°,0°⟩ at the center of a 960×500 area.
*
* @param point A two-element array [tx, ty] specifying the translation offset. The default translation offset of defaults to [480, 250] places ⟨0°,0°⟩ at the center of a 960×500 area.
*/
translate(point: [number, number]): this;
/**
* Returns the current center of the projection, which defaults to ⟨0°,0°⟩.
*/
center(): [number, number];
/**
* Sets the projection’s center to the specified center,
* a two-element array of longitude and latitude in degrees and returns the projection.
* The default is ⟨0°,0°⟩.
*
* @param point A point specified as a two-dimensional array [longitude, latitude] in degrees.
*/
center(point: [number, number]): this;
/**
* Returns the projection’s current angle, which defaults to 0°.
*/
angle(): number;
/**
* Sets the projection’s post-projection planar rotation angle to the specified angle in degrees and returns the projection.
* @param angle The new rotation angle of the projection.
*/
angle(angle: number): this;
/**
* Returns true if x-reflection is enabled, which defaults to false.
*/
reflectX(): boolean;
/**
* Sets whether or not the x-dimension is reflected (negated) in the output.
* @param reflect Whether or not the x-dimension is reflected (negated) in the output.
*/
reflectX(reflect: boolean): this;
/**
* Returns true if y-reflection is enabled, which defaults to false.
*/
reflectY(): boolean;
/**
* Sets whether or not the y-dimension is reflected (negated) in the output.
* @param reflect Whether or not the y-dimension is reflected (negated) in the output.
*/
reflectY(reflect: boolean): this;
/**
* Returns the current rotation [lambda, phi, gamma] specifying the rotation angles in degrees about each spherical axis.
* (These correspond to yaw, pitch and roll.) which defaults [0, 0, 0].
*/
rotate(): [number, number, number];
/**
* Sets the projection’s three-axis rotation to the specified angles, which must be a two- or three-element array of numbers.
*
* @param angles A two- or three-element array of numbers [lambda, phi, gamma] specifying the rotation angles in degrees about each spherical axis.
* (These correspond to yaw, pitch and roll.) If the rotation angle gamma is omitted, it defaults to 0.
*/
rotate(angles: [number, number] | [number, number, number]): this;
/**
* Returns the projection’s current resampling precision which defaults to square root of 0.5.
* This value corresponds to the Douglas–Peucker distance.
*/
precision(): number;
/**
* Sets the threshold for the projection’s adaptive resampling to the specified value in pixels and returns the projection.
* This value corresponds to the Douglas–Peucker distance.
*
* @param precision A numeric value in pixels to use as the threshold for the projection’s adaptive resampling.
*/
precision(precision: number): this;
/**
* Sets the projection’s scale and translate to fit the specified GeoJSON object in the center of the given extent.
* The extent is specified as an array [[x₀, y₀], [x₁, y₁]], where x₀ is the left side of the bounding box, y₀ is the top, x₁ is the right and y₁ is the bottom.
* Returns the projection.
*/
fitExtent(
extent: [[number, number], [number, number]],
object: ExtendedFeature | ExtendedFeatureCollection | GeoGeometryObjects | ExtendedGeometryCollection,
): this;
/**
* A convenience method for projection.fitExtent where the top-left corner of the extent is [0, 0].
*/
fitSize(
size: [number, number],
object: ExtendedFeature | ExtendedFeatureCollection | GeoGeometryObjects | ExtendedGeometryCollection,
): this;
/**
* A convenience method for projection.fitSize where the height is automatically chosen from the aspect ratio of object and the given constraint on width.
*/
fitWidth(
width: number,
object: ExtendedFeature | ExtendedFeatureCollection | GeoGeometryObjects | ExtendedGeometryCollection,
): this;
/**
* A convenience method for projection.fitSize where the width is automatically chosen from the aspect ratio of object and the given constraint on height.
*/
fitHeight(
height: number,
object: ExtendedFeature | ExtendedFeatureCollection | GeoGeometryObjects | ExtendedGeometryCollection,
): this;
}
/**
* A Conic Projection
*/
export interface GeoConicProjection extends GeoProjection {
/**
* Return the standard parallels for the conic projection in degrees.
*/
parallels(): [number, number];
/**
* Set the standard parallels for the conic projection in degrees and return the projection.
*
* @param value A two-dimensional array representing the standard parallels in degrees.
*/
parallels(value: [number, number]): this;
}
// geoPath ==============================================================
/**
* A minimal rendering context for a GeoPath generator. The minimum implemented
* methods are a subset of the CanvasRenderingContext2D API.
*
* For reference to the CanvasRenderingContext2D see https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D
*/
export interface GeoContext {
/**
* Adds an arc to the path with center point (x, y) and radius r starting at startAngle and ending at endAngle.
* The arc is drawn in clockwise direction by default.
*
* @param x x-coordinate of arc center point.
* @param y y-coordinate of arc center point.
* @param radius Radius of arc.
* @param startAngle The starting angle of the arc, measured clockwise from the positive x axis and expressed in radians.
* @param endAngle The end angle of the arc, measured clockwise from the positive x axis and expressed in radians.
* @param anticlockwise Optional boolean flag, if true the arc is drawn counter-clockwise between the two angles.
*/
arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void;
/**
* Start a new path by emptying the list of sub-paths.
*/
beginPath(): void;
/**
* Causes the point of the pen to move back to the start of the current sub-path.
* It tries to draw a straight line from the current point to the start.
* If the shape has already been closed or has only one point, this function does nothing.
*/
closePath(): void;
/**
* Connects the last point in the sub-path to the x, y coordinates with a straight line (but does not actually draw it).
*
* @param x The x-coordinate for the end of the line.
* @param y The y-coordinate for the end of the line.
*/
lineTo(x: number, y: number): void;
/**
* Move the starting point of a new sub-path to the (x, y) coordinates.
*
* @param x The x-coordinate for the new starting point.
* @param y The y-coordinate for the new starting point.
*/
moveTo(x: number, y: number): void;
}
/**
* A Geo Path generator
*
* The first generic corresponds to the "this"-context within which the geo path generator will be invoked.
* This could be e.g. the DOMElement bound to "this" when using selection.attr("d", ...) with the path generator.
*
* The second generic corresponds to the type of the DatumObject which will be passed into the geo path generator for rendering.
*/
export interface GeoPath<This = any, DatumObject extends GeoPermissibleObjects = GeoPermissibleObjects> {
/**
* Renders the given object, which may be any GeoJSON feature or geometry object:
*
* + Point - a single position.
* + MultiPoint - an array of positions.
* + LineString - an array of positions forming a continuous line.
* + MultiLineString - an array of arrays of positions forming several lines.
* + Polygon - an array of arrays of positions forming a polygon (possibly with holes).
* + MultiPolygon - a multidimensional array of positions forming multiple polygons.
* + GeometryCollection - an array of geometry objects.
* + Feature - a feature containing one of the above geometry objects.
* + FeatureCollection - an array of feature objects.
*
* The type Sphere is also supported, which is useful for rendering the outline of the globe; a sphere has no coordinates.
*
* Any additional arguments are passed along to the pointRadius accessor.
*
* IMPORTANT: If the rendering context of the geoPath generator is null,
* then the geoPath is returned as an SVG path data string.
*
* Separate path elements are typically slower than a single path element. However, distinct path elements are useful for styling and interaction (e.g., click or mouseover).
* Canvas rendering (see path.context) is typically faster than SVG, but requires more effort to implement styling and interaction.
*
* The first generic type of the GeoPath generator used, must correspond to the "this" context bound to the function upon invocation.
*
* @param object An object to be rendered.
*/
(this: This, object: DatumObject, ...args: any[]): string | null;
/**
* Renders the given object, which may be any GeoJSON feature or geometry object:
*
* + Point - a single position.
* + MultiPoint - an array of positions.
* + LineString - an array of positions forming a continuous line.
* + MultiLineString - an array of arrays of positions forming several lines.
* + Polygon - an array of arrays of positions forming a polygon (possibly with holes).
* + MultiPolygon - a multidimensional array of positions forming multiple polygons.
* + GeometryCollection - an array of geometry objects.
* + Feature - a feature containing one of the above geometry objects.
* + FeatureCollection - an array of feature objects.
*
* The type Sphere is also supported, which is useful for rendering the outline of the globe; a sphere has no coordinates.
*
* Any additional arguments are passed along to the pointRadius accessor.
*
* IMPORTANT: If the geoPath generator has been configured with a rendering context,
* then the geoPath is rendered to this context as a sequence of path method calls and this function returns void.
*
* Separate path elements are typically slower than a single path element. However, distinct path elements are useful for styling and interaction (e.g., click or mouseover).
* Canvas rendering (see path.context) is typically faster than SVG, but requires more effort to implement styling and interaction.
*
* The first generic type of the GeoPath generator used, must correspond to the "this" context bound to the function upon invocation.
*
* @param object An object to be rendered.
*/
(this: This, object: DatumObject, ...args: any[]): void;
/**
* Returns the projected planar area (typically in square pixels) for the specified GeoJSON object.
* Point, MultiPoint, LineString and MultiLineString geometries have zero area. For Polygon and MultiPolygon geometries,
* this method first computes the area of the exterior ring, and then subtracts the area of any interior holes.
* This method observes any clipping performed by the projection; see projection.clipAngle and projection.clipExtent. This is the planar equivalent of d3.geoArea.
*
* @param object An object for which the area is to be calculated.
*/
area(object: DatumObject): number;
/**
* Returns the projected planar bounding box (typically in pixels) for the specified GeoJSON object.
* The bounding box is represented by a two-dimensional array: [[x₀, y₀], [x₁, y₁]], where x₀ is the minimum x-coordinate, y₀ is the minimum y-coordinate,
* x₁ is maximum x-coordinate, and y₁ is the maximum y-coordinate.
*
* This is handy for, say, zooming in to a particular feature. (Note that in projected planar coordinates,
* the minimum latitude is typically the maximum y-value, and the maximum latitude is typically the minimum y-value.)
* This method observes any clipping performed by the projection; see projection.clipAngle and projection.clipExtent. This is the planar equivalent of d3.geoBounds.
*
* @param object An object for which the bounds are to be calculated.
*/
bounds(object: DatumObject): [[number, number], [number, number]];
/**
* Returns the projected planar centroid (typically in pixels) for the specified GeoJSON object.
* This is handy for, say, labeling state or county boundaries, or displaying a symbol map.
* For example, a noncontiguous cartogram might scale each state around its centroid.
* This method observes any clipping performed by the projection; see projection.clipAngle and projection.clipExtent. This is the planar equivalent of d3.geoCentroid.
*
* @param object An object for which the centroid is to be calculated.
*/
centroid(object: DatumObject): [number, number];
/**
* Returns the projected planar length (typically in pixels) for the specified GeoJSON object.
* Point and MultiPoint geometries have zero length. For Polygon and MultiPolygon geometries, this method computes the summed length of all rings.
*
* This method observes any clipping performed by the projection; see projection.clipAngle and projection.clipExtent. This is the planar equivalent of d3.geoLength.
*
* @param object An object for which the measure is to be calculated.
*/
measure(object: DatumObject): number;
/**
* Returns the current render context which defaults to null.
*
* Use the generic to cast the return type of the rendering context, if it is known for a specific application.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
context<C extends GeoContext | null>(): C;
/**
* sets the current render context and returns the path generator.
* If the context is null, then the path generator will return an SVG path string;
* if the context is non-null, the path generator will instead call methods on the specified context to render geometry.
*/
context(context: null | GeoContext): this;
/**
* Get the current projection. The generic parameter can be used to cast the result to the
* correct, known type of the projection, e.g. GeoProjection or GeoConicProjection. Otherwise,
* the return type defaults to the minimum type requirement for a projection which
* can be passed into a GeoPath.
*
* Use the generic to cast the return type of the projection, if it is known for a specific application.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
projection<P extends GeoConicProjection | GeoProjection | GeoStreamWrapper | null>(): P;
/**
* Sets the current projection to the specified projection.
* The null projection represents the identity transformation: the input geometry is not projected and is instead rendered directly in raw coordinates.
* This can be useful for fast rendering of pre-projected geometry, or for fast rendering of the equirectangular projection.
*/
projection(projection: null | GeoProjection | GeoStreamWrapper): this;
/**
* Returns the current radius or radius accessor used to determine the radius for the display of Point and MultiPoint geometries.
* The default is a constant radius of 4.5.
*/
pointRadius(): ((this: This, object: DatumObject, ...args: any[]) => number) | number;
/**
* Sets the radius used to display Point and MultiPoint geometries to the specified number.
* While the radius is commonly specified as a number constant, it may also be specified as a function which is computed per feature, being passed the any arguments passed to the path generator.
* For example, if your GeoJSON data has additional properties, you might access those properties inside the radius function to vary the point size;
* alternatively, you could d3.symbol and a projection for greater flexibility.
*/
pointRadius(value: number | ((this: This, object: DatumObject, ...args: any[]) => number)): this;
/**
* Returns the current number of digits, which defaults to 3.
*/
digits(): number;
/**
* Sets the number of fractional digits for coordinates generated in SVG path strings.
* @param digits New amount of digits
*/
digits(digits: number): this;
}
/**
* Creates a new geographic path generator.
*
* The default projection is the null projection. The null projection represents the identity transformation, i.e.
* the input geometry is not projected and is instead rendered directly in raw coordinates.
* This can be useful for fast rendering of pre-projected geometry, or for fast rendering of the equirectangular projection.
*
* The default context is null, which implies that the path generator will return an SVG path string.
*
* @param projection An (optional) current projection to be used. Typically this is one of D3’s built-in geographic projections;
* however, any object that exposes a projection.stream function can be used, enabling the use of custom projections.
* See D3’s transforms for more examples of arbitrary geometric transformations. Setting the projection to "null" uses the identity projection. The default value is "null", the identity projection.
* @param context An (optional) rendering context to be used. If a context is provided, it must at least implement the interface described by GeoContext, a subset of the CanvasRenderingContext2D API.
* Setting the context to "null" means that the path generator will return an SVG path string representing the to be rendered object. The default is "null".
*/
export function geoPath(projection?: GeoProjection | GeoStreamWrapper | null, context?: GeoContext | null): GeoPath;
/**
* Creates a new geographic path generator with the default settings.
*
* The default projection is the null projection. The null projection represents the identity transformation:
* the input geometry is not projected and is instead rendered directly in raw coordinates.
* This can be useful for fast rendering of pre-projected geometry, or for fast rendering of the equirectangular projection.
*
* The default context is null, which implies that the path generator will return an SVG path string.
*
* The generic corresponds to the type of the DatumObject which will be passed into the geo path generator for rendering
*
* @param projection An (optional) current projection to be used. Typically this is one of D3’s built-in geographic projections;
* however, any object that exposes a projection.stream function can be used, enabling the use of custom projections.
* See D3’s transforms for more examples of arbitrary geometric transformations. Setting the projection to "null" uses the identity projection. The default value is "null", the identity projection.
* @param context An (optional) rendering context to be used. If a context is provided, it must at least implement the interface described by GeoContext, a subset of the CanvasRenderingContext2D API.
* Setting the context to "null" means that the path generator will return an SVG path string representing the to be rendered object. The default is "null".
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function geoPath<DatumObject extends GeoPermissibleObjects>(
projection?: GeoProjection | GeoStreamWrapper | null,
context?: GeoContext | null,
): GeoPath<any, DatumObject>;
/**
* Creates a new geographic path generator with the default settings.
*
* The default projection is the null projection. The null projection represents the identity transformation:
* the input geometry is not projected and is instead rendered directly in raw coordinates.
* This can be useful for fast rendering of pre-projected geometry, or for fast rendering of the equirectangular projection.
*
* The default context is null, which implies that the path generator will return an SVG path string.
*
* The first generic corresponds to the "this"-context within which the geo path generator will be invoked.
* This could be e.g. the DOMElement bound to "this" when using selection.attr("d", ...) with the path generator.
*
* The second generic corresponds to the type of the DatumObject which will be passed into the geo path generator for rendering.
*
* @param projection An (optional) current projection to be used. Typically this is one of D3’s built-in geographic projections;
* however, any object that exposes a projection.stream function can be used, enabling the use of custom projections.
* See D3’s transforms for more examples of arbitrary geometric transformations. Setting the projection to "null" uses the identity projection. The default value is "null", the identity projection.
* @param context An (optional) rendering context to be used. If a context is provided, it must at least implement the interface described by GeoContext, a subset of the CanvasRenderingContext2D API.
* Setting the context to "null" means that the path generator will return an SVG path string representing the to be rendered object. The default is "null".
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function geoPath<This, DatumObject extends GeoPermissibleObjects>(
projection?: GeoProjection | GeoStreamWrapper | null,
context?: GeoContext | null,
): GeoPath<This, DatumObject>;
// geoProjection ==========================================================
/**
* Constructs a new projection from the specified raw projection, project.
* The project function takes the longitude and latitude of a given point in radians,
* often referred to as lambda (λ) and phi (φ), and returns a two-element array [x, y] representing its unit projection.
* The project function does not need to scale or translate the point, as these are applied automatically by projection.scale, projection.translate, and projection.center.
* Likewise, the project function does not need to perform any spherical rotation, as projection.rotate is applied prior to projection.
*
* If the project function exposes an invert method, the returned projection will also expose projection.invert.
*/
export function geoProjection(project: GeoRawProjection): GeoProjection;
// geoProjectionMutator ====================================================
/**
* Constructs a new projection from the specified raw projection factory and returns a mutate function to call whenever the raw projection changes.
* The factory must return a raw projection. The returned mutate function returns the wrapped projection.
*
* When creating a mutable projection, the mutate function is typically not exposed.
*/
export function geoProjectionMutator(factory: (...args: any[]) => GeoRawProjection): () => GeoProjection;
// Pre-Defined Projections and Raw Projections =============================
// Azimuthal Projections ---------------------------------------------------
/**
* The azimuthal equal-area projection.
*/
export function geoAzimuthalEqualArea(): GeoProjection;
/**
* The raw azimuthal equal-area projection.
*/
export function geoAzimuthalEqualAreaRaw(): GeoRawProjection;
/**
* The azimuthal equidistant projection.
*/
export function geoAzimuthalEquidistant(): GeoProjection;
/**
* The raw azimuthal equidistant projection.
*/
export function geoAzimuthalEquidistantRaw(): GeoRawProjection;
/**
* The gnomonic projection.
*/
export function geoGnomonic(): GeoProjection;
/**
* The raw gnomonic projection.
*/
export function geoGnomonicRaw(): GeoRawProjection;
/**
* The orthographic projection.
*/
export function geoOrthographic(): GeoProjection;
/**
* The raw orthographic projection.
*/
export function geoOrthographicRaw(): GeoRawProjection;
/**
* The stereographic projection.
*/
export function geoStereographic(): GeoProjection;
/**
* The raw stereographic projection.
*/
export function geoStereographicRaw(): GeoRawProjection;
/**
* The Equal Eartch projection, by Bojan Šavrič et al., 2018.
*/
export function geoEqualEarth(): GeoProjection;
/**
* The raw Equal Earth projection, by Bojan Šavrič et al., 2018.
*/
export function geoEqualEarthRaw(): GeoRawProjection;
// Composite Projections ---------------------------------------------------
/**
* A U.S.-centric composite projection of three d3.geoConicEqualArea projections: d3.geoAlbers is used for the lower forty-eight states,
* and separate conic equal-area projections are used for Alaska and Hawaii. Note that the scale for Alaska is diminished: it is projected at 0.35× its true relative area.
*
* Composite consist of several projections that are composed into a single display. The constituent projections have fixed clip, center and rotation,
* and thus composite projections do not support projection.center, projection.rotate, projection.clipAngle, or projection.clipExtent.
*/
export function geoAlbersUsa(): GeoProjection;
// Conic Projections -------------------------------------------------------
/**
* The Albers’ equal area-conic projection. This is a U.S.-centric configuration of d3.geoConicEqualArea.
*/
export function geoAlbers(): GeoConicProjection;
/**
* The conic conformal projection. The parallels default to [30°, 30°] resulting in flat top.
*/
export function geoConicConformal(): GeoConicProjection;
/**
* The raw conic conformal projection.
*/
export function geoConicConformalRaw(phi0: number, phi1: number): GeoRawProjection;
/**
* The Albers’ equal-area conic projection.
*/
export function geoConicEqualArea(): GeoConicProjection;
/**
* The raw Albers’ equal-area conic projection.
*/
export function geoConicEqualAreaRaw(phi0: n