Skip to content

Visualization

Public API

bvhplot

Visualization module for pybvh.

Provides six main functions, all accepting style= (a :class:Style preset name or instance; "paper" is the default):

  • :func:rest_pose — T-pose / bind pose visualization (matplotlib).
  • :func:frame — static 3D skeleton snapshot (matplotlib, or a shadowed capsule render via backend="vedo").
  • :func:sequence — the motion-paper still: sampled poses in one figure, lightness encoding time.
  • :func:play — interactive playback with camera controls.
  • :func:render — export to video/GIF/HTML.
  • :func:trajectory — 2D top-down root trajectory plot.
Backends

render supports "opencv" (fast, optional dep), "matplotlib" (default fallback), and "vedo" (shadowed capsule skeletons, never auto-selected). When backend is "auto" (the default), OpenCV is used if available.

play supports "k3d" (Jupyter notebooks, optional dep), "vedo" (desktop window, optional dep), "opencv" (notebook inline video), and "matplotlib" (fallback). When backend is "auto", the best available backend for the current environment is selected automatically.

Install optional backends::

pip install pybvh[opencv]       # fast video rendering
pip install pybvh[interactive]  # k3d for Jupyter
pip install pybvh[viewer]       # vedo desktop viewer + renders
pip install pybvh[all-viz]      # all of the above

Style(preset: str = 'paper', **overrides: object) dataclass

Visual styling for every bvhplot function.

Construct from a preset name plus any field overrides::

Style("paper")                    # the defaults
Style("paper", floor=None)        # paper look, no ground plane
Style("dark", bone_width=4.0)

Presets: "paper" (publication-grade default: ground plane, per-chain colors, joint markers, axes off), "debug" (the pre-0.9.0 look: single blue skeleton, full axes and ticks, no floor — for coordinate inspection), "dark" (paper on a near-black ground, for slides and project pages).

A Style keeps which fields its caller set: those passed to the constructor, and to every replace since. Each backend declares the values it draws, and a field set at a value the backend does not draw is refused, as an option it does not read is: a named backend raises ValueError naming the field and any backend that draws it and accepts the rest of the call (for sequence, the other layout), and backend="auto" (render and play) warns, naming the backend chosen, and goes on. frame, rest_pose, sequence and trajectory have no auto, so they always raise. A preset's own values are never refused, so Style("paper") and the other presets draw on every backend, each drawing what it can of them (OpenCV draws paper's "persp" orthographic). Which fields were set does not count for == or repr: two Styles of the same values are the same look. The alternative, refusing a field whose value differs from its preset's, would let Style("paper", projection="persp") pass unrefused on OpenCV.

What each call and backend does with a field its caller set::

              frame       render            play                    matplotlib alone
field         mpl   vedo  mpl   cv    vedo  mpl   cv    k3d   vedo  rest  offs  over  traj
bone_width    yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   n/a
bone_color    yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   n/a
color_mode    yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   n/a
chain_colors  yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   n/a
joint_markers yes   no    yes   yes   no    yes   yes   yes   no    yes   yes   yes   n/a
joint_size    yes   no    yes   yes   no    yes   yes   yes   no    yes   yes   yes   n/a
joint_color   yes   no    yes   yes   no    yes   yes   yes   no    yes   yes   yes   n/a
floor         yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   n/a
floor_alpha   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   n/a
background    yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes
axes          yes   off   yes   yes   off   yes   yes   no    off   yes   yes   yes   no
projection    yes   persp yes   ortho persp yes   ortho persp persp yes   ortho yes   n/a
dpi           yes   n/a   n/a   n/a   n/a   n/a   n/a   n/a   n/a   yes   yes   yes   n/a
supersample   n/a   n/a   n/a   yes   n/a   n/a   yes   n/a   n/a   n/a   n/a   n/a   n/a
shadow        False yes   False False yes   False False False False False False False False
ghost_spacing n/a   n/a   yes   yes   n/a   n/a   n/a   n/a   n/a   n/a   n/a   n/a   n/a

The columns: frame's backends (mpl matplotlib, vedo the shadowed capsule renderer), render's (cv OpenCV), play's (cv the OpenCV notebook video, k3d the notebook widget, vedo the desktop window, at both qualities), then the calls matplotlib alone draws: rest is rest_pose, offs and over are sequence's "offset" and "overlay" layouts, traj is trajectory.

yes: drawn at every value. A value (ortho, persp, off, False): drawn at that value alone; another is refused. no: refused at every value. n/a: accepted at every value without a word, since it names something that drawing does not hold: dpi outside the figures of frame, rest_pose and sequence (the pixels of a video or a vedo picture are its resolution, and k3d and the vedo window make no figure); supersample, which OpenCV alone draws with; ghost_spacing where no ghosts are drawn; and in trajectory, a 2D plot of the root's path, the bone, joint and floor fields and projection. trajectory and matplotlib's play do make a figure, at matplotlib's own dpi, and accept dpi without drawing it all the same. So one Style serves stills and videos, and a Style built for frame serves trajectory.

What the table leaves out: both vedo backends draw each joint as the capsules' sphere, sized and colored by its bones; k3d always shows its grid box; OpenCV draws axes="full", set by the caller or by a preset, as a small axis indicator in a corner of each panel, and with joint_markers=False still draws a small bone-colored dot at each joint, which joins its bones; the vedo renderer casts its shadow on the floor, so under floor=None it draws none; sequence draws the joint fields on its last pose. The k3d widget also shows k3d's own axes helper in a corner, beside its grid box, at either value of axes (k3d's axes_helper, which pybvh leaves at k3d's default).

ghost_spacing is in seconds of clip time, not playback time, between the faded trailing poses that render(ghost=...) draws (see there). dpi is a matplotlib figure's, supersample how many times the resolution OpenCV draws at before scaling down, and shadow the vedo renderer's projected shadow.

bone_color, joint_color, background and the values of chain_colors take any color matplotlib parses (a name, a hex string, an RGB tuple in [0, 1]), the parser every backend reads them with; one it cannot parse raises ValueError when the Style is made, by the constructor or by replace. chain_colors may leave chains out: those are drawn in its "spine" color, or the paper preset's spine color when it has none.

background also colors the grid box of play(backend="k3d"): its lines and labels are the background stepped toward black on a light background and toward white on a dark one (luminance below one half, the split that picks the floor colors), the lines about 10% of the way, the labels about 73%. Those fractions put white exactly on k3d's own defaults, #E6E6E6 lines and #444444 labels, so a white background looks as it always did; on "dark" (#16181D) they give #2D2F33 lines and #C1C1C3 labels. The alternative, one fixed pair for all light and one for all dark backgrounds, differs as soon as the background is not white: fixed lines can vanish into an off-white background, and the fixed dark pair ignores how dark it is. matplotlib's panel titles (labels) take the label color on a dark background; on a light one they keep matplotlib's black rather than the label color (#444444 on white), so the light pictures look as they always did.

color_mode: "auto" uses per-chain colors for a single skeleton and flat per-skeleton palette colors for multi-skeleton comparisons (the GT-vs-generated convention); "chains" forces chain colors everywhere; "skeleton" forces the flat palette; "single" draws one skeleton in bone_color (multi-skeleton still uses the palette — the pre-0.9.0 behavior). The vedo and OpenCV backends draw a skeleton's label, and the vedo viewer its root trail, in that flat color; under chain colors, which give a skeleton no single color, in the spine color rather than the color of whichever bone the file lists first.

joint_size is matplotlib's marker size, an area in points squared, so four times the size draws joints twice as wide. OpenCV draws the joint discs through the scale that turns bone_width into pixels: their radius grows with the square root of joint_size, 4 pixels for the presets' 9.0 on a drawing surface 1080 rows high, which it draws at supersample times the resolution and scales down.

axes and floor are independent, so Style("paper", axes="full") keeps the ground plane — and on the matplotlib backend that plane paints over the axis panes and grid lines, because any floor forces manual draw order (mplot3d's computed z-order would wash the skeleton out under the semi-transparent plane). For clean coordinate-inspection axes use "debug", or add floor=None.

replace(**overrides: object) -> Style

A new Style with the given fields changed. The fields changed join those the caller set before (see :class:Style).

rest_pose(bvh: Bvh | list[Bvh], *, style: Style | str = 'paper', labels: list[str] | None = None, figsize: tuple[float, float] | None = None, show: bool = False, camera: str | tuple[float, float] = 'front', ax: matplotlib.axes.Axes | None = None) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes | list[matplotlib.axes.Axes]]

Plot the rest pose (T-pose / bind pose) of one or more skeletons.

All joint angles are zero and root is at the origin.

Parameters:

Name Type Description Default
bvh Bvh or list[Bvh]

One or more BVH objects. Pass a list for side-by-side comparison.

required
style Style or str

Visual styling: a preset name ("paper", "debug", "dark") or a :class:Style instance for field-level control, e.g. Style("paper", floor=None). Default "paper". Drawn as :func:frame draws it on matplotlib: a field the Style's caller set (in Style(...) or replace(...)) at a value it does not draw (shadow=True) raises ValueError naming it; a preset's own values never do (see :class:Style).

'paper'
labels list[str]

Subplot titles for side-by-side comparison.

None
figsize (float, float)

Figure size in inches.

None
show bool

If True, call plt.show(). Default False.

False
camera str or (float, float)

Camera preset ("front", "side", "top") or (azimuth_deg, elevation_deg) tuple. Default "front".

'front'
ax Axes

Existing 3D axes to draw on. If provided, no new figure is created. Only supported for a single skeleton (raises ValueError when bvh is a list).

None

Returns:

Name Type Description
fig Figure

The figure holding the axes. For an ax inside a SubFigure, the root Figure, which can be saved and shown; the SubFigure is ax.get_figure(), and only it takes the style's background, so the caller's other panels keep their colors.

ax Axes or list[Axes]

Single axes when one skeleton, list when multiple.

frame(bvh: Bvh | list[Bvh], frame: int = 0, *, style: Style | str = 'paper', backend: str = 'matplotlib', coords: npt.NDArray[np.floating] | None = None, centered: str = 'world', labels: list[str] | None = None, figsize: tuple[float, float] | None = None, show: bool | None = None, camera: str | tuple[float, float] = 'front', resolution: tuple[int, int] | None = None, filepath: str | Path | None = None, ax: matplotlib.axes.Axes | None = None, spacing: float | str | None = None, match_size: bool | None = None) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes | list[matplotlib.axes.Axes]] | npt.NDArray[np.uint8]

Plot a static 3D skeleton snapshot.

Parameters:

Name Type Description Default
bvh Bvh or list[Bvh]

One or more BVH objects. Pass a list for side-by-side comparison.

required
frame int

Frame index (default 0). Negative indices count from the end. Ignored when coords is given.

0
style Style or str

Visual styling: a preset name ("paper", "debug", "dark") or a :class:Style instance for field-level control, e.g. Style("paper", floor=None). "paper" (default) draws a ground plane, per-chain bone colors, and joint markers with axes hidden; "debug" reproduces the pre-0.9.0 look (single blue, full axes/ticks, no floor). A field the Style's caller set (in Style(...) or replace(...)) at a value the backend does not draw raises ValueError naming it; a preset's own values never do (see :class:Style).

'paper'
backend str

"matplotlib" (default) returns (fig, ax); it reads figsize, show and ax, and not resolution. "vedo" renders a shadowed 3D capsule skeleton offscreen (headless-safe, requires pybvh[viewer]) and returns an (H, W, 3) uint8 RGB image instead — display it with plt.imshow or save it via filepath. Shadows are hard-edged projections (Style.shadow); it reads resolution, and not figsize, show or ax, and all skeletons share one scene rather than side-by-side panels, spread side by side by spacing. An option given (not None) that the backend does not read raises ValueError naming it, even at its default value (show=False on vedo, resolution=(1100, 1000) on matplotlib), rather than be dropped from the picture. frame has no "auto": the backend is always named, by default "matplotlib". spacing and match_size are accepted by both backends.

'matplotlib'
coords ndarray

Pre-computed spatial coordinates to plot instead of computing forward kinematics from bvh: (N, 3) for one frame, or (F, N, 3) of which only the first frame is used, drawn and framed exactly as coords[0] would be. frame does not pick a row of coords; to draw another row, pass coords[i]. Only valid when bvh is a single Bvh object.

None
centered str

Centering mode: "world" (default), "anchor", "first_ground" or "anchor_ground". Ignored when coords is given.

'world'
labels list[str]

Subplot titles for side-by-side comparison.

None
figsize (float, float)

Figure size in inches; None (default) is 6.5 inches wide per skeleton and 6 tall. Read by matplotlib only (see backend).

None
show bool or None

If True, call plt.show(). None (default) is False. Read by matplotlib only (see backend).

None
camera str or (float, float)

Camera preset ("front", "side", "top") or (azimuth_deg, elevation_deg) tuple. Default "front".

'front'
resolution (int, int) or None

Image size (width, height) in pixels. None (default) is (1100, 1000). Read by vedo only (see backend); matplotlib sizes its figure by figsize and Style.dpi.

None
filepath str or Path

Also write the rendered image here (fig.savefig on the matplotlib backend, a PNG write on vedo).

None
ax Axes

Existing 3D axes to draw on. If provided, no new figure is created. Only supported for a single skeleton (raises ValueError when bvh is a list). The style is applied to the provided axes — the default paper style hides its ticks and panes; pass style="debug" to draw into an axes whose full axis machinery you want to keep. Read by matplotlib only (see backend).

None
spacing (float, 'auto' or None)

Lateral separation between skeletons on the vedo backend, which draws every skeleton in one scene, by the rule :func:play uses (see there for the direction): skeleton k sits k × spacing to the first skeleton's own left. None (default) is "auto", which spaces them by 1.2 × the first skeleton's lateral width when centered is "first_ground", "anchor" or "anchor_ground", and leaves them where their files put them under centered="world"; a float, in scene units, always spaces them. The arrangement is measured on the whole clips (cut to the shortest, as :func:play and :func:render cut them under their default sync="truncate"), not on the frame drawn: the direction and the "auto" width on the first skeleton's clip, and the point match_size scales each skeleton about on its clip's first frame, both read in the still's coordinates. Under centered="world" the still therefore draws every skeleton where the viewer and the video draw it at that frame, for a frame index every clip has and clips played at their own rate (the still draws index frame of each clip, so -1 is each one's own last frame, where the viewer stops at the shortest, or holds it under sync="pad", and resamples under match_fps). Under "first_ground" and "anchor_ground" the still draws every skeleton where the viewer and the video draw it at that frame, as under "world": the frame drawn is that frame's row of the whole clip (:meth:Bvh.node_positions). Under "anchor" the still differs by its floor alone: its floor is the pose's, not the clip's, and a matched skeleton is scaled about that floor. Measured on the frame, the spread would also differ when the first skeleton sweeps wider over the clip (walking sideways, say) than at that frame, or has turned by then. coords draws a single skeleton, which is never spread. Accepted and ignored by matplotlib, which draws each skeleton in its own panel.

None
match_size bool or None

Draw every skeleton as tall as the first, with the factor on its label, as :func:play does (see there for the height matched and its alternative). None (default) is False. Only the vedo backend, which draws every skeleton in one space, is changed; matplotlib draws the same figure either way, since it frames each skeleton in its own panel.

None

Returns:

Name Type Description
fig Figure

The figure holding the axes. For an ax inside a SubFigure, the root Figure, which can be saved and shown; the SubFigure is ax.get_figure(), and only it takes the style's background, so the caller's other panels keep their colors.

ax Axes or list[Axes]

Single axes when one skeleton, list when multiple. With backend="vedo": an (H, W, 3) uint8 RGB image array instead.

sequence(bvh: Bvh, *, n_poses: int = 8, frames: slice | tuple[int, int] | None = None, layout: str = 'offset', style: Style | str = 'paper', centered: str = 'world', camera: str | tuple[float, float] | None = None, trajectory: bool = True, figsize: tuple[float, float] | None = None, show: bool = False, ax: matplotlib.axes.Axes | None = None) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

The motion-paper sequence still: sampled poses in one figure, with lightness encoding time (lighter = earlier, the TEMOS convention).

Parameters:

Name Type Description Default
bvh Bvh

A single BVH object (sequence figures are single-skeleton).

required
n_poses int

Number of equidistantly sampled poses (default 8).

8
frames slice or (start, stop)

Restrict sampling to a frame range. Default: the whole clip.

None
layout str

"offset" (default): poses at their world positions — locomotion spreads them left to right; drawn orthographic from the side with equal-scale non-cubic bounds so the travel fills the frame, whatever the style's projection (a projection="persp" set in the Style raises, see style). "overlay": poses superimposed, each centred on the body anchor (:attr:~pybvh.bvh.Bvh.body_anchor) in the ground plane: each pose is shifted so that the anchor stands above the origin, at the height centered gives it. It stands on the floor the offset layout draws under the same centered, so poses in the air float above it. Seen from the front in the style's projection (perspective unless the style asks otherwise) — the right mode for in-place motion; on locomotion the legs tangle. A clip with no body (body_anchor None) raises ValueError naming the candidates, as centered="anchor" does; the offset layout still draws it.

'offset'
style Style or str

Visual styling preset or instance. Default "paper". The joint fields are drawn on the last pose, the others on every pose. A field the Style's caller set (in Style(...) or replace(...)) at a value the layout does not draw raises ValueError naming it: projection="persp" under "offset", and shadow=True. supersample and ghost_spacing are accepted, and a preset's own values never raise (see :class:Style).

'paper'
centered str

Centering mode for the underlying coords (default "world").

'world'
camera str, (float, float), or None

None (default) picks the layout's natural view: "side" for offset, "front" for overlay. Presets and explicit (azimuth, elevation) tuples override it.

None
trajectory bool

Draw the dashed root trace on the floor (offset layout only). Default True.

True
figsize (float, float)

Figure size; defaults to a wide figure for offset layout.

None
show bool

Call plt.show(). Default False.

False
ax Axes

Existing 3D axes to draw into.

None

Returns:

Name Type Description
fig Figure

The figure holding the axes. For an ax inside a SubFigure, the root Figure, which can be saved and shown; the SubFigure is ax.get_figure(), and only it takes the style's background, so the caller's other panels keep their colors.

ax Axes

render(bvh: Bvh | list[Bvh], filepath: str | Path = Path('./anim.mp4'), *, style: Style | str = 'paper', centered: str = 'world', labels: list[str] | None = None, fps: float | None = None, backend: str = 'auto', camera: str | tuple[float, float] = 'front', turntable_period: float | None = None, resolution: tuple[int, int] = (1920, 1080), sync: str = 'truncate', follow: bool | None = None, ghost: int | None = None, trajectory: bool | None = None, frame_counter: bool | None = None, match_fps: str | None = None, codec: str = 'auto', spacing: float | str | None = None, match_size: bool | None = None) -> Path

Render animation to a video, GIF, or HTML file.

Parameters:

Name Type Description Default
bvh Bvh or list[Bvh]

One or more BVH objects. Pass a list for side-by-side comparison.

required
filepath str or Path

Output file path (default "./anim.mp4"). Format is inferred from the extension: .mp4, .mov, .avi, .gif, .webp, .apng, .html.

Path('./anim.mp4')
style Style or str

Visual styling: a preset name ("paper", "debug", "dark") or a :class:Style instance, e.g. Style("paper", floor=None). Axes visibility follows style.axes (the former show_axis=True is Style("paper", axes="full")). A field the Style's caller set (in Style(...) or replace(...)) at a value the backend does not draw raises ValueError naming it when the backend is named, and warns under "auto"; a preset's own values never do (see :class:Style).

'paper'
centered str

Centering mode: "world" (default), "anchor", "first_ground" or "anchor_ground".

'world'
labels list[str]

Labels for each skeleton when comparing.

None
fps float

Frames per second (fractional rates like 119.88 are fine). None (default) uses the BVH frame rate, which then must be set: a clip whose frame_time is 0 (unset, as on a Bvh built in memory) raises ValueError unless fps is given. A video container is written at this rate as given, on every backend. An animated image (.gif, .webp, .apng) stores each frame's duration in whole milliseconds, 1000 / fps rounded to the nearest (42 ms at 24 fps, so 23.81 fps), and a GIF stores it further truncated to 10 ms. A run of identical frames (a held pose) is stored as one frame shown for the run's summed duration, which a GIF truncates as a whole: 5 frames at 24 fps last 210 ms. An .html page embeds 1000 // fps milliseconds, floored as matplotlib's player computes it.

None
backend str

"auto" (default), "opencv", "matplotlib" or "vedo". Every backend writes a video container through the ffmpeg executable or pybvh[opencv], as codec says, and raises naming both when neither is there. Only matplotlib writes .html, its player page; OpenCV writes every other format. Under "auto", .gif, .webp, .apng and .html always use matplotlib. "vedo" draws shadowed 3D capsule skeletons offscreen (headless-safe, requires pybvh[viewer]) to every format but .html, every skeleton in one scene (see spacing); it is never chosen by "auto", and has no follow, turntable, ghost, trajectory or frame_counter. An option given (not None) that the named backend does not read raises ValueError naming it, even at its default value (frame_counter=False on vedo), rather than be dropped from the file; "auto" chooses OpenCV or matplotlib, which read the same options, so it drops none. Raising only on a value other than the default was the alternative, and the two differ only when the default is passed explicitly; None is the one value that says the caller left the option alone. spacing and match_size are accepted by every backend.

'auto'
camera str or (float, float)

Camera preset ("front", "side", "top"), the special "turntable" (an orbit starting from the front view, by default one full 360-degree orbit over the clip duration; see turntable_period), or an (azimuth_deg, elevation_deg) tuple. Default "front". The vedo backend has no turntable (see backend).

'front'
turntable_period float

Seconds per revolution of camera="turntable"; any other camera raises ValueError. None (default) makes one orbit over the clip, so the speed follows the clip's length (82 degrees per second on the 4.4 s bundled walk). A period sets the speed instead. Shorter than the clip, the camera makes several orbits, the last one possibly partial, while the clip plays once. Longer, the clip loops: it is played again from its first frame until the orbit completes, so the video lasts one period, rounded to the nearest frame, and the last pass of the clip may be cut short. Rounding up instead would always complete the orbit, but a period a hair over a whole number of frames (as a rate read back from a frame time often gives) would then end on a frame showing nearly the first view again, which a looping GIF shows twice in a row. The seconds are seconds of the video at the rate it is written at: fps, or the clip's own rate by default, except that an animated image and an .html page are written at whole milliseconds per frame (see fps). GIF frame durations are further quantized to 10 ms by the format, so a GIF may play slightly faster than written. They are not seconds of the clip: the two differ when fps plays the clip faster or slower than recorded, and the period is the speed the viewer sees. A clip whose frame_time is 0 (unset) is therefore timed by the fps it needs anyway. This differs from ghost spacing and follow smoothing, which are seconds of clip time because they describe the motion. A period of 2 frames of the video or less raises ValueError: at 180 degrees a frame or more the camera looks frozen or turning backwards. The default orbit is not checked, so a clip of one or two frames still renders. At each loop seam the pose jumps from the clip's last frame back to its first, with no blending, while the camera turns on without a break. Ghosts, the root trace and the frame counter restart with the clip, so each pass is drawn as the first was and only the camera differs; carrying them across the seam would draw ghosts of the previous pass where the character no longer is and a trace segment from the clip's end back to its start. The clips of a comparison loop together, after sync has given them one length. follow is ignored, as under any turntable. A number of turns over the clip was the rejected alternative: it cannot slow a short clip down without cutting the orbit short.

None
resolution (int, int)

Output resolution (width, height) in pixels. Default (1920, 1080). The OpenCV backend draws at style.supersample times this and downsamples for anti-aliasing; primitive sizes scale with resolution (1080p is the 1:1 anchor).

(1920, 1080)
sync str

How to handle different frame counts in side-by-side comparison: "truncate" (default) stops at the shortest clip; "pad" continues to the longest clip (shorter clips freeze on their last frame).

'truncate'
follow bool or None

If True, the camera turns with each skeleton's heading, so the view orbits with the character: the first frame is seen from the preset, later frames turned by the rotation of the body's left-to-right axis about the up axis since then. That axis also sways with every stride, so its rotation is smoothed with a centred Gaussian window of 0.5 s standard deviation (reaching ±1.5 s) of clip time, from the clip's own frame_time, or from fps when that is 0 (unset). The camera follows a turn in place, which the direction of travel would not, and follows a turn without the lag a window over past frames only would have, at the cost of starting a little before the character does. The rotation is unwrapped, so a turn past half a turn is followed all the way round, and a frame whose left-to-right axis cannot be measured takes its heading from the measured frames around it (interpolated, not held at the last one, so the camera does not step when measurement resumes); if the first frame cannot be measured, there is no reference and the camera stays fixed. The first and last frames keep their heading, so the net turn is exact, and the smoothing weakens toward them. Only affects preset cameras ("front", "side", "top"); custom (azimuth, elevation) tuples are fixed and ignore follow. None (default) is False, a stable camera. Not read by vedo (see backend).

None
ghost int or None

Number of faded trailing poses drawn behind the live skeleton; None (default) is 0, none. Spacing between ghosts is style.ghost_spacing seconds of clip time, taken from each clip's own frame_time, not playback time from fps; the two differ when fps plays the clip faster or slower than recorded, and clip time keeps the trail the same poses at any playback speed. Ghosts therefore need every clip's frame rate set, even when fps is given. Older ghosts fade further toward the background. Not read by vedo (see backend).

None
trajectory bool or None

Draw the root trace on the floor, growing with playback. None (default) is False. Not read by vedo (see backend).

None
frame_counter bool or None

Stamp a Frame f/F counter in the corner, counting frames of the clip: a looped turntable (turntable_period) counts from 0 again on each pass. Not read by vedo (see backend). None (default) is False — publication output never stamps text; pass True to restore the pre-0.9.0 counter.

None
match_fps str or None

How to handle clips with different frame rates in side-by-side rendering (different by :meth:Bvh.matches_rate's rule, so 29.97 and 30 fps differ). None (default) emits a warning but does not resample. "lowest" resamples all clips to the lowest frame rate. "highest" resamples all clips to the highest frame rate (using SLERP interpolation for added frames); a clip that has the target rate keeps its samples. Resampling starts from each clip's own rate, so a clip whose frame_time is 0 (unset) raises ValueError under "lowest" or "highest", even when fps is given; under None the warning names it.

None
codec str

Video codec for .mp4/.mov/.avi output (invalid for other formats). "auto" (default) writes H.264 through the system ffmpeg executable when one is on PATH, and falls back to OpenCV's MPEG-4 Part 2 (mp4v) otherwise, with a warning — OpenCV builds cannot encode H.264 themselves (patent licensing). The two diverge in where the file plays: H.264 plays everywhere (browsers, VSCode, notebook embeds, GitHub); mp4v only in desktop players such as VLC or mpv. Pass "h264" when you need the guarantee (raises with an install hint if no ffmpeg is found) or "mpeg4" to write MPEG-4 Part 2 without the warning. Either way the file is written at the path given, and the choice is the same on every backend.

'auto'
spacing (float, 'auto' or None)

Lateral separation between skeletons on the vedo backend, which draws every skeleton in one scene, exactly as :func:play spaces them (see there for the direction), so a video shows the arrangement the viewer does: skeleton k sits k × spacing to the first skeleton's own left. None (default) is "auto", which spaces them by 1.2 × the first skeleton's lateral width over the clip when centered is "first_ground", "anchor" or "anchor_ground", and leaves them where their files put them under centered="world"; a float, in scene units, always spaces them. Accepted and ignored by OpenCV and matplotlib, which draw each skeleton in its own panel.

None
match_size bool or None

Draw every skeleton as tall as the first, with the factor on its label, as :func:play does (see there for the height matched and its alternative). None (default) is False. Only the vedo backend, which draws every skeleton in one space, is changed; OpenCV and matplotlib write the same video either way, since they frame each skeleton in its own panel.

None

Returns:

Type Description
Path

The path to the written file.

play(bvh: Bvh | list[Bvh], *, style: Style | str = 'paper', centered: str = 'world', labels: list[str] | None = None, fps: float | None = None, backend: str = 'auto', camera: str | tuple[float, float] = 'front', sync: str = 'truncate', resolution: tuple[int, int] | None = None, quality: str | None = None, frame_counter: bool | None = None, match_fps: str | None = None, spacing: float | str | None = None, match_size: bool | None = None) -> None

Play back motion data.

Auto-detects the best backend for the current environment:

  • Tier 1 (interactive): k3d in Jupyter notebooks, vedo on desktop.
  • Tier 2 (fast fallback): OpenCV renders to an inline video (notebook) or matplotlib animated window (script).
  • Tier 3 (slow fallback): matplotlib jshtml inline (notebook) or animated window (script).

When falling back, warnings indicate which packages to install for a better experience.

Parameters:

Name Type Description Default
bvh Bvh or list[Bvh]

One or more BVH objects. Pass a list for side-by-side comparison.

required
style Style or str

Visual styling: a preset name ("paper", "debug", "dark") or a :class:Style instance. Each player draws it as its column of the table in :class:Style says. dpi, supersample and ghost_spacing are accepted by every player without a word (the OpenCV video draws supersample; play draws no ghosts). No player casts a shadow, so each draws shadow at False alone. Of the other fields, matplotlib's player draws all; the OpenCV notebook video likewise, but with projection at "ortho" alone, as render draws it on OpenCV. k3d draws all but axes, refused at both values since its grid box is always shown, with projection at "persp" alone. The vedo window, at both qualities, refuses the joint fields (joint_markers, joint_size, joint_color), each joint being the capsules' sphere, sized and colored by its bones, and draws axes at "off" alone and projection at "persp" alone. A field the Style's caller set (in Style(...) or replace(...)) that the backend refuses, or at a value it does not draw, raises ValueError naming it when the backend is named, and warns under "auto", as an option the backend does not read does (see backend); a preset's own values never do.

'paper'
centered str

Centering mode: "world" (default), "anchor", "first_ground" or "anchor_ground".

'world'
labels list[str]

Labels for each skeleton when comparing.

None
fps float

Frames per second (fractional rates like 119.88 are fine). None (default) uses the BVH frame rate, capped at 30 for the k3d and matplotlib backends (via frame subsampling) — notebook widgets and matplotlib windows can't keep up with high frame rates. That rate then must be set: a clip whose frame_time is 0 (unset, as on a Bvh built in memory) raises ValueError unless fps is given.

None
backend str

"auto" (default), "k3d", "vedo", "opencv" (the notebook inline-video fallback — nameable so a backend auto-selection picked can be pinned), or "matplotlib". Each reads its own options: quality is read by vedo, resolution and frame_counter by the OpenCV notebook video, spacing and match_size by k3d and vedo, which draw every skeleton in one scene; matplotlib reads none of them, and like every backend accepts spacing and match_size (see below). An option given (not None) that the named backend does not read raises ValueError naming it, even at its default value (frame_counter=False on vedo). Under "auto" it warns instead, naming the option and the backend chosen, and playback goes on: auto's choice depends on the session (notebook, display), which the script does not control, so a raise would fail a correct script on another machine, while a dropped option costs a look, not a file. Either message offers the backends that read the option and accept the rest of the call, the notebook video only in a notebook. spacing and match_size are accepted by every backend.

'auto'
camera str or (float, float)

Camera preset ("front", "side", "top") or (azimuth_deg, elevation_deg) tuple. Default "front". The interactive viewers open with every joint and end site of every frame inside 90% of the picture: the vedo window, between its controls; the k3d widget's height alone, since its width is the notebook's and k3d does not report it. Fitting an assumed width instead would stand k3d's camera further back for a scene wider than that width, whatever the notebook's; as it is, several skeletons spread side by side can reach past the sides of a narrow widget, and the mouse wheel zooms out.

'front'
sync str

How to handle different frame counts in side-by-side comparison: "truncate" (default) stops at the shortest clip; "pad" continues to the longest clip (shorter clips freeze on their last frame).

'truncate'
resolution (int, int) or None

Output resolution (width, height) in pixels of the OpenCV notebook video, the only backend that reads it (see backend). None (default) is (960, 540).

None
quality str or None

Visual quality of the vedo desktop window, the only backend that reads it (see backend): "high" draws shaded capsules, 3D tubes and spheres lit as render(backend="vedo") lights them but without their shadows; "fast" uses flat lines and points for maximum performance. None (default) is "high". The light is a single headlight, at the camera wherever you orbit, so the side of a capsule facing you is the lit one and its edges fall off into shade. The alternative is VTK's light kit (a key, a fill and a back light, also tied to the camera), which lights more evenly but reads less sharply at the edges.

None
frame_counter bool or None

Stamp a Frame f/F counter on the OpenCV notebook video, the only backend that reads it (see backend). None (default) is False; pass True to restore the pre-0.9.0 counter.

None
match_fps str or None

How to handle clips with different frame rates (different by :meth:Bvh.matches_rate's rule, so 29.97 and 30 fps differ). None (default) emits a warning. "lowest" or "highest" resamples all clips to match; a clip that has the target rate keeps its samples. Resampling starts from each clip's own rate, so a clip whose frame_time is 0 (unset) raises ValueError under "lowest" or "highest", even when fps is given; under None the warning names it.

None
spacing (float, 'auto' or None)

Lateral separation between skeletons in single-scene backends (k3d, vedo). None (default) is "auto", which spaces skeletons by 1.2 × the lateral width of the first skeleton over the clip when centered is "first_ground", "anchor" or "anchor_ground"; no spacing is applied when centered="world" (raw world coordinates are honoured). Pass a float (in scene units) to override. Accepted and ignored by multi-panel backends (matplotlib, OpenCV). Skeleton k sits k × spacing to the first skeleton's own left (up × forward at its first frame, forward snapped to the nearest axis), the viewer's right from the "front" camera, so the skeletons read left to right in the order given whatever the rig's up axis or the character's facing. The alternative, a fixed world axis, is the left of a +y-up character facing +z but the right of one facing -z. When the facing cannot be measured (no left/right joint pairs, which warns), forward is the fallback the "front" camera also faces, so the skeletons still read left to right from that camera, whichever side of the body that is.

None
match_size bool or None

Draw every skeleton as tall as the first, in the single-scene backends (k3d, vedo), where clips from files in different units would otherwise differ in size by an order of magnitude. None (default) is False. The first skeleton is drawn as it is, so the order of the clips chooses the scale (rather than the tallest skeleton's or a fixed height). Each other skeleton is scaled about the point on its floor under its root at the first frame, before the lateral spacing, and its label shows the factor ("test2 ×0.13", or "×0.13" alone for a skeleton with no label). Only the drawing changes: the clips are not touched. The height matched is the body's in the rest pose, along the rest pose's own up axis (:attr:Bvh.rest_up), without the nodes beside the body (a prop, a reference root); the alternative, the median over the clip's frames of the pose's height, differs for a clip that does not stand as its rest pose does (crouched, seated or lying), which it would blow up to the first skeleton's standing height. A skeleton whose rest pose has no size to measure is drawn at its own size, with a warning. See :meth:~._scene.Scene.size_matched. Accepted and ignored by multi-panel backends (matplotlib, OpenCV), which frame each skeleton in its own panel.

None

Returns:

Type Description
None

All backends display or open their viewer as a side effect.

trajectory(bvh: Bvh | list[Bvh], *, style: Style | str = 'paper', centered: str = 'world', labels: list[str] | None = None, figsize: tuple[float, float] | None = None, show: bool = False, ax: matplotlib.axes.Axes | None = None, facing_arrows: bool = False, tight: bool = False) -> tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

Plot 2D top-down trajectory of the root joint.

Parameters:

Name Type Description Default
bvh Bvh or list[Bvh]

One or more BVH objects. Pass a list for overlaid comparison.

required
style Style or str

Visual styling: a preset name ("paper", "debug", "dark") or a :class:Style instance. Default "paper". Only its background is drawn: a trajectory is a 2D data plot whose axes, ticks and grid carry the information, so it keeps them whatever style.axes says, and an axes the Style's caller set (in Style(...) or replace(...)) raises ValueError, as does shadow=True. The bone, joint and floor fields and projection name what the plot does not hold, and are accepted at any value, as are supersample, ghost_spacing and dpi (the figure takes matplotlib's own), so a Style built for :func:frame serves here too.

'paper'
centered str

Centering mode: "world" (default), "anchor", "first_ground" or "anchor_ground".

'world'
labels list[str]

Legend labels.

None
figsize (float, float)

Figure size in inches.

None
show bool

If True, call plt.show(). Default False.

False
ax Axes

Existing 2D axes to draw on. If provided, no new figure is created. Works with single or multiple skeletons (overlaid).

None
facing_arrows bool

If True, overlay small arrowheads along each skeleton's path showing the character's facing direction at ~10 evenly-spaced frames. Arrows use the same color as the trajectory line and are sized at ~8 % of the path's span. The direction is :func:~pybvh.analysis.root_trajectory's heading; a frame where it is NaN (unreadable) gets no arrow. Default False.

False
tight bool

If False (default), the axis range matches the full horizontal extent of the skeleton across all joints and frames — the same bounding box bvh.play() uses. Keeps the motion scale honest relative to the character's body so a near-stationary clip doesn't get auto-zoomed into looking like a large walk. If True, axes auto-scale to just the root path — gives maximum detail on the path shape but can exaggerate small motions.

False

Returns:

Name Type Description
fig Figure

The figure holding the axes. For an ax inside a SubFigure, the root Figure, which can be saved and shown; the SubFigure is ax.get_figure(), and only it takes the style's background, so the caller's other panels keep their colors.

ax Axes

Shared Helpers

_scene

The Scene every bvhplot backend consumes.

Pure data: :class:SkeletonView, :class:Scene, the operations that change a Scene, and the helper that aligns frame counts. No plotting library imports and no imports from the pybvh core; signed axes are read with the axis vocabulary of :mod:pybvh.tools, which knows no clip. A Scene is built from a :class:~pybvh.bvh.Bvh in :mod:._from_bvh, or from plain arrays.

GroundFrame

What follows from a signed up axis and a floor height.

Mixed into the two values that hold an up string and a floor_height, :class:SkeletonView and :class:~._viewport.Viewport, so both read the up axis the same way.

up_letter: str property

The up axis letter, 'x', 'y' or 'z', sign dropped.

up_index: int property

The up coordinate's column in a (..., 3) position array.

up_sign: float property

+1.0 for '+y', -1.0 for '-y'.

up_vector: npt.NDArray[np.float64] property

The unit vector pointing up, sign included, shape (3,).

A fresh array on every access.

ground_indices: tuple[int, int] property

The columns of the two ground coordinates, in x, y, z order with the up axis removed ((0, 2) for a y-up rig).

below_floor(distance: float) -> float

The coordinate distance visually below the floor plane.

"Below" follows the signed up axis: for a '-y'-up rig the ground sits at the coordinate MAXIMUM, so below means +y. Backends use this for z-fighting nudges and shadow offsets so negative-up rigs get their floor under the feet, not overhead.

SkeletonView(coords: npt.NDArray[np.float64], bones: list[tuple[int, int]], label: str | None, azimuth: float, elevation: float, up: str, floor_height: float, frame_time: float, node_names: list[str], rest_coords: npt.NDArray[np.float64], rest_up: str | None, lr_pairs: npt.NDArray[np.intp], initial_forward: str, bone_chains: list[str], anchor_heading: npt.NDArray[np.float64] | None, coords_in_rest_unit: bool = False, body: npt.NDArray[np.bool_] | None = None) dataclass

Bases: GroundFrame

Everything a backend needs to draw one skeleton in its own panel.

A dumb data container — no plotting imports, no behavior beyond field access. The camera angles are per-view because side-by-side comparisons of skeletons with different up or forward axes need each panel oriented independently. A view holds no bounding box: what a picture frames is computed from the coords when the picture is made (:func:~._viewport.make_viewport), so no operation on a Scene can leave a box behind that no longer fits.

The view is complete: every fact a backend needs about the skeleton (its timing, names, rest pose, left/right pairing, orientation and chain classification) is a field, so a view built from plain arrays with no :class:Bvh behind it draws exactly like one made by :func:make_scene. Frame-indexed fields (coords, anchor_heading) always share their first axis.

A view is checked when it is built: the shapes and lengths of its fields must agree with each other, every bone and L/R index must be an integer that names a node, and the two axes must be signed axis strings. An inconsistent view raises ValueError here, at construction, rather than drawing something wrong later. Only consistency is checked, never plausibility: a floor above the head or a rest pose unrelated to the coords is the builder's business.

frame_time follows :attr:Bvh.frame_time: seconds per frame, with 0 meaning "unset", which a rest pose or a still of a Bvh built in memory legitimately carries. The static entry points never read it; the animated ones check it before drawing and raise when they need a rate that is unset. Only a negative or non-finite value is rejected here.

Conventions the fields follow:

  • anchor_heading is [sin(theta), cos(theta)] of :func:~pybvh.analysis.root_trajectory's heading angle theta = atan2(f[b], f[a]), where f is the rest-pose forward rotated by the body anchor's world rotation and (a, b) are the two ground axes in natural x, y, z order with the up axis removed ((x, z) for a y-up rig). It is a ground-plane angle, not a signed rotation about the up vector: for +y up, a positive rotation about +y decreases it. Orientation-derived and continuous; NaN on a row whose heading cannot be read (the anchor's forward stands along up), which draws no facing arrow; None when the coords are not the clip's.
  • initial_forward is a different quantity: the snapped facing of the view's first shown row, coords[0], not of clip frame 0 (a view of a clip's frames 40 onward holds the facing at frame 40). It is read by the facing chain :meth:~pybvh.bvh.Bvh.forward_at reads (the L/R joint geometry; where it is degenerate, the anchor's heading at the row's clip frame when the coords are the clip's, then the house default) and snapped to the dominant signed axis, the value the "front" camera preset is derived from. Follow-camera math never reads it; it reads coords, lr_pairs, up_vector and frame_time directly.
  • up is the one statement of which way is up: a signed axis string ('+y', '-z'), the form :attr:Bvh.world_up and initial_forward use. The letter (up_letter), the column (up_index), the sign (up_sign) and the unit vector (up_vector) are derived from it, so they cannot disagree. The alternative, storing the vector, would admit an off-axis or unnormalised up that no backend can draw: matplotlib's vertical axis and the floor plane are axis-aligned.
  • rest_up is the up axis of rest_coords (:attr:Bvh.rest_up), in the same signed form, or None when it is not known. It usually equals up; a file that authors its rest pose in one convention and animates it in another has two, and :attr:body_size needs the rest pose's. An unknown rest axis is not replaced by up, which on such a file would name the rest pose's depth; :attr:body_size measures without it instead.
  • body marks the nodes of the clip's body, the part of the skeleton that :attr:Bvh.body_anchor names and that rest up and the feet are looked for in. They are the nodes :attr:body_size measures. None measures every node, as for a clip with no body. A prop or a reference root beside the body would otherwise add its distance from the body to the body's height.
  • coords_in_rest_unit states that coords were posed from rest_coords by forward kinematics, so they share its unit and :attr:coords_per_rest_unit is exactly 1. :func:make_scene states it for the clip's own frames. It defaults to False, the safe side: the ratio is then measured, which is right for coordinates a caller supplies in any unit and a few ulps off for posed ones.
  • lr_pairs are joint pairs only, in node index space, the pairs the facing geometry averages; end-site pairs are deliberately excluded so follow azimuths match the Bvh path bit for bit.
  • Arrays are read-only and borrowed. A view stores a read-only NumPy view of each array it is given (coords, rest_coords, lr_pairs, anchor_heading), so writing into one through the view raises. That matters because storage is shared: no array is copied at construction, and a Scene operation may share storage with its source (subsampled shares coords and anchor_heading; offset allocates new coords and shares the heading; looped copies both), so a write through one Scene would change another. The alternative, copying, would double the memory of every clip drawn. The array the caller passed in keeps its own flags; writing into it afterwards still changes what the view shows, which is the caller's to avoid. A copied or unpickled view is protected like the original. The lists (bones, node_names, bone_chains) are not protected: treat them as immutable. Change a Scene through its operations.

initial_forward_vector: npt.NDArray[np.float64] property

The unit vector of initial_forward, shape (3,).

A fresh array on every access.

body_size: float property

The body's height, the length what is drawn on it is sized from.

The extent of the body (body) in the rest pose, along the rest pose's own up axis (rest_up), in the unit of coords. It is a property of the skeleton, not of the motion: it does not change with the distance the clip travels, with the frames shown, or with the other skeletons of a Scene, so a still and the whole clip draw a body at the same proportions, and each skeleton of a Scene gets its own. It is always positive: a body that has no height to measure is measured another way, and :attr:body_size_measure says which of these it got, first that applies:

Each measure reads the nodes of body alone.

  • "rest height": the rest pose's extent along rest_up.
  • "rest extent": the rest pose's widest extent along any axis, when rest_up is None (the rest pose's up axis could not be inferred) or the rest pose has no extent along it. For a standing rest pose it is the height, or the arm span of a T-pose whose arms reach wider than it stands tall (bvh_test3: 71.4 across the arms, 62.6 tall). The alternative, the extent along the animation's up, is wrong exactly where the two axes differ: there it measures the rest pose's depth (bvh_test3: 10.7).
  • "clip extent": the widest extent of the box coords sweeps over the clip, when the rest pose has no extent at all (one node, or nodes that all coincide) or no ratio to put it in the unit of coords (below). There is no body to measure, so it grows with the distance the clip travels.
  • "default": DEFAULT_BODY_SIZE, one unit of coords, when every coordinate of the clip is at one point. Nothing was measured; the size is a stand-in so that nothing drawn on the body has size zero.

Conventions:

  • The alternative to the rest height is the median over the clip's frames of the pose's extent along up. It follows what the clip does, and the two differ when the clip does not stand: a crouched, seated or lying clip reads smaller than its rest pose, and a rest pose with raised arms reads taller than the character stands. (Taken as the pose's widest extent rather than along up, the alternative also differs for a T-pose whose arm span exceeds its height.) The rest pose is used because what is drawn on a body should not thin when the body crouches, and because it needs no pass over the motion.
  • The extent is taken along rest_up, not along up. The two agree on most files; they differ when a file authors its rest pose in one convention and animates it in another (Bvh.rest_up against Bvh.world_up), and there the rest pose's extent along up is its depth, not its height.
  • The unit is the coords': the rest pose's measures are scaled by :attr:coords_per_rest_unit. A view without that ratio does not use its rest pose (see there).

body_size_measure: BodySizeMeasure property

Which measure :attr:body_size took: "rest height", "rest extent", "clip extent" or "default" (see there). Only "default" is not measured from the view.

coords_per_rest_unit: float | None property

How many units of coords one unit of rest_coords is: the factor that puts a rest-pose length in the unit of what is drawn, or None when there is no ratio to measure.

For a view whose coords_in_rest_unit is set (coords posed from the rest pose, as the clip's frames are) it is exactly 1, stated rather than measured. Measured, it comes out a few ulps from 1, differently for each clip, since each reads it off its own first frame; two clips of one skeleton would then have two body sizes, and be drawn at two sizes when they are matched.

Otherwise it is measured: the median, over the bones of positive rest length, of each bone's length in coordinate row 0 over its rest length. It differs from 1 for coordinates a caller supplies in another unit (metres against the file's centimetres). Any bone would do; the median keeps one odd bone from deciding it, and bones of zero rest length (end sites or helper joints placed on their parent) are left out because they have no ratio. Taken over every bone instead, as a ratio of median lengths, it is 0 over 0 on a rig where most bones have zero length.

None for a view with no bone of positive rest length, and for one whose coordinate row 0 collapses most of those bones to zero length (a median ratio of 0 is no unit). Its rest pose is then not converted at all, and what would measure it measures coords instead (as :attr:body_size does): the alternative, taking the rest pose to share the unit of coords, draws a body a hundred times too thin or too thick when a caller's coordinates are in centimetres against a rest pose in metres, or the reverse.

Scene(views: list[SkeletonView], loop_length: int | None = None) dataclass

A prepared visualization: the single input every backend consumes.

Multi-panel backends (matplotlib, OpenCV) iterate :attr:views and make one viewport per view; single-scene backends (k3d, vedo) make one viewport of all the views, whose camera is the first view's.

A Scene has at least one view, and all its views hold the same number of frames: backends step every view with one frame counter, the first view's. Building a Scene that breaks either raises ValueError; align the clips first (:func:align_frame_counts). Frame times may differ between views, see :attr:frame_time.

loop_length is None for a Scene that plays its clips once. A Scene made by :meth:looped plays them again from the first frame every loop_length frames; each such run is a pass (:meth:pass_start), and what trails the live pose (ghosts, the root trace, the frame counter) belongs to its pass.

labels: list[str | None] | None property

Per-view labels, or None when no view is labelled.

frame_time: float property

Seconds per frame, from the first view.

The animated entry points offer to resample the clips to a common rate before the Scene is built (match_fps), but the default only warns on a mismatch, so views can disagree. The first view's timing then drives playback and the others play at its rate. The static entry points never read it.

pass_length: int property

Frames in one pass of the clip: loop_length for a looped Scene, every frame otherwise.

pass_start(frame: int) -> int

The first frame of the pass that shows frame.

0 for every frame of a Scene that is not looped. Backends draw a frame's ghosts and root trace from this frame on, and count frames from it, so every pass is drawn as the first was.

looped(num_frames: int) -> Scene

The clip played again from its first frame until the Scene holds num_frames frames, as a new Scene.

Every frame-indexed field is repeated (a copy, not a view: the passes are laid end to end), the last pass is cut short where num_frames ends, and nothing is blended at the seam: the pose jumps from the clip's last frame back to its first, as a looping video does. Timing, floor and camera angles are kept. A Scene that is already looped plays its original pass again, so looping twice is looping once to the longer length.

subsampled(step: int) -> Scene

Every step-th frame of every view, as a new Scene.

Slices coords and every other frame-indexed field (anchor_heading) with [::step] and scales frame_time by step, so the kept frames stay at their original moments in time; up to step - 1 trailing frames are dropped, so the span from the first to the last kept sample can shorten by that many original intervals and the last frame is not necessarily kept. The floor is kept as is: it describes the whole clip (the canonical floor is a clip-wide estimate, the coords floor the full clip's extreme), and a plane that sits where the full clip's ground was is the honest one for a preview of it. The alternative, recomputing from the kept frames, would move the ground between the full and the subsampled view of one clip.

A looped Scene cannot be subsampled: its every step-th frame is not one clip played again, since its passes would no longer share a length. Subsample first, then loop.

offset(offsets: list[npt.NDArray[np.float64]]) -> Scene

Translate each view by its own (3,) vector, as a new Scene.

Moves coords, and floor_height by the offset's component along the view's up axis, so the plane stays under the feet. Orientation, heading, timing and the loop are translation-invariant and are kept.

scaled(factors: list[float], *, measured_on: Scene | None = None) -> Scene

Draw each view at its own factor times its size, as a new Scene.

A view is scaled about its ground point: the root's position at coordinate row 0 of the matching view of measured_on (this Scene by default), moved along the up axis onto this view's floor_height. That point stays where it is, so the skeleton keeps its place on the ground, its floor stays where it was and its feet stay on it, whichever way up points (for a '-y' rig the floor is the coordinate maximum, and the point is there). The alternatives move the body off its floor: about the origin, a skeleton standing away from it slides along the ground and rises or sinks with it; about the root, the feet leave the floor.

measured_on must hold as many views, in this Scene's coordinates. A still of one frame passes the Scene of its whole clip, so each skeleton is scaled about its root at the clip's first frame, as the clip is; where the two share coordinates (no centering), the still then stands where the clip's frame puts it, and scaled about its root at the frame drawn, it would stand off by that root's travel since the first frame times one minus the factor. The height is always this view's own floor, not measured_on's, so the scaled skeleton stays on the floor it is drawn on: the two differ for a still whose floor is its pose's rather than the clip's.

coords and rest_coords are scaled together, so the view stays one skeleton in one unit: its :attr:~SkeletonView.coords_per_rest_unit is kept, and its :attr:~SkeletonView.body_size, with everything drawn from it, follows the factor. What else is drawn from coords (the root trail, the picture's framing) is computed when the picture is made, and the heading, orientation, timing and loop are scale-invariant.

A view drawn at another size says so: its label is followed by the factor to two significant digits, "test2 ×0.14", or is the factor alone, "×0.14", for a view with no label. A view whose factor is exactly 1 is kept as it is, label included.

size_matched(*, measured_on: Scene | None = None) -> Scene

Draw every view as tall as the first one, as a new Scene.

For the backends that draw several skeletons in one space (k3d, vedo), where clips from files in different units (centimetres, inches, metres) would otherwise differ in size by an order of magnitude. Each view is :meth:scaled by the first view's :attr:~SkeletonView.body_size over its own, about its own ground point, and its label shows the factor. The clips are not touched; only what is drawn changes. measured_on places each view's ground point, as in :meth:scaled.

Conventions:

  • The reference is the first view, the one the caller put first, which is drawn as it is. The alternatives are the tallest view, the median view, or a fixed height such as 1.8 m. They differ when the first view is not the tallest (or the median): the tallest would enlarge every other skeleton, the first included, and the median would move with every view added. A fixed height would need each file's unit, which a BVH file does not state. With the first as reference, the caller chooses the scale by the order of the clips, and the first view's label never carries a factor.
  • The height matched is :attr:~SkeletonView.body_size: the rest pose's extent along the rest pose's own up axis (rest_up, :attr:Bvh.rest_up), in the unit of coords. The alternative is the median over the clip's frames of the pose's extent along up. The two differ when the clip does not stand as its rest pose does. Matched on the median, a crouched, seated or lying clip would be blown up until it crouches as tall as the first skeleton stands; matched on the rest pose, it would stand as tall as the first and crouches below it. The other way round, a rest pose that raises its arms is matched on its hands, where the median would match the head. The rest pose is used because it is the skeleton's, whatever the clip does, and it is the length every size drawn on the body is taken from, so matched bodies are drawn with matching bones.
  • Where rest_up is unknown the body size is the rest pose's widest extent (body_size_measure == "rest extent"), and it is matched as it is: for a T-pose whose arms span wider than it stands tall, that skeleton is drawn shorter than the first, by its height over its arm span.
  • A body size that is not measured from the rest pose (body_size_measure "clip extent", which grows with the distance the clip travels, or "default", nothing measured) is not a body's size, and no factor is taken from it: such a view is drawn at its own size and its label shows no factor, and when the first view has one, no view is matched. Either way a UserWarning names the view. The alternative, taking the factor from the stand-in, would draw a skeleton at a size nobody measured and label it as matched.
  • A view whose factor is exactly 1 is left as it is, with no factor on its label. Two clips of one skeleton get exactly 1 when their coords state their unit (coords_in_rest_unit, as :func:make_scene states for a clip's frames): both body sizes are then the one rest pose's height. No tolerance is applied to the factor: a factor a few ulps from 1 comes from coords whose unit was measured, and is shown as ×1.

spread(spacing: float | str, *, measured_on: Scene | None = None) -> Scene

Offset the views laterally so skeletons sharing one 3-D scene do not overlap.

For the single-scene backends (k3d, vedo); multi-panel backends draw each view in its own axes and never need it. View k moves by k × spacing toward the first skeleton's own left: up × forward of the first view, with forward its initial_forward (the facing of its first shown frame, snapped to an axis). Seen from the "front" camera that is the viewer's right, so the skeletons read left to right in the order given, on every rig. The alternative it replaces, a fixed world axis (the positive axis that is neither up nor forward), flips with the rig: +x is the left of a +y-up character facing +z, but the right of the same character facing -z or turned -y-up. In a Scene made from a Bvh, a facing that cannot be measured on the first frame (no left/right joint pairs, or pairs lying along up) leaves initial_forward at the facing chain's fallback (:func:~pybvh.analysis.facing_frame), which the "front" camera also faces, so the next skeleton still lands on the front camera's right, whichever side of the body that is.

"auto" spaces by 1.2 × the first view's extent along that direction (at least 0.1 scene units); a float is used directly, in scene units. Whether to spread at all is the caller's policy (play respects raw world coordinates under "auto").

The direction and the "auto" extent are read from measured_on, this Scene by default, which must hold as many views, in this Scene's coordinates. A still of one frame passes the Scene of its whole clip, so it is spread exactly as the clip is at that frame: by the extent over the clip, toward the left the first skeleton faces at the clip's first frame. Measured on the still itself, the two would differ whenever the first skeleton sweeps wider over the clip than in the pose drawn, or has turned by then.

align_frame_counts(coords_list: list[npt.NDArray[np.float64]], pad: bool = False) -> list[npt.NDArray[np.float64]]

Align all coordinate arrays to the same frame count.

When comparing multiple skeletons with different frame counts, arrays are either truncated to the minimum or padded to the maximum (by repeating the last frame).

Parameters:

Name Type Description Default
coords_list list of ndarray

Each element has shape (F, N, 3).

required
pad bool

If False (default), truncate to the shortest clip. If True, pad shorter clips by repeating their last frame so all clips match the longest.

False

Returns:

Name Type Description
coords_list list of ndarray

Arrays all with the same frame count.

_from_bvh

From a :class:~pybvh.bvh.Bvh to a Scene.

Input normalization, Scene construction, skeleton topology, camera presets and bone chain classification. Together with the router, which is handed the user's Bvh and prepares it (resampling, rest pose, world-up checks), this is the Bvh-facing layer of bvhplot. The router imports this module; nothing else in the package does.

as_clip_list(bvh: Bvh | list[Bvh]) -> list[Bvh]

The clips an entry point was given, as a non-empty list.

Every bvhplot entry point that accepts one Bvh or a list calls this first, so an empty list is rejected with one message before any other work.

Raises:

Type Description
ValueError

If bvh is an empty list.

normalize_input(bvh: Bvh | list[Bvh], frames: int | npt.NDArray[np.floating] | None, centered: str) -> tuple[list[Bvh], list[npt.NDArray[np.float64]]]

Normalize single/list Bvh + frame spec into parallel lists.

Parameters:

Name Type Description Default
bvh Bvh or list[Bvh]

One or more BVH objects to visualize.

required
frames int, ndarray, or None
  • None: all frames (spatial coords for entire motion).
  • int: single frame index (NumPy semantics — negative counts from the end).
  • 2-D array (N, 3): single frame of spatial coordinates (only valid when bvh is a single Bvh).
  • 3-D array (F, N, 3): pre-computed spatial coordinates, of which one frame is kept, the first, as an int keeps one (only valid when bvh is a single Bvh).
required
centered str

Centering mode passed to bvh.node_positions().

required

Returns:

Name Type Description
bvh_list list[Bvh]

Always a list (length >= 1).

coords_list list[ndarray]

Parallel list of spatial coordinates, each (F, N, 3).

make_scene(bvh_list: list[Bvh], coords_list: list[npt.NDArray[np.float64]], camera: str | tuple[float, float], labels: list[str] | None, *, canonical_floor: bool = True, clip_frames: int | slice | None = None) -> Scene

Assemble a :class:Scene from parallel per-skeleton data.

The Bvh -> Scene adapter. Together with :func:normalize_input, which turns a Bvh into coords, it is where bvhplot reads a :class:Bvh; backends only ever see the Scene. Computes, per view, the topology, camera angles, floor height and every skeleton fact the backends draw from (timing, node names, rest pose, L/R pairs, orientation, chain classification, the body anchor's heading), so the views are complete once this returns.

clip_frames says which frames of the clip the coords are, so the clip-derived, frame-indexed facts can be aligned to them: the body anchor's heading (the [sin, cos] columns of :func:~pybvh.analysis.root_trajectory), and the anchor's heading at the first shown row, which initial_forward falls back to where that row's left/right joints give no facing. An int names the single clip frame the coords hold (NumPy semantics, negative from the end) and requires one-row coords; a slice selects the frames, and the result is truncated or last-row padded to the coords' frame count, mirroring :func:align_frame_counts, so slice(None) is the whole clip. The default None means the coords are not the clip's (a rest pose, a caller-supplied array, a transformed copy) and no clip frame corresponds to them; anchor_heading is then None rather than a number that would be wrong, and initial_forward reads no heading. The default is the safe one on purpose: a caller has to vouch for the coords' provenance to get frame-indexed clip facts attached to them. Coords vouched for as the clip's frames were posed from the skeleton's rest pose, so the view also states that they share its unit (:attr:~._scene.SkeletonView.coords_in_rest_unit); for the default the unit ratio is measured from the coords.

Floor convention: with canonical_floor=True the floor is the cached :attr:Bvh.floor_height — the robust 2nd percentile over all nodes, end sites included, so the plane sits under the whole skeleton rather than at a joint centre. Valid for world-frame coords, and for centered="first_ground" and "anchor_ground" coords because those modes are ground-plane-only (heights stay in world units). An outlier-low frame can therefore dip a node slightly below the drawn plane; the alternative (the true minimum) would let a single glitched frame sink the plane for the whole clip. With canonical_floor=False (coords under centered="anchor", rest-pose or caller-supplied coords) the floor is the minimum up-coordinate of the coords in use — the clip-wide estimate does not apply to coords in another frame of reference, and the true minimum is the safe choice for a pose whose own extent is all we have.

This is the scene ground, not the reference foot_contacts measures clearance against; see :attr:Bvh.floor_height.

get_skeleton_lines(bvh: Bvh) -> list[tuple[int, int]]

Precompute (parent_node_idx, child_node_idx) pairs for bone drawing.

Computed once per skeleton, reused every frame by all backends.

Parameters:

Name Type Description Default
bvh Bvh

The BVH object containing the skeleton hierarchy.

required

Returns:

Name Type Description
lines list of (int, int)

Each tuple is (parent_index, child_index) into the flat nodes list (i.e. the same indexing used by spatial coordinates).

Notes

The parent-first view of :attr:Bvh.node_edges, so the drawn bones are the same topology forward kinematics posed — including on skeletons whose node names repeat, where a name-keyed lookup would draw one bone twice and omit another.

get_camera_angles(bvh: Bvh, ref_frame: npt.NDArray[np.float64], camera: str | tuple[float, float] = 'front') -> tuple[float, float, str]

Resolve a camera specification to (azimuth, elevation, up_letter).

Thin view of :func:_camera_angles_and_forward, which also returns the forward axis the azimuth was derived from.

Parameters:

Name Type Description Default
bvh Bvh

The BVH object (used for axis detection).

required
ref_frame ndarray of shape (N, 3)

A reference frame of spatial coordinates for axis heuristics.

required
camera str or (float, float)
  • "front" — auto-detected front view (default).
  • "side" — 90 degrees from front.
  • "top" — bird's-eye view looking down the up axis.
  • (azimuth_deg, elevation_deg) — custom angles.
'front'

Returns:

Name Type Description
azimuth float

Azimuth angle in degrees.

elevation float

Elevation angle in degrees.

up_letter str

Single character: 'x', 'y', or 'z'.

get_bone_chains(bvh: Bvh) -> dict[str, list[int]]

Classify each drawn bone into a kinematic chain for coloring.

Chains are "spine" (every unpaired node — torso, neck, head), "l_arm" / "r_arm", and "l_leg" / "r_leg". Sides come from :attr:Bvh.node_lr_pairs (the same left/right detection that powers mirror); legs are told apart from arms by walking the topology from the auto-detected feet (paired ancestors of a foot, the foot itself, and everything below it), so no joint-name heuristics beyond what those two detectors already encode.

Returns:

Name Type Description
chains dict[str, list[int]]

Maps chain name to indices into :func:get_skeleton_lines's bone list. Every bone index appears in exactly one chain.

Notes

A limb is the maximal run of paired nodes: a bone belongs to a limb chain only when both its endpoints are paired, so the junction bones connecting the torso to a limb (an unpaired parent like Spine3 or Hips to a paired child like a shoulder or hip joint) stay in "spine" — limbs start at the shoulder ball and hip socket, the TEMOS/MDM capsule-figure convention. The alternative (a bone belongs to its child node's chain, coloring those connectors as limbs) diverges visibly on rigs whose shoulder joints sit on the spine axis: the connector is then a vertical segment lying on the spine, and limb-coloring it paints a stray arm-colored "vertebra" onto the torso.

Fallbacks: with no left/right pairs (node_lr_pairs is None) every bone lands in "spine" — the caller should draw a single color. With pairs but no detectable feet, every paired-to-paired bone is classified as an arm: side coloring survives, the arm/leg shade distinction does not. A clip with no body (:attr:Bvh.body_anchor None) has no feet to look for, so the same.

_viewport

The geometry of the picture: what is framed, where the ground plane lies, where the camera stands and how it moves.

One :class:Viewport is computed from the view or views a picture shows, and every backend translates its numbers into its toolkit's calls. Pure numpy. No plotting library imports and nothing from the pybvh core: signed axes are read with the axis vocabulary of :mod:pybvh.tools, and the per-frame leftward the follow camera turns with comes from :mod:pybvh._orientation, two modules that know no clip.

Camera

Bases: NamedTuple

Where a perspective camera stands, what it looks at, which way is up on screen. World coordinates, each of shape (3,).

Turntable(period: float) dataclass

A turntable camera that turns at a set speed: one revolution every period frames, whatever the number of frames.

The schedule a backend hands to :func:make_viewport when the caller chose the speed; the plain "turntable" is the one orbit over the frames, Turntable(period=num_frames). The period is a number of frames of the picture, not necessarily whole, positive and finite; a period shorter than the frames makes several orbits.

Viewport(lo: npt.NDArray[np.float64], hi: npt.NDArray[np.float64], center: npt.NDArray[np.float64], half_span: float, up: str, floor_height: float, azimuth: float, elevation: float, azimuths: npt.NDArray[np.float64] | None, projection: str, shown_coords: tuple[npt.NDArray[np.float64], ...]) dataclass

Bases: GroundFrame

The geometry of one picture, in world coordinates.

Built by :func:make_viewport from one view (a panel of a multi-panel figure) or from several (the one scene k3d and vedo draw everything into). A backend reads the numbers and translates them; it computes no box, floor extent or eye position of its own.

Two boxes, on purpose:

  • center and half_span are the cube around every coordinate shown, 5% margin included. It is the scale of the picture: the floor's extent is a multiple of half_span, and perspective cameras look at center (from a distance fitted to the coordinates shown, :meth:eye_distance). It is not the scale of what is drawn on a body, since it grows with the distance a clip travels: the vedo capsules and k3d's lines and joints are sized from each skeleton's :attr:~._scene.SkeletonView.body_size.
  • lo and hi are the framing box, what the axes or the orthographic projection are fitted to. For framing="still" it is that same cube (shifted along up when a floor must sit inside it); for framing="clip" it is the box the motion sweeps, see :func:framing_bounds.

The floor is one plane for the whole viewport: at the ground-side extreme of the views' floor heights (the coordinate minimum for a positive up axis, the maximum for a negative one), exactly there. A toolkit that needs the plane nudged to avoid z-fighting applies its own epsilon through :meth:below_floor.

azimuths is the camera's schedule: one azimuth in degrees per frame, or None when the camera does not move. A schedule that turns out constant, whatever the reason (a follow camera on a rig with no left/right pairs, or on a character that never turns; a facing that is degenerate at frame 0; a turntable over a single frame), is stored as None, so rotating means what it says and such a clip is framed as a fixed camera frames it.

rotating: bool property

Whether the camera's azimuth changes during the clip.

floor_reach: float property

How far the ground plane reaches from its centre in each ground direction: FLOOR_EXTENT half-spans.

view_half: tuple[float, float] cached property

Half extents of the framing box on screen, in view units: the largest over every frame of the camera's schedule.

azimuth_at(frame: int = 0) -> float

The camera azimuth at frame, in degrees.

view_matrix(frame: int = 0) -> npt.NDArray[np.float64]

World-to-view rotation at frame, see :func:build_view_matrix.

camera(frame: int = 0, *, view_angle: float, aspect: float | None = None, band: tuple[float, float] = (0.0, 1.0)) -> Camera

Where a perspective camera stands at frame.

The camera looks at the cube's centre along the viewing direction, from :meth:eye_distance for the toolkit's vertical view_angle (degrees), the picture's aspect ratio (width over height; None fits the vertical direction alone) and the band of its height the figure may take.

eye_distance(view_angle: float, aspect: float | None = None, band: tuple[float, float] = (0.0, 1.0)) -> float

How far the perspective camera stands from the cube's centre.

The smallest distance at which every coordinate shown projects inside FIT_FRACTION of the picture, in whichever direction is tighter, as the orthographic projection fits its box; where only a band of the picture's height is free for the figure, inside FIT_FRACTION of that band, about its middle. Solved exactly: a coordinate at x across, y up and z towards the eye from the target (view units) needs the eye at least z + max(y / (t b), |x| / (f t aspect)) away, where t is the tangent of half the view angle, f the fraction, and b how far the fitted band reaches from the picture's middle on the coordinate's side (up for y > 0, down, negative, for y < 0; f either way for the whole height). The distance is the largest of these.

Conventions, and the alternatives they were chosen over:

  • Only the distance is fitted. The camera keeps its target, the cube's centre, and its viewing direction. The alternative, aiming at the middle of the coordinates as they project, would let the eye come closer wherever the figure sits off the cube's centre on screen (a still whose floor shifts it, seen from above), but the target would then depend on the view angle, and every backend aims at the same point today.
  • The target stays at the picture's middle, whatever the band. Around a band whose middle is off the picture's, the figure reaches the band's nearer edge first and leaves room unused at the farther one. The alternative, shifting the projection so that the band's middle is the picture's middle (VTK's window centre), would use that room, but a camera would then need that shift besides its eye, target and up, and every toolkit a way to apply it. The two differ by as much as the band's middle is off the picture's: the vedo viewer's band is nearly centred, and its figure is about 1.5% smaller than the shifted projection would draw it.
  • The coordinates shown are fitted, every node of every view on every frame, not the corners of the framing cube. The cube's depth is mostly empty, and fitting its corners stands the camera much further back (about 6.6 half-spans at a 30 degree view angle, where a standing figure's coordinates need 4.1) and shrinks every picture. What is drawn around a node, a capsule's radius or a joint's sphere, is not fitted, and the floor plane is not either.
  • Fitted to the view angle. The alternative, a fixed multiple of the half-span (4 until v0.10.0), fits one view angle only: at 4 half-spans a still fills the height of VTK's 30 degree picture and about half of k3d's 60 degree one.
  • One distance for a moving camera, the largest over the schedule (each frame's coordinates seen from that frame's direction), so the figure does not zoom in and out as a turntable or follow camera turns.
  • The whole cube stays in front of the eye: the eye stands at least as far as the cube's corner nearest it, so every coordinate, inside the cube by its margin, is in front of the eye. This binds on a figure flat across the fitted direction, whose coordinates land near the middle of the picture however close the eye comes (a line of joints seen end on, or a figure lying in the plane of the viewing direction and the screen's horizontal, fitted vertically alone): the fit alone would bring the eye onto, or past, the nearest of them. It also binds, fitted vertically alone, on a scene much wider than it is tall, whose cube its width sets (skeletons side by side in k3d): the fit alone would bring the eye inside the cube, and the scene further past the sides of a picture whose width is not fitted. None then reaches the fraction. The alternative, a small fixed gap in front of the nearest coordinate, would need a length of its own and leave the eye among the joints.

Parameters:

Name Type Description Default
view_angle float

The toolkit's vertical view angle, in degrees: 30 for VTK, 60 for k3d.

required
aspect float

The picture's width over its height. None fits the vertical direction alone, for a toolkit that does not know its picture's width.

None
band tuple of float

The part of the picture's height the figure may take, as (bottom, top) fractions of the height from its bottom edge: what a toolkit's controls leave free. The default is the whole height.

(0.0, 1.0)

Returns:

Type Description
float

The distance from the cube's centre to the eye.

Raises:

Type Description
ValueError

If band is not inside the picture's height, or the part of it the coordinates are fitted into does not hold the picture's middle, where the camera aims.

enclosing_cube() -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]

The smallest cube around the framing box, centred on it, as (lo, hi). For axes that must stay cubic around a box that is not: the overlaid sequence figure.

grounded_box() -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]

The cube with its ground-side face moved to just under the ground, as (lo, hi).

For a toolkit that draws the box itself, as k3d draws its grid. The face under the skeleton sits FLOOR_INSET half-spans below the ground plane, so whatever lies on the ground (the floor, the root trail) is seen lying on the box's bottom face. Left at the cube's own bottom, that face can be far below the ground (a clip that travels has a cube much taller than the body), and a trail drawn at the ground then floats inside the box and reads as displaced sideways from an oblique angle. Only the extent along up changes, so the box is no longer a cube. A ground that lies beyond the cube's far face (above the head, for a positive up axis) still gives a valid box, from that far face to the ground.

floor_quad(clip_to_box: bool = False) -> npt.NDArray[np.float64]

The four corners of the ground plane, shape (4, 3).

A square of half side :attr:floor_reach around the cube's centre (which is also the framing box's centre on the ground), at floor_height. With clip_to_box the rectangle of the framing box on the ground instead: a wide orthographic still turns a full-extent plane into a backdrop wall.

Corners run (lo, lo), (hi, lo), (hi, hi), (lo, hi) over the two :attr:ground_indices, so opposite corners are 0 and 2.

ground_path(points: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]

points dropped onto the ground plane, as a new array.

For the root trace and the viewers' trails: the path a joint takes, drawn where the floor is.

project(points: npt.NDArray[np.float64], resolution: tuple[int, int], frame: int = 0) -> npt.NDArray[np.int32]

Orthographic pixel coordinates of points at frame.

The framing box's centre lands in the middle of the panel, and one scale holds for the whole clip: the box is fitted at the widest it gets over the camera's schedule. The alternative, fitting it frame by frame, rescales the drawing continuously under a rotating camera and reads as the character zooming in and out.

check_schedule(schedule: str | Turntable) -> None

Raise ValueError unless schedule is a camera schedule :func:make_viewport takes.

make_viewport(views: Sequence[SkeletonView], *, framing: str = 'still', schedule: str | Turntable = 'fixed', include_floor: bool = True, projection: str = 'persp', fps: float | None = None) -> Viewport

Compute the :class:Viewport of a picture of views.

Parameters:

Name Type Description Default
views sequence of SkeletonView

What the picture shows: one view for a panel, all of a Scene's views for a single-scene backend. The camera angles, the up axis and the follow schedule are the first view's.

required
framing ('still', 'clip')

"still" frames the cube around the coordinates. "clip" frames the box the motion sweeps (:func:framing_bounds), so a clip that travels far sideways does not shrink the character to fit a cube.

"still"
schedule ('fixed', 'turntable', 'follow')

How the camera moves. "turntable" orbits once over the clip, a :class:Turntable once every period frames (:func:turntable_azimuths); "follow" tracks the character's rotation (:func:compute_follow_azimuths).

"fixed"
include_floor bool

Whether the framing box must contain the ground plane. A still whose floor lies beyond its cube's ground-side face, or closer to that face than FLOOR_INSET half-spans, shifts the cube along up, as far as it takes, until the plane sits that far inside; the cube keeps its size. It never shifts the other way: a floor beyond the far face (above the head) stays outside a still. A clip extends its box to the plane on whichever side the plane lies.

True
projection ('persp', 'ortho')

The projection the picture is drawn with, stated by the adapter that draws it: matplotlib passes what the style asks for (sequence's offset layout is always orthographic), OpenCV always "ortho", k3d and vedo always "persp". The viewport does not choose it; it records it, so that viewport.projection describes the picture.

"persp"
fps float

The rate the picture plays at. Read only by "follow", to time a view whose frame_time is 0 (unset); see :func:compute_follow_azimuths.

None

Returns:

Type Description
Viewport

panel_viewports(views: Sequence[SkeletonView], **options: object) -> list[Viewport]

One :class:Viewport per view, for the multi-panel backends.

Each panel is framed, floored and scheduled from its own view; options are :func:make_viewport's.

compute_unified_limits(coords_list: list[npt.NDArray[np.float64]]) -> tuple[npt.NDArray[np.float64], float]

Compute a cubic bounding box encompassing all skeletons and frames.

The half-span is the larger of the per-frame body size and the trajectory extent from center. This ensures stationary skeletons fill the frame while walking skeletons never clip.

Parameters:

Name Type Description Default
coords_list list of ndarray

Each element has shape (F, N, 3) or (N, 3).

required

Returns:

Name Type Description
center ndarray of shape (3,)

Center of the bounding box in world coordinates.

half_span float

Half the side length of the cubic bounding box.

framing_bounds(view: SkeletonView, rotating: bool = False) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]

The world-space box animated output frames to, as (lo, hi).

Animated backends frame the motion, not a cube around it: each axis gets the extent the clip actually uses, so a clip that travels two body-lengths sideways no longer forces that same extent vertically, shrinking the character to fit. The floor plane is included along the up axis so the ground never falls outside the box. Scale stays equal on all three axes — this crops empty space, it never stretches the skeleton.

We frame to the box the whole clip sweeps, not to each frame's own box. The alternative — re-framing per frame — keeps the character largest at every instant but makes the world drift and breathe behind it, which reads as camera shake and destroys any sense of travel; it is also what makes a still and a video of the same clip disagree (:func:frame frames one pose, so its box is tighter).

With rotating (turntable or follow), the two ground axes are squared off to the motion's circumscribed radius, so the framing is invariant to azimuth. Without it, an orbiting camera would sweep a long clip's travel axis from across-screen to into-screen and the character would appear to zoom in and out.

Parameters:

Name Type Description Default
view SkeletonView

The panel's view; coords supplies the motion, up_index and floor_height place the ground.

required
rotating bool

Whether the camera azimuth changes during the clip.

False

Returns:

Type Description
lo, hi : ndarray of shape (3,)

Opposite corners of the framing box, margin included.

box_corners(lo: npt.NDArray[np.float64], hi: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]

The eight corners of an axis-aligned box, shape (8, 3).

turntable_azimuths(base_azim: float, num_frames: int, period: float) -> npt.NDArray[np.float64]

Per-frame azimuths of a camera turning one revolution every period frames, for num_frames frames.

The trivial case of follow: a constant-rate azimuth ramp starting at the base camera angle, in degrees, not wrapped (a period shorter than the frames climbs past 360). With a period of num_frames, frame num_frames would be the first view again, so a looped playback does not hold the identical view for two frames.

compute_follow_azimuths(view: SkeletonView, base_azim: float, *, fps: float | None = None) -> npt.NDArray[np.float64]

Per-frame camera azimuths that follow the character's heading.

The camera turns with the character's body: frame 0 is seen from base_azim, and every later frame from base_azim plus the heading change since frame 0, measured around up_vector from the rotation of the body's left-to-right axis (the mean of the view's L/R joint pairs, projected onto the ground).

That axis also swings with the gait: pelvis, shoulders, knees, feet and hands turn back and forth with every stride, by about 30 degrees peak to peak on the bundled CMU walk. The camera follows the heading, not that sway, so the per-frame heading change is smoothed before it is used. The conventions of that smoothing:

  • Heading, not direction of travel. The body's axis is what is smoothed. The alternative, the direction the body anchor travels, sways less with the gait, but it has no direction on a clip that turns in place and points sideways on a side step.
  • A centred Gaussian window, of standard deviation FOLLOW_SIGMA = 0.5 s, so that ±1 standard deviation spans one second, about one stride of a walk, cut off at FOLLOW_TRUNCATE = 3 standard deviations (±1.5 s). Centred, it follows a steady turn exactly and a real turn without delay, and the camera starts to turn a little before the character does. The alternative, a causal window over past frames only, never looks ahead but lags behind every turn.
  • Seconds of clip time, from the view's frame_time, so the camera takes the same path at any playback rate. A view whose frame_time is 0 (unset) has no clip time; its window is then sized from fps, the rate the picture plays at, which is the rate such a clip is drawn at. On such a clip, and only there, the camera's path depends on fps. The alternative, refusing the clip as ghost spacing does, would take the follow camera away from a clip render(fps=...) otherwise draws, for a window whose exact width matters far less than a ghost's spacing.
  • Unwrapped: each frame's change is taken within ±180 degrees of the previous valid frame's, so a character that turns more than half a turn is followed all the way round rather than snapped back by a full turn.
  • Valid frames only. A frame whose left-to-right axis is degenerate (parallel to up) is not measured: its heading change is linearly interpolated between the valid frames around it, or held at the last valid frame's after it. The alternative, holding the last measurement across a gap too, agrees on a character that is not turning; on one that turns through the gap it freezes the camera and then makes it catch up in a step when measurement resumes, where interpolation turns it steadily through the gap. When frame 0 itself is not measured the camera stays fixed (see Returns).
  • The ends are held: the heading change is extended past each end of the clip by point reflection about the end frame (the padtype="odd" extension of scipy.signal.filtfilt), so the first and last frames keep their heading (the last frame's measured one, or the last valid frame's when it cannot be measured), the net turn over the clip is kept exactly, and a steady turn is followed to the last frame. The alternative, averaging only the frames that exist, would move both ends toward the middle of the clip and flatten a turn at the ends. Near an end, the smoothing therefore weakens: on the walk, the last frame is caught mid-stride, and the camera turns about 13 degrees toward it over the last half second.

A clip shorter than the window is smoothed with the window cut to the clip's length on each side.

Parameters:

Name Type Description Default
view SkeletonView

The skeleton's coords for the whole clip plus its L/R pairs, signed up vector and frame_time.

required
base_azim float

The frame-0 azimuth in degrees (from :func:get_camera_angles).

required
fps float

The rate the picture plays at. Read only when the view's frame_time is 0 (unset), to size the window.

None

Returns:

Name Type Description
azimuths ndarray of shape (F,)

Azimuth in degrees for every frame, unwrapped, so it may leave [-180, 180). Frame 0 is the reference every change is measured from, so when frame 0 is degenerate, or the rig has no L/R pairs, there is no reference and the whole sequence stays at base_azim, later valid frames included: a fixed camera, not a partial follow.

Raises:

Type Description
ValueError

If the view's frame_time is 0 and no fps is given, unless frame 0's left-to-right axis cannot be measured (the camera is then fixed, and needs no rate).

build_view_matrix(azimuth_deg: float, elevation_deg: float, up_letter: str) -> npt.NDArray[np.float64]

Build a 3x3 rotation that maps world coordinates to view coordinates.

Uses the same look-at camera math as matplotlib's view_init so that both backends produce identical views for the same (azimuth, elevation, up_letter) parameters.

View coordinate convention: x = right on screen, y = up on screen, z = out of screen (toward viewer).

Parameters:

Name Type Description Default
azimuth_deg float

Azimuth rotation in degrees.

required
elevation_deg float

Elevation rotation in degrees.

required
up_letter str

'x', 'y', or 'z'.

required

Returns:

Name Type Description
view_matrix ndarray of shape (3, 3)

ortho_project(points: npt.NDArray[np.float64], view_matrix: npt.NDArray[np.float64], center: npt.NDArray[np.float64], view_half: tuple[float, float], resolution: tuple[int, int]) -> npt.NDArray[np.int32]

Orthographic projection from 3D world to 2D pixel coordinates.

The kernel under :meth:Viewport.project, which supplies the centre and the half extents. One scale serves both screen directions, so a world unit covers the same number of pixels across and up: the scale is the smaller of the two that would fit view_half into FIT_FRACTION of the panel's width and of its height.

Parameters:

Name Type Description Default
points ndarray of shape (N, 3)

World-space positions.

required
view_matrix ndarray of shape (3, 3)

From :func:build_view_matrix.

required
center ndarray of shape (3,)

The world point that lands in the middle of the panel.

required
view_half (float, float)

Half extents, across and up the screen in view units, of what must fit. A direction with no extent (below 1e-8) sets no constraint; with none in either the scale is 1 pixel per unit.

required
resolution (width, height)

Panel size in pixels.

required

Returns:

Name Type Description
pixels ndarray of shape (N, 2)

Integer pixel coordinates (x, y), y growing downward.

_style

The look of a figure: :class:Style, its presets, the palettes and the ghost, trace and frame-counter conventions every backend shares.

Pure data, no plotting library imports but one: the Style checks its color fields with matplotlib's color parser, imported where it checks them. Turning colors into a backend's values, which needs that parser too, lives in :mod:._colors.

Style(preset: str = 'paper', **overrides: object) dataclass

Visual styling for every bvhplot function.

Construct from a preset name plus any field overrides::

Style("paper")                    # the defaults
Style("paper", floor=None)        # paper look, no ground plane
Style("dark", bone_width=4.0)

Presets: "paper" (publication-grade default: ground plane, per-chain colors, joint markers, axes off), "debug" (the pre-0.9.0 look: single blue skeleton, full axes and ticks, no floor — for coordinate inspection), "dark" (paper on a near-black ground, for slides and project pages).

A Style keeps which fields its caller set: those passed to the constructor, and to every replace since. Each backend declares the values it draws, and a field set at a value the backend does not draw is refused, as an option it does not read is: a named backend raises ValueError naming the field and any backend that draws it and accepts the rest of the call (for sequence, the other layout), and backend="auto" (render and play) warns, naming the backend chosen, and goes on. frame, rest_pose, sequence and trajectory have no auto, so they always raise. A preset's own values are never refused, so Style("paper") and the other presets draw on every backend, each drawing what it can of them (OpenCV draws paper's "persp" orthographic). Which fields were set does not count for == or repr: two Styles of the same values are the same look. The alternative, refusing a field whose value differs from its preset's, would let Style("paper", projection="persp") pass unrefused on OpenCV.

What each call and backend does with a field its caller set::

              frame       render            play                    matplotlib alone
field         mpl   vedo  mpl   cv    vedo  mpl   cv    k3d   vedo  rest  offs  over  traj
bone_width    yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   n/a
bone_color    yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   n/a
color_mode    yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   n/a
chain_colors  yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   n/a
joint_markers yes   no    yes   yes   no    yes   yes   yes   no    yes   yes   yes   n/a
joint_size    yes   no    yes   yes   no    yes   yes   yes   no    yes   yes   yes   n/a
joint_color   yes   no    yes   yes   no    yes   yes   yes   no    yes   yes   yes   n/a
floor         yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   n/a
floor_alpha   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   n/a
background    yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes   yes
axes          yes   off   yes   yes   off   yes   yes   no    off   yes   yes   yes   no
projection    yes   persp yes   ortho persp yes   ortho persp persp yes   ortho yes   n/a
dpi           yes   n/a   n/a   n/a   n/a   n/a   n/a   n/a   n/a   yes   yes   yes   n/a
supersample   n/a   n/a   n/a   yes   n/a   n/a   yes   n/a   n/a   n/a   n/a   n/a   n/a
shadow        False yes   False False yes   False False False False False False False False
ghost_spacing n/a   n/a   yes   yes   n/a   n/a   n/a   n/a   n/a   n/a   n/a   n/a   n/a

The columns: frame's backends (mpl matplotlib, vedo the shadowed capsule renderer), render's (cv OpenCV), play's (cv the OpenCV notebook video, k3d the notebook widget, vedo the desktop window, at both qualities), then the calls matplotlib alone draws: rest is rest_pose, offs and over are sequence's "offset" and "overlay" layouts, traj is trajectory.

yes: drawn at every value. A value (ortho, persp, off, False): drawn at that value alone; another is refused. no: refused at every value. n/a: accepted at every value without a word, since it names something that drawing does not hold: dpi outside the figures of frame, rest_pose and sequence (the pixels of a video or a vedo picture are its resolution, and k3d and the vedo window make no figure); supersample, which OpenCV alone draws with; ghost_spacing where no ghosts are drawn; and in trajectory, a 2D plot of the root's path, the bone, joint and floor fields and projection. trajectory and matplotlib's play do make a figure, at matplotlib's own dpi, and accept dpi without drawing it all the same. So one Style serves stills and videos, and a Style built for frame serves trajectory.

What the table leaves out: both vedo backends draw each joint as the capsules' sphere, sized and colored by its bones; k3d always shows its grid box; OpenCV draws axes="full", set by the caller or by a preset, as a small axis indicator in a corner of each panel, and with joint_markers=False still draws a small bone-colored dot at each joint, which joins its bones; the vedo renderer casts its shadow on the floor, so under floor=None it draws none; sequence draws the joint fields on its last pose. The k3d widget also shows k3d's own axes helper in a corner, beside its grid box, at either value of axes (k3d's axes_helper, which pybvh leaves at k3d's default).

ghost_spacing is in seconds of clip time, not playback time, between the faded trailing poses that render(ghost=...) draws (see there). dpi is a matplotlib figure's, supersample how many times the resolution OpenCV draws at before scaling down, and shadow the vedo renderer's projected shadow.

bone_color, joint_color, background and the values of chain_colors take any color matplotlib parses (a name, a hex string, an RGB tuple in [0, 1]), the parser every backend reads them with; one it cannot parse raises ValueError when the Style is made, by the constructor or by replace. chain_colors may leave chains out: those are drawn in its "spine" color, or the paper preset's spine color when it has none.

background also colors the grid box of play(backend="k3d"): its lines and labels are the background stepped toward black on a light background and toward white on a dark one (luminance below one half, the split that picks the floor colors), the lines about 10% of the way, the labels about 73%. Those fractions put white exactly on k3d's own defaults, #E6E6E6 lines and #444444 labels, so a white background looks as it always did; on "dark" (#16181D) they give #2D2F33 lines and #C1C1C3 labels. The alternative, one fixed pair for all light and one for all dark backgrounds, differs as soon as the background is not white: fixed lines can vanish into an off-white background, and the fixed dark pair ignores how dark it is. matplotlib's panel titles (labels) take the label color on a dark background; on a light one they keep matplotlib's black rather than the label color (#444444 on white), so the light pictures look as they always did.

color_mode: "auto" uses per-chain colors for a single skeleton and flat per-skeleton palette colors for multi-skeleton comparisons (the GT-vs-generated convention); "chains" forces chain colors everywhere; "skeleton" forces the flat palette; "single" draws one skeleton in bone_color (multi-skeleton still uses the palette — the pre-0.9.0 behavior). The vedo and OpenCV backends draw a skeleton's label, and the vedo viewer its root trail, in that flat color; under chain colors, which give a skeleton no single color, in the spine color rather than the color of whichever bone the file lists first.

joint_size is matplotlib's marker size, an area in points squared, so four times the size draws joints twice as wide. OpenCV draws the joint discs through the scale that turns bone_width into pixels: their radius grows with the square root of joint_size, 4 pixels for the presets' 9.0 on a drawing surface 1080 rows high, which it draws at supersample times the resolution and scales down.

axes and floor are independent, so Style("paper", axes="full") keeps the ground plane — and on the matplotlib backend that plane paints over the axis panes and grid lines, because any floor forces manual draw order (mplot3d's computed z-order would wash the skeleton out under the semi-transparent plane). For clean coordinate-inspection axes use "debug", or add floor=None.

replace(**overrides: object) -> Style

A new Style with the given fields changed. The fields changed join those the caller set before (see :class:Style).

DrawnStyle(fields: Collection[str], **values: Collection[object]) dataclass

The Style values one backend draws for one call, declared beside its entry function: each field drawn whole, and of each field of :data:STYLE_VALUES it does not draw whole, the values it draws.

A value drawn is drawn as the Style says, or in a reduced form of the backend's own (OpenCV's axis indicator for axes="full"). OpenCV draws orthographic whatever the projection asked, so it declares projection with "ortho" only, and the vedo renderer, which sizes and colors every joint by its bones, declares none of the joint fields. A field absent draws none of its values.

draws(field: str, value: object) -> bool

Whether field at value is drawn as the Style asks, in full or in a reduced form of the backend's own.

derive(*, drop: Collection[str] = (), add: Collection[str] = ()) -> DrawnStyle

This declaration, for a call drawn as this one is but for the fields drop, of which it draws no value, and add, which it draws whole: render()'s from frame()'s. The values declared of every other field are kept, so a value declared on this one is never lost from a declaration derived from it.

bone_width_scale(bone_width: float) -> float

The factor a style's bone_width scales bones drawn in scene units by: 1 at ANCHOR_BONE_WIDTH, the paper default.

joint_size_scale(joint_size: float) -> float

The factor a style's joint_size scales a joint's diameter by: 1 at ANCHOR_JOINT_SIZE.

joint_size is an area, as matplotlib's marker size is (square points), so the diameter goes as its square root, as a matplotlib marker's does: four times the joint size draws joints twice as wide on every backend. The alternative, a diameter in proportion to the size as bone_width gives the bones, would make the same change twice as large on k3d and OpenCV as on matplotlib.

fields_set(style: Style) -> dict[str, object]

The fields of style its caller set, by the constructor's overrides or by :meth:Style.replace, with their values: none for a preset alone.

resolve_style(style: Style | str) -> Style

Accept a preset name or a Style instance; return a Style.

effective_color_mode(style: Style, n_skeletons: int) -> str

Resolve "auto"/"single" to the concrete mode for n panels.

The multi-skeleton auto-switch rule: comparisons get flat per-skeleton palette colors unless chains are forced explicitly.

spine_color(style: Style) -> str

The style's spine color: the color of every bone no limb chain claims, and of the root joint, under chain colors.

A chain_colors without a "spine" entry falls back to the paper preset's.

skeleton_color(style: Style, view_index: int, n_skeletons: int) -> tuple[float, float, float] | str

The one color that stands for a whole skeleton, in matplotlib-friendly form.

Under the flat color modes it is the color all its bones share: the view's palette color ("skeleton") or style.bone_color ("single"). Under "chains" no bone color stands for the whole skeleton, so it is :func:spine_color, the color the root joint takes, rather than the first bone's color, which would depend on the order the file lists the root's children in.

bone_colors_for_view(view: SkeletonView, style: Style, view_index: int, n_skeletons: int) -> list

Per-bone colors for one view, in matplotlib-friendly form.

Each entry is a hex string or an RGB float tuple, parallel to view.bones. The OpenCV backend converts these at its border. Under the flat color modes every bone takes :func:skeleton_color.

bone_width_px(bone_width: float, px_scale: float = 1.0) -> int

A style's bone_width in whole pixels: bone_width pixels at the 1080p anchor (px_scale 1), scaled by px_scale, rounded half up as the OpenCV backend has always rounded it (2.5 draws 3 pixels, where Python's round, half to even, gives 2) and at least 1.

joint_radius_px(joint_size: float, px_scale: float = 1.0) -> int

A style's joint_size as a joint disc's radius in whole pixels: ANCHOR_JOINT_RADIUS_PX at the 1080p anchor (px_scale 1) scaled by :func:joint_size_scale, which grows with the square root of the size, and by px_scale, as :func:bone_width_px scales the bones; rounded half up and at least 1.

ghost_schedule(style: Style, frame_time: float, n_ghosts: int) -> tuple[int, npt.NDArray[np.float64]]

Frame lag and fade weights for a ghost trail.

Ghost slot j trails the live pose by (j+1) * lag frames; weights fade from 0.32 (nearest, darkest) to 0.15 (oldest). frame_time must be positive: the router refuses ghosts on a clip whose rate is unset.

counter_left_px(width: int) -> int

The left edge of the counter on a frame width pixels wide: 200 pixels in from the right edge, or 5 in from the left on a frame narrower than 205.

frame_counter_text(scene: Scene, frame: int) -> str

The counter stamped on frame: Frame f/F, f the frame of the clip it shows and F the clip's last frame, so a looped Scene counts from 0 again on each pass (:meth:~._scene.Scene.pass_start).