widgets

Custom widgets for the ClearMap GUI.

This module provides reusable Qt widgets and compound controls used throughout the ClearMap graphical interface, including:

• OrthoViewer — orthogonal slice viewer for 3-D images.

• ProgressWatcher — progress monitoring with log-file polling.

• TwoListSelection — dual-list item picker (available ↔ selected).

• CheckableListWidget — list with per-item checkboxes.

• DataFrameWidget — simple table display for pandas DataFrames.

• WizardWidget — base class for multi-step dialogs built from .ui files.

• PatternDialog — file-pattern wizard for tiled acquisitions.

• SamplePickerDialog — experiment-folder picker with group support.

• LandmarksSelectorDialog — 3-D landmark selection for registration.

• StructurePickerWidget / StructureSelector — atlas region tree browser.

• PerfMonitor — CPU / RAM / GPU usage bars.

• ExtendableTabWidget — tab widget with an optional (+) button.

• FileDropListWidget — list that accepts file drag-and-drop.

• LandmarksWeightsPanel — slider panel for landmark weight tuning.

• GraphFilterList — AND/OR filter chain for graph properties.

• ComparisonsWidgetAdapter — group-comparison checkbox builder.

• GroupsWidgetAdapter — toolbox-based sample-group editor.

• NProcessesWidget — label + spin box for n_processes.

• BlockProcessingWidget — grouped controls for block-processing parameters.

• ClickableFrame — QFrame that emits a clicked signal.

class BlockProcessingWidget(parent=None, title: str = 'Block processing', with_overlap: bool = True, default_min: int = 1000000, default_max: int = 10000000)

Bases: QGroupBox

Reusable UI for block_processing parameters:

• size_min

• size_max

• overlap

• n_processes

The internal controls are spinboxes. We expose properties with value()/setValue() style methods to play nice with ParamLink.

property n_processes: int

property overlap: int | None

property size_max: int

property size_min: int

class CheckableListWidget(parent=None)

Bases: QWidget

A list widget where each item has a checkbox.

add_item(item)

check_item_at(index)

check_items(items_list)

clear()

delete_item(index)

get_checked_items()

get_item(item_name)

on_item_changed(item)

set_item_checked(item_name, state)

set_items(items)

check_state_changed

(index, checked, item_text).

Type:

Emitted when an item’s check state changes. Arguments

class ClickableFrame

Bases: QFrame

A QFrame that emits a clicked signal on mouse press.

mousePressEvent(self, a0: Optional[QMouseEvent])

clicked

Emitted on mouse press.

class ComparisonsModel(group_names: List[str] = <factory>, selected: List[Tuple[str, str]]=<factory>, sep: str = ' vs ')

Bases: object

all_pairs() → List[Tuple[str, str]]

parse_label(label: str) → Tuple[str, str]

serialize_label(pair: Tuple[str, str]) → str

group_names: List[str]

selected: List[Tuple[str, str]]

sep: str = ' vs '

class ComparisonsWidgetAdapter(layout, groups_sep: str = ' vs ')

Bases: object

Owns and (re)builds the comparisons area. Exposes only high-level ops so GroupAnalysisParams doesn’t touch low-level widgetry.

rebuild(model: ComparisonsModel, *, on_plot_group: Callable[[str], None], channels: List[str], on_channel_changed: Callable[[str], None], suffixes: List[str] = None, preselected_comparisons: List[Tuple[str, str]] | None = None) → None

selected_pairs(model: ComparisonsModel) → List[Tuple[str, str]]

class DataFrameWidget(df, n_digits=2, parent=None)

Bases: QWidget

A simple widget to display a pandas DataFrame

class ExtendableTabWidget(parent=None, with_add_tab=True)

Bases: QTabWidget

add_channel_widget(widget, name='')

current_channel()

get_channel_widget(name=None, return_idx=False)

get_channels_names()

handle_tab_bar_click(index)

remove_channel_widget(name)

set_current_channel_name(name)

addTabClicked

Emitted when the (+) tab is clicked.

channelChanged

channel name.

Type:

Emitted when a channel tab is clicked. Argument

channelRenamed

(old_name, new_name).

Type:

Emitted when a channel tab is renamed. Arguments

property last_real_tab_idx

class FileDropListWidget(parent=None, plus_btn=None, minus_btn=None)

Bases: QListWidget

addItem(self, aitem: Optional[QListWidgetItem])

addItem(self, label: str)

addItems(self, labels: Iterable[str])

add_files(file_paths=None)

dragEnterEvent(self, e: Optional[QDragEnterEvent])

dragMoveEvent(self, e: Optional[QDragMoveEvent])

dropEvent(self, event: Optional[QDropEvent])

get_items_text()

remove_selected()

itemsChanged

Emitted when items are added or removed.

class GraphFilterList(layout: QVBoxLayout, parent: QWidget | None = None)

Bases: QWidget

A vertical list of graph-filter rows with AND/OR combiners between them.

Compatibility guarantees for GraphFilterParams:

• The container layout is a QVBoxLayout named 'filterParamsVerticalLayout'.

• Each filter row widget is named 'filter_{idx}'.

• Between row i and i+1 a QFrame is inserted that contains two QRadioButton instances named 'filter_{i}_and_btn' (checked by default) and 'filter_{i}_or_btn'.

add_filter_row(*, title: str | None = None) → QWidget

Add a new filter row. Returns the filter QWidget to pass to GraphFilterParams.

row_count() → int

filtersChanged

Emitted when filters are added or modified.

class GroupPage(*, ui_name: str = 'sample_group_controls.ui', start_folder_getter=<function GroupPage.<lambda>>)

Bases: object

Wrapper around one sample_group_controls.ui page.

connect(on_changed: Callable[[], None]) → None

Wire config-writing callbacks. Idempotent.

connect_group_name_changed(on_name_changed: Callable[[str], None]) → None

property name: str

property paths: List[str]

property widget: QWidget

class GroupsWidgetAdapter(*, toolbox: QToolBox, container_layout: QLayout, add_btn: QPushButton, remove_btn: QPushButton, start_folder_getter=<function GroupsWidgetAdapter.<lambda>>, groups_ui_file='sample_group_controls.ui')

Bases: QWidget

ParamLink-compatible adapter:

• owns a list[GroupPage] kept in the same order as the toolbox pages.

• add/remove uses the provided buttons and QToolBox currentIndex.

• set_value/get_value talk only dict[str, list[str]].

add_group(name: str | None = None, paths: List[str] | None = None) → int

Add a new (possibly empty) group and return its index.

connect(on_changed: Callable[[], None]) → None

get_all_paths() → list[str]

get_paths(idx: int) → list[str]

get_value() → Dict[str, List[str]]

group_count() → int

remove_current_page() → Tuple[int, str]

set_paths(idx: int, paths: list[str]) → None

set_value(groups: Dict[str, List[str]]) → None

property group_names: list[str]

class Landmark(idx, dialog, color)

Bases: object

activate()

formatted_coords(img_type)

isChecked()

is_set()

Coords of both fixed and moving images are set

Returns

bool

property color

class LandmarksSelectorDialog(fixed_image_path, moving_image_path, fixed_image_landmarks_path, moving_image_landmarks_path, app=None)

Bases: WizardWidget

A dialog to select landmarks in 3D space for registration The dialog allows to select landmarks in two views (fixed and moving) The landmarks are displayed in two 3D viewers with matching colors The dialog saves the landmarks to files for the fixed and moving images

add_marker()

Add a new marker to the dialog

clear_landmarks()

Clear all the markers and the landmarks file paths and reset the dialog

connect_buttons()

Connect the buttons to their slots. This method is called automatically in the constructor

get_coords(img_type)

Get the coordinates of all the markers for the specified image type.

Parameters:

img_type (str) – The type of the image (‘fixed_image’ or ‘moving_image’).

Returns

np.ndarray

The array of marker coordinates.

get_new_color()

Get a new color for a marker (not already used) .. rubric:: Returns

str

The new color name

plot(lut=None, parent=None)

Plot the 3D landmarks onto the fixed and moving images using data viewers.

Parameters:

• lut (str) – Lookup table for coloring the 3D plot.

• parent (QWidget) – The parent widget for the plot.

remove_marker()

Remove the last marker

set_current_coords(x, y, z, img_type)

Set the coordinates for the specified image type.

Parameters:

• img_type (str) – The type of the image (‘fixed_image’ or ‘moving_image’).

• x (float) – The x-coordinate.

• y (float) – The y-coordinate.

• z (float) – The z-coordinate.

setup()

Setup the dialog after creation from the ui file. This method is called automatically in the constructor

write_coords()

Write the coordinates of the markers to the respective landmarks files

property colors

Get the ordered list of colors of the markers

Returns

list(str)

The markers colors

property current_color

Get the color of the currently selected marker

Returns

str

The color of the currently selected marker

property current_marker

Get the index of the currently selected marker .. rubric:: Returns

int : the index of the currently selected marker

class LandmarksWeightsPanel(parent: QWidget = None, value_to_model=None, model_to_value=None)

Bases: QFrame

Compact panel that renders one row per landmark-params file.

Each row contains a label, a 0–100 slider, and a value display.

Public API:

• set_items() — rebuild rows from names and optional initial weights.

• get_weights() — return current slider values (0–100) as integers.

• set_weights() — set slider values without rebuilding rows.

• valueChangedConnect() — Qt-like hook for external binding.

Optional transforms can be supplied to map between slider value (0–100) and model value (float). Defaults are identity; keep scaling (e.g. exp) in the controller.

getValue()

get_params_and_weights() → dict[str, int]

Return current mapping of param file name to raw slider value (0..100).

get_weights() → list[int]

Return current raw slider values (0..100).

setValue(weights)

set_items(names: list[str], weights: list[int] | None = None) → None

Rebuild rows for the given names; optionally seed slider positions.

set_weights(weights: list[int]) → None

Set weights without rebuilding rows (length must match).

valueChangedConnect(cb)

Qt-like connector used by our generic binder.

weightAtChanged

(index, value).

Type:

Emitted when a single slider changes. Arguments

weightsChanged

full list of weights (0–100).

Type:

Emitted when any slider changes. Argument

class ManageAssetsWidget(src_folder, params, sample_manager, app=None)

Bases: WizardWidget

action(action_name)

Perform the specified action on the selected assets. This will broadcast the action to the appropriate method of the sample manager

Parameters:

action_name (str) – The name of the action to perform

assert_all_images()

asset_types_to_assets(asset_names)

connect_buttons()

Connect the buttons to their slots. This method is called automatically in the constructor but should be implemented in the subclass

crop_dialog()

handle_selection_changed(itm_text)

Handle the selection change in the list_selection widget. This will update the asset info text browser with the information of the selected asset

Parameters:

itm_text (str) – The text of the selected item in the list_selection widget. This is a string representation of the asset type and channel, e.g. “(channel, asset_type)”

prompt_params(action_name)

Create a new dialog to prompt the user for the additional parameters of the specified action

Parameters:

action_name (str) – The name of the action to perform

Returns

dict

The parameters to use for the action

resample_assets()

resample_dialog()

setup()

Setup the dialog after creation from the ui file. This method is called automatically in the constructor but should be implemented in the subclass

update_resample_params(param_name, value)

property channel

property selected_asset_types

property selected_assets

class NProcessesWidget(parent: QWidget | None = None, label: str = 'n_processes')

Bases: QWidget

Simple n_processes widget: label + spinbox.

Exposes value() / setValue() and a valueChanged signal so it can be used transparently by ParamLink.

setMaximum(maximum: int)

setMinimum(minimum: int)

setRange(minimum: int, maximum: int)

setValue(v: int)

value() → int

valueChanged

new value.

Type:

Emitted when the spin box value changes. Argument

class OrthoViewer(img=None, parent=None)

Bases: object

Orthogonal viewer for 3D images.

This is a class that allows to visualize 3D images in 3 orthogonal views.

add_regions()

Add the interactive linear-region overlays to each orthogonal view.

plot_orthogonal_views(img=None, parent=None)

Plot the orthogonal views of the image.

Parameters:

• img (np.ndarray) – The image to plot. If None, the image set at initialization will be used.

• parent (QWidget) – The parent widget to plot into. If None, the parent set at initialization will be used.

Returns

list of DataViewer

setup(img, params, parent=None, no_scale=False)

Initialize the viewer after the object has been created.

Parameters:

• img (np.ndarray) – The 3D image to visualize.

• params (UiParameter) – The parameters object.

• parent (QWidget) – The parent widget.

• no_scale (bool) – If True, disable coordinate scaling.

update_ranges(ranges)

Update the ranges (min, max) for each axis of the viewer.

Parameters:

ranges (list of tuple of float)

property depth

Get the depth of the image.

Returns

int

property height

Get the height of the image.

Returns

int

property shape

Get the shape of the image.

Returns

tuple of int

property width

Get the width of the image.

Returns

int

class PatternDialog(src_folder, params, app=None, min_file_number=10, tile_extension='.ome.tif')

Bases: WizardWidget

A wizard dialog to help the user define file patterns for a set of image file paths The dialog scans the source folder to find patterns in the file names and suggests them to the user there must be at least min_file_number files in the folder with the extension tile_extension to trigger the pattern search

add_group()

Add a new group of widgets to the dialog This is a group of widgets to define a pattern for a set of image files (typically a channel)

all_channels_defined()

connect_buttons()

Connect the buttons to their slots. This method is called automatically in the constructor

get_channel_names()

get_patterns() → List[PatternFinder]

Scan the current source folder to get the pattern finders for the image files

Non blocking to keep the UI responsive

Returns

list(PatternFinder)

The pattern finders for the source folder

get_results() → List[ChannelPatternSpec]

get_widgets(image_group_id, axis)

Get the widgets (label, pattern and combo) for a given image group and axis

Parameters:

• image_group_id (int) – The index of the image group

• axis (int) – The index of the axis

Returns

tuple(QLabel, QLabel, QComboBox)

The label of the axis, pattern for the axis pattern and combobox containing the axis name (as a letter)

save_results()

setup()

Setup the dialog after creation from the ui file. This method is called automatically in the constructor

validate_pattern()

Validate the pattern defined by the user and update the result widget The result is saved in the pattern_strings attribute for the current channel name

min_file_number: int

n_image_groups: int

patterns_finders: List[PatternFinder]

tile_extension: str

class PerfMonitor(parent, fast_period, slow_period, *args, **kwargs)

Bases: QWidget

get_cpu_percent()

get_ram_percent()

get_thread_percent()

handle_gpu_vals_updated()

handle_proc_changed(file_path)

start()

stop()

update_cpu_values()

update_gpu_values()

cpu_vals_changed

(cpu_percent, thread_percent, ram_percent).

Type:

Emitted when CPU values update. Arguments

gpu_vals_changed

(gpu_percent, vram_percent).

Type:

Emitted when GPU values update. Arguments

percent_thread

The percentage of the CPU used by the most active process of ClearMap

class ProgressWatcher(max_progress=100, main_max_progress=1, timer_interval_ms=250, parent=None)

Bases: QWidget

A QWidget that watches the progress of a process.

It uses signals to update the progress bar and the text. The main setup methods are setup() and prepare_for_substep(). It is meant to be used in conjunction with a progress dialog to which it is connected through its signals.

count_dones()

Parse the logs to extract the number of completed operations (based on self.pattern). For each match, the progress is incremented by 1. For efficiency, the logs are read from the last read position.

Returns

int

The cumulative number of matched operations.

finish()

Trigger the finished signal.

get_progress()

Get the current progress.

Returns

int

increment(increment)

Increment the progress value of the current main or sub step.

Parameters:

increment (int or float) – The increment value. If float, it is considered as a fraction of the maximum progress value.

increment_main_progress(increment=1)

Integer increment of the main progress.

Parameters:

increment (int) – The increment value (default is 1).

prepare_for_substep(step_length, pattern, step_name)

Setup the watcher for a new substep.

Parameters:

• step_length (int) – The number of steps in the operation.

• pattern (str or re.Pattern or tuple or None) – The text to look for in the logs to check for progress.

• step_name (str) – Name (title) of the substep.

reset()

Reset all the values to their initial state.

reset_log_length()

Reset the done counter and seek to the end of the log file.

set_main_progress(value)

Set the progress value for the main step.

Parameters:

value (int) – The progress value.

set_poll_interval(ms: int)

Set the log-polling interval in milliseconds.

set_progress(value)

Set the progress value of the current main or sub step.

Parameters:

value (int) – The progress value.

setup(main_step_name, main_step_length, sub_step_length=0, pattern=None)

Post-initialisation setup.

Parameters:

• main_step_name (str) – Title of the main processing step.

• main_step_length (int) – Total number of main steps.

• sub_step_length (int) – Total number of sub-steps within the current main step.

• pattern (str or re.Pattern or tuple or None) – Text pattern to search for in logs to detect progress increments.

start_polling()

Start polling the log file for progress pattern matches.

stop_polling()

Stop log-file polling.

aborted

whether abort was confirmed.

Type:

Emitted when processing is aborted. Argument

finished

main step name.

Type:

Emitted when all processing has finished. Argument

main_max_changed

new maximum.

Type:

Emitted when the main progress maximum changes. Argument

property main_max_progress

Current main-step maximum.

main_progress_changed

current value.

Type:

Emitted when the main progress value changes. Argument

property main_step_name

Current main step name.

main_step_name_changed

step name.

Type:

Emitted when the main step name changes. Argument

max_changed

new maximum.

Type:

Emitted when the sub-step progress maximum changes. Argument

property max_progress

Current sub-step maximum.

progress_changed

current value.

Type:

Emitted when the sub-step progress value changes. Argument

property sub_step_name

Current sub-step name.

sub_step_name_changed

step name.

Type:

Emitted when the sub-step name changes. Argument

class SamplePickerDialog(src_folder, params, app=None)

Bases: WizardWidget

A dialog to help the user pick the sample folders from a source folder. The dialog scans the source folder to find the sample folders based on the presence of a sample_params.cfg file The results are displayed in two lists. The user can move the sample folders from the left (available items) list to the right (selected items) list. The samples can be split into groups to allow for different processing of the groups.

connect_buttons()

Connect the buttons to their slots. This method is called automatically in the constructor

parse_sample_folders()

Scan the source folder to find experiment folders based on the presence of a sample config file (any supported name/extension).

Returns

list(str)

The list of sample folders, naturally sorted.

setup()

Setup the dialog after creation from the ui file. This method is called automatically in the constructor

class StructurePickerWidget(parent=None, json_base_name='ABA json 2022')

Bases: QTreeWidget

static build_tree(tree=None, parent=None)

static parse_json(base_name='ABA json 2022')

print_id(itm, col)

DARK_COLOR = '#2E3436'

LIGHT_COLOR = 'white'

class StructureSelector(app=None)

Bases: WizardWidget

close()

connect_buttons()

Connect the buttons to their slots. This method is called automatically in the constructor but should be implemented in the subclass

setup()

Setup the dialog after creation from the ui file. This method is called automatically in the constructor but should be implemented in the subclass

show()

class TwoListSelection(parent=None, input_title=None, output_title=None)

Bases: QWidget

A widget that allows to select items from a list and move them to another list.

This is useful for selecting items from a list of available items and moving them to a list of selected items.

addAvailableItems(items)

Add the list of available items to the left list.

Parameters:

items (list) – The list of items to add. Each element can be a string or a (text, user_data) tuple.

clear()

Clear both lists.

get_left_elements(with_data=False)

Get the list of items in the left list (available items).

Returns

list of str

get_right_elements(with_data=False)

Get the list of items in the right list (selected items).

Returns

list of str

on_selection_changed(list_widget)

setSelectedItems(items)

Add the list of selected items to the right list.

Parameters:

items (list) – The list of items to add.

update_buttons_status()

itemSelectionChanged

item text.

Type:

Emitted when a single item is selected in either list. Argument

class WizardWidget(ui_name, ui_title, src_folder='', params=None, app=None, size=None, patch_parent_class='QDialog')

Bases: object

A base class for a complex dialogs designed with QT creator and exported as ui files. It is meant to be subclassed. The subclass should implement the setup and connect_buttons methods This class needs a src_folder, a ui_name, a ui_title. The ui names and titles are used to build a dialog from the ui file of the same name and parametrise the dialog

static enable_widgets(widgets)

Helper method to enable a list of widgets

Parameters:

widgets (list(QWidget)) – The list of widgets to enable

static hide_widgets(widgets)

Helper method to hide a list of widgets

Parameters:

widgets (list(QWidget)) – The list of widgets to hide

connect_buttons()

Connect the buttons to their slots. This method is called automatically in the constructor but should be implemented in the subclass

exec()

Execute the dialog

setup()

Setup the dialog after creation from the ui file. This method is called automatically in the constructor but should be implemented in the subclass

ensure_inline_histogram(histogram: PlotWidget | QWidget, hist_idx: int, layout: QLayout)