Interactive pickers

cruiseplan.interactive package.

This package contains interactive components for cruise planning:

campaign_selector: Interface for selecting and managing PANGAEA campaign data
station_picker: Main interactive matplotlib-based tool for planning cruise stations and transects
widgets: Custom matplotlib widgets for the interactive interface (mode indicators, status displays)

These modules provide the graphical user interface components for interactive cruise planning, allowing users to visually design cruise tracks, select stations, and integrate with external data sources through an intuitive matplotlib-based interface.

cruiseplan.interactive.campaign_selector module

PANGAEA campaign selection and management interface.

class cruiseplan.interactive.campaign_selector.CampaignSelector(campaign_data: list[dict[str, Any]] | None = None)[source]

Bases: object

Manages PANGAEA campaign data loading and selection interface.

Provides checkbox interface for toggling campaign visibility on interactive maps. Allows users to selectively display or hide PANGAEA cruise tracks for better visualization and planning.

campaign_data

List of campaign datasets with coordinate and metadata information.

Type:: List[Dict]

selected_campaigns

Dictionary mapping campaign names to their visibility state.

Type:: Dict[str, bool]

campaign_artists

Dictionary mapping campaign names to their matplotlib artist objects.

Type:: Dict[str, Any]

ax_campaign

Matplotlib axes for the campaign selection interface.

Type:: Optional[plt.Axes]

check_buttons

Matplotlib CheckButtons widget for campaign selection.

Type:: Optional[CheckButtons]

map_ax

Reference to the main map axes for updating campaign display.

Type:: Optional[plt.Axes]

__init__(campaign_data: list[dict[str, Any]] | None = None)[source]

Initialize the campaign selector.

Parameters:: campaign_data (Optional[List[Dict]], optional) – Pre-loaded campaign track data from PANGAEA (default: None).

get_selected_campaigns() → list[dict][source]

Return list of currently selected campaigns.

Returns:: List of campaign dictionaries that are currently visible/selected.
Return type:: List[Dict]

save_selection(file_path: str) → None[source]

Save current campaign selection to a pickle file.

Parameters:: file_path (str) – Path where the selected campaign data will be saved.

setup_ui(ax_campaign: Axes) → None[source]

Initialize the campaign selection interface.

Parameters:: ax_campaign (plt.Axes) – Matplotlib axes where the campaign selector will be displayed.

toggle_all(state: bool) → None[source]

Toggle all campaigns on/off.

Parameters:: state (bool) – True to show all campaigns, False to hide all campaigns.

cruiseplan.interactive.station_picker module

Interactive station picker for oceanographic cruise planning.

This module provides the StationPicker class, which creates an interactive matplotlib-based interface for planning cruise stations, transects, and survey areas.

class cruiseplan.interactive.station_picker.StationPicker(campaign_data: list[dict] | None = None, output_file: str = 'stations.yaml', bathymetry_stride: int = 10, bathymetry_source: str = 'etopo2022', bathymetry_dir: str = 'data', overwrite: bool = False)[source]

Bases: object

Interactive matplotlib-based tool for oceanographic cruise planning.

Combines the original functionality with modern widget integration for enhanced user experience and accessibility. Provides interactive tools for placing stations, drawing transects, and defining survey areas on a bathymetric map with PANGAEA campaign data overlay.

MODES

Available interaction modes: navigation, point, line, area.

Type:: List[str]

KEY_BINDINGS

Keyboard shortcuts for mode switching and actions.

Type:: Dict[str, str]

mode

Current interaction mode.

Type:: str

output_file

Path for saving cruise configuration.

Type:: str

stations

List of planned sampling stations.

Type:: List[Dict]

transects

List of planned transects.

Type:: List[Dict]

areas

List of planned survey areas.

Type:: List[Dict]

history

Undo history for operations.

Type:: List[Tuple[str, Dict, any]]

campaigns

PANGAEA campaign data for visualization.

Type:: List[Dict]

fig

Main matplotlib figure.

Type:: plt.Figure

ax_map

Main map axes for bathymetry and planning elements.

Type:: plt.Axes

KEY_BINDINGS: ClassVar[dict[str, str]] = {'a': 'area', 'escape': 'exit', 'l': 'line', 'n': 'navigation', 'p': 'point', 'r': 'remove', 's': 'line', 'u': 'remove_last', 'w': 'point', 'y': 'save'}

MODES: ClassVar[list[str]] = ['navigation', 'point', 'line', 'area']

__init__(campaign_data: list[dict] | None = None, output_file: str = 'stations.yaml', bathymetry_stride: int = 10, bathymetry_source: str = 'etopo2022', bathymetry_dir: str = 'data', overwrite: bool = False)[source]

Initialize the station picker interface.

Parameters:

campaign_data (List[Dict], optional) – Pre-loaded campaign track data from PANGAEA
output_file (str) – Output filename for saving cruise plans
bathymetry_stride (int) – Downsampling factor for bathymetry data (default: 10, higher = faster but less detailed)
bathymetry_source (str) – Bathymetry data source: “etopo2022” or “gebco2025” (default: etopo2022)
bathymetry_dir (str) – Directory containing bathymetry data files (default: “data”)
overwrite (bool) – Whether to overwrite existing files without prompting (default: False)

get_cruise_data() → dict[source]

Get the current cruise plan data.

Returns:: Dictionary containing current stations and transects data.
Return type:: Dict

set_mode(new_mode: str) → None[source]

Change the current interaction mode and update the display.

Parameters:: new_mode (str) – New interaction mode. Must be one of MODES or “remove”.

show()[source]: Display the interactive cruise planning interface.

cruiseplan.interactive.widgets module

Custom matplotlib widgets for oceanographic cruise planning interface.

class cruiseplan.interactive.widgets.ModeIndicator(ax: Axes, modes: list[str], initial_mode: str = 'navigation')[source]

Bases: Widget

Visual indicator for current interaction mode.

Shows current mode (navigation/point/line/area) with clear styling. Provides visual feedback to users about the current interaction state.

ax

Matplotlib axes for the widget display.

Type:: plt.Axes

modes

List of available interaction modes.

Type:: List[str]

current_mode

Currently active interaction mode.

Type:: str

callbacks

Dictionary of callback functions for mode changes.

Type:: Dict[str, Callable]

colors

Color mapping for different modes.

Type:: Dict[str, str]

text_obj

Matplotlib text object for mode display.

Type:: Optional[plt.Text]

__init__(ax: Axes, modes: list[str], initial_mode: str = 'navigation')[source]

Initialize the mode indicator widget.

Parameters:

ax (plt.Axes) – Matplotlib axes for widget placement.
modes (List[str]) – List of available interaction modes.
initial_mode (str, optional) – Initial mode to display (default: “navigation”).

on_mode_change(mode: str, callback: Callable[[], None]) → None[source]

Register callback for mode changes.

Parameters:

mode (str) – Mode for which to register the callback.
callback (Callable) – Function to call when mode changes to the specified mode.

set_mode(mode: str) → None[source]

Change the current mode.

Parameters:: mode (str) – New mode to set. Must be one of the available modes.

class cruiseplan.interactive.widgets.StatusDisplay(ax: Axes)[source]

Bases: Widget

Real-time status display for coordinates, depth, and operation counts.

Shows current mouse coordinates, bathymetric depth, and counts of planned stations, transects, and areas.

ax

Matplotlib axes for the widget display.

Type:: plt.Axes

status_lines

List of matplotlib text objects for status display lines.

Type:: List[plt.Text]

__init__(ax: Axes)[source]

Initialize the status display widget.

Parameters:: ax (plt.Axes) – Matplotlib axes for widget placement.

update_coordinates(lat: float | None, lon: float | None) → None[source]

Update coordinate display, using Degrees Decimal Minutes format.

Parameters:

lat (Optional[float]) – Latitude coordinate in decimal degrees.
lon (Optional[float]) – Longitude coordinate in decimal degrees.

update_counts(stations: int, transects: int, areas: int) → None[source]

Update operation counters.

Parameters:

stations (int) – Number of planned stations.
transects (int) – Number of planned transects.
areas (int) – Number of planned survey areas.

update_depth(depth: float | None) → None[source]

Update depth display, handling positive elevation and negative depth.

Parameters:: depth (Optional[float]) – Depth/elevation value in meters (negative for depth, positive for elevation).