Package sc.fiji.snt.viewer

Class Bvv

java.lang.Object
sc.fiji.snt.viewer.Bvv
public class Bvv extends Object
Support for Big Volume Viewer.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Bvv.AnnotationOverlay
    Renders spherical annotations at SNTPoint world coordinates.
    static class 
    Bvv.Keyframe
    A snapshot of the BVV viewer state at a particular moment, used as a keyframe for movie recording.
    static class 
    Bvv.PathRenderingOptions
    Configuration options for path rendering.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Bvv()
    Constructor for standalone BVV instance.
    Bvv(SNT snt)
    Constructor for assembling a BVV instance tethered to SNT.

  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    accel(double t, int type)
    Easing functions for keyframe transitions, adapted from BDV movie recorder.
    void
    add(File[] reconstructionFiles)
    Loads reconstruction files and adds them to the viewer with live progress feedback.
    void
    add(Object object)
    Script friendly method to add a supported object (Tree, DirectedWeightedGraph) to the viewer overlay.
    void
    addTree(Tree tree)
    Adds a Tree to the viewer as overlay
    Bvv.AnnotationOverlay
    annotations()
     
    Bvv.Keyframe
    captureKeyframe()
    Captures the current viewer state as a Bvv.Keyframe.
    void
    clearAllTrees()
    Clears all rendered trees from the overlay.
    boolean
    getDisplayRadii()
    Returns whether paths are currently rendered with per-node radii as tapered frusta (true) or as simple lines (false).
    static Bvv
    getInstance()
    Returns the most recently created Bvv instance, or null if none has been created yet.
    BookmarkManager
    getMarkerManager()
    Returns the BookmarkManager used for placing and managing markers in this BVV instance.
    List<BvvMultiSource>
    getMultiSources()
    Returns all BvvMultiSource groups currently managed by this viewer.
    bvv.vistools.BvvOptions
    getOptions()
     
    Collection<Tree>
    getRenderedTrees()
    Gets all the trees currently rendered.
    Bvv.PathRenderingOptions
    getRenderingOptions()
    Gets the path rendering options for controlling thickness, transparency, etc.
    bvv.core.BigVolumeViewer
    getViewer()
     
    bvv.core.VolumeViewerFrame
    getViewerFrame()
     
    bvv.core.VolumeViewerPanel
    getViewerPanel()
     
    static Bvv
    open(ij.ImagePlus... imps)
    Convenience factory: creates a standalone BVV viewer and displays one or more ImagePlus volumes in one step.
    static Bvv
    open(String filePathOrUrl)
    Convenience factory: opens a file path into a BVV viewer.
    static Bvv
    open(String... paths)
    Convenience factory: opens one or more file paths into the same BVV viewer window, choosing the most appropriate loading strategy per file: .ims Imaris HDF5: creates a BDV XML sidecar file next to the .ims file (using the same base name, e.g.
    static Bvv
    open(List<?> imgs)
    Script friendly convenience factory: creates a standalone BVV viewer and displays a list of images in one step.
    static Bvv
    open(mpicbg.spim.data.generic.AbstractSpimData<?> spimData)
    Convenience factory: creates a standalone BVV viewer and displays a AbstractSpimData dataset using BVV's pyramid-aware GPU cache manager.
    static <T extends net.imglib2.type.numeric.RealType<T>>
    Bvv
    open(net.imagej.ImgPlus<T>... imgs)
    Convenience factory: creates a standalone BVV viewer and displays one or more ImgPlus volumes in one step.
    static Bvv
    open(SNT snt)
    Convenience factory: creates a BVV instance tethered to the given SNT instance and immediately displays its currently loaded image data.
    void
    playback(List<Bvv.Keyframe> keyframes)
    Plays back an animation between keyframes in the viewer without saving frames.
    void
    playback(List<Bvv.Keyframe> keyframes, int from, int to)
    Plays back a subset of keyframes (from index from to index to, inclusive).
    boolean
    removeTree(String treeLabel)
     
    void
    renderFrames(List<Bvv.Keyframe> keyframes, String outputDir)
    Renders an animation between a list of keyframes, saving each frame as a PNG screenshot.
    void
    repaint()
    Forces a repaint of the viewer, updating volume renderings but not overlays.
    void
    resetView()
    Resets the viewer to a fit-to-viewport transform, centering the loaded volume in the canvas.
    boolean
    saveSnapshot(String filePath)
    Saves a snapshot of current scene as a PNG image to the specified path.
    void
    setCalibration(double[] spacing, String unit)
    Overrides the voxel calibration (spacing and unit) for all loaded sources.
    void
    setCanvasOffset(double offsetX, double offsetY, double offsetZ)
    Offsets all paths being rendered.
    void
    setChannelColors(Color... colors)
    Sets per-channel colors across all source groups, assigning colors sequentially by global channel order across all groups.
    void
    setChannelColors(String... colorNames)
    Script-friendly method for setting per-channel colors
    void
    setChannelColors(BvvMultiSource group, Color... colors)
    Sets per-channel colors for a specific source group.
    void
    setDisplayRadii(boolean display)
    Sets whether paths are rendered as tapered frusta with per-node radii (true) or as anti-aliased lines (false).
    void
    setDisplayRange(BvvMultiSource group, double min, double max)
    Sets the display range (min/max intensity) for all channels of a specific source group.
    bvv.vistools.BvvSource
    show(ij.ImagePlus imp)
    Displays the BVV viewer with the specified image.
    <T extends net.imglib2.type.numeric.RealType<T>>
    List<BvvMultiSource>
    show(List<net.imglib2.RandomAccessibleInterval<T>> imgs, List<double[]> calibrations)
    Displays a list of RandomAccessibleInterval volumes, each as a BvvMultiSource.
    List<BvvMultiSource>
    show(mpicbg.spim.data.generic.AbstractSpimData<?> spimData)
    Displays a AbstractSpimData dataset using BVV's pyramid-aware GPU cache manager.
    <T extends net.imglib2.type.numeric.RealType<T>>
    bvv.vistools.BvvSource
    show(net.imagej.ImgPlus<T> imgPlus)
     
    <T extends net.imglib2.type.numeric.RealType<T>>
    bvv.vistools.BvvSource
    show(net.imglib2.RandomAccessibleInterval<T> img, double... calibration)
    Displays the BVV viewer with the specified image.
    bvv.vistools.BvvSource
    showLoadedData()
    Displays the main tracing data from the associated SNT instance.
    bvv.vistools.BvvSource
    showSecondaryData()
    Displays the secondary tracing data from the associated SNT instance.
    ij.ImagePlus
    snapshot()
    Retrieves the current scene as an image.
    ij.ImagePlus
    snapshot(String viewMode)
    Retrieves the specified scene view as an image.
    void
    syncOverlays()
    Updates the viewer display to reflect changes in rendered trees and paths.
    boolean
    syncPathManagerList()
    Synchronizes the Path Manager contents with BVV display.
    void
    updateStatus(String message, int step, int nSteps)
    Updates the progress bar at the bottom of the BVV frame.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Bvv

      public Bvv()
      Constructor for standalone BVV instance.

    • Bvv

      public Bvv(SNT snt)
      Constructor for assembling a BVV instance tethered to SNT.
      Parameters:
      snt - the snt instance providing paths and imagery to be rendered

  • Method Details

    • getInstance

      public static Bvv getInstance()
      Returns the most recently created Bvv instance, or null if none has been created yet. This is a convenience accessor for scripts that need to reference the active BVV viewer without passing it around.
      Returns:
      the last initialised Bvv, or null

    • show

      public <T extends net.imglib2.type.numeric.RealType<T>> bvv.vistools.BvvSource show(net.imglib2.RandomAccessibleInterval<T> img, double... calibration)
      Displays the BVV viewer with the specified image.
      Type Parameters:
      T - the numeric type of the image data
      Parameters:
      img - the image data to display
      calibration - optional calibration values for x, y, z dimensions. If null, defaults to {1, 1, 1}
      Returns:
      the BvvSource representing the displayed image

    • show

      public <T extends net.imglib2.type.numeric.RealType<T>> bvv.vistools.BvvSource show(net.imagej.ImgPlus<T> imgPlus)

    • show

      public <T extends net.imglib2.type.numeric.RealType<T>> List<BvvMultiSource> show(List<net.imglib2.RandomAccessibleInterval<T>> imgs, List<double[]> calibrations)
      Displays a list of RandomAccessibleInterval volumes, each as a BvvMultiSource. All volumes are added to the same BVV window.
      Type Parameters:
      T - the numeric type
      Parameters:
      imgs - the volumes to display
      calibrations - per-image calibration arrays (x, y, z pixel sizes); may be null to use defaults of {1,1,1}
      Returns:
      list of BvvMultiSource, one per volume

    • getMultiSources

      public List<BvvMultiSource> getMultiSources()
      Returns all BvvMultiSource groups currently managed by this viewer. This includes multichannel images and any grouped multi-image sources.
      Returns:
      unmodifiable list of BvvMultiSource groups

    • setChannelColors

      public void setChannelColors(String... colorNames)
      Script-friendly method for setting per-channel colors
      Parameters:
      colorNames - color representations (HTML/css values, or hex)
      See Also:

    • setChannelColors

      public void setChannelColors(BvvMultiSource group, Color... colors)
      Sets per-channel colors for a specific source group. Each color is applied to the corresponding channel in order; extra colors are ignored, and channels without a supplied color are left unchanged. Typical script usage: 
         def bvv = Bvv.open([reference, moving])
   bvv.setChannelColors(bvv.getMultiSources().get(0), Color.RED, Color.GREEN, Color.BLUE)
      Parameters:
      group - the target source group, obtained from getMultiSources()
      colors - one color per channel, in channel order

    • setChannelColors

      public void setChannelColors(Color... colors)
      Sets per-channel colors across all source groups, assigning colors sequentially by global channel order across all groups. For example, with two 3-channel images and colors [R, G, B, C, M, Y], image 1 gets R/G/B and image 2 gets C/M/Y. With a single multichannel image or a dataset where each setup is its own group (e.g. IMS), colors are assigned one-to-one in load order.

      To apply the same color pattern to every group independently, call setChannelColors(BvvMultiSource, Color...) per group.

      Typical script usage: 
         def bvv = Bvv.open(img)
   bvv.setChannelColors(Color.RED, Color.GREEN, Color.BLUE)
      Parameters:
      colors - colors assigned sequentially across all channels in all groups

    • setDisplayRange

      public void setDisplayRange(BvvMultiSource group, double min, double max)
      Sets the display range (min/max intensity) for all channels of a specific source group.
      Parameters:
      group - the target source group, obtained from getMultiSources()
      min - the minimum intensity value (maps to black)
      max - the maximum intensity value (maps to full color)

    • getMarkerManager

      public BookmarkManager getMarkerManager()
      Returns the BookmarkManager used for placing and managing markers in this BVV instance. The manager is created lazily on first call. Use BookmarkManager.showPanel() to display the floating marker panel, and BookmarkManager.save(File) to persist markers to CSV.
      Returns:
      the marker manager (never null)

    • open

      public static Bvv open(ij.ImagePlus... imps)
      Convenience factory: creates a standalone BVV viewer and displays one or more ImagePlus volumes in one step. Multichannel images have their channels grouped and transformed together.

      Equivalent to: 

         Bvv bvv = new Bvv();
   bvv.show(imp); // single image
   bvv.show(Arrays.asList(ref, moving)); // multiple images
      Typical Groovy/PySNT usage: 
         def bvv = Bvv.open(imp)               // single image
   def bvv = Bvv.open(reference, moving) // multiple images
      Parameters:
      imps - one or more images to display; all are added to the same BVV window
      Returns:
      the fully initialised Bvv instance
      Throws:
      IllegalArgumentException - if an image type is unsupported (COLOR_256)

    • open

      @SafeVarargs public static <T extends net.imglib2.type.numeric.RealType<T>> Bvv open(net.imagej.ImgPlus<T>... imgs)
      Convenience factory: creates a standalone BVV viewer and displays one or more ImgPlus volumes in one step. Calibration (pixel sizes) is read automatically from each ImgPlus's metadata.

      Equivalent to: 

         Bvv bvv = new Bvv();
   bvv.show(img);  // single image
      Typical Groovy/PySNT usage: 
         def bvv = Bvv.open(imgPlus)
   def bvv = Bvv.open(imgPlus1, imgPlus2)
      Type Parameters:
      T - the numeric type of the image data
      Parameters:
      imgs - one or more volumes to display; all are added to the same BVV window
      Returns:
      the fully initialised Bvv instance

    • open

      public static Bvv open(List<?> imgs)
      Script friendly convenience factory: creates a standalone BVV viewer and displays a list of images in one step. Accepts any mix of ImagePlus, ImgPlus, or RandomAccessibleInterval objects.

      Typical Groovy/PySNT usage: 

         def bvv = Bvv.open([reference, moving])
   def bvv = Bvv.open(myImageList)
      Parameters:
      imgs - the images to display; all are added to the same BVV window. Each element must be an ImagePlus, ImgPlus, or RandomAccessibleInterval
      Returns:
      the fully initialised Bvv instance
      Throws:
      IllegalArgumentException - if any element is null or of an unsupported type

    • open

      public static Bvv open(SNT snt)
      Convenience factory: creates a BVV instance tethered to the given SNT instance and immediately displays its currently loaded image data.

      Equivalent to: 

         Bvv bvv = new Bvv(snt);
   bvv.showLoadedData();
      Typical Groovy/PySNT usage: 
         def bvv = Bvv.open(snt)
   bvv.add(snt.getPathAndFillManager().getTrees())
      Parameters:
      snt - the SNT instance providing image data and paths
      Returns:
      the fully initialised Bvv instance tethered to snt
      Throws:
      IllegalArgumentException - if no valid image data is loaded in snt

    • open

      public static Bvv open(mpicbg.spim.data.generic.AbstractSpimData<?> spimData)
      Convenience factory: creates a standalone BVV viewer and displays a AbstractSpimData dataset using BVV's pyramid-aware GPU cache manager. Unlike the ImgPlus/ImagePlus paths, this does not attempt to upload the entire volume at once: data is streamed as tiles on demand, making it suitable for out-of-core datasets.

      The caller is responsible for constructing the AbstractSpimData object, typically via an XML/HDF5 loader: 

         import bdv.spimdata.XmlIoSpimDataMinimal
   spimData = new XmlIoSpimDataMinimal().load("/path/to/dataset.xml")
   def bvv = Bvv.open(spimData)
      or via Bio-Formats/IMS loaders that produce a AbstractSpimData with a multiresolution pyramid.
      Parameters:
      spimData - the dataset to display
      Returns:
      the fully initialised Bvv instance

    • open

      public static Bvv open(String filePathOrUrl)
      Convenience factory: opens a file path into a BVV viewer. See open(String...) for supported formats and behavior.
      Parameters:
      filePathOrUrl - the file path or URL to open
      Returns:
      the fully initialised Bvv instance
      Throws:
      IllegalArgumentException - if the file cannot be opened or an .ims directory is not writable

    • open

      public static Bvv open(String... paths)
      Convenience factory: opens one or more file paths into the same BVV viewer window, choosing the most appropriate loading strategy per file:
      • .ims Imaris HDF5: creates a BDV XML sidecar file next to the .ims file (using the same base name, e.g. dataset.xml), then loads it via XmlIoSpimDataMinimal. BVV's pyramid-aware GPU cache manager is used, so the full volume is never loaded into RAM. If the directory is not writable, an IllegalArgumentException is thrown with instructions to create the XML manually using Plugins > BigDataViewer > Create XML for Imaris file.
      • .xml BDV XML/HDF5: loaded directly via XmlIoSpimDataMinimal and displayed using BVV's cache manager. This covers BDV HDF5, BDV N5, and OME-Zarr datasets.
      • anything else delegated to ImgUtils.open(String) and displayed via the standard ImgPlus path. Very large flat volumes will fail with a descriptive error rather than a GL crash.
      Typical Groovy/PySNT usage: 
         def bvv = Bvv.open("/path/to/reference.xml", "/path/to/moving.ims")
      Parameters:
      paths - one or more file paths or URLs to open
      Returns:
      the fully initialised Bvv instance
      Throws:
      IllegalArgumentException - if any file cannot be opened or an .ims directory is not writable

    • show

      public List<BvvMultiSource> show(mpicbg.spim.data.generic.AbstractSpimData<?> spimData)
      Displays a AbstractSpimData dataset using BVV's pyramid-aware GPU cache manager. Each setup (channel/angle) is added as a source and wrapped in a BvvMultiSource. Unlike the ImgPlus/ImagePlus paths, the full volume is never loaded into RAM or GPU at once.
      Parameters:
      spimData - the dataset to display
      Returns:
      list of BvvMultiSource, one per BDV setup, in setup order

    • show

      public bvv.vistools.BvvSource show(ij.ImagePlus imp)
      Displays the BVV viewer with the specified image.
      Parameters:
      imp - the ImagePlus to display
      Returns:
      the BvvSource representing the displayed image
      Throws:
      IllegalArgumentException - if the image type is unsupported (COLOR_256)

    • addTree

      public void addTree(Tree tree)
      Adds a Tree to the viewer as overlay
      Parameters:
      tree - the Tree to render

    • add

      public void add(Object object)
      Script friendly method to add a supported object (Tree, DirectedWeightedGraph) to the viewer overlay. Collections are also supported, which is an effective way of adding multiple items since the scene is only updated once all items have been added.
      Parameters:
      object - the object to be added. Null objects are ignored
      Throws:
      IllegalArgumentException - if object is not supported

    • add

      public void add(File[] reconstructionFiles)
      Loads reconstruction files and adds them to the viewer with live progress feedback. Files are loaded one at a time on a background thread; the viewer scene is updated after each file so the user sees trees appearing incrementally. The progress bar in the SNT Annotations card tracks progress.
      Parameters:
      reconstructionFiles - the reconstruction files (SWC, JSON, etc.) to load

    • updateStatus

      public void updateStatus(String message, int step, int nSteps)
      Updates the progress bar at the bottom of the BVV frame.
      • nSteps = 0: hides the bar
      • nSteps < 0: indeterminate mode (animated, no percentage)
      • nSteps > 0: determinate mode showing step/nSteps
      Safe to call from any thread.
      Parameters:
      message - short status message displayed inside the bar
      step - current step (0-based; ignored in indeterminate mode)
      nSteps - total steps (0 = hide, negative = indeterminate)

    • syncOverlays

      public void syncOverlays()
      Updates the viewer display to reflect changes in rendered trees and paths. This method should be called after modifying the collection of rendered objects to ensure the display is synchronized.

    • annotations

      public Bvv.AnnotationOverlay annotations()

    • repaint

      public void repaint()
      Forces a repaint of the viewer, updating volume renderings but not overlays.

    • resetView

      public void resetView()
      Resets the viewer to a fit-to-viewport transform, centering the loaded volume in the canvas. Equivalent to the Reset button in Camera Controls. No-op if no volume has been loaded.

    • snapshot

      public ij.ImagePlus snapshot()
      Retrieves the current scene as an image.
      Returns:
      the bitmap image of the current scene

    • snapshot

      public ij.ImagePlus snapshot(String viewMode)
      Retrieves the specified scene view as an image. Must be called from a non-EDT thread (e.g. a script or SwingWorker), otherwise the render latch will time out.
      Parameters:
      viewMode - the view mode (case-insensitive): "xy", "xz", "yz", "default" (fit-to-viewport), or "current" (scene as-is).
      Returns:
      the bitmap image of the scene view, or null if the viewer is not initialized

    • saveSnapshot

      public boolean saveSnapshot(String filePath)
      Saves a snapshot of current scene as a PNG image to the specified path.
      Parameters:
      filePath - the absolute path of the destination file
      Returns:
      true, if file was successfully saved

    • removeTree

      public boolean removeTree(String treeLabel)

    • clearAllTrees

      public void clearAllTrees()
      Clears all rendered trees from the overlay.

    • getRenderedTrees

      public Collection<Tree> getRenderedTrees()
      Gets all the trees currently rendered.
      Returns:
      collection of rendered trees

    • getViewerFrame

      public bvv.core.VolumeViewerFrame getViewerFrame()
      Returns:
      a reference to the viewer's frame.

    • getOptions

      public bvv.vistools.BvvOptions getOptions()
      Returns:
      a reference to the viewer's options.

    • getViewer

      public bvv.core.BigVolumeViewer getViewer()
      Returns:
      a reference to the underlying BigVolumeViewer instance.

    • getViewerPanel

      public bvv.core.VolumeViewerPanel getViewerPanel()
      Returns:
      a reference to the viewer's panel.

    • getRenderingOptions

      public Bvv.PathRenderingOptions getRenderingOptions()
      Gets the path rendering options for controlling thickness, transparency, etc.
      Returns:
      the rendering options

    • setCalibration

      public void setCalibration(double[] spacing, String unit)
      Overrides the voxel calibration (spacing and unit) for all loaded sources. This is useful when the image metadata does not carry the correct spatial calibration (e.g., ND2 files opened via SCIFIO/Bio-Formats where the unit string is lost). The change takes effect immediately: the scale bar, distance measurements, and slab-thickness controls will all use the new values.
      Parameters:
      spacing - voxel size in {x, y, z} order
      unit - physical unit string (e.g. "µm")

    • setDisplayRadii

      public void setDisplayRadii(boolean display)
      Sets whether paths are rendered as tapered frusta with per-node radii (true) or as anti-aliased lines (false). Line rendering is significantly faster for datasets with many paths. Automatically invalidates the overlay cache and repaints.
      Parameters:
      display - true for frustum/radius rendering (default), false for fast line rendering

    • getDisplayRadii

      public boolean getDisplayRadii()
      Returns whether paths are currently rendered with per-node radii as tapered frusta (true) or as simple lines (false).
      Returns:
      true if frustum/radius rendering is active

    • setCanvasOffset

      public void setCanvasOffset(double offsetX, double offsetY, double offsetZ)
      Offsets all paths being rendered. This allows for 'dislodging' paths from their underlying signal without altering their coordinates.
      Parameters:
      offsetX - X offset (calibrated distance)
      offsetY - Y offset (calibrated distance)
      offsetZ - Z offset (calibrated distance)

    • showLoadedData

      public bvv.vistools.BvvSource showLoadedData()
      Displays the main tracing data from the associated SNT instance. This method is only available for BVV instances that are tethered to an SNT instance.
      Returns:
      the BvvSource representing the displayed tracing data
      Throws:
      IllegalArgumentException - if this is a standalone viewer or no valid image data is available

    • showSecondaryData

      public bvv.vistools.BvvSource showSecondaryData()
      Displays the secondary tracing data from the associated SNT instance. This method is only available for BVV instances that are tethered to an SNT instance.
      Returns:
      the BvvSource representing the displayed secondary data
      Throws:
      IllegalArgumentException - if this is a standalone viewer or no valid image data is available

    • syncPathManagerList

      public boolean syncPathManagerList()
      Synchronizes the Path Manager contents with BVV display.
      Returns:
      true if synchronization was successful
      Throws:
      IllegalArgumentException - if this is a standalone viewer not tethered to a SNT instance

    • captureKeyframe

      public Bvv.Keyframe captureKeyframe()
      Captures the current viewer state as a Bvv.Keyframe. The transform, camera/slab parameters, and visible actor set are all snapshotted.
      Returns:
      the current state as a Keyframe

    • accel

      public static double accel(double t, int type)
      Easing functions for keyframe transitions, adapted from BDV movie recorder.
      Parameters:
      t - progress value in [0, 1]
      type - easing type: 0 = symmetric, 1 = slow start, 2 = slow end, 3 = soft symmetric, 4 = soft slow start, 5 = soft slow end
      Returns:
      eased progress value in [0, 1]

    • playback

      public void playback(List<Bvv.Keyframe> keyframes)
      Plays back an animation between keyframes in the viewer without saving frames. Useful for previewing a movie before committing to a render. The frame count for each transition is read from Bvv.Keyframe.frames on the destination keyframe.
      Parameters:
      keyframes - ordered list of keyframes (at least 2)
      See Also:

    • playback

      public void playback(List<Bvv.Keyframe> keyframes, int from, int to)
      Plays back a subset of keyframes (from index from to index to, inclusive). Useful for previewing a specific transition without replaying the entire sequence.
      Parameters:
      keyframes - ordered list of all keyframes
      from - start index (inclusive, 0-based)
      to - end index (inclusive, 0-based)
      See Also:

    • renderFrames

      public void renderFrames(List<Bvv.Keyframe> keyframes, String outputDir)
      Renders an animation between a list of keyframes, saving each frame as a PNG screenshot. The transform is interpolated smoothly between keyframes using SimilarityTransformAnimator; visibility and slab bounds snap at keyframe boundaries (no interpolation).

      The number of frames for each transition is read from Bvv.Keyframe.frames on each destination keyframe (the first keyframe's value is ignored).

      This method must be called from a non-EDT thread. It blocks until all frames have been rendered and saved.

      Parameters:
      keyframes - ordered list of keyframes (at least 2)
      outputDir - directory where PNGs will be saved (created if needed); if null, frames are played back live without saving
      Throws:
      IllegalArgumentException - if arguments are inconsistent
      IllegalStateException - if no BVV viewer is active