SequenceRecorder
================

Sequence-based workflow recording using Slicer Sequences.

Records full segmentation workflows for step-by-step playback review:
- Segmentation state at each brush stroke
- Slice positions (Red/Yellow/Green)
- 3D camera position
- Effect parameter node
- Text notes for reviewer annotations

Integrates with existing ActionRecorder infrastructure to provide visual
state capture alongside stroke data.

See ADR-016 for architecture context.

Classes
-------

.. py:class:: SequenceRecorder

   Record full segmentation workflow using Slicer Sequences.
   
   This class captures visual state (how the segmentation looks) at each step,
   complementing ActionRecorder which captures action data (what happened).
   
   Usage:
       recorder = SequenceRecorder()
   
       # Start recording with a segmentation node
       recorder.start_recording(segmentation_node, reference_volume)
   
       # Record a step after each brush stroke
       recorder.record_step("Geodesic at (128, 100, 45)")
   
       # Add standalone notes
       recorder.add_note("Reviewer noted boundary uncertainty")
   
       # Navigate to a specific step
       recorder.goto_step(5)
   
       # Clean up
       recorder.cleanup()
   
   Attributes:
       step_count: Number of recorded steps.
       is_recording: True if currently recording.

   **Methods:**

   .. py:method:: __init__()

      Initialize the sequence recorder.

   .. py:method:: step_count()

      Return number of recorded steps.

   .. py:method:: is_recording()

      Return True if currently recording.

   .. py:method:: start_recording()

      Initialize sequences for recording.

   .. py:method:: record_step()

      Record current state as a new step.

   .. py:method:: add_note()

      Add a text note at the current step.

   .. py:method:: goto_step()

      Navigate to a specific step in the recording.

   .. py:method:: get_note_at_step()

      Get the note text at a specific step.

   .. py:method:: stop_recording()

      Stop recording but keep sequences for playback.

   .. py:method:: cleanup()

      Clean up all sequences and browser node.

   .. py:method:: get_browser_node()

      Get the sequence browser node for direct manipulation.

   .. py:method:: get_sequence()

      Get a specific sequence by name.


.. py:class:: ViewGroupManager

   Manage Slicer View Groups for synchronized slice navigation.
   
   Provides native Slicer view linking using ViewGroups and LinkedControl,
   replacing manual slice synchronization.
   
   Usage:
       manager = ViewGroupManager()
   
       # Enable linked navigation
       manager.enable_linking()
   
       # Views now sync automatically
   
       # Disable if needed
       manager.disable_linking()
   
       # Clean up observers on module close
       manager.cleanup()

   **Methods:**

   .. py:method:: __init__()

      Initialize the view group manager.

   .. py:method:: is_linked()

      Return True if view linking is enabled.

   .. py:method:: enable_linking()

      Enable linked control for all slice views.

   .. py:method:: disable_linking()

      Disable linked control for all slice views.

   .. py:method:: set_linked()

      Set the linked state.

   .. py:method:: setup_slice_observer()

      Set up observer on a slice node for bidirectional sync.

   .. py:method:: get_slice_offset()

      Get the current slice offset for a view.

   .. py:method:: get_slice_range()

      Get the slice offset range for a view.

   .. py:method:: set_slice_offset()

      Set the slice offset for a view.

   .. py:method:: cleanup()

      Remove all observers.


.. py:class:: SceneViewBookmarks

   Manage Scene View bookmarks for interesting slices.
   
   Scene Views capture complete visualization state:
   - All slice positions
   - 3D camera position
   - Node visibility
   - Display properties
   - Window/level
   
   Usage:
       bookmarks = SceneViewBookmarks()
   
       # Create a bookmark
       idx = bookmarks.add_bookmark("Interesting boundary at slice 45")
   
       # List bookmarks
       for name, desc in bookmarks.list_bookmarks():
           print(f"{name}: {desc}")
   
       # Restore a bookmark
       bookmarks.restore_bookmark(0)
   
       # Clean up
       bookmarks.cleanup()

   **Methods:**

   .. py:method:: __init__()

      Initialize the bookmarks manager.

   .. py:method:: count()

      Return number of bookmarks.

   .. py:method:: add_bookmark()

      Save current view as a Scene View bookmark.

   .. py:method:: restore_bookmark()

      Restore a saved Scene View bookmark.

   .. py:method:: list_bookmarks()

      List all bookmarks.

   .. py:method:: get_bookmark_name()

      Get the name of a bookmark.

   .. py:method:: remove_bookmark()

      Remove a bookmark.

   .. py:method:: clear_all()

      Remove all bookmarks.

   .. py:method:: cleanup()

      Clean up all bookmarks.


Functions
---------

.. py:function:: step_count()

   Return number of recorded steps.

.. py:function:: is_recording()

   Return True if currently recording.

.. py:function:: start_recording()

   Initialize sequences for recording.
   
   Args:
       segmentation_node: The segmentation node to record.
       reference_volume: Optional reference volume for geometry.
   
   Returns:
       True if recording started successfully, False otherwise.

.. py:function:: record_step()

   Record current state as a new step.
   
   Args:
       action_description: Optional description of the action.
   
   Returns:
       The step index recorded, or -1 if not recording.

.. py:function:: add_note()

   Add a text note at the current step.
   
   Args:
       text: The note text.

.. py:function:: goto_step()

   Navigate to a specific step in the recording.
   
   Args:
       step: The step index to navigate to.
   
   Returns:
       True if navigation succeeded, False otherwise.

.. py:function:: get_note_at_step()

   Get the note text at a specific step.
   
   Args:
       step: The step index.
   
   Returns:
       The note text, or None if no note at that step.

.. py:function:: stop_recording()

   Stop recording but keep sequences for playback.

.. py:function:: cleanup()

   Clean up all sequences and browser node.

.. py:function:: get_browser_node()

   Get the sequence browser node for direct manipulation.
   
   Returns:
       The vtkMRMLSequenceBrowserNode, or None if not recording.

.. py:function:: get_sequence()

   Get a specific sequence by name.
   
   Args:
       name: Sequence name (e.g., "segmentation", "notes", "slice_Red").
   
   Returns:
       The sequence node, or None if not found.

.. py:function:: is_linked()

   Return True if view linking is enabled.

.. py:function:: enable_linking()

   Enable linked control for all slice views.
   
   This enables Slicer's native view synchronization:
   - Slice offset (position)
   - Zoom/field of view
   - Pan
   - Orientation changes
   
   Args:
       view_group: View group ID to use (default 0).

.. py:function:: disable_linking()

   Disable linked control for all slice views.

.. py:function:: set_linked()

   Set the linked state.
   
   Args:
       linked: True to enable linking, False to disable.

.. py:function:: setup_slice_observer()

   Set up observer on a slice node for bidirectional sync.
   
   This allows the UI (e.g., slider) to update when the user
   navigates by other means (dragging in slice view).
   
   Args:
       callback: Function to call when slice changes: (caller, event) -> None
       slice_name: Name of slice node to observe (default "Red").
   
   Returns:
       True if observer was set up, False otherwise.

.. py:function:: get_slice_offset()

   Get the current slice offset for a view.
   
   Args:
       slice_name: Name of the slice view.
   
   Returns:
       The slice offset, or None if not available.

.. py:function:: get_slice_range()

   Get the slice offset range for a view.
   
   Args:
       slice_name: Name of the slice view.
   
   Returns:
       Tuple of (min_offset, max_offset), or None if not available.

.. py:function:: set_slice_offset()

   Set the slice offset for a view.
   
   Note: If view linking is enabled, this will affect all linked views.
   
   Args:
       offset: The slice offset value.
       slice_name: Name of the slice view to set.
   
   Returns:
       True if set successfully, False otherwise.

.. py:function:: cleanup()

   Remove all observers.

.. py:function:: count()

   Return number of bookmarks.

.. py:function:: add_bookmark()

   Save current view as a Scene View bookmark.
   
   Args:
       description: Description of what's interesting.
       name: Optional name for the bookmark.
   
   Returns:
       Index of the created bookmark, or -1 on failure.

.. py:function:: restore_bookmark()

   Restore a saved Scene View bookmark.
   
   Args:
       index: Index of the bookmark to restore.
   
   Returns:
       True if restored successfully, False otherwise.

.. py:function:: list_bookmarks()

   List all bookmarks.
   
   Returns:
       List of (name, description) tuples.

.. py:function:: get_bookmark_name()

   Get the name of a bookmark.
   
   Args:
       index: Bookmark index.
   
   Returns:
       The bookmark name, or None if invalid.

.. py:function:: remove_bookmark()

   Remove a bookmark.
   
   Args:
       index: Index of the bookmark to remove.
   
   Returns:
       True if removed successfully, False otherwise.

.. py:function:: clear_all()

   Remove all bookmarks.

.. py:function:: cleanup()

   Clean up all bookmarks.