# plasma_plots.hero

*module*

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.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L1-L1)

## plasma_plots.hero.TONES

*attribute* · *module attribute*

```python
TONES = ('accent', 'high', 'low', 'muted', 'bg')
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L30-L30)

## plasma_plots.hero.HeroFigure

*class*

```python
class HeroFigure
```

An animated SVG picture for the header of a docs home page.

**Parameters**

- `xlim` (`(float, float)`) (default: `(0.0, 1.0)`) — The data range shown across and up the picture.
- `ylim` (`(float, float)`) (default: `(0.0, 1.0)`) — The data range shown across and up the picture.
- `width` (`int`) (default: `1600`) — The size of the picture in pixels (the theme scales it to the header).
- `height` (`int`) (default: `1600`) — The size of the picture in pixels (the theme scales it to the header).
- `xscale` (`('linear', 'log')`) (default: `"linear"`) — The scale of each axis; non-positive values on a log axis are left out.
- `yscale` (`('linear', 'log')`) (default: `"linear"`) — The scale of each axis; non-positive values on a log axis are left out.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L113-L471)

### plasma_plots.hero.HeroFigure.height

*attribute* · *instance attribute*

```python
height = int(height)
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L151-L151)

### plasma_plots.hero.HeroFigure.marks

*attribute* · *instance attribute*

```python
marks = []
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L152-L152)

### plasma_plots.hero.HeroFigure.width

*attribute* · *instance attribute*

```python
width = int(width)
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L150-L150)

### plasma_plots.hero.HeroFigure.xlim

*attribute* · *instance attribute*

```python
xlim = tuple((float(v) for v in self._scaled(xlim, xscale)))
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L148-L148)

### plasma_plots.hero.HeroFigure.xscale

*attribute* · *instance attribute*

```python
xscale = xscale
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L146-L146)

### plasma_plots.hero.HeroFigure.ylim

*attribute* · *instance attribute*

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

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L149-L149)

### plasma_plots.hero.HeroFigure.yscale

*attribute* · *instance attribute*

```python
yscale = yscale
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L147-L147)

### plasma_plots.hero.HeroFigure.circle

*method*

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

Draw a circle.

**Parameters**

- `x` (`float`) — The centre, in data coordinates.
- `y` (`float`) — The centre, in data coordinates.
- `r` (`float`) — The radius in pixels.
- `tone` (`str`) (default: `'accent'`) — Its colour.
- `fill` (`bool`) (default: `True`) — Filled, or only the outline.
- `opacity` (`float`) (default: `1.0`) — Between 0 and 1.
- `width` (`float`) (default: `1.5`) — The outline width in pixels, when not filled.
- `title` (`str or None`) (default: `None`) — A tooltip shown on hover.

**Returns**

- (`Mark`) — The circle.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L331-L369)

### plasma_plots.hero.HeroFigure.disc

*method*

```python
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**

- `x` (`float`) — The centre, in data coordinates.
- `y` (`float`) — The centre, in data coordinates.
- `radius` (`float`) — The radius in data units (of ``x``).
- `tone` (`str`) (default: `'bg'`) — The fill colour.
- `outline` (`str`) (default: `'accent'`) — The outline colour.
- `width` (`float`) (default: `2.5`) — The outline width in pixels.
- `title` (`str or None`) (default: `None`) — A tooltip shown on hover.

**Returns**

- (`Mark`) — The disc.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L371-L403)

### plasma_plots.hero.HeroFigure.line

*method*

```python
def line(x, y, tone='accent', width=1.5, opacity=1.0, dash=None, title=None)
```

Draw a line through points.

**Parameters**

- `x` (`array_like`) — The points, in data coordinates; non-finite points are left out.
- `y` (`array_like`) — The points, in data coordinates; non-finite points are left out.
- `tone` (`str`) (default: `'accent'`) — Its colour (see the module docstring).
- `width` (`float`) (default: `1.5`) — The line width in pixels.
- `opacity` (`float`) (default: `1.0`) — Between 0 and 1.
- `dash` (`str or None`) (default: `None`) — An SVG dash pattern, e.g. ``"4 6"``.
- `title` (`str or None`) (default: `None`) — A tooltip shown on hover.

**Returns**

- (`Mark`) — The line, to animate or to pass to [`tracer()`][plasma_plots.hero.HeroFigure.tracer].

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L178-L212)

### plasma_plots.hero.HeroFigure.morph

*method*

```python
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**

- `x` (`array_like`) — The common abscissa of the profiles.
- `ys` (`sequence of array_like`) — 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`) — Seconds for one pass.
- `tone` (`str`) (default: `'accent'`) — Its colour.
- `width` (`float`) (default: `1.5`) — The line width in pixels.
- `opacity` (`float`) (default: `1.0`) — Between 0 and 1.
- `begin` (`float`) (default: `0.0`) — Seconds into the pass at which the page starts.
- `title` (`str or None`) (default: `None`) — A tooltip shown on hover.

**Returns**

- (`Mark`) — The line.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L214-L256)

### plasma_plots.hero.HeroFigure.polygon

*method*

```python
def polygon(x, y, tone='accent', opacity=1.0, outline=None, title=None, width=1.5)
```

Fill a closed shape.

**Parameters**

- `x` (`array_like`) — The corners, in data coordinates.
- `y` (`array_like`) — The corners, in data coordinates.
- `tone` (`str`) (default: `'accent'`) — The fill colour.
- `opacity` (`float`) (default: `1.0`) — The fill opacity.
- `outline` (`str or None`) (default: `None`) — The tone of an outline, or ``None`` for none.
- `title` (`str or None`) (default: `None`) — A tooltip shown on hover.
- `width` (`float`) (default: `1.5`) — The outline width in pixels.

**Returns**

- (`Mark`) — The shape.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L258-L291)

### plasma_plots.hero.HeroFigure.rect

*method*

```python
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**

- `x0` (`float`) — Two opposite corners, in data coordinates.
- `y0` (`float`) — Two opposite corners, in data coordinates.
- `x1` (`float`) — Two opposite corners, in data coordinates.
- `y1` (`float`) — Two opposite corners, in data coordinates.
- `tone` (`str`) (default: `'accent'`) — The fill colour.
- `opacity` (`float`) (default: `1.0`) — The fill opacity.
- `outline` (`str or None`) (default: `None`) — The tone of an outline, or ``None`` for none.
- `title` (`str or None`) (default: `None`) — A tooltip shown on hover.
- `width` (`float`) (default: `1.5`) — The outline width in pixels.

**Returns**

- (`Mark`) — The rectangle.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L293-L329)

### plasma_plots.hero.HeroFigure.save

*method*

```python
def save(path)
```

Write the picture to an SVG file.

**Parameters**

- `path` (`str or pathlib.Path`) — The file, usually ``docs/src/assets/hero.svg``.

**Returns**

- (`pathlib.Path`) — The file written.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L455-L471)

### plasma_plots.hero.HeroFigure.to_svg

*method*

```python
def to_svg()
```

Return the picture as SVG text.

**Returns**

- (`str`) — The SVG document.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L441-L453)

### plasma_plots.hero.HeroFigure.tracer

*method*

```python
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**

- `along` (`Mark or array_like`) — A line from [`line()`][plasma_plots.hero.HeroFigure.line], or the ``x`` of a trajectory (with ``y``).
- `duration` (`float`) — Seconds for one pass.
- `offset` (`float`) (default: `0.0`) — Seconds into the pass at which the page starts.
- `r` (`float`) (default: `4.0`) — The radius in pixels.
- `tone` (`str`) (default: `'high'`) — Its colour.
- `y` (`array_like or None`) (default: `None`) — The ``y`` of the trajectory, when ``along`` is its ``x``.

**Returns**

- (`Mark`) — The dot, e.g. to animate its colour or size too.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L405-L439)

## plasma_plots.hero.Mark

*class*

```python
class Mark
```

One element of a [`HeroFigure`][plasma_plots.hero.HeroFigure], returned by its drawing methods.

**Parameters**

- `tag` (`str`) — The SVG element.
- `attrs` (`dict`) — Its attributes.
- `path` (`str or None`) (default: `None`) — The SVG path of a line, which [`HeroFigure.tracer()`][plasma_plots.hero.HeroFigure.tracer] follows.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L44-L110)

### plasma_plots.hero.Mark.attrs

*attribute* · *instance attribute*

```python
attrs = attrs
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L59-L59)

### plasma_plots.hero.Mark.children

*attribute* · *instance attribute*

```python
children = []
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L61-L61)

### plasma_plots.hero.Mark.path

*attribute* · *instance attribute*

```python
path = path
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L60-L60)

### plasma_plots.hero.Mark.tag

*attribute* · *instance attribute*

```python
tag = tag
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L58-L58)

### plasma_plots.hero.Mark.animate

*method*

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

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

**Parameters**

- `attribute` (`str`) — The SVG attribute, e.g. ``"opacity"``, ``"r"`` or ``"cx"``.
- `values` (`sequence`) — The values it passes through, evenly spaced in time; repeat the first at the end for a smooth loop.
- `duration` (`float`) — Seconds for one pass.
- `begin` (`float`) (default: `0.0`) — Seconds into the pass at which the page starts (spreads several marks apart).
- `discrete` (`bool`) (default: `False`) — Jump from value to value instead of blending, for frame-by-frame states.

**Returns**

- (`Mark`) — This mark, to chain calls.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L63-L95)

### plasma_plots.hero.Mark.to_svg

*method*

```python
def to_svg()
```

Return the element as SVG text.

**Returns**

- (`str`) — The element.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L97-L110)

## plasma_plots.hero.from_array

*function*

```python
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`][plasma_plots.styles]).

**Parameters**

- `data` (`xarray.DataArray`) — A profile over one dimension and ``sweep``, e.g. a potential over ``x`` and ``t``.
- `sweep` (`str`) (default: `'t'`) — The dimension the animation runs over. Default: ``"t"``.
- `duration` (`float`) (default: `8.0`) — Seconds for one pass through the frames. Default: 8.
- `max_frames` (`int`) (default: `24`) — At most this many frames, evenly spaced, the first and last included. Default: 24.
- `tone` (`('accent', 'high', 'low', 'muted', 'bg')`) (default: `"accent"`) — The line's colour in the site's palette. Default: ``"accent"``.
- `width` (`float`) (default: `2.0`) — The line width in pixels. Default: 2.
- `opacity` (`float`) (default: `0.9`) — Between 0 and 1. Default: 0.9.
- `pad` (`float`) (default: `0.08`) — Space above and below the profile, as a fraction of its range. Default: 0.08.
- `tracer` (`bool`) (default: `False`) — Add a dot drifting along the line. Default: ``False``.
- `picture` (`(int, int)`) (default: `(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**

```pycon
>>> from plasma_plots.hero import from_array
>>> from_array(phi.isel(y=0)).save("docs/src/assets/hero.svg")
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/hero.py#L474-L560)
