plasma_plots.hero
Animated SVG header pictures for the home pages of the docs: plasma_plots.hero.
The max-models docs theme (starlight-theme) shows docs/src/assets/hero.svg, when a project
has one, across the top of its home page instead of the default streamlines. The picture takes the
site’s colours: every mark has a tone ("accent", "high", "low", "muted" or
"bg") that the theme turns into a colour of the palette, in light and dark mode. Moving parts
are SVG animations, which the theme stops for readers who prefer reduced motion.
import numpy as np from plasma_plots.hero import HeroFigure fig = HeroFigure(xlim=(0, 4), ylim=(-1, 1)) x = np.linspace(0, 4, 200) line = fig.line(x, np.sin(np.pi * x), opacity=0.8) dot = fig.tracer(line, duration=6) # a dot drifting along the line fig.save(“docs/src/assets/hero.svg”) # doctest: +SKIP
Coordinates are data coordinates within xlim and ylim (y pointing up); radii and line
widths are in pixels of the width x height picture. The theme crops the picture to the
header (preserveAspectRatio="xMidYMid slice") and fades its left part behind the title, so the
interesting part goes to the right.
Attributes
| Name | Description |
|---|---|
TONES | No description. |
Classes
| Name | Description |
|---|---|
HeroFigure | An animated SVG picture for the header of a docs home page. |
Mark | One element of a HeroFigure, returned by its drawing methods. |
Functions
| Name | Description |
|---|---|
from_array | Turn a profile that changes over a sweep (usually time) into an animated header picture. |
TONESattributemodule attribute#
TONES = ('accent', 'high', 'low', 'muted', 'bg')HeroFigureclass#
class HeroFigure(xlim=(0.0, 1.0), ylim=(0.0, 1.0), width=1600, height=600, xscale='linear', yscale='linear')An animated SVG picture for the header of a docs home page.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
xlim | (float, float) | (0.0, 1.0) | The data range shown across and up the picture. |
ylim | (float, float) | (0.0, 1.0) | The data range shown across and up the picture. |
width | int | 1600 | The size of the picture in pixels (the theme scales it to the header). |
height | int | 1600 | The size of the picture in pixels (the theme scales it to the header). |
xscale | ('linear', 'log') | "linear" | The scale of each axis; non-positive values on a log axis are left out. |
yscale | ('linear', 'log') | "linear" | The scale of each axis; non-positive values on a log axis are left out. |
heightattributeinstance attribute#
height = int(height)marksattributeinstance attribute#
marks = []widthattributeinstance attribute#
width = int(width)xlimattributeinstance attribute#
xlim = tuple((float(v) for v in self._scaled(xlim, xscale)))xscaleattributeinstance attribute#
xscale = xscaleylimattributeinstance attribute#
ylim = tuple((float(v) for v in self._scaled(ylim, yscale)))yscaleattributeinstance attribute#
yscale = yscalecirclemethod#
def circle(x, y, r, tone='accent', fill=True, opacity=1.0, width=1.5, title=None)Draw a circle.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
x | float | required | The centre, in data coordinates. |
y | float | required | The centre, in data coordinates. |
r | float | required | The radius in pixels. |
tone | str | 'accent' | Its colour. |
fill | bool | True | Filled, or only the outline. |
opacity | float | 1.0 | Between 0 and 1. |
width | float | 1.5 | The outline width in pixels, when not filled. |
title | str or None | None | A tooltip shown on hover. |
Returns
Mark- The circle.
discmethod#
def disc(x, y, radius, tone='bg', outline='accent', width=2.5, title=None)Draw a solid body, such as an obstacle or an electrode, with a radius in data units.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
x | float | required | The centre, in data coordinates. |
y | float | required | The centre, in data coordinates. |
radius | float | required | The radius in data units (of x). |
tone | str | 'bg' | The fill colour. |
outline | str | 'accent' | The outline colour. |
width | float | 2.5 | The outline width in pixels. |
title | str or None | None | A tooltip shown on hover. |
Returns
Mark- The disc.
linemethod#
def line(x, y, tone='accent', width=1.5, opacity=1.0, dash=None, title=None)Draw a line through points.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
x | array_like | required | The points, in data coordinates; non-finite points are left out. |
y | array_like | required | The points, in data coordinates; non-finite points are left out. |
tone | str | 'accent' | Its colour (see the module docstring). |
width | float | 1.5 | The line width in pixels. |
opacity | float | 1.0 | Between 0 and 1. |
dash | str or None | None | An SVG dash pattern, e.g. "4 6". |
title | str or None | None | A tooltip shown on hover. |
morphmethod#
def morph(x, ys, duration, tone='accent', width=1.5, opacity=1.0, begin=0.0, title=None)Draw a line that changes shape through several profiles, on a loop.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
x | array_like | required | The common abscissa of the profiles. |
ys | sequence of array_like | required | The profiles in time order; the line returns to the first at the end of a pass. All must have the same finite points (the shape blends point by point). |
duration | float | required | Seconds for one pass. |
tone | str | 'accent' | Its colour. |
width | float | 1.5 | The line width in pixels. |
opacity | float | 1.0 | Between 0 and 1. |
begin | float | 0.0 | Seconds into the pass at which the page starts. |
title | str or None | None | A tooltip shown on hover. |
Returns
Mark- The line.
polygonmethod#
def polygon(x, y, tone='accent', opacity=1.0, outline=None, title=None, width=1.5)Fill a closed shape.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
x | array_like | required | The corners, in data coordinates. |
y | array_like | required | The corners, in data coordinates. |
tone | str | 'accent' | The fill colour. |
opacity | float | 1.0 | The fill opacity. |
outline | str or None | None | The tone of an outline, or None for none. |
title | str or None | None | A tooltip shown on hover. |
width | float | 1.5 | The outline width in pixels. |
Returns
Mark- The shape.
rectmethod#
def rect(x0, y0, x1, y1, tone='accent', opacity=1.0, outline=None, title=None, width=1.5)Draw a rectangle between two corners.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
x0 | float | required | Two opposite corners, in data coordinates. |
y0 | float | required | Two opposite corners, in data coordinates. |
x1 | float | required | Two opposite corners, in data coordinates. |
y1 | float | required | Two opposite corners, in data coordinates. |
tone | str | 'accent' | The fill colour. |
opacity | float | 1.0 | The fill opacity. |
outline | str or None | None | The tone of an outline, or None for none. |
title | str or None | None | A tooltip shown on hover. |
width | float | 1.5 | The outline width in pixels. |
Returns
Mark- The rectangle.
savemethod#
def save(path)Write the picture to an SVG file.
Parameters
| Name | Type | Description |
|---|---|---|
path | str or pathlib.Path | The file, usually docs/src/assets/hero.svg. |
Returns
pathlib.Path- The file written.
to_svgmethod#
def to_svg()Return the picture as SVG text.
Returns
str- The SVG document.
tracermethod#
def tracer(along, duration, offset=0.0, r=4.0, tone='high', y=None)Add a dot that moves along a line or a trajectory, on a loop.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
along | Mark or array_like | required | A line from line(), or the x of a trajectory (with y). |
duration | float | required | Seconds for one pass. |
offset | float | 0.0 | Seconds into the pass at which the page starts. |
r | float | 4.0 | The radius in pixels. |
tone | str | 'high' | Its colour. |
y | array_like or None | None | The y of the trajectory, when along is its x. |
Returns
Mark- The dot, e.g. to animate its colour or size too.
Markclass#
class Mark(tag, attrs, path=None)One element of a HeroFigure, returned by its drawing methods.
Parameters
attrsattributeinstance attribute#
attrs = attrschildrenattributeinstance attribute#
children = []pathattributeinstance attribute#
path = pathtagattributeinstance attribute#
tag = taganimatemethod#
def animate(attribute, values, duration, begin=0.0, discrete=False)Animate an attribute through a list of values, on a loop.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
attribute | str | required | The SVG attribute, e.g. "opacity", "r" or "cx". |
values | sequence | required | The values it passes through, evenly spaced in time; repeat the first at the end for a smooth loop. |
duration | float | required | Seconds for one pass. |
begin | float | 0.0 | Seconds into the pass at which the page starts (spreads several marks apart). |
discrete | bool | False | Jump from value to value instead of blending, for frame-by-frame states. |
Returns
Mark- This mark, to chain calls.
to_svgmethod#
def to_svg()Return the element as SVG text.
Returns
str- The element.
from_arrayfunction#
def from_array(data, *, sweep: str = 't', duration: float = 8.0, max_frames: int = 24, tone: str = 'accent', width: float = 2.0, opacity: float = 0.9, pad: float = 0.08, tracer: bool = False, picture=(1600, 600)) -> HeroFigureTurn a profile that changes over a sweep (usually time) into an animated header picture.
The profile’s shape morphs through evenly spaced frames of the sweep and back to the first,
on a loop, in the bare look of a header: no axes, the site’s colours. It is the animated SVG
counterpart of the "bare" style (see plasma_plots.styles).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
data | xarray.DataArray | required | A profile over one dimension and sweep, e.g. a potential over x and t. |
sweep | str | 't' | The dimension the animation runs over. Default: "t". |
duration | float | 8.0 | Seconds for one pass through the frames. Default: 8. |
max_frames | int | 24 | At most this many frames, evenly spaced, the first and last included. Default: 24. |
tone | ('accent', 'high', 'low', 'muted', 'bg') | "accent" | The line’s colour in the site’s palette. Default: "accent". |
width | float | 2.0 | The line width in pixels. Default: 2. |
opacity | float | 0.9 | Between 0 and 1. Default: 0.9. |
pad | float | 0.08 | Space above and below the profile, as a fraction of its range. Default: 0.08. |
tracer | bool | False | Add a dot drifting along the line. Default: False. |
picture | (int, int) | (1600, 600) | The picture’s width and height in pixels. Default: (1600, 600). |
Returns
HeroFigure- The picture;
.save("docs/src/assets/hero.svg")writes it.
Raises
ValueError- If
datahas dimensions other thansweepand one more, or no finite values.
Examples
>>> from plasma_plots.hero import from_array>>> from_array(phi.isel(y=0)).save("docs/src/assets/hero.svg")