Package sc.fiji.snt.viewer

Class AbstractBigViewer

java.lang.Object
sc.fiji.snt.viewer.AbstractBigViewer
Direct Known Subclasses:
Bdv, Bvv
public abstract class AbstractBigViewer extends Object
Abstract base for SNT's BigDataViewer-family viewers (Bvv, Bdv, etc.).

Provides shared infrastructure for tree/path management, calibration, and bookmark support, leaving viewer-specific rendering, source loading, and camera control to concrete subclasses.

The AbstractBigViewer.AnnotationOverlay interface defined here is the common contract that all viewer overlays must satisfy so that BookmarkManager can drive them without knowing the concrete viewer type.

Author:
Tiago Ferreira
See Also:

  • Field Details

    • lastInstance

      protected static volatile AbstractBigViewer lastInstance
      Most recently instantiated viewer; scripting convenience.

    • snt

      protected final SNT snt
      The SNT instance this viewer is tethered to, or null if no SNT instance is available.

    • tracingEnabled

      protected boolean tracingEnabled

    • CLICK_MOVE_TOLERANCE_PX

      protected static final int CLICK_MOVE_TOLERANCE_PX
      See Also:

    • renderedTrees

      protected final Map<String,Tree> renderedTrees
      Trees currently rendered in this viewer, keyed by unique display label. Insertion order is preserved so the first-added tree stays first.

      SNT#updateTracingViewers(boolean, boolean) fires off a new background Thread for every syncPathManagerList() call, with no coordination between successive calls - during active interactive tracing (many calls in quick succession) more than one of these can run at the same time. All reads/writes of this plain, non-thread-safe LinkedHashMap (here, addTree(Tree, boolean), removeTree(String), clearAllTrees(), syncPathManagerList(), getRenderedTrees()) must go through renderedTreesLock to avoid a ConcurrentModificationException

    • syncedPathManagerLabels

      protected final Set<String> syncedPathManagerLabels
      Labels of the trees rendered by the last syncPathManagerList() call. Needed because that method's own diff (remove labels that are still current, then re-add) never catches a tree that has been entirely deleted from the Path Manager (all its paths removed): such a tree simply stops appearing in PathAndFillManager.getTrees() altogether, so it would otherwise never be pruned from renderedTrees and would linger in the scene forever. Comparing against this set is what lets a fully-deleted tree be detected and removed

    • spimDataFilePaths

      protected final Map<mpicbg.spim.data.generic.AbstractSpimData<?>,String> spimDataFilePaths
      Maps SpimData sources back to the file that produced them.

    • cal

      protected double[] cal
      Voxel sizes [x, y, z] for the primary loaded volume, in calUnit units.

    • dims

      protected long[] dims
      Pixel dimensions [x, y, z] of the primary loaded volume.

    • renderingOptions

      protected AbstractBigViewer.PathRenderingOptions renderingOptions
      Rendering options shared across all path/annotation overlays in this viewer.

    • calUnit

      protected String calUnit
      Physical unit for calibration values (e.g., "um", "pixel").

    • markerManager

      protected BookmarkManager markerManager
      Lazily initialized bookmark/marker manager panel.

    • tracingStatusBar

      protected JProgressBar tracingStatusBar

    • tracingCancelButton

      protected JButton tracingCancelButton

    • tracingUndoButton

      protected JButton tracingUndoButton

    • tracingExtendButton

      protected JToggleButton tracingExtendButton

    • secondaryLayerIndicator

      protected JToggleButton secondaryLayerIndicator

    • FLY_TO_DURATION_MS

      public static final long FLY_TO_DURATION_MS
      Animation duration used by flyTo(BoundingBox) itself, exposed so a caller that needs to run something else only once the camera has actually settled there (e.g. a rotation that must pivot on the box flyTo(BoundingBox) just framed, not on wherever the camera was beforehand - see GuidedTutorial#showCurrentStep()) knows how long to wait first
      See Also:

    • NATIVE_KEYS_EXCLUDED_FROM_PALETTE

      protected static final KeyStroke[] NATIVE_KEYS_EXCLUDED_FROM_PALETTE
      Keystrokes bound to BDV/BVV native commands intentionally kept out of the command palette by registerNativeCommands(sc.fiji.snt.gui.SNTCommandFinder, javax.swing.ActionMap, javax.swing.InputMap, java.util.List<java.lang.String>, javax.swing.Icon, java.util.Set<java.lang.String>, javax.swing.KeyStroke...): per-source selection/visibility digits, continuous pan/zoom/ rotate stepping, timepoint stepping, and bookmark set/recall/rotation. These read as noise in a command finder

    • NATIVE_NAMES_EXCLUDED_FROM_PALETTE

      protected static final Set<String> NATIVE_NAMES_EXCLUDED_FROM_PALETTE
      Action-map keys that registerNativeCommands(sc.fiji.snt.gui.SNTCommandFinder, javax.swing.ActionMap, javax.swing.InputMap, java.util.List<java.lang.String>, javax.swing.Icon, java.util.Set<java.lang.String>, javax.swing.KeyStroke...) should always skip, shared by every BDV/BVV-family viewer: natives that only make sense mid-gesture (aborting an in-progress bookmark placement or manual transform, neither of which has a dedicated trigger key of its own), and SNT's own press/release-pair or modal-pick overlays -- present under the same literal keys in both Bvv and Bdv -- which are meaningless as a one-shot palette command (see, e.g., Actions#hideAnnotationsPressAction).

  • Constructor Details

    • AbstractBigViewer

      protected AbstractBigViewer()

    • AbstractBigViewer

      protected AbstractBigViewer(SNT snt)

  • Method Details

    • getSNT

      public SNT getSNT()
      Returns:
      SNT instance this viewer is tethered to, or null if no SNT instance is available.

    • isTracingEnabled

      public boolean isTracingEnabled()
      Returns:
      whether this viewer's own Start/Stop Tracing toggle is on, i.e. whether AbstractBigViewer.AbstractTracer.handleClick(MouseEvent) will act on the next click (start/extend/fork a path) rather than ignoring it outright. Exposed so other click-consuming features sharing this viewer's display component (e.g. SeedOverlayBigViewerHandler's Alt+Click, which collides with Alt+Click-to-fork below) can back off while tracing-by-click is live, since AbstractTracer reacts in mouseReleased - always dispatched before mouseClicked - so a later listener's MouseEvent#consume() cannot undo it.

    • enableTracing

      public abstract void enableTracing(boolean manual)
      Enables tracing on this viewer, as if the user had clicked its manual/interactive tracing-mode toggle button (see AbstractTracer#getToggleAction(boolean)), so a click on the canvas traces instead of panning it. Shows an error dialog and leaves tracing off if manual is false (semi-automated tracing) and no image data is available to trace on. Does nothing if this viewer has no tracer (e.g. a standalone viewer with no attached SNT instance, or the toolbar has not been built yet).
      Parameters:
      manual - true for manual (point-and-click) tracing, false for semi-automated (auto-trace) tracing
      See Also:

    • isPathInProgress

      public abstract boolean isPathInProgress()
      Returns:
      whether this viewer currently has a path in progress, i.e. the user has clicked to start (or extend/fork) a path but has not yet finished or discarded it. Always false if this viewer has no tracer (see enableTracing(boolean)).
      See Also:

    • syncPathManagerList

      public boolean syncPathManagerList()
      Replaces the rendered trees with the current contents of the Path Manager. Only available in SNT-tethered instances.
      Returns:
      true if paths were synced; false if the path manager is empty
      Throws:
      IllegalArgumentException - if this is a standalone viewer

    • getViewerFrame

      public abstract JFrame getViewerFrame()
      Returns the top-level Swing window for this viewer, or null if not yet open.

    • getViewerSplitPanel

      protected abstract JSplitPane getViewerSplitPanel()
      Returns the JSplitPane that separates the viewer canvas from the card panel. Both BDV and BVV frames expose this via their own getSplitPanel() methods, but those classes share no common supertype above JFrame, so this method lets subclasses expose the split pane without the abstract method returning a viewer-specific frame type.

    • getViewerWidth

      public abstract int getViewerWidth()
      Returns the width of the viewer canvas in logical pixels, or 0 if the viewer is not yet initialized.

    • getViewerHeight

      public abstract int getViewerHeight()
      Returns the height of the viewer canvas in logical pixels, or 0 if the viewer is not yet initialized.

    • getViewerCanvas

      public abstract Component getViewerCanvas()
      Returns the viewer canvas itself, i.e., the actual Component getViewerWidth()/ getViewerHeight() measure, or null if the viewer is not yet initialized. Unlike those two, callers can use this to locate the canvas on screen (e.g. via SwingUtilities.convertPoint()) - the canvas is not necessarily centered in, or even the same size as, the frame's content pane, since getViewerSplitPanel() may also be hosting a side panel next to it

    • getViewerTransform

      public abstract net.imglib2.realtransform.AffineTransform3D getViewerTransform()
      Returns a snapshot of the current viewer-to-screen (world-to-screen) transform. The returned object is a copy; callers may modify it freely.

    • setViewerTransform

      public abstract void setViewerTransform(net.imglib2.realtransform.AffineTransform3D target, long durationMs)
      Animates the viewer transform to target over durationMs milliseconds. Use durationMs = 0 for an immediate jump.
      Parameters:
      target - the desired world-to-screen transform
      durationMs - animation duration in milliseconds (0 = immediate)

    • showViewerMessage

      public abstract void showViewerMessage(String msg)
      Displays a short status message in the viewer's overlay area.

      This is bdv-core/bvv-core's fading toast: it auto-dismisses after a few seconds. For an ongoing, non-auto-dismissing indication of a long-running operation, use updateStatus(java.lang.String, int, int) instead.

      Parameters:
      msg - the message to show

    • updateStatus

      public void updateStatus(String message, int step, int nSteps)
      Updates the persistent progress bar docked at the bottom of this viewer's card panel. Unlike showViewerMessage(java.lang.String), it stays visible until reset.
      • 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)

    • initProgressBar

      protected void initProgressBar(bdv.ui.CardPanel cardPanel)
      Creates the progress bar driven by updateStatus(String, int, int) and docks it at the bottom of the card panel, below all cards and without a card header. This avoids the viewport flicker caused by adding the bar to the frame's BorderLayout.SOUTH.
      Parameters:
      cardPanel - the viewer's card panel

    • resyncCalibrationFromActiveSource

      public abstract void resyncCalibrationFromActiveSource()
      Forces snt's image metadata (dimensions, calibration, pixel data, channel/frame) to be re-read from this viewer's currently active Source, the same resync AbstractBigViewer.AbstractTracer performs on its own before starting a new path (see AbstractTracer#syncChannelFromActiveSource()).

      That resync is otherwise only triggered by the first click of a new path, so snt's calibration can be stale (or still at whatever BigDataLoaderCmd's best-effort fallback produced at load time) for anything that reads it beforehand - such as SNT#buildMaterializedCrop(BoundingBox). Callers that need calibration to reflect exactly what this viewer is currently rendering, before the user has traced anything, should call this first.

      A no-op if no tracer has been created yet, or if the active source can't be resolved.

    • applyAutoBrightness

      protected abstract void applyAutoBrightness(AbstractBigViewer.BrightnessScope scope)
      Recomputes the display range (brightness/contrast) for the source(s) selected by scope, from data percentiles, on a bounded background thread - see ViewerSettingsUtils.initBrightnessSafely(bdv.viewer.ViewerState, bdv.viewer.ConverterSetups, java.lang.String). Called automatically with AbstractBigViewer.BrightnessScope.ALL right after a source is first added, and re-invocable on demand (any scope) via the "Auto Brightness/Contrast" scene-control button (see autoBrightnessButton(sc.fiji.snt.viewer.AbstractBigViewer.Actions)). Does nothing if this viewer isn't yet backed by an underlying BDV/BVV scene (e.g. show(...) hasn't been called).
      Parameters:
      scope - which source(s) to recompute

    • addToCardPanelBottom

      protected static void addToCardPanelBottom(bdv.ui.CardPanel cardPanel, JComponent comp)
      Docks a component at the bottom of a CardPanel, below all cards, without a card header. Uses MigLayout's "dock south" constraint. If the CardPanel's container layout ever changes away from MigLayout this degrades gracefully: the component simply won't appear (no crash, no viewport flicker). Shared by Bvv and Bdv's own progress bars.

    • showLoadedData

      public abstract void showLoadedData()
      Displays the main tracing data (the currently active channel/frame of the image being traced) from the associated SNT instance. Only available in SNT-tethered instances.
      Throws:
      IllegalArgumentException - if this is a standalone viewer, or no valid image data is available

    • showSecondaryData

      public abstract void showSecondaryData()
      Displays the secondary tracing data (the filtered/processed layer used for cost-function-based tracing) from the associated SNT instance. Only available in SNT-tethered instances.
      Throws:
      IllegalArgumentException - if this is a standalone viewer, or no secondary data is available

    • hideSecondaryData

      public abstract void hideSecondaryData()
      Removes the secondary tracing data layer previously added by showSecondaryData() from this viewer, if one is currently displayed. No-op otherwise (e.g., standalone viewers, untethered instances, or when no secondary layer has been shown yet).
      See Also:

    • updateSecondaryLayerIndicator

      public abstract void updateSecondaryLayerIndicator()
      Refreshes the persistent "secondary layer active" indicator shown in this viewer's SNT Controls card, reflecting SNT.isTracingOnSecondaryImageActive(). No-op if this is not a tethered, tracer-enabled instance (i.e., the indicator was never built). Safe to call from any thread.

    • resetView

      public abstract void resetView()
      Resets the view to frame all loaded data.

    • isOpen

      public abstract boolean isOpen()
      Returns true if the viewer window is currently visible and usable.

    • repaint

      public abstract void repaint()
      Requests a repaint of the viewer canvas.

    • syncOverlays

      public abstract void syncOverlays()
      Synchronizes all active rendering overlays (paths, markers) with the current state of renderedTrees and any pending annotation changes.

    • setDisplayRadii

      public abstract void setDisplayRadii(boolean display)
      Sets whether paths are rendered as frusta (tubes) or simple centerlines, and triggers an overlay cache invalidation.
      Parameters:
      display - true to render frusta using per-node radii; false for fast centerline rendering

    • annotations

      public abstract AbstractBigViewer.AnnotationOverlay annotations()
      Returns the annotation overlay for this viewer. The overlay renders point markers in the viewer's world coordinate space. May return null if the viewer has not been opened yet.

    • getDefaultMarkerSize

      public abstract float getDefaultMarkerSize()
      Returns the default sphere radius (in physical units) for newly placed markers. Implementations typically derive this from their rendering-options or a sensible default.

    • getDefaultMarkerColor

      public abstract Color getDefaultMarkerColor()
      Returns the default color for newly placed markers, or null to use the viewer's own fallback color.

    • getCurrentTimepoint

      public abstract int getCurrentTimepoint()
      Returns this viewer's current timepoint (1-based, matching Path.getFrame()'s convention), or 1 if no data is loaded / timepoint tracking is unavailable.

    • setCurrentTimepoint

      public abstract void setCurrentTimepoint(int timepoint)
      Navigates this viewer to the specified timepoint (1-based, matching Path.getFrame()'s convention). Does nothing if no data is loaded.
      Parameters:
      timepoint - the 1-based timepoint to navigate to; values < 1 are coerced to 1

    • flyTo

      public boolean flyTo(BoundingBox box)
      Animates the camera to frame the given world-coordinate bounding box: an isotropic scale is computed so the box's width/height fit the viewport, and the transform is translated to center the box's centroid on screen. Any existing rotation is dropped.

      A degenerate box (zero width/height - e.g. a single-node selection, whose origin and originOpposite are the same point) cannot be "fit" (there is nothing to scale to), so this recenters on the centroid at the viewer's current zoom level instead.

      Parameters:
      box - the world-coordinate bounding box to frame; a no-op if null, its corners are not real (e.g. an empty/uncomputed box), or the viewport has not yet been realized
      Returns:
      true if the transform was computed and applied; false otherwise

    • getSceneCenter

      public SNTPoint getSceneCenter()
      The world-space point currently displayed at the center of this viewer, i.e. the inverse of flyTo(sc.fiji.snt.util.BoundingBox)'s centroid-to-screen-center mapping: applies the inverse viewer transform to the viewport's center screen point, at the focal plane (viewer-space Z = 0).

      Correct as-is for an orthogonal slicing view (the displayed slice is the focal plane). Bvv overrides this to prefer the depth of whatever is actually visible there (see Bvv.findSceneCenterMaxima()), falling back to this same focal-plane result when that ray finds nothing.

      Returns:
      the world-space scene center, or null if the viewport has not yet been realized

    • createMarkerManager

      protected abstract BookmarkManager createMarkerManager()
      Creates and returns a new BookmarkManager for this viewer. Called exactly once (lazily) by getMarkerManager().

    • getGlobalMouseCoordinates

      public abstract void getGlobalMouseCoordinates(net.imglib2.RealPoint pos)
      Writes the current global (world-space) mouse position into pos. Callers must supply a pre-allocated RealPoint with at least 3 dimensions.
      Parameters:
      pos - 3D point to receive the world-space cursor position

    • getCurrentSource

      protected abstract bdv.viewer.SourceAndConverter<?> getCurrentSource()
      Returns the currently active source, or null if none.

    • addMouseListenerToDisplay

      public abstract void addMouseListenerToDisplay(MouseListener ml)
      Adds a mouse listener to the viewer's canvas component so that click events on the display surface can be handled (e.g. for hit testing annotation markers).
      Parameters:
      ml - the listener to add

    • getViewerAction

      protected abstract Action getViewerAction(String name)
      Looks up a named action from the viewer's keybindings action map. Returns null if the action is not registered or the viewer is not ready.
      Parameters:
      name - the action key (e.g., "align XY plane")

    • registerNativeCommands

      protected void registerNativeCommands(SNTCommandFinder commandFinder, ActionMap actionMap, InputMap inputMap, List<String> path, Icon icon, Set<String> excludedNames, KeyStroke... excludedTriggers)
      Registers this viewer's native (library-level) single-shot commands -- i.e., entries of the BDV/BVV keybindings ActionMap, as opposed to SNT's own overlaid commands (see AbstractBigViewer.Actions) -- in commandFinder, so they become searchable/runnable from the command palette. Meant to be called once per viewer instance, only while Stream mode is active

      Continuous, held-key or mouse-drag behaviors (pan, rotate, zoom, scroll) are not picked up by this scrape: they live elsewhere so they are excluded by construction. excludedTriggers additionally drops named actions bound to specific keys that clutter the palette.

      Parameters:
      commandFinder - the palette to register into; a no-op if null
      actionMap - the viewer's concatenated keybindings ActionMap
      inputMap - the viewer's concatenated keybindings InputMap, used only to resolve excludedTriggers to the action keys they are bound to
      path - palette category shown for every registered entry, e.g. List.of("Bvv Viewer")
      icon - icon applied to every registered entry via Action.SMALL_ICON; may be null
      excludedNames - action-map keys to skip outright, matched case-insensitively against the raw (un-prettified) key -- for contextual/"abort this in-progress gesture" natives that have no single dedicated trigger key, or SNT press/release-pair overlays (e.g., "hide annotations (hold)") that only make sense as a held key, never as a one-shot palette command
      excludedTriggers - keystrokes whose bound action should be skipped (the keystroke itself does not need to be a valid trigger for this viewer; unresolved ones are ignored)

    • registerCommandFinderAccelerator

      protected static void registerCommandFinderAccelerator(InputMap sntIMap, ActionMap sntAMap, SNTCommandFinder commandFinder)
      Wires commandFinder's own show/toggle shortcut (SNTCommandFinder.getAccelerator()) into this viewer's keybindings, so it fires while the Bvv/Bdv window itself has focus. Standard Swing accelerators (as installed by SNTCommandFinder.attach(JDialog)) don't reach here: BDV/BVV's behavior-based trigger layer intercepts keystrokes before a component's ordinary InputMap/ActionMap ever sees them (see the identical constraint noted where sntIMap/ sntAMap are built in Bvv/Bdv), so the shortcut has to be added to that same sntIMap/sntAMap pair instead, alongside SNT's other viewer-overlay bindings.
      Parameters:
      sntIMap - the viewer's own SNT-overlay InputMap, not yet installed via addInputMap
      sntAMap - the matching ActionMap, not yet installed via addActionMap
      commandFinder - the palette whose accelerator should open/focus it; a no-op if null

    • registerSntKeybindings

      protected void registerSntKeybindings(InputMap sntIMap, ActionMap sntAMap, AbstractBigViewer.Actions actions, Action addMarker, AbstractBigViewer.AbstractTracer tracer)
      Registers SNT's viewer keybindings shared by Bvv and Bdv: M (marker), H (hold to hide annotations), L (secondary layer), P (pick sigma point) and, if a tracer is available, the tracing shortcuts (G, Shift+G, Enter, Esc, Z, Space). They must go through BDV/BVV's keybindings system, since its input trigger layer shadows ordinary Swing InputMaps. Same sntIMap/sntAMap constraints as registerCommandFinderAccelerator(javax.swing.InputMap, javax.swing.ActionMap, sc.fiji.snt.gui.SNTCommandFinder).
      Parameters:
      sntIMap - the viewer's own SNT-overlay InputMap, not yet installed
      sntAMap - the matching ActionMap, not yet installed
      actions - the viewer's AbstractBigViewer.Actions
      addMarker - the action bound to M
      tracer - the viewer's tracer, or null if tracing is unavailable

    • registerKeyframeCapture

      protected void registerKeyframeCapture(InputMap sntIMap, ActionMap sntAMap)
      Registers the keyframe hotkeys: K captures a Keyframe and appends it to a running script-ready kfs block that is printed to the console and copied to the clipboard, and Shift+K clears that block. Same sntIMap/sntAMap constraints as registerCommandFinderAccelerator(javax.swing.InputMap, javax.swing.ActionMap, sc.fiji.snt.gui.SNTCommandFinder).
      Parameters:
      sntIMap - the viewer's own SNT-overlay InputMap, not yet installed
      sntAMap - the matching ActionMap, not yet installed

    • captureKeyframe

      public Keyframe captureKeyframe()
      Captures the current viewer state as a Keyframe: transform, camera/slab parameters (BVV only), timepoint, and visible actors.
      Returns:
      the current state as a Keyframe
      Throws:
      IllegalStateException - if no viewer is active

    • playback

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

    • playback

      public void playback(List<Keyframe> keyframes, int from, int to)
      Plays back keyframes from to to (both inclusive, 0-based).
      Parameters:
      keyframes - ordered list of all keyframes
      from - start index
      to - end index
      See Also:

    • renderFrames

      public void renderFrames(List<Keyframe> keyframes, String outputDir)
      Renders an animation between keyframes, saving each frame as a PNG. The transform is interpolated using SimilarityTransformAnimator and the timepoint linearly (if specified in both keyframes); visibility and slab bounds snap at keyframe boundaries. The first keyframe's Keyframe.frames is ignored. Must be called from a non-EDT thread: blocks until done.
      Parameters:
      keyframes - ordered list of keyframes (at least 2)
      outputDir - directory for the PNGs (created if needed); if null, frames are played back live without saving
      Throws:
      IllegalArgumentException - if arguments are inconsistent
      IllegalStateException - if no viewer is active

    • getViewerState

      protected abstract bdv.viewer.SynchronizedViewerState getViewerState()
      Returns the viewer's state (sources, groups, timepoint) or null if not yet live

    • loadViewerSettings

      protected abstract void loadViewerSettings(String path) throws Exception
      Loads viewer settings (display ranges, colors, etc.) from an XML file.
      Parameters:
      path - the path of the settings file
      Throws:
      Exception - if the settings could not be loaded

    • saveViewerSettings

      protected abstract void saveViewerSettings(String path) throws Exception
      Saves viewer settings (display ranges, colors, etc.) to an XML file.
      Parameters:
      path - the path of the settings file
      Throws:
      Exception - if the settings could not be saved

    • getSettingsTag

      protected abstract String getSettingsTag()
      Tag identifying the viewer type in the names of settings files (e.g., "bdv" or "bvv")

    • initBrightnessOrRestore

      protected void initBrightnessOrRestore(bdv.viewer.ViewerState state, bdv.viewer.ConverterSetups setups, String title, String id, String label)
      Initializes the display range of the sources. If saved settings for this dataset exist, and the user agrees to restore them, they are loaded instead of computing the display range
      Parameters:
      state - the viewer state
      setups - the converter setups
      title - the dataset title (null to use the name of the first source)
      id - the dataset identifier, e.g., path (null to use the title)
      label - short description of the viewer/dataset, for logging

    • setupIdToName

      protected Map<Integer,String> setupIdToName()
      Maps current converter setup ids to source names

    • showShortcuts

      protected abstract void showShortcuts(GuiUtils gui)
      Displays the dialog listing the viewer's keyboard shortcuts

    • getConverterSetups

      protected abstract bdv.viewer.ConverterSetups getConverterSetups()
      Returns the viewer's per-source display settings (levels, LUTs) or null if not yet live

    • getCamParams

      protected double[] getCamParams()
      Returns the current {dCam, nearClip, farClip}. Defaults to BVV's defaults: viewers without a perspective camera (BDV) keep this implementation.

    • applyCamParams

      protected void applyCamParams(double dCam, double nearClip, double farClip)
      Applies camera/slab parameters from a Keyframe. No-op by default

    • awaitRender

      protected void awaitRender(Runnable trigger) throws InterruptedException
      Runs trigger (which updates the viewer and requests a repaint) and blocks until the resulting frame has been rendered. Must not be called on the EDT. The default implementation waits a fixed interval.
      Parameters:
      trigger - the action that changes the scene
      Throws:
      InterruptedException - if interrupted while waiting

    • addTree

      public void addTree(Tree tree)
      Adds a Tree to the viewer overlay, assigning it a unique display label.
      Parameters:
      tree - the Tree to render; must not be null or empty

    • addTree

      protected void addTree(Tree tree, boolean syncNow)
      Internal add with optional immediate overlay sync. Subclasses may override if they need to track per-tree state beyond the shared map.

    • add

      public void add(Object o)
      Script-friendly dispatcher: accepts a Tree, DirectedWeightedGraph, File[], or any Collection of supported objects.
      Parameters:
      o - the object to add
      Throws:
      IllegalArgumentException - if the type is not supported

    • add

      protected void add(Object o, boolean syncNow)
      Internal dispatcher with deferred sync support for batch operations.

    • addCollection

      protected void addCollection(Collection<?> collection, boolean syncNow)
      Adds all elements of a collection, optionally syncing once at the end.

    • add

      public void add(File[] reconstructionFiles)
      Loads reconstruction files (SWC, JSON, TRACES) and adds them to the viewer. Trees are colored with distinct colors and the overlay is synced once at the end. Subclasses may override for async loading with progress feedback (see Bvv).
      Parameters:
      reconstructionFiles - the files to load; null or empty is silently ignored

    • removeTree

      public boolean removeTree(String treeLabel)
      Removes the tree with the given label from the overlay.
      Parameters:
      treeLabel - the display label of the tree to remove
      Returns:
      true if a tree with that label existed and was removed

    • clearAllTrees

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

    • getRenderedTrees

      public Collection<Tree> getRenderedTrees()
      Returns a snapshot of the currently rendered trees (insertion order). Deliberately an independent copy, not a live view over renderedTrees - see renderedTreesLock': a live view (the previous behavior) is vulnerable to a ConcurrentModificationException if another thread mutates renderedTrees while this collection is being iterated, which for a caller like Bvv.OverlayRenderer#updatePaths(Collection) (iterating well after this method returns) is a real, previously-observed race during active interactive tracing.
      Returns:
      collection of rendered trees (insertion order)

    • getMarkerManager

      public BookmarkManager getMarkerManager()
      Returns the marker manager panel, creating it lazily on first call via createMarkerManager().
      Returns:
      the marker manager for this viewer

    • hasMarkerManager

      public boolean hasMarkerManager()
      Checks whether a BookmarkManager has already been created for this viewer, without triggering its (lazy, non-trivial) creation as getMarkerManager() would. Useful for display/logging code that wants to report marker counts only if the panel is already in use.

    • setCalibration

      public void setCalibration(double[] spacing, String unit)
      Sets the voxel calibration for the viewer.
      Parameters:
      spacing - voxel sizes [x, y, z]
      unit - physical unit string (e.g., "um")

    • getCalibration

      public double[] getCalibration()
      Returns the current voxel sizes, or null if not set.

    • getBoundingBox

      public BoundingBox getBoundingBox()
      Returns the world-space bounding box of the primary loaded volume, assuming an origin at (0,0,0), i.e., no world-origin offset or per-source transform is factored in.
      Returns:
      the volume's bounding box, or null if dimensions/calibration are not yet known

    • getPrimarySourcePath

      public String getPrimarySourcePath()
      Returns the file path/URL of the primary loaded volume, for display/logging purposes (e.g., a Notes entry documenting the dataset being traced).

      Only sources registered through spimDataFilePaths (i.e., datasets opened via AbstractSpimData-based show(...) overloads, such as N5/Zarr/BDV/IMS data) are tracked. There is no guaranteed order if more than one source is loaded; this simply returns the first entry found.

      Returns:
      the source path/URL, or null if unknown/not applicable

    • getPhysicalUnit

      public String getPhysicalUnit()
      Derives the best available physical unit string. Subclasses may override to add viewer-specific fallbacks (e.g., reading units from source VoxelDimensions).

    • getUniqueLabel

      protected String getUniqueLabel(Tree tree)
      Returns a display label for the tree that is unique within renderedTrees. Derived from the tree's own label, appending "(2)", "(3)" etc. as needed.

    • isPathRenderingEnabled

      protected abstract boolean isPathRenderingEnabled()
      Returns true if path/tree overlay rendering is currently enabled.

    • setPathRenderingEnabled

      protected abstract void setPathRenderingEnabled(boolean enabled)
      Enables or disables path/tree overlay rendering.

    • setPathOverlayOffset

      public abstract void setPathOverlayOffset(double offsetX, double offsetY, double offsetZ)
      Applies a world-space offset to all rendered path annotations.
      Parameters:
      offsetX - x offset in calibrated units
      offsetY - y offset in calibrated units
      offsetZ - z offset in calibrated units

    • getRenderingOptions

      public AbstractBigViewer.PathRenderingOptions getRenderingOptions()
      Returns the rendering options shared across this viewer's overlays.

    • blockMarkerPlacement

      protected boolean blockMarkerPlacement()
      Whether M-key marker placement should be blocked in the current mode, showing a viewer message if so. True whenever SNTUI is present in "classic-mode-tracing", since the image canvas already has a fully working Bookmarks tab (Shift+B, right-click, etc.). Shared by Bvv/Bdv's own M-key bindings.
      Returns:
      true if placement was blocked (and a message shown); callers should return immediately without placing a marker

    • optionsButton

      protected JButton optionsButton(AbstractBigViewer.Actions actions)
      Builds the "Options" button (Import Reconstructions.../Remove All Annotations...) shared by Bvv/Bdv's own SNT Annotations toolbar.

    • autoBrightnessButton

      protected JButton autoBrightnessButton(AbstractBigViewer.Actions actions)
      Builds the "Auto Brightness/Contrast" options button (Current Source.../Active Source(s).../All Sources...) for the scene-control toolbar. See applyAutoBrightness(BrightnessScope).

    • tracingStatusRow

      protected JComponent tracingStatusRow(AbstractBigViewer.Actions actions, AbstractBigViewer.AbstractTracer tracer)
      Builds the second row shown below the SNT Annotations toolbar whenever this viewer has an active AbstractBigViewer.AbstractTracer (undo/cancel controls, secondary-layer toggle, progress bar). Shared by Bvv/Bdv, which both keep the returned components (see tracingStatusBar, tracingCancelButton, tracingUndoButton, secondaryLayerIndicator) in sync from their own AbstractBigViewer.AbstractTracer subclass.

    • showCalibrationDialog

      public void showCalibrationDialog(Component parent)
      Prompts the user for voxel spacing and its physical unit, and updates calibration.

      Confirming here also propagates to snt via SNT.setImageMetadata(int, int, int, double, double, double, java.lang.String).Dimensions are left untouched (passed as 0, which setImageMetadata treats as "no change").

      Parameters:
      parent - component used to anchor the dialog

    • buildBaseSceneControlToolbar

      protected JToolBar buildBaseSceneControlToolbar()
      Builds the shared scene-control toolbar: fit-source button, align-plane buttons (XY, XZ, YZ), minimap toggle, text-overlay toggle, scale-bar toggle. Subclasses call this and may prepend or append viewer-specific buttons.
      Returns:
      a partially populated JToolBar ready for additional buttons