From 99b76bd1038ee213e0b5039f8f001acc538331d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Thu, 23 Mar 2023 15:59:19 +0100 Subject: [PATCH 1/2] document projection --- src/plot.d.ts | 4 +++- src/projection.d.ts | 53 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 1 deletion(-) diff --git a/src/plot.d.ts b/src/plot.d.ts index 00286e9b08..d98ae0afee 100644 --- a/src/plot.d.ts +++ b/src/plot.d.ts @@ -242,7 +242,9 @@ export interface PlotOptions extends ScaleDefaults { /** * Options for projection. A projection is an alternative to the *x* and *y* * scales for encoding position, and is typically used to convert polygonal - * geometry in spherical coordinates to a planar visual representation. + * geometry in spherical coordinates to a planar visual representation. For + * planar (already-projected) coordinates, use the identity projection, or the + * reflect-y projection if *y* points up. */ projection?: ProjectionOptions | ProjectionName | ProjectionFactory | ProjectionImplementation | null; diff --git a/src/projection.d.ts b/src/projection.d.ts index ed096a8c77..01ee102686 100644 --- a/src/projection.d.ts +++ b/src/projection.d.ts @@ -19,14 +19,67 @@ export type ProjectionName = | "stereographic" | "transverse-mercator"; +/** An instantiated projection, implementing a stream method. */ export type ProjectionImplementation = GeoStreamWrapper; +/** A function returning an instantiated projection. */ export type ProjectionFactory = (options: any) => ProjectionImplementation; export interface ProjectionOptions extends InsetOptions { + /** + * When specified as a name, the projection is automatically scaled and + * translated to make its **domain** fit the frame’s size (with any insets + * discounted). If specified as a function, it receives a configuration object + * ({width, height, ...options}) that must return an instantiated projection. + * + * For example, to use the [Bertin 1953 projection](https://observablehq.com/@d3/geo-bertin-1953): + * + * ```js + * {type: ({width, height, domain}) => d3.geoBertin1953().fitSize([width, height], domain)} + * ``` + */ type?: ProjectionName | ProjectionFactory | null; + + /** + * A GeoJSON object to fit to the frame’s dimensions (width and height, minus + * any insets). The default for spherical projections is the Sphere (outline + * of the the whole globe). + */ domain?: GeoPermissibleObjects; + + /** + * A rotation of the sphere before projection. Specified as Euler angles λ + * (yaw, or reference longitude), φ (pitch, or reference latitude), and + * optionally γ (roll), in degrees. + */ rotate?: [x: number, y: number, z?: number]; + + /** + * The [standard + * parallels](https://github.com/d3/d3-geo/blob/main/README.md#conic_parallels) + * (for conic projections only). + */ parallels?: [y1: number, y2: number]; + + /** + * The projection’s [sampling threshold](https://github.com/d3/d3-geo/blob/main/README.md#projection_precision). + */ + precision?: number; + + /** + * The projection’s clipping method. One of: + * + * * *frame* or true (default) - clip to the extent of the frame (including + * margins but not insets) + * * a number - clip to a great circle of the given radius in degrees centered + * around the origin + * * null or false - do not clip + * + * Some projections (such as + * [armadillo](https://observablehq.com/@d3/armadillo) or + * [berghaus](https://observablehq.com/@d3/berghaus-star))) additionally + * require path clipping: in that case set the marks’ **clip** option to + * *sphere*. + */ clip?: boolean | number | "frame" | null; } From 2d6547f07aee5d56df5ba480eaeee5e7144cda50 Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Tue, 28 Mar 2023 15:43:16 -0700 Subject: [PATCH 2/2] edits --- src/plot.d.ts | 18 ++++++++--- src/projection.d.ts | 79 +++++++++++++++++++++++++++++++-------------- 2 files changed, 67 insertions(+), 30 deletions(-) diff --git a/src/plot.d.ts b/src/plot.d.ts index d98ae0afee..22316e8e66 100644 --- a/src/plot.d.ts +++ b/src/plot.d.ts @@ -240,11 +240,19 @@ export interface PlotOptions extends ScaleDefaults { length?: ScaleOptions; /** - * Options for projection. A projection is an alternative to the *x* and *y* - * scales for encoding position, and is typically used to convert polygonal - * geometry in spherical coordinates to a planar visual representation. For - * planar (already-projected) coordinates, use the identity projection, or the - * reflect-y projection if *y* points up. + * Options for projection; one of: + * + * - a named built-in projection such as *albers-usa* + * - a projection implementation, implementing the projection.*stream* method + * - a function that returns a projection implementation + * - a projection options object + * - null, for no projection + * + * A projection is an alternative to the *x* and *y* scales for encoding + * position, and is typically used to convert polygonal geometry in spherical + * coordinates to a planar visual representation. For planar (projected) + * coordinates, use the *identity* projection, or the *reflect-y* projection + * if *y* points up. */ projection?: ProjectionOptions | ProjectionName | ProjectionFactory | ProjectionImplementation | null; diff --git a/src/projection.d.ts b/src/projection.d.ts index 01ee102686..82bd130c8e 100644 --- a/src/projection.d.ts +++ b/src/projection.d.ts @@ -1,6 +1,26 @@ import type {GeoPermissibleObjects, GeoStreamWrapper} from "d3"; import type {InsetOptions} from "./inset.js"; +/** + * The built-in projection implementations; one of: + * + * - *albers-usa* - a U.S.-centric composite projection with insets for Alaska and Hawaii + * - *albers* - a U.S.-centric *conic-equal-area* projection + * - *azimuthal-equal-area* - the azimuthal equal-area projection + * - *azimuthal-equidistant* - the azimuthal equidistant projection + * - *conic-conformal* - the conic conformal projection + * - *conic-equal-area* - the conic equal-area projection + * - *conic-equidistant* - the conic equidistant projection + * - *equal-earth* - the Equal Earth projection Šavrič et al., 2018 + * - *equirectangular* - the equirectangular (plate carrée) projection + * - *gnomonic* - the gnomonic projection + * - *identity* - the identity projection + * - *reflect-y* - the identity projection, but flipping *y* + * - *mercator* - the spherical Mercator projection + * - *orthographic* - the orthographic projection + * - *stereographic* - the stereographic projection + * - *transverse-mercator* - the transverse spherical Mercator projection + */ export type ProjectionName = | "albers-usa" | "albers" @@ -25,61 +45,70 @@ export type ProjectionImplementation = GeoStreamWrapper; /** A function returning an instantiated projection. */ export type ProjectionFactory = (options: any) => ProjectionImplementation; +/** Options for projection. */ export interface ProjectionOptions extends InsetOptions { /** - * When specified as a name, the projection is automatically scaled and - * translated to make its **domain** fit the frame’s size (with any insets - * discounted). If specified as a function, it receives a configuration object - * ({width, height, ...options}) that must return an instantiated projection. + * The desired projection; one of: * - * For example, to use the [Bertin 1953 projection](https://observablehq.com/@d3/geo-bertin-1953): + * - a named built-in projection such as *albers-usa* + * - a function that returns a projection implementation + * - null, for no projection + * + * When specified as a name, the projection is scaled and translated to fit + * the **domain** to the plot’s frame (minus insets). If a function, it + * receives a configuration object ({width, height, ...options}) and must + * return an object that implements the *projection*.stream method. + * + * For example, to use the [Bertin 1953 projection][1]: * * ```js * {type: ({width, height, domain}) => d3.geoBertin1953().fitSize([width, height], domain)} * ``` + * + * [1]: https://observablehq.com/@d3/geo-bertin-1953 */ type?: ProjectionName | ProjectionFactory | null; /** - * A GeoJSON object to fit to the frame’s dimensions (width and height, minus - * any insets). The default for spherical projections is the Sphere (outline - * of the the whole globe). + * A GeoJSON object to fit to the plot’s frame (minus insets); defaults to a + * Sphere for spherical projections (outline of the the whole globe). */ domain?: GeoPermissibleObjects; /** - * A rotation of the sphere before projection. Specified as Euler angles λ - * (yaw, or reference longitude), φ (pitch, or reference latitude), and - * optionally γ (roll), in degrees. + * A rotation of the sphere before projection; defaults to [0, 0, 0]. + * Specified as Euler angles λ (yaw, or reference longitude), φ (pitch, or + * reference latitude), and optionally γ (roll), in degrees. */ rotate?: [x: number, y: number, z?: number]; /** - * The [standard - * parallels](https://github.com/d3/d3-geo/blob/main/README.md#conic_parallels) - * (for conic projections only). + * The [standard parallels][1]. For conic projections only. + * + * [1]: https://github.com/d3/d3-geo/blob/main/README.md#conic_parallels */ parallels?: [y1: number, y2: number]; /** - * The projection’s [sampling threshold](https://github.com/d3/d3-geo/blob/main/README.md#projection_precision). + * The projection’s [sampling threshold][1]. + * + * [1]: https://github.com/d3/d3-geo/blob/main/README.md#projection_precision */ precision?: number; /** - * The projection’s clipping method. One of: + * The projection’s clipping method; one of: * - * * *frame* or true (default) - clip to the extent of the frame (including - * margins but not insets) - * * a number - clip to a great circle of the given radius in degrees centered - * around the origin - * * null or false - do not clip + * - *frame* or true (default) - clip to the plot’s frame (including margins but not insets) + * - a number - clip to a circle of the given radius in degrees centered around the origin + * - null or false - do not clip * - * Some projections (such as - * [armadillo](https://observablehq.com/@d3/armadillo) or - * [berghaus](https://observablehq.com/@d3/berghaus-star))) additionally - * require path clipping: in that case set the marks’ **clip** option to + * Some projections (such as [*armadillo*][1] and [*berghaus*][2]) require + * spherical clipping: in that case set the marks’ **clip** option to * *sphere*. + * + * [1]: https://observablehq.com/@d3/armadillo + * [2]: https://observablehq.com/@d3/berghaus-star */ clip?: boolean | number | "frame" | null; }