scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/engine/viz/_base.py

@@ -0,0 +1,365 @@
+"""Define the base class of visuals, which log one element or agent group to a Rerun recording."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+
+from typing import Self
+
+import networkx as nx
+import numpy as np
+import numpy.typing as npt
+import rerun as rr
+import rerun.blueprint as rrb
+
+from ...base import BaseConfig
+from ...core.spaces import BaseSpace, NetworkSpace
+from ...core.specs import CompiledAgentsSpec, CompiledElementSpec
+from ...errors import ValidationError
+from ...specs import AgentSnapshotSpec
+from ..problems import BaseProblemSpec, FrameSpec
+
+_UPWARD = np.array([1.0, -1.0])
+_LAYOUT_SEED = 0
+_NODE_SPACING = 40.0
+_POINT_SHARE = 0.02
+_CROWD_SIZE = 10
+_CROWD_EXPONENT = 0.25
+_GRID_RADIUS = 0.4
+_MODULUS = 'modulus'
+_PHASE = 'phase'
+PARTS = ('real', 'imag')
+_SERIES_COLORS = (
+    (230, 159, 0),
+    (86, 180, 233),
+    (0, 158, 115),
+    (240, 228, 66),
+    (0, 114, 178),
+    (213, 94, 0),
+    (204, 121, 167),
+    (170, 170, 170),
+)
+_POINT_FLOOR = 0.25
+_COLOR_SCALE = np.array(
+    [[68, 1, 84], [59, 82, 139], [33, 145, 140], [94, 201, 98], [253, 231, 37]],
+    dtype=float,
+)
+_PALETTE = (
+    np.stack(
+        [
+            np.interp(np.linspace(0.0, 1.0, 256), np.linspace(0.0, 1.0, len(_COLOR_SCALE)), _COLOR_SCALE[:, channel])
+            for channel in range(3)
+        ],
+        axis=-1,
+    )
+    .round()
+    .astype(np.uint8)
+)
+_PHASE_SCALE = np.array(
+    [[230, 90, 80], [225, 190, 70], [90, 190, 110], [70, 160, 210], [150, 100, 200], [230, 90, 80]],
+    dtype=float,
+)
+_PHASE_PALETTE = (
+    np.stack(
+        [
+            np.interp(np.linspace(0.0, 1.0, 256), np.linspace(0.0, 1.0, len(_PHASE_SCALE)), _PHASE_SCALE[:, channel])
+            for channel in range(3)
+        ],
+        axis=-1,
+    )
+    .round()
+    .astype(np.uint8)
+)
+
+
+class BaseVisual(BaseConfig[BaseProblemSpec, FrameSpec]):
+    """Base class of visuals, which log the state of one element or agent group to a Rerun recording.
+
+    A visual follows the common API of the engine. `prepare(problem)` finds the element or agent group of the problem
+    at the entity path `path`, forgets what earlier frames left, and sets the Rerun views that show what the visual
+    logs. `run(frame)` logs the element at one frame to the recording `recording`: a compiled element through the hook
+    `_log`, and agents through the hook `_log_agents` with the snapshot of the frame. Subclasses implement `_log`,
+    `_log_agents`, or both, declare their views with `_views`, and are named by the kind of a `VisualSpec`.
+    `RerunObserver` builds the visual of every element and agent group with their path and its recording.
+
+    Args:
+        path:
+            The entity path of the element or agent group to draw, which also names it in the problem.
+
+        recording:
+            The Rerun recording to log to, or `None` for the active recording of the thread.
+
+    Attributes:
+        element_:
+            The compiled element or agents the visual logs.
+
+        recording_:
+            The Rerun recording the visual logs to, or `None` while no recording is active.
+
+        space_:
+            The space the agents of the problem live in, or `None`.
+
+        layouts_:
+            The positions of the nodes of every network drawn so far, by the id of its graph.
+
+        views_:
+            The Rerun views that show what the visual logs, each with an entity path of the element as origin.
+
+    Examples:
+        >>> from skcomplex.engine.compile import compile_system
+        >>> from skcomplex.engine.viz import ScalarsVisual
+        >>> from skcomplex.models import create
+        >>> problem = compile_system(create('lotka_volterra'))
+        >>> visual = ScalarsVisual(path='prey').check().prepare(problem)
+        >>> visual.element_.path, str(visual.views_[0].origin)
+        ('prey', 'prey')
+    """
+
+    def __init__(self, *, path: str | None = None, recording: rr.RecordingStream | None = None) -> None:
+        self.path = path
+        self.recording = recording
+
+    def _check(self) -> None:
+        """Raise an error unless the path is a string."""
+        if not isinstance(self.path, str):
+            error_msg = f'path = {self.path!r} must be the entity path of the element or agent group to draw.'
+            raise ValidationError(error_msg)
+
+    def _prepare(self, context: BaseProblemSpec | None) -> None:
+        """Find the element at the path, keep the recording and the space of the agents, and set the views.
+
+        Args:
+            context:
+                The compiled problem.
+
+        Raises:
+            ValidationError:
+                No problem is passed, or no element or agent group of the problem has the path of the visual.
+        """
+        if context is None:
+            error_msg = 'A visual prepares on a compiled problem. Pass the problem to `prepare`.'
+            raise ValidationError(error_msg)
+        problem = context
+        elements = {item.path: item for item in (*problem.elements, *problem.agents)}
+        if self.path not in elements:
+            error_msg = (
+                f'No element or agent group of the problem has the path {self.path!r}. The paths are: '
+                f'{", ".join(elements)}.'
+            )
+            raise ValidationError(error_msg)
+        self.element_ = elements[self.path]
+        self.recording_ = self.recording if self.recording is not None else rr.get_data_recording()
+        self.space_: BaseSpace | None = problem.agent_space
+        self.layouts_: dict[int, dict[str, npt.NDArray[np.float64]]] = {}
+        self.views_ = self._views(self.element_, problem)
+
+    def _run(self, inputs: FrameSpec | None) -> None:
+        """Log the element at a frame, or the agents of the frame when the element is an agent group.
+
+        Args:
+            inputs:
+                The frame.
+
+        Raises:
+            ValidationError:
+                No frame is passed, or no Rerun recording is active.
+        """
+        if inputs is None:
+            error_msg = 'A visual runs on a frame. Pass the frame to `run`.'
+            raise ValidationError(error_msg)
+        if self.recording_ is None:
+            error_msg = 'No Rerun recording is active. Pass `recording` or start one with `rerun.init`.'
+            raise ValidationError(error_msg)
+        if isinstance(self.element_, CompiledAgentsSpec):
+            snapshot = inputs.agents.get(self.element_.path)
+            if snapshot is not None:
+                self._log_agents(self.recording_, self.element_.path, snapshot, self.space_)
+            return
+        self._log(self.recording_, self.element_, inputs)
+
+    def prepare(self, problem: BaseProblemSpec | None = None) -> Self:
+        """Prepare the checked visual for the element at its path in a compiled problem.
+
+        Args:
+            problem:
+                The compiled problem.
+
+        Returns:
+            self:
+                The prepared visual, with its views `views_`.
+
+        Raises:
+            ValidationError:
+                No element or agent group of the problem has the path of the visual.
+        """
+        return super().prepare(problem)
+
+    def run(self, frame: FrameSpec | None = None, final: bool = False) -> Self:
+        """Log the element or the agents of the visual at a frame.
+
+        Args:
+            frame:
+                The frame.
+
+            final:
+                Whether this is the last call of the run.
+
+        Returns:
+            self:
+                The visual.
+        """
+        super().run(frame, final)
+        return self
+
+    def _views(self, element: CompiledElementSpec | CompiledAgentsSpec, problem: BaseProblemSpec) -> list[rrb.View]:
+        """Return the Rerun views that show what the visual logs for an element, none by default."""
+        return []
+
+    def _log(self, recording: rr.RecordingStream, element: CompiledElementSpec, frame: FrameSpec) -> None:
+        """Log the state of a compiled element at one frame; a subclass that logs elements implements it."""
+        raise NotImplementedError
+
+    def _log_agents(
+        self,
+        recording: rr.RecordingStream,
+        path: str,
+        snapshot: AgentSnapshotSpec,
+        space: BaseSpace | None,
+    ) -> None:
+        """Log the agents of a group at one frame; log nothing by default."""
+
+    def _colors(
+        self,
+        values: npt.NDArray[np.float64],
+        low: float | None,
+        high: float | None,
+    ) -> npt.NDArray[np.uint8]:
+        """Return the colors of values over the given range, or over the extremes of the values for a missing end."""
+        low = float(values.min()) if low is None else float(low)
+        high = float(values.max()) if high is None else float(high)
+        return self._palette_colors(values, low, high)
+
+    def _layout(self, space: NetworkSpace) -> dict[str, npt.NDArray[np.float64]]:
+        """Return the positions of the nodes of a network, computed once per network."""
+        if id(space.graph) not in self.layouts_:
+            self.layouts_[id(space.graph)] = self._network_layout(space.graph)
+        return self.layouts_[id(space.graph)]
+
+    @staticmethod
+    def _phase_colors(phases: npt.NDArray[np.float64]) -> npt.NDArray[np.uint8]:
+        """Return the colors of phases in `(-pi, pi]` from a cyclic palette, so `-pi` and `pi` share one color."""
+        levels = np.mod(phases + np.pi, 2 * np.pi) * (255.0 / (2 * np.pi))
+        return _PHASE_PALETTE[np.clip(levels, 0.0, 255.0).astype(np.uint8)]
+
+    @staticmethod
+    def _widened(span: tuple[float, float] | None, values: npt.NDArray[np.float64]) -> tuple[float, float]:
+        """Return a color range widened to cover values, starting from their extremes when there is no range yet."""
+        low, high = float(np.min(values)), float(np.max(values))
+        return (low, high) if span is None else (min(span[0], low), max(span[1], high))
+
+    @staticmethod
+    def _colors_of(values: npt.NDArray[np.float64], low: float, high: float) -> npt.NDArray[np.uint8]:
+        """Return one color per value on a scale from blue at `low` to yellow at `high`, bright enough to see on black.
+
+        Args:
+            values:
+                The values.
+
+            low:
+                The value of the darkest color.
+
+            high:
+                The value of the brightest color.
+
+        Returns:
+            colors:
+                One RGB color per value.
+
+        Examples:
+            >>> import numpy as np
+            >>> from skcomplex.engine.viz import BaseVisual
+            >>> BaseVisual._colors_of(np.array([0.0, 1.0]), 0.0, 1.0).shape
+            (2, 3)
+        """
+        fractions = np.clip((values - low) / (high - low), 0.0, 1.0) if high > low else np.zeros_like(values)
+        fractions = _POINT_FLOOR + (1.0 - _POINT_FLOOR) * fractions
+        anchors = np.linspace(0.0, 1.0, len(_COLOR_SCALE))
+        channels = [np.interp(fractions, anchors, _COLOR_SCALE[:, channel]) for channel in range(3)]
+        return np.stack(channels, axis=-1).round().astype(np.uint8)
+
+    @staticmethod
+    def _palette_colors(values: npt.NDArray[np.float64], low: float, high: float) -> npt.NDArray[np.uint8]:
+        """Return the colors of an array of values from a palette of 256 levels, fast enough for large images.
+
+        Args:
+            values:
+                The values.
+
+            low:
+                The value of the darkest color.
+
+            high:
+                The value of the brightest color.
+
+        Returns:
+            colors:
+                One RGB color per value, the darkest one for every value when the range is empty.
+
+        Examples:
+            >>> import numpy as np
+            >>> from skcomplex.engine.viz import BaseVisual
+            >>> BaseVisual._palette_colors(np.array([0.0, 1.0]), 0.0, 1.0).shape
+            (2, 3)
+        """
+        if high <= low:
+            return np.broadcast_to(_PALETTE[0], (*values.shape, 3))
+        levels = np.clip((values - low) * (255.0 / (high - low)), 0.0, 255.0).astype(np.uint8)
+        return _PALETTE[levels]
+
+    @staticmethod
+    def _network_layout(graph: nx.Graph) -> dict[str, npt.NDArray[np.float64]]:
+        """Return fixed positions of the nodes of a network, with neighbours about a spacing apart.
+
+        The positions are the `pos` attributes of the nodes when every node has one, and a seeded spring layout
+        otherwise.
+        """
+        scale = _NODE_SPACING * float(np.sqrt(max(graph.number_of_nodes(), 1))) / 2
+        given = nx.get_node_attributes(graph, 'pos')
+        if given and len(given) == graph.number_of_nodes():
+            layout = nx.rescale_layout_dict(
+                {node: np.asarray(position, dtype=float) for node, position in given.items()},
+            )
+        else:
+            layout = nx.spring_layout(graph, seed=_LAYOUT_SEED)
+        return {str(node): np.asarray(position, dtype=float) * scale for node, position in layout.items()}
+
+    @staticmethod
+    def _radius_of(extent: float, count: int) -> float:
+        """Return a point radius that is a share of the extent of a view, smaller for crowds so they do not overlap."""
+        return _POINT_SHARE * (extent if extent > 0 else 1.0) / max(count / _CROWD_SIZE, 1.0) ** _CROWD_EXPONENT
+
+    @staticmethod
+    def _log_scalars(recording: rr.RecordingStream, path: str, value: object) -> None:
+        """Log the components of a value as scalar series, the real and imaginary parts of a complex value apart.
+
+        Args:
+            recording:
+                The Rerun recording.
+
+            path:
+                The entity path of the series.
+
+            value:
+                A number or an array of numbers, real or complex.
+
+        Examples:
+            >>> import rerun as rr
+            >>> from skcomplex.engine.viz import BaseVisual
+            >>> BaseVisual._log_scalars(rr.RecordingStream('example'), 'value', 1.0 + 2.0j)
+        """
+        values = np.ravel(np.asarray(value))
+        if not np.iscomplexobj(values):
+            recording.log(path, rr.Scalars(values))
+            return
+        for part, components in zip(PARTS, (values.real, values.imag), strict=True):
+            recording.log(f'{path}/{part}', rr.Scalars(components))

skcomplex/engine/viz/_bodies.py

@@ -0,0 +1,334 @@
+"""Draw bodies, the rods that join them, their fading trails, and static outlines from the states of an element."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections import deque
+from collections.abc import Callable, Sequence
+
+import numpy as np
+import numpy.typing as npt
+import rerun as rr
+import rerun.blueprint as rrb
+
+from ...core.specs import CompiledAgentsSpec, CompiledElementSpec
+from ...errors import ValidationError
+from ..problems import BaseProblemSpec, FrameSpec
+from ..types import Colors, Marks, Outline, Positions
+from ._base import _UPWARD, BaseVisual
+from ._points import _TRAIL_LENGTH
+
+_BODY_COLOR = (250, 180, 60)
+_ROD_COLOR = (220, 220, 220)
+_TRAIL_COLOR = (90, 170, 230)
+_OUTLINE_COLOR = (200, 200, 200)
+_MARK_COLOR = (150, 150, 150)
+_FAINTEST = 20
+_ROD_SHARE = 0.25
+_TRAIL_SHARE = 0.1
+MARGIN = 0.1
+PAIR = 2
+_SPACE = 3
+
+
+class BodiesVisual(BaseVisual):
+    """Visual that draws bodies at positions computed from the states of an element, with rods, trails, and outlines.
+
+    The bodies are logged as points under `<path>/bodies`, the rods from the pivot through the bodies in order as one
+    line strip under `<path>/rods`, the trails of the traced bodies as segments under `<path>/trail` that grow more
+    transparent with age, the outlines once as static line strips under `<path>/outline`, and the marks once as static
+    points under `<path>/marks`. Every state is also logged as a time series under `<path>/<state>`. Bodies with three
+    coordinates are drawn in a 3D view. Bodies with two are drawn in a 2D view with the second coordinate negated,
+    since Rerun's 2D views point their vertical axis down, so the views draw it upward.
+
+    Args:
+        positions:
+            A function of the parameters and states of the element by keyword that returns one row `(x, y)` per body,
+            or the names of the two states that hold the position of a single body.
+
+        pivot:
+            The fixed point the rods start from, or `None` to start them at the first body.
+
+        rods:
+            Whether to draw rods through the bodies.
+
+        traced:
+            The indices of the bodies whose trails are drawn, or `None` for every body.
+
+        trail:
+            The number of recent positions in a trail, 0 for no trail, or `None` for the whole path.
+
+        outline:
+            Static polylines, each an array of rows `(x, y)`, such as the walls of a table, or a function of the
+            parameters and states by keyword that returns them from the first frame.
+
+        marks:
+            Static points, such as fixed attracting centres, or a function of the parameters and states by keyword that
+            returns them from the first frame.
+
+        radius:
+            The radius of the bodies, or `None` for a share of the extent of the view.
+
+        path:
+            The entity path of the element or agent group to draw, which also names it in the problem.
+
+        recording:
+            The Rerun recording to log to, or `None` for the active recording of the thread.
+
+    Attributes:
+        history_:
+            The recent positions of the traced bodies, the oldest first.
+
+        drawn_:
+            The entity paths whose outline and marks are logged.
+
+    Examples:
+        >>> from skcomplex.engine.viz import BodiesVisual
+        >>> BodiesVisual(('x', 'y'), trail=None).trail is None
+        True
+    """
+
+    def __init__(
+        self,
+        positions: Positions,
+        *,
+        pivot: Sequence[float] | None = None,
+        rods: bool = False,
+        traced: Sequence[int] | None = None,
+        trail: int | None = _TRAIL_LENGTH,
+        outline: Outline = (),
+        marks: Marks = (),
+        radius: float | None = None,
+        path: str | None = None,
+        recording: rr.RecordingStream | None = None,
+    ) -> None:
+        self.positions = positions
+        self.pivot = pivot
+        self.rods = rods
+        self.traced = traced
+        self.trail = trail
+        self.outline = outline
+        self.marks = marks
+        self.radius = radius
+        self.path = path
+        self.recording = recording
+
+    def _prepare(self, context: BaseProblemSpec | None) -> None:
+        """Keep the element, forget the trail and the static drawings of earlier runs, and set the views."""
+        self.history_: deque[npt.NDArray[np.float64]] = deque(maxlen=self.trail if self.trail else None)
+        self.drawn_: set[str] = set()
+        super()._prepare(context)
+
+    def _bodies(self, values: dict[str, object]) -> npt.NDArray[np.float64]:
+        """Return the positions of the bodies as rows `(x, y)` or `(x, y, z)`."""
+        if callable(self.positions):
+            points = np.asarray(self.positions(**values), dtype=float)
+        else:
+            points = np.array([[float(np.ravel(np.asarray(values[name]))[0]) for name in self.positions]])
+        points = np.atleast_2d(points)
+        if points.ndim != PAIR or points.shape[1] not in {PAIR, _SPACE}:
+            error_msg = (
+                f'The positions of the bodies visual have shape {points.shape}, but they must be pairs of coordinates, '
+                'one row (x, y) per body, or triples, one row (x, y, z) per body.'
+            )
+            raise ValidationError(error_msg)
+        return points
+
+    def _static(
+        self,
+        values: dict[str, object],
+        dimension: int,
+    ) -> tuple[list[npt.NDArray[np.float64]], npt.NDArray[np.float64]]:
+        """Return the outline polylines and the marks, evaluated from the values when they are functions."""
+        outline = self.outline(**values) if callable(self.outline) else self.outline
+        marks = self.marks(**values) if callable(self.marks) else self.marks
+        strips = [np.atleast_2d(np.asarray(item, dtype=float)) for item in outline]
+        points = np.asarray(marks, dtype=float).reshape(-1, dimension)
+        return strips, points
+
+    def _chain(self, bodies: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
+        """Return the points the rods join, from the pivot when there is one."""
+        return bodies if self.pivot is None else np.vstack([np.asarray(self.pivot, dtype=float), bodies])
+
+    def _scale(self, bodies: npt.NDArray[np.float64], values: dict[str, object]) -> float:
+        """Return the extent of the drawing: the outline, the marks, the pivot, and the rods at full length."""
+        chain = self._chain(bodies)
+        strips, marks = self._static(values, bodies.shape[1])
+        points = np.vstack([chain, *strips, marks])
+        extent = float(np.ptp(points, axis=0).max())
+        if self.rods and len(chain) > 1:
+            extent = max(extent, 2 * float(np.linalg.norm(np.diff(chain, axis=0), axis=1).sum()))
+        return extent
+
+    def _log_static(
+        self,
+        recording: rr.RecordingStream,
+        path: str,
+        values: dict[str, object],
+        sizes: tuple[int, float],
+    ) -> None:
+        """Log the outline and the marks once, for bodies of a dimension and a radius."""
+        if path in self.drawn_:
+            return
+        self.drawn_.add(path)
+        dimension, radius = sizes
+        strips, marks = self._static(values, dimension)
+        if strips:
+            recording.log(f'{path}/outline', self._strips(strips, None, _OUTLINE_COLOR), static=True)
+        if len(marks):
+            recording.log(f'{path}/marks', self._points(marks, radius, _MARK_COLOR), static=True)
+
+    def _log_trail(
+        self,
+        recording: rr.RecordingStream,
+        path: str,
+        bodies: npt.NDArray[np.float64],
+        width: float,
+    ) -> None:
+        """Log the fading trails of the traced bodies."""
+        if self.trail == 0:
+            return
+        traced = list(range(len(bodies))) if self.traced is None else list(self.traced)
+        self.history_.append(bodies[traced])
+        if len(self.history_) < PAIR:
+            return
+        history = np.stack(self.history_)
+        segments, colors = self._fading_segments([history[:, column] for column in range(len(traced))])
+        recording.log(f'{path}/trail', self._strips(segments, width, colors))
+
+    def _log(self, recording: rr.RecordingStream, element: CompiledElementSpec, frame: FrameSpec) -> None:
+        """Log the bodies, the rods, the trails, the outline, and the states of an element at one frame.
+
+        Args:
+            recording:
+                The Rerun recording.
+
+            element:
+                The compiled element, with its path and the dotted names of its variables.
+
+            frame:
+                The frame.
+
+        Raises:
+            ValidationError:
+                The positions are not pairs of coordinates.
+        """
+        path = element.path
+        values = self._values_of(element, frame.value)
+        bodies = self._bodies(values)
+        share = BaseVisual._radius_of(self._scale(bodies, values), len(bodies))
+        radius = share if self.radius is None else float(self.radius)
+        self._log_static(recording, path, values, (bodies.shape[1], radius))
+        recording.log(f'{path}/bodies', self._points(bodies, radius, _BODY_COLOR))
+        if self.rods:
+            recording.log(
+                f'{path}/rods',
+                self._strips([self._chain(bodies)], share * _ROD_SHARE, _ROD_COLOR),
+            )
+        self._log_trail(recording, path, bodies, share * _TRAIL_SHARE)
+        for state, name in element.states.items():
+            BaseVisual._log_scalars(recording, f'{path}/{state}', frame.value(name))
+
+    def _views(self, element: CompiledElementSpec | CompiledAgentsSpec, problem: BaseProblemSpec) -> list[rrb.View]:
+        """Return a 2D view of the bodies that covers the drawing, and a time series view of the states.
+
+        Args:
+            element:
+                The compiled element, with its path and the dotted names of its variables.
+
+            problem:
+                The compiled problem the element belongs to.
+
+        Returns:
+            views:
+                A 2D spatial view with the element path as origin, bounded by the rods at full length around the
+                pivot or by the outline, and prepared to the drawing otherwise, and a time series view of the states.
+        """
+        if not isinstance(element, CompiledElementSpec):
+            return []
+
+        def read(name: str) -> object:
+            layout, vector = (
+                (problem.states, problem.initial_state)
+                if problem.states.has(name)
+                else (problem.parameters, problem.initial_parameters)
+            )
+            return layout.read(vector, name)
+
+        values = self._values_of(element, read)
+        bodies = self._bodies(values)
+        path = element.path
+        contents = [f'+ {path}/{state}/**' for state in element.states]
+        series = rrb.TimeSeriesView(origin=path, contents=contents, name=f'{path} states')
+        if bodies.shape[1] == _SPACE:
+            return [rrb.Spatial3DView(origin=path, name=path), series]
+        chain = self._chain(bodies)
+        strips, marks = self._static(values, PAIR)
+        bounds = None
+        if self.rods and self.pivot is not None:
+            half = self._scale(bodies, values) / 2
+            bounds = self._bounds_of(np.vstack([chain[0] - half, chain[0] + half]))
+        elif strips:
+            bounds = self._bounds_of(np.vstack([chain, *strips, marks]))
+        return [rrb.Spatial2DView(origin=path, name=path, visual_bounds=bounds), series]
+
+    @staticmethod
+    def _strips(
+        strips: Sequence[npt.NDArray[np.float64]],
+        radius: float | None,
+        colors: Colors,
+    ) -> rr.LineStrips2D | rr.LineStrips3D:
+        """Return the line strips archetype of the dimension of some polylines."""
+        if strips and strips[0].shape[-1] == _SPACE:
+            return rr.LineStrips3D(list(strips), radii=radius, colors=colors)
+        return rr.LineStrips2D([BodiesVisual._shown(strip) for strip in strips], radii=radius, colors=colors)
+
+    @staticmethod
+    def _values_of(element: CompiledElementSpec, read: Callable[[str], object]) -> dict[str, object]:
+        """Return the parameters and states of an element by their short names, read by dotted name."""
+        names = {**element.parameters, **element.states}
+        return {name: read(dotted) for name, dotted in names.items()}
+
+    @staticmethod
+    def _fading_segments(
+        paths: Sequence[npt.NDArray[np.float64]],
+    ) -> tuple[list[npt.NDArray[np.float64]], list[tuple[int, int, int, int]]]:
+        """Return the segments of paths and their colors, more transparent for older segments."""
+        segments: list[npt.NDArray[np.float64]] = []
+        colors: list[tuple[int, int, int, int]] = []
+        for path in paths:
+            count = len(path) - 1
+            for index in range(count):
+                segments.append(path[index : index + 2])
+                alpha = round(_FAINTEST + (255 - _FAINTEST) * (index + 1) / count)
+                colors.append((*_TRAIL_COLOR, alpha))
+        return segments, colors
+
+    @staticmethod
+    def _bounds_of(points: npt.NDArray[np.float64]) -> rrb.VisualBounds2D | None:
+        """Return 2D view bounds around points with a margin, in logged coordinates, or `None` for one point."""
+        low, high = points.min(axis=0), points.max(axis=0)
+        extent = float((high - low).max())
+        if extent <= 0:
+            return None
+        center, half = (low + high) / 2, (1 + MARGIN) * extent / 2
+        return rrb.VisualBounds2D(
+            x_range=(center[0] - half, center[0] + half),
+            y_range=(-(center[1] + half), -(center[1] - half)),
+        )
+
+    @staticmethod
+    def _shown(points: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
+        """Return points as logged: with the vertical axis up in two dimensions, unchanged in three."""
+        return points * _UPWARD if points.shape[-1] == PAIR else points
+
+    @staticmethod
+    def _points(
+        points: npt.NDArray[np.float64],
+        radius: float,
+        colors: Colors,
+    ) -> rr.Points2D | rr.Points3D:
+        """Return the points archetype of the dimension of some points."""
+        if points.shape[-1] == PAIR:
+            return rr.Points2D(BodiesVisual._shown(points), radii=radius, colors=colors)
+        return rr.Points3D(points, radii=radius, colors=colors)