Movie API

Movie API#

The movie namespace converts scientific image stacks into GIF or MP4 artifacts without owning the upstream scientific computation. Install the movie extra using the current command on the installation page.

Inputs and outputs#

from quantem.gpu import movie

movie.save_gif(data, "movie.gif")
movie.save_mp4(data, "movie.mp4", backend="auto")
movie.save_movie(data, "movie.mp4")

save_movie() dispatches from the path suffix: .gif uses save_gif() and .mp4 uses save_mp4(). Each function returns the written path according to its public signature.

Shapes, coordinates, dtypes, and units#

One stack has shape (frame, row, column). Several aligned stacks use (movie, frame, row, column) or a sequence of 3D arrays. All stacks must have the same frame count and spatial shape. Input scientific dtype is preserved up to the declared display normalization; encoded frames are presentation data, not a replacement for the source array. Frame rate is in frames per second.

Errors and unsupported requests#

  • Empty data, unsupported rank, mismatched stack shapes, or mismatched frame counts raise with the conflicting shape.

  • An unsupported suffix passed to save_movie() raises instead of guessing a container.

  • An explicitly requested accelerator backend must be available. Automatic dispatch may choose another documented encoder, but the reported backend must match the path actually used.

Provenance#

For a scientific export, retain the source/result identity, source shape and dtype, selected frames, spatial orientation, normalization/percentiles, colormap, labels, frame rate, encoder backend, codec/container, output checksum, and package revision. Encoded bitstreams can differ across valid encoders, so parity compares decoded frames and metadata rather than requiring identical container bytes.

Backend dispatch#

save_mp4(..., backend="auto") tries CUDA/NVENC when available, then Apple Metal/MPS on macOS, then CPU frame rendering plus ffmpeg. Use backend="cuda" or backend="mps" only when that exact path is part of the required contract or benchmark.

Integration boundary#

QuantEM.GPU owns deterministic frame preparation, backend selection, encoding, and export metadata. A consuming application owns which scientific result and frames to export, user-visible labels, destination choice, and presentation.

See Display and export kernels for the shared orientation, color, histogram, FFT, and parity rules.