braincell.vis.plot_movie

Contents

braincell.vis.plot_movie#

braincell.vis.plot_movie(morpho, values_over_time, *, dt=None, dimensionality='2d', out=None, fps=30, cmap='viridis', vmin=None, vmax=None, value_label=None, layout=None, shape=None, layout_config=None, mode=None, ax=None, figsize=None)[source]#

Render a time-varying colour-by-values animation over a morphology.

Parameters:

  • morpho (Morphology) – Morphology the values are defined against.

  • values_over_time (ArrayLike) – A (T, N) array where T is the number of frames and N matches one of the supported shapes for ValueSpec (n_branches, total segment count, or total centerline-point count). Units attached via brainunit are stripped and used as the default colour-bar label.

  • dt (Quantity or None) – Optional timestep between frames. Only used to display the current time in the figure title.

  • dimensionality (str) – Target backend. 2D uses matplotlib FuncAnimation; 3D uses PyVista’s movie writer.

  • out (Path | str | None) – If set, the animation is written to this path (.mp4 / .gif for 2D, .mp4 for 3D). The directory must already exist.

  • fps (int) – Frames per second for the output file.

  • cmap (str) – Forwarded to ValueSpec and applied uniformly across every frame.

  • vmin (float | None) – Forwarded to ValueSpec and applied uniformly across every frame.

  • vmax (float | None) – Forwarded to ValueSpec and applied uniformly across every frame.

  • value_label (str | None) – Forwarded to ValueSpec and applied uniformly across every frame.

  • layout (str | None) – Layout / rendering knobs forwarded to the scene builder. Match the semantics of plot2d() / plot3d().

  • shape (str | None) – Layout / rendering knobs forwarded to the scene builder. Match the semantics of plot2d() / plot3d().

  • layout_config (LayoutConfig | None) – Layout / rendering knobs forwarded to the scene builder. Match the semantics of plot2d() / plot3d().

  • mode (str | None) – Layout / rendering knobs forwarded to the scene builder. Match the semantics of plot2d() / plot3d().

  • ax (matplotlib Axes or None) – Optional Axes to render into. Ignored in 3D mode.

  • figsize (tuple[float, float] | None) – Matplotlib figure size. Ignored when ax is supplied.

Returns:

The underlying animation / plotter, frame count, and output path (if any).

Return type:

MovieResult

Raises:

ValueError – If values_over_time is not 2-D or if the frame count is zero.

Contents