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 viabackend="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'
|
labels
|
list[str]
|
Subplot titles for side-by-side comparison. |
None
|
figsize
|
(float, float)
|
Figure size in inches. |
None
|
show
|
bool
|
If |
False
|
camera
|
str or (float, float)
|
Camera preset ( |
'front'
|
ax
|
Axes
|
Existing 3D axes to draw on. If provided, no new figure is
created. Only supported for a single skeleton (raises
|
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 |
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'
|
backend
|
str
|
|
'matplotlib'
|
coords
|
ndarray
|
Pre-computed spatial coordinates to plot instead of computing
forward kinematics from bvh: |
None
|
centered
|
str
|
Centering mode: |
'world'
|
labels
|
list[str]
|
Subplot titles for side-by-side comparison. |
None
|
figsize
|
(float, float)
|
Figure size in inches; |
None
|
show
|
bool or None
|
If |
None
|
camera
|
str or (float, float)
|
Camera preset ( |
'front'
|
resolution
|
(int, int) or None
|
Image size |
None
|
filepath
|
str or Path
|
Also write the rendered image here ( |
None
|
ax
|
Axes
|
Existing 3D axes to draw on. If provided, no new figure is
created. Only supported for a single skeleton (raises
|
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: |
None
|
match_size
|
bool or None
|
Draw every skeleton as tall as the first, with the factor on
its label, as :func: |
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 |
Axes or list[Axes]
|
Single axes when one skeleton, list when multiple.
With |
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'
|
style
|
Style or str
|
Visual styling preset or instance. Default |
'paper'
|
centered
|
str
|
Centering mode for the underlying coords (default |
'world'
|
camera
|
str, (float, float), or None
|
|
None
|
trajectory
|
bool
|
Draw the dashed root trace on the floor (offset layout only).
Default |
True
|
figsize
|
(float, float)
|
Figure size; defaults to a wide figure for offset layout. |
None
|
show
|
bool
|
Call |
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 |
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 |
Path('./anim.mp4')
|
style
|
Style or str
|
Visual styling: a preset name ( |
'paper'
|
centered
|
str
|
Centering mode: |
'world'
|
labels
|
list[str]
|
Labels for each skeleton when comparing. |
None
|
fps
|
float
|
Frames per second (fractional rates like 119.88 are fine).
|
None
|
backend
|
str
|
|
'auto'
|
camera
|
str or (float, float)
|
Camera preset ( |
'front'
|
turntable_period
|
float
|
Seconds per revolution of |
None
|
resolution
|
(int, int)
|
Output resolution |
(1920, 1080)
|
sync
|
str
|
How to handle different frame counts in side-by-side comparison:
|
'truncate'
|
follow
|
bool or None
|
If |
None
|
ghost
|
int or None
|
Number of faded trailing poses drawn behind the live skeleton;
|
None
|
trajectory
|
bool or None
|
Draw the root trace on the floor, growing with playback.
|
None
|
frame_counter
|
bool or None
|
Stamp a |
None
|
match_fps
|
str or None
|
How to handle clips with different frame rates in side-by-side
rendering (different by :meth: |
None
|
codec
|
str
|
Video codec for |
'auto'
|
spacing
|
(float, 'auto' or None)
|
Lateral separation between skeletons on the vedo backend, which
draws every skeleton in one scene, exactly as :func: |
None
|
match_size
|
bool or None
|
Draw every skeleton as tall as the first, with the factor on
its label, as :func: |
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'
|
centered
|
str
|
Centering mode: |
'world'
|
labels
|
list[str]
|
Labels for each skeleton when comparing. |
None
|
fps
|
float
|
Frames per second (fractional rates like 119.88 are fine).
|
None
|
backend
|
str
|
|
'auto'
|
camera
|
str or (float, float)
|
Camera preset ( |
'front'
|
sync
|
str
|
How to handle different frame counts in side-by-side comparison:
|
'truncate'
|
resolution
|
(int, int) or None
|
Output resolution |
None
|
quality
|
str or None
|
Visual quality of the vedo desktop window, the only backend
that reads it (see backend): |
None
|
frame_counter
|
bool or None
|
Stamp a |
None
|
match_fps
|
str or None
|
How to handle clips with different frame rates (different by
:meth: |
None
|
spacing
|
(float, 'auto' or None)
|
Lateral separation between skeletons in single-scene backends
(k3d, vedo). |
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
|
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'
|
centered
|
str
|
Centering mode: |
'world'
|
labels
|
list[str]
|
Legend labels. |
None
|
figsize
|
(float, float)
|
Figure size in inches. |
None
|
show
|
bool
|
If |
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: |
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 |
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 |
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_headingis[sin(theta), cos(theta)]of :func:~pybvh.analysis.root_trajectory's heading angletheta = atan2(f[b], f[a]), wherefis the rest-pose forward rotated by the body anchor's world rotation and(a, b)are the two ground axes in naturalx, y, zorder 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+yup, a positive rotation about+ydecreases it. Orientation-derived and continuous;NaNon a row whose heading cannot be read (the anchor's forward stands along up), which draws no facing arrow;Nonewhen the coords are not the clip's.initial_forwardis 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_atreads (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 readscoords,lr_pairs,up_vectorandframe_timedirectly.upis the one statement of which way is up: a signed axis string ('+y','-z'), the form :attr:Bvh.world_upandinitial_forwarduse. 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_upis the up axis ofrest_coords(:attr:Bvh.rest_up), in the same signed form, orNonewhen it is not known. It usually equalsup; a file that authors its rest pose in one convention and animates it in another has two, and :attr:body_sizeneeds the rest pose's. An unknown rest axis is not replaced byup, which on such a file would name the rest pose's depth; :attr:body_sizemeasures without it instead.bodymarks the nodes of the clip's body, the part of the skeleton that :attr:Bvh.body_anchornames and that rest up and the feet are looked for in. They are the nodes :attr:body_sizemeasures.Nonemeasures 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_unitstates thatcoordswere posed fromrest_coordsby forward kinematics, so they share its unit and :attr:coords_per_rest_unitis exactly 1. :func:make_scenestates it for the clip's own frames. It defaults toFalse, 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_pairsare 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 (subsampledsharescoordsandanchor_heading;offsetallocates new coords and shares the heading;loopedcopies 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 alongrest_up."rest extent": the rest pose's widest extent along any axis, whenrest_upisNone(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'sup, 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 boxcoordssweeps 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 ofcoords(below). There is no body to measure, so it grows with the distance the clip travels."default":DEFAULT_BODY_SIZE, one unit ofcoords, 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 alongup, 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 alongup. 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_upagainstBvh.world_up), and there the rest pose's extent alongupis 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 ofcoords. The alternative is the median over the clip's frames of the pose's extent alongup. 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_upis 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 aUserWarningnames 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_scenestates 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 |
required |
pad
|
bool
|
If |
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
|
|
required |
centered
|
str
|
Centering mode passed to |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bvh_list |
list[Bvh]
|
Always a list (length >= 1). |
coords_list |
list[ndarray]
|
Parallel list of spatial coordinates, each |
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 |
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'
|
Returns:
| Name | Type | Description |
|---|---|---|
azimuth |
float
|
Azimuth angle in degrees. |
elevation |
float
|
Elevation angle in degrees. |
up_letter |
str
|
Single character: |
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: |
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:
centerandhalf_spanare the cube around every coordinate shown, 5% margin included. It is the scale of the picture: the floor's extent is a multiple ofhalf_span, and perspective cameras look atcenter(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.loandhiare the framing box, what the axes or the orthographic projection are fitted to. Forframing="still"it is that same cube (shifted along up when a floor must sit inside it); forframing="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
|
band
|
tuple of float
|
The part of the picture's height the figure may take, as
|
(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"
|
schedule
|
('fixed', 'turntable', 'follow')
|
How the camera moves. |
"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 |
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 ( |
"persp"
|
fps
|
float
|
The rate the picture plays at. Read only by |
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 |
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; |
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 atFOLLOW_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 whoseframe_timeis 0 (unset) has no clip time; its window is then sized fromfps, 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 onfps. The alternative, refusing the clip as ghost spacing does, would take the follow camera away from a cliprender(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 ofscipy.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 |
required |
base_azim
|
float
|
The frame-0 azimuth in degrees (from :func: |
required |
fps
|
float
|
The rate the picture plays at. Read only when the view's
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
azimuths |
ndarray of shape (F,)
|
Azimuth in degrees for every frame, unwrapped, so it may leave
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the view's |
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
|
|
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: |
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 |
required |
resolution
|
(width, height)
|
Panel size in pixels. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
pixels |
ndarray of shape (N, 2)
|
Integer pixel coordinates |
_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).