brain_deer.application.brain_deer_api¶

BrainDeer API - Core interface for plugins and external tools 🧠🦌

This API provides a comprehensive interface for plugins to interact with BrainDeer’s core functionality. It’s designed to be stable and easy to use for external researchers developing custom tools.

Key Features: - Event-driven architecture for plugin communication - Comprehensive data access methods - 3D visualization controls - File management utilities - Thread-safe operations

@author: maikemustin

Classes¶

BrainDeerAPI

Main API interface for BrainDeer plugins and external tools.

Module Contents¶

class brain_deer.application.brain_deer_api.BrainDeerAPI(main_window)¶

Main API interface for BrainDeer plugins and external tools.

This class provides access to all core BrainDeer functionality in a clean, documented interface that external researchers can easily use.

set_crosshair(x, y, z)¶: Set crosshair position and emit crosshair_moved event.

get_crosshair()¶: Get current crosshair position.

get_crosshair_world()¶: Get current crosshair position in world coordinates.

zoom(factor)¶: Multiplicatively zoom the 2D slice views.

available_colormaps() → list¶: Colormap names supported by the 2D viewer layers.

rotate_camera_3d(azimuth: float = 0.0, elevation: float = 0.0, roll: float = 0.0)¶: Rotate the 3D camera by degrees around the current focal point.

reset_camera_3d()¶: Reset the 3D camera to frame the whole scene.

set_camera_view_3d(view: str)¶: Snap the 3D camera to a canonical anatomical viewpoint.

set_background_color_3d(r: float, g: float, b: float)¶: Set the 3D scene background color (RGB in 0..1).

set_layout(mode: str)¶: Set viewer tile layout: ‘2x2’, ‘1x3’, or ‘3x1’.

set_orientation(mode: str)¶: Set radiological/neurological display orientation.

capture_screenshot(path: str, scale_factor: float = 2.0, white_background: bool = False) → bool¶: Render the viewer to an image file (PNG/JPEG/TIFF by extension).

register_interaction_handler(callback)¶: Register a plugin mouse handler: callback(phase, view_name, x, y, button).

begin_interaction_capture(owner: str) → bool¶

Claim exclusive left-drag (press/move/release) for owner.

Returns False if another owner already holds it. While held, drags on the 2D views go only to registered interaction handlers, not the crosshair.

interaction_capture_owner()¶: Return the current capture owner token, or None.

add_view_overlay_item(view_name: str, item) → bool¶: Add a pyqtgraph item to a 2D view’s ViewBox. Returns success.

add_scene_actor(actor) → bool¶: Add a VTK actor to the 3D renderer. Returns success.

set_selected_file(filename: str) → bool¶: Select a loaded layer in the viewer (same as picking it in the file dropdown).

subscribe_to_event(event_name: str, handler: collections.abc.Callable, priority: brain_deer.application.events.EventPriority = EventPriority.NORMAL, plugin_name: str = 'unknown')¶

Subscribe to an event in the BrainDeer event system.

Parameters:

event_name – Name of the event to listen for
handler – Function to call when event occurs
priority – Handler priority level
plugin_name – Name of the subscribing plugin

emit_event(event_name: str, data: Any = None)¶

Emit an event that other plugins can listen to.

Parameters:

event_name – Name of the event
data – Optional data to pass with the event

unsubscribe_from_event(event_name: str, handler: collections.abc.Callable = None, plugin_name: str = None)¶

Unsubscribe from an event.

Parameters:

event_name – Name of the event
handler – Specific handler to remove
plugin_name – Plugin name

get_available_events() → dict¶: Get list of all available events plugins can listen to.

get_current_data_info() → dict | None¶: Get comprehensive information about currently selected data.

get_data_at_position(x: int, y: int, z: int, filename: str = None) → float | None¶

Get data value at specific coordinates.

Parameters:

x – Coordinates
y – Coordinates
z – Coordinates
filename – File to query (uses current if None)

Returns:

Data value at position or None if invalid

get_slice_data(view: str, position: int = None, filename: str = None) → Any | None¶

Get 2D slice data for a specific view.

Parameters:

view – ‘axial’, ‘coronal’, or ‘sagittal’
position – Slice position (uses current crosshair if None)
filename – File to query (uses current if None)

Returns:

2D numpy array or None if invalid

load_file(file_path: str, layer_overrides: dict | None = None) → bool¶

Load a file programmatically.

Parameters:

file_path – Path to the file to load
layer_overrides – Optional per-layer defaults (label, show_in_3d, render_mode, opacity, colormap, …) applied after the usual NIfTI defaults — used by Lead-Lizard / CLI host launches.

Returns:

True if successful, False otherwise

remove_file(filename: str) → bool¶

Remove a loaded file.

Parameters:: filename – Name of file to remove
Returns:: True if successful, False otherwise

open_bids_dataset(root: str) → dict¶: Index a BIDS dataset and show it in the BIDS tab.

load_bids_bundle(bundle: str, subject: str | None = None, session: str | None = None) → dict¶: Load a named BIDS bundle preset into the Files tab.

switch_bids_subject(subject: str, session: str | None = None, bundle: str | None = None) → dict¶: Hot-swap BIDS layers to another subject; keep scene display settings.

import_bids_from_folder(source: str, output: str, *, mode: str = 'nifti', subject: str = '01', session: str = '01', dataset_name: str = 'BrainDeer import') → dict¶: Import DICOM or flat NIfTI folder as a new BIDS dataset.

run_bids_bundle_all_subjects(bundle: str, session: str | None = None) → dict¶: Load a bundle preset for every subject in the open BIDS dataset.

atlas_browser_widget(*, activate: bool = True)¶: Return the Atlas Browser 2 widget, optionally activating the plugin.

stimulation_manager_widget(*, activate: bool = True)¶: Return the Lead-DBS Stimulation Manager widget, optionally activating it.

warpdrive_widget(*, activate: bool = True)¶: Return the WarpDrive widget, optionally activating the plugin.

blender_widget(*, activate: bool = True)¶: Return the BrainDeer × Blender widget, optionally activating the plugin.

set_file_visibility(filename: str, visible: bool) → bool¶

Set visibility of a loaded file.

Parameters:

filename – Name of file
visible – Whether file should be visible

Returns:

True if successful, False otherwise

create_roi(roi_type: str, coordinates: list, name: str = None) → str¶

Create a region of interest.

Parameters:

roi_type – Type of ROI (‘sphere’, ‘box’, ‘polygon’)
coordinates – ROI coordinates
name – Optional ROI name

Returns:

ROI identifier

take_measurement(measurement_type: str, coordinates: tuple, value: float, units: str = None) → str¶

Record a measurement.

Parameters:

measurement_type – Type of measurement
coordinates – Location of measurement
value – Measured value
units – Optional units

Returns:

Measurement identifier

show_notification(message: str, level: str = 'info')¶

Show a notification to the user.

Parameters:

message – Message to display
level – ‘info’, ‘warning’, or ‘error’

get_plugin_data_directory(plugin_name: str) → str¶

Get a directory for plugin data storage.

Parameters:: plugin_name – Name of the plugin
Returns:: Path to plugin data directory

surface_open() → bool¶: Focus/expand the Surface Studio panel (rendered in the main 3D view).

surface_list_resources(kind: str = None, category: str = None) → list¶: List available atlas / surface / tract resources (catalogue entries).

surface_get_atlas_regions(parcellation_path: str) → list¶: Return the ordered region names of a parcellation file.

surface_plot_cortical(lh_surface: str, lh_parc: str, data: str, rh_surface: str = None, rh_parc: str = None, cmap: str = 'viridis', vmin: float = None, vmax: float = None, threshold: float = None, view: str = 'left_lateral') → dict¶: Region-colour a cortical surface by data (CSV name->value or array file).

surface_plot_vertexwise(lh_surface: str, values: str, rh_surface: str = None, rh_values: str = None, cmap: str = 'viridis', view: str = 'left_lateral') → dict¶: Plot per-vertex scalar arrays directly on the surface.

surface_project_vol2surf(volume: str, lh_surface: str, rh_surface: str = None, method: str = 'trilinear', ribbon_mm: float = 2.0, cmap: str = 'viridis', view: str = 'left_lateral') → dict¶: Project a NIfTI volume onto surface vertices and plot the result.

surface_plot_voxelwise(volume, threshold=None, cmap: str = 'hot', view: str = 'left_lateral') → dict¶

Plot supra-threshold voxels of one or more volumes as coloured points in template space.

volume is a NIfTI path or a list of paths (e.g. both hemisphere maps); all are thresholded and concatenated into one scene + colorbar on a shared scale. Signed values get symmetric limits (+/-max|v|) so a diverging cmap such as red_blue centres at zero.

surface_plot_subcortical(label_volume: str, data: str = None, cmap: str = 'hot', view: str = 'left_lateral') → dict¶: Plot per-structure subcortical meshes from an aseg-style label volume.

surface_plot_tracts(tracts: str, cmap: str = 'fa', max_streamlines: int = 5000, view: str = 'left_lateral', color_by_scalars: bool = True) → dict¶

Load and plot white-matter tracts as tubes.

When color_by_scalars and the file carries per-point scalars (e.g. a fiber-filtering statistic in data_per_point), the tubes are coloured by that scalar over a colorbar. Signed scalars are given symmetric limits (±max|v|) so a diverging colormap such as "red_blue" centres at zero. Without scalars (or when disabled), tubes are orientation- coloured as before.

surface_plot_connectome(matrix: str, nodes: str, node_values: str = None, edge_threshold=None, node_cmap: str = 'hot', edge_cmap: str = 'jet', view: str = 'superior') → dict¶: Plot a connectome: node spheres + thresholded edge tubes from a matrix.

surface_set_view(view: str) → bool¶: Snap the Surface Studio camera to a canonical view (in the main 3D view).

surface_export_figure(path: str, views=None) → dict¶: Export a multi-view Surface Studio figure (PNG/SVG) from the 3D view.

display_to_image_coordinates(display_coords, view_name=None)¶

Convert display coordinates (after image flips) to image coordinates (before flips).

Honors the viewer’s radiological/neurological mode via the shared coords module (self-inverse: the same flip maps display<->image).

Parameters:

display_coords – (x, y, z) coordinates in display space
view_name – Optional view name for context

Returns:

(x, y, z) coordinates in image space

image_to_display_coordinates(image_coords, view_name=None)¶

Convert image coordinates (before flips) to display coordinates (after flips).

Honors the viewer’s radiological/neurological mode via the shared coords module.

Parameters:

image_coords – (x, y, z) coordinates in image space
view_name – Optional view name for context

Returns:

(x, y, z) coordinates in display space

get_corrected_crosshair()¶: Get crosshair position corrected for coordinate system flips. This returns coordinates in the image coordinate system (suitable for direct indexing).