Skip to content
Projects

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

NameDescription
TONESNo description.

Classes

NameDescription
HeroFigureAn animated SVG picture for the header of a docs home page.
MarkOne element of a HeroFigure, returned by its drawing methods.

Functions

NameDescription
from_arrayTurn 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

NameTypeDefaultDescription
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.
widthint1600The size of the picture in pixels (the theme scales it to the header).
heightint1600The 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 = xscale

ylimattributeinstance attribute#

ylim = tuple((float(v) for v in self._scaled(ylim, yscale)))

yscaleattributeinstance attribute#

yscale = yscale

circlemethod#

def circle(x, y, r, tone='accent', fill=True, opacity=1.0, width=1.5, title=None)

Draw a circle.

Parameters

NameTypeDefaultDescription
xfloatrequiredThe centre, in data coordinates.
yfloatrequiredThe centre, in data coordinates.
rfloatrequiredThe radius in pixels.
tonestr'accent'Its colour.
fillboolTrueFilled, or only the outline.
opacityfloat1.0Between 0 and 1.
widthfloat1.5The outline width in pixels, when not filled.
titlestr or NoneNoneA 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

NameTypeDefaultDescription
xfloatrequiredThe centre, in data coordinates.
yfloatrequiredThe centre, in data coordinates.
radiusfloatrequiredThe radius in data units (of x).
tonestr'bg'The fill colour.
outlinestr'accent'The outline colour.
widthfloat2.5The outline width in pixels.
titlestr or NoneNoneA 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

NameTypeDefaultDescription
xarray_likerequiredThe points, in data coordinates; non-finite points are left out.
yarray_likerequiredThe points, in data coordinates; non-finite points are left out.
tonestr'accent'Its colour (see the module docstring).
widthfloat1.5The line width in pixels.
opacityfloat1.0Between 0 and 1.
dashstr or NoneNoneAn SVG dash pattern, e.g. "4 6".
titlestr or NoneNoneA tooltip shown on hover.

Returns

Mark
The line, to animate or to pass to tracer().

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

NameTypeDefaultDescription
xarray_likerequiredThe common abscissa of the profiles.
yssequence of array_likerequiredThe 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).
durationfloatrequiredSeconds for one pass.
tonestr'accent'Its colour.
widthfloat1.5The line width in pixels.
opacityfloat1.0Between 0 and 1.
beginfloat0.0Seconds into the pass at which the page starts.
titlestr or NoneNoneA 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

NameTypeDefaultDescription
xarray_likerequiredThe corners, in data coordinates.
yarray_likerequiredThe corners, in data coordinates.
tonestr'accent'The fill colour.
opacityfloat1.0The fill opacity.
outlinestr or NoneNoneThe tone of an outline, or None for none.
titlestr or NoneNoneA tooltip shown on hover.
widthfloat1.5The 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

NameTypeDefaultDescription
x0floatrequiredTwo opposite corners, in data coordinates.
y0floatrequiredTwo opposite corners, in data coordinates.
x1floatrequiredTwo opposite corners, in data coordinates.
y1floatrequiredTwo opposite corners, in data coordinates.
tonestr'accent'The fill colour.
opacityfloat1.0The fill opacity.
outlinestr or NoneNoneThe tone of an outline, or None for none.
titlestr or NoneNoneA tooltip shown on hover.
widthfloat1.5The outline width in pixels.

Returns

Mark
The rectangle.

savemethod#

def save(path)

Write the picture to an SVG file.

Parameters

NameTypeDescription
pathstr or pathlib.PathThe 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

NameTypeDefaultDescription
alongMark or array_likerequiredA line from line(), or the x of a trajectory (with y).
durationfloatrequiredSeconds for one pass.
offsetfloat0.0Seconds into the pass at which the page starts.
rfloat4.0The radius in pixels.
tonestr'high'Its colour.
yarray_like or NoneNoneThe 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

NameTypeDefaultDescription
tagstrrequiredThe SVG element.
attrsdictrequiredIts attributes.
pathstr or NoneNoneThe SVG path of a line, which HeroFigure.tracer() follows.

attrsattributeinstance attribute#

attrs = attrs

childrenattributeinstance attribute#

children = []

pathattributeinstance attribute#

path = path

tagattributeinstance attribute#

tag = tag

animatemethod#

def animate(attribute, values, duration, begin=0.0, discrete=False)

Animate an attribute through a list of values, on a loop.

Parameters

NameTypeDefaultDescription
attributestrrequiredThe SVG attribute, e.g. "opacity", "r" or "cx".
valuessequencerequiredThe values it passes through, evenly spaced in time; repeat the first at the end for a smooth loop.
durationfloatrequiredSeconds for one pass.
beginfloat0.0Seconds into the pass at which the page starts (spreads several marks apart).
discreteboolFalseJump 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)) -> HeroFigure

Turn 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

NameTypeDefaultDescription
dataxarray.DataArrayrequiredA profile over one dimension and sweep, e.g. a potential over x and t.
sweepstr't'The dimension the animation runs over. Default: "t".
durationfloat8.0Seconds for one pass through the frames. Default: 8.
max_framesint24At 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".
widthfloat2.0The line width in pixels. Default: 2.
opacityfloat0.9Between 0 and 1. Default: 0.9.
padfloat0.08Space above and below the profile, as a fraction of its range. Default: 0.08.
tracerboolFalseAdd 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 data has dimensions other than sweep and 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")