From dd1956082007689a778ca3d6d391b62ce58a3782 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Sun, 26 Mar 2023 17:53:14 +0200 Subject: [PATCH 1/3] document image --- src/marks/image.d.ts | 91 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/src/marks/image.d.ts b/src/marks/image.d.ts index ff90f13773..d52cfbcd29 100644 --- a/src/marks/image.d.ts +++ b/src/marks/image.d.ts @@ -1,18 +1,109 @@ import type {ChannelValue, ChannelValueSpec} from "../channel.js"; import type {Data, FrameAnchor, MarkOptions, RenderableMark} from "../mark.js"; +/** Options for the image mark. */ export interface ImageOptions extends MarkOptions { + /** The horizontal position of the image; typically bound to the *x* scale. */ x?: ChannelValueSpec; + + /** The vertical position of the image; typically bound to the *y* scale. */ y?: ChannelValueSpec; + + /** + * The image width (in pixels, default 16). Images with a nonpositive width or + * height are not drawn. If a **width** is specified but not a **height**, or + * *vice versa*, the one defaults to the other. + */ width?: ChannelValue; + + /** + * The image height (in pixels, default 16). Images with a nonpositive width + * or height are not drawn. If a **width** is specified but not a **height**, + * or *vice versa*, the one defaults to the other. + */ height?: ChannelValue; + + /** + * The URL (or relative path) of each image (required). If **src** is + * specified as a string that starts with a dot, slash, or URL protocol + * (*e.g.*, “https:”) it is assumed to be a constant; otherwise it is + * interpreted as a channel. + */ src?: ChannelValue; + + /** + * The image [aspect ratio][1]; defaults to “xMidYMid meet”. + * + * To crop the image instead of scaling it to fit, set **preserveAspectRatio** + * to “xMidYMid slice”. The **imageRendering** option may be set to + * *pixelated* to disable bilinear interpolation on enlarged images; however, + * note that this is not supported in WebKit. + * + * [1]: + * https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio + */ preserveAspectRatio?: string; + + /** + * The [cross-origin][1] behavior. See the [Plot.image notebook][2] for details. + * + * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/crossorigin + * [2]: https://observablehq.com/@observablehq/plot-image + */ crossOrigin?: string; + + /** + * Position of the image relative to the frame if any of **x** or **y** are + * not specified. + */ frameAnchor?: FrameAnchor; + + /** + * The [image-rendering attribute][1]; defaults to *auto* (bilinear). The + * option may be set to *pixelated* to disable bilinear interpolation for a + * sharper image; however, note that this is not supported in WebKit. + * + * [1]: + * https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/image-rendering + */ imageRendering?: string; } +/** + * Draws images as in a scatterplot. For example, portraits of U.S. presidents + * by date of inauguration and favorability: + * + * ```js + * Plot.image(presidents, {x: "inauguration", y: "favorability", src: "portrait"}) + * ``` + * + * The required **src** option specifies the URL (or relative path) of each + * image. If **src** is specified as a string that starts with a dot, slash, or + * URL protocol (*e.g.*, “https:”) it is assumed to be a constant; otherwise it + * is interpreted as a channel. + * + * In addition to the standard mark options, the following optional channels are + * supported: + * + * * **x** - the horizontal position + * * **y** - the vertical position + * * **width** - the image width (in pixels) + * * **height** - the image height (in pixels) + * + * If either of the **x** or **y** channels are not specified, the corresponding + * position is controlled by the **frameAnchor** option. If neither the **x** + * nor **y** nor **frameAnchor** options are specified, *data* is assumed to be + * an array of pairs [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that + * **x** = [*x₀*, *x₁*, *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …]. + * + * The following image-specific constant options are also supported: + * **preserveAspectRatio**, **crossOrigin**, and **imageRendering**. + * + * Images are drawn in input order, with the last data drawn on top. If sorting + * is needed, say to mitigate overplotting, consider a [sort and reverse + * transform](#transforms). + */ export function image(data?: Data, options?: ImageOptions): Image; +/** The image mark. */ export class Image extends RenderableMark {} From 859b74fc4087df8ce183af2367bcc126b476fce4 Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Thu, 30 Mar 2023 15:32:33 -0700 Subject: [PATCH 2/3] edits --- src/marks/dot.d.ts | 16 ++++----- src/marks/image.d.ts | 86 ++++++++++++++++++-------------------------- 2 files changed, 43 insertions(+), 59 deletions(-) diff --git a/src/marks/dot.d.ts b/src/marks/dot.d.ts index 5da5314154..98733da5fc 100644 --- a/src/marks/dot.d.ts +++ b/src/marks/dot.d.ts @@ -48,12 +48,11 @@ export interface DotOptions extends MarkOptions { symbol?: ChannelValueSpec | SymbolType; /** - * The frame anchor may be specified as one of the four sides (*top*, *right*, - * *bottom*, *left*), one of the four corners (*top-left*, *top-right*, - * *bottom-right*, *bottom-left*), or the *middle* of the frame. It controls - * any component of the dot’s position not specified by **x** or **y**. For - * example, for a dots distributed in a horizontal line positioned at the top - * of the frame: + * The frame anchor specifies defaults for **x** and **y** based on the plot’s + * frame; it may be one of the four sides (*top*, *right*, *bottom*, *left*), + * one of the four corners (*top-left*, *top-right*, *bottom-right*, + * *bottom-left*), or the *middle* of the frame. For example, for a dots + * distributed in a horizontal line positioned at the top of the frame: * * ```js * Plot.dot(data, {x: "date", frameAnchor: "top"}) @@ -93,8 +92,9 @@ export interface DotYOptions extends Omit { } /** - * Draws circles, or other symbols, as in a scatterplot. For example, a - * scatterplot of sales by fruit type (category) and units sold (quantitative): + * Returns a new dot mark for the given *data* and *options* that draws circles, + * or other symbols, as in a scatterplot. For example, a scatterplot of sales by + * fruit type (category) and units sold (quantitative): * * ```js * Plot.dot(sales, {x: "units", y: "fruit"}) diff --git a/src/marks/image.d.ts b/src/marks/image.d.ts index d52cfbcd29..b8117ffdc4 100644 --- a/src/marks/image.d.ts +++ b/src/marks/image.d.ts @@ -3,44 +3,46 @@ import type {Data, FrameAnchor, MarkOptions, RenderableMark} from "../mark.js"; /** Options for the image mark. */ export interface ImageOptions extends MarkOptions { - /** The horizontal position of the image; typically bound to the *x* scale. */ + /** + * The horizontal position channel specifying the image’s center; typically + * bound to the *x* scale. + */ x?: ChannelValueSpec; - /** The vertical position of the image; typically bound to the *y* scale. */ + /** + * The vertical position channel specifying the image’s center; typically + * bound to the *y* scale. + */ y?: ChannelValueSpec; /** - * The image width (in pixels, default 16). Images with a nonpositive width or - * height are not drawn. If a **width** is specified but not a **height**, or - * *vice versa*, the one defaults to the other. + * The image width in pixels. When a number, it is interpreted as a constant + * radius in pixels; otherwise it is interpreted as a channel. Also sets the + * default **height**; if neither are set, defaults to 16. Images with a + * nonpositive width are not drawn. */ width?: ChannelValue; /** - * The image height (in pixels, default 16). Images with a nonpositive width - * or height are not drawn. If a **width** is specified but not a **height**, - * or *vice versa*, the one defaults to the other. + * The image height in pixels. When a number, it is interpreted as a constant + * radius in pixels; otherwise it is interpreted as a channel. Also sets the + * default **height**; if neither are set, defaults to 16. Images with a + * nonpositive height are not drawn. */ height?: ChannelValue; /** - * The URL (or relative path) of each image (required). If **src** is - * specified as a string that starts with a dot, slash, or URL protocol - * (*e.g.*, “https:”) it is assumed to be a constant; otherwise it is - * interpreted as a channel. + * The required image URL (or relative path). If a string that starts with a + * dot, slash, or URL protocol (*e.g.*, “https:”) it is assumed to be a + * constant; otherwise it is interpreted as a channel. */ src?: ChannelValue; /** - * The image [aspect ratio][1]; defaults to “xMidYMid meet”. - * - * To crop the image instead of scaling it to fit, set **preserveAspectRatio** - * to “xMidYMid slice”. The **imageRendering** option may be set to - * *pixelated* to disable bilinear interpolation on enlarged images; however, - * note that this is not supported in WebKit. + * The image [aspect ratio][1]; defaults to *xMidYMid meet*. To crop the image + * instead of scaling it to fit, use *xMidYMid slice*. * - * [1]: - * https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio + * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio */ preserveAspectRatio?: string; @@ -53,8 +55,10 @@ export interface ImageOptions extends MarkOptions { crossOrigin?: string; /** - * Position of the image relative to the frame if any of **x** or **y** are - * not specified. + * The frame anchor specifies defaults for **x** and **y** based on the plot’s + * frame; it may be one of the four sides (*top*, *right*, *bottom*, *left*), + * one of the four corners (*top-left*, *top-right*, *bottom-right*, + * *bottom-left*), or the *middle* of the frame. */ frameAnchor?: FrameAnchor; @@ -63,45 +67,25 @@ export interface ImageOptions extends MarkOptions { * option may be set to *pixelated* to disable bilinear interpolation for a * sharper image; however, note that this is not supported in WebKit. * - * [1]: - * https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/image-rendering + * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/image-rendering */ imageRendering?: string; } /** - * Draws images as in a scatterplot. For example, portraits of U.S. presidents - * by date of inauguration and favorability: + * Returns a new image mark for the given *data* and *options* that draws images + * as in a scatterplot. For example, portraits of U.S. presidents by date of + * inauguration and favorability: * * ```js * Plot.image(presidents, {x: "inauguration", y: "favorability", src: "portrait"}) * ``` * - * The required **src** option specifies the URL (or relative path) of each - * image. If **src** is specified as a string that starts with a dot, slash, or - * URL protocol (*e.g.*, “https:”) it is assumed to be a constant; otherwise it - * is interpreted as a channel. - * - * In addition to the standard mark options, the following optional channels are - * supported: - * - * * **x** - the horizontal position - * * **y** - the vertical position - * * **width** - the image width (in pixels) - * * **height** - the image height (in pixels) - * - * If either of the **x** or **y** channels are not specified, the corresponding - * position is controlled by the **frameAnchor** option. If neither the **x** - * nor **y** nor **frameAnchor** options are specified, *data* is assumed to be - * an array of pairs [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that - * **x** = [*x₀*, *x₁*, *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …]. - * - * The following image-specific constant options are also supported: - * **preserveAspectRatio**, **crossOrigin**, and **imageRendering**. - * - * Images are drawn in input order, with the last data drawn on top. If sorting - * is needed, say to mitigate overplotting, consider a [sort and reverse - * transform](#transforms). + * If either **x** or **y** is not specified, the default is determined by the + * **frameAnchor** option. If none of **x**, **y**, and **frameAnchor** are + * specified, *data* is assumed to be an array of pairs [[*x₀*, *y₀*], [*x₁*, + * *y₁*], [*x₂*, *y₂*], …] such that **x** = [*x₀*, *x₁*, *x₂*, …] and **y** = + * [*y₀*, *y₁*, *y₂*, …]. */ export function image(data?: Data, options?: ImageOptions): Image; From 2e7b1b1c92853ed47a268e6b985086b56c9db908 Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Thu, 30 Mar 2023 15:33:13 -0700 Subject: [PATCH 3/3] edits --- src/marks/dot.d.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/marks/dot.d.ts b/src/marks/dot.d.ts index 98733da5fc..c078bb96b1 100644 --- a/src/marks/dot.d.ts +++ b/src/marks/dot.d.ts @@ -51,8 +51,8 @@ export interface DotOptions extends MarkOptions { * The frame anchor specifies defaults for **x** and **y** based on the plot’s * frame; it may be one of the four sides (*top*, *right*, *bottom*, *left*), * one of the four corners (*top-left*, *top-right*, *bottom-right*, - * *bottom-left*), or the *middle* of the frame. For example, for a dots - * distributed in a horizontal line positioned at the top of the frame: + * *bottom-left*), or the *middle* of the frame. For example, for dots + * distributed horizontally at the top of the frame: * * ```js * Plot.dot(data, {x: "date", frameAnchor: "top"})