Skip to content

colight.plot_extras

Custom marks

bitmap

Renders raw pixel data from an array.

Parameters

  • pixels (Union[list, np.ndarray, JSExpr]): Image data in one of these formats:

    • Raw pixel data in RGB or RGBA format (flat array of bytes)

    • 2D numpy array (grayscale image, values 0-1 or 0-255)

    • 3D numpy array with shape (height, width, channels)

  • width (int | None): Width of the image in pixels. Required for flat arrays,

    inferred from array shape for numpy arrays.

  • height (int | None): Height of the image in pixels. Required for flat arrays,

    inferred from array shape for numpy arrays.

  • interpolation (str): How to interpolate pixels when scaling. Options:

          - "nearest": Sharp pixels (default)

      - "bilinear": Smooth interpolation

      Similar to matplotlib's imshow interpolation.

Returns

  • A PlotSpec object representing the bitmap mark. (LayoutItem)

canvas_mark

Create a custom Plot mark that renders using HTML5 Canvas within an SVG context.

This function enables high-performance custom visualization by allowing direct canvas drawing operations while maintaining compatibility with Observable Plot's coordinate system and layout. The canvas is automatically scaled for high-DPI displays and embedded as a foreignObject in the SVG.

Parameters

  • user_canvas_fn (callable): A function that performs the canvas drawing operations.

    Called with arguments:

    • ctx: Canvas 2D rendering context (pre-scaled for device pixel ratio)

    • scales: Observable Plot scale functions for converting data to pixel coordinates

    • dim: Object with width/height properties in CSS pixels

    • mark_context: Plot mark context extended with 'mark_canvas' property

Returns

  • A plot specification that can be included in plot compositions.

ellipse

Returns a new ellipse mark for the given values and options.

If neither x nor y are specified, values 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 rx and ry options specify the x and y radii respectively. If only r is specified, it is used for both radii. The optional rotate option specifies rotation in degrees.

Additional styling options such as fill, stroke, and strokeWidth can be specified to customize the appearance of the ellipses.

Parameters

  • values (Any): The data for the ellipses.

  • options (dict[str, Any]): Additional options for customizing the ellipses.

  • **kwargs: Additional keyword arguments to be merged with options.

Returns

  • A PlotSpec object representing the ellipse mark. (PlotSpec)

histogram

Create a histogram plot from the given values.

Args:

values (list or array-like): The data values to be binned and plotted. mark (str): 'rectY' or 'dot'. thresholds (str, int, list, or callable, optional): The thresholds option may be specified as a named method or a variety of other ways:

  • auto (default): Scott’s rule, capped at 200.
  • freedman-diaconis: The Freedman–Diaconis rule.
  • scott: Scott’s normal reference rule.
  • sturges: Sturges’ formula.
  • A count (int) representing the desired number of bins.
  • An array of n threshold values for n - 1 bins.
  • An interval or time interval (for temporal binning).
  • A function that returns an array, count, or time interval.

Returns: PlotSpec: A plot specification for a histogram with the y-axis representing the count of values in each bin.

img

The image mark renders images on the plot. The src option specifies the image source, while x, y, width, and height define the image's position and size in the x/y scales. This differs from the built-in Observable Plot image mark, which specifies width/height in pixels.

Parameters

  • values: The data for the images.

  • options (dict[str, Any]): Options for customizing the images.

  • **kwargs: Additional keyword arguments to be merged with options.

Returns

  • A PlotSpec object representing the image mark. (PlotSpec)

The following options are supported: - src: The source path of the image. - x: The x-coordinate of the top-left corner. - y: The y-coordinate of the top-left corner. - width: The width of the image. - height: The height of the image.

pixels

A custom mark for efficiently rendering a single image from raw RGB(A) pixel data. Unlike most Observable Plot marks which render multiple elements from data arrays, this mark renders a single image from a flat array of pixel values.

Parameters

  • pixelData (list[float] | JSCode | Any): Raw pixel data as a flat array in either RGB format [r,g,b,r,g,b,...]

      or RGBA format [r,g,b,a,r,g,b,a,...]. Each value should be 0-255.

  • imageWidth (int | JSCode | None): Width of the source image in pixels

  • imageHeight (int | JSCode | None): Height of the source image in pixels

  • x (float | JSCode): X coordinate of top-left corner in plot coordinates (default: 0)

  • y (float | JSCode): Y coordinate of top-left corner in plot coordinates (default: 0)

  • width (float | JSCode | None): Displayed width in plot coordinates (defaults to imageWidth)

  • height (float | JSCode | None): Displayed height in plot coordinates (defaults to imageHeight)

Returns

  • A PlotSpec object representing the pixel image mark (PlotSpec)

Interactivity Utils

events

Captures events on a plot.

Parameters

  • options (dict[str, Any]): Callback functions. Supported: onClick, onMouseMove, onMouseDown, onDrawStart, onDraw, onDrawEnd.

  • **kwargs: Additional keyword arguments to be merged with options.

Each callback receives an event object with:

  • type, the event name
  • x, the x coordinate
  • y, the y coordinate
  • for draw events, startTime

Returns

  • A PlotSpec object representing the events mark. (PlotSpec)

renderChildEvents

Creates a render function that adds drag-and-drop and click functionality to child elements of a plot. Must be passed as the 'render' option to a mark, e.g.:

Plot.dot(data, render=Plot.renderChildEvents(
    onDrag=update_position,
    onClick=handle_click
))

This function enhances the rendering of plot elements by adding interactive behaviors such as dragging, clicking, and tracking position changes. It's designed to work with Observable Plot's rendering pipeline.

Parameters

  • options (dict): Configuration options for the child events

  • **kwargs: Event handlers passed as keyword arguments:

    • onDragStart (callable): Callback function called when dragging starts

    • onDrag (callable): Callback function called during dragging

    • onDragEnd (callable): Callback function called when dragging ends

    • onClick (callable): Callback function called when a child element is clicked

Returns

  • A render function to be used in the Observable Plot rendering pipeline. (JSRef)

Utils

htl

Hypertext Literal library (https://observablehq.com/@observablehq/htl)