widgets

Description

This module contains classes (QtWidgets) and functions managing the user interfaces used by openhdemg.library.

check_app()

Return the active QApplication, creation state, and default icon path.

PointSelectorDialog

Bases: QDialog

Interactive dialog for selecting points on a 1D signal.

It shows a Matplotlib figure in a Qt dialog. The dialog ensures the number of selected points matches the required count (if specified) before closing.

Users can move the mouse to track coordinates and press:

- "A" or "a" to add a point at the current cursor location
- "D" or "d" to delete the last selected point
- "Enter" to confirm the selection and close the window

Check the implementation of run_point_selector() to see how it can be used. It is always suggested to call the PointSelectorDialog from run_point_selector() instead of directly running its instance, as this is also managing the QApplication.

PARAMETER	DESCRIPTION
data	1D signal to display for point selection. This can be anything suitable for matplotlib.axes.Axes.plot. TYPE: array - like
nclic	Number of points to enforce selection before confirming. Default is -1, which means no limit. TYPE: int DEFAULT: -1
y_label	Label for the y-axis. TYPE: str DEFAULT: "Data"
title	Title shown above the plot. TYPE: str DEFAULT: "A to select, D to delete, Enter to continue"
title_fontsize	Font size of the title. TYPE: int or float DEFAULT: 10
title_fontweight	Font weight of the title text. This will be passed to matplotlib.text.Text.set_fontweight. TYPE: str DEFAULT: "bold"
path_to_icon	The path to the window icon. Use none if this widget inherits from a parent. TYPE: None or str DEFAULT: None
parent	Optional parent used when embedding the dialog. TYPE: QWidget or None DEFAULT: None

ATTRIBUTE	DESCRIPTION
points	A list of Lists containing the [x, y] coordinates of the selected points. TYPE: list of lists

See also

• run_point_selector : Run the point selector dialog and return the selected points.

on_mouse_move(event)

Record mouse position on the figure coordinates.

on_key_press(event)

React to pressed buttons.

redraw_points()

Update the figure with the selected points.

cleanup()

Release all memory-intensive Matplotlib and Qt references.

run_point_selector(data, nclic=-1, y_label='Data', title='A to select, D to delete, Enter to continue', title_fontsize=10, title_fontweight='bold', parent=None)

Run the point selector dialog and return the selected points.

Opens a blocking Qt dialog where the user can select points on a 1D signal using keyboard and mouse interactions. The dialog ensures the number of selected points matches the required count (if specified) before closing.

Compared to directly creating a PointSelectorDialog instance, this function automatically manages the app integration for the user.

Users can move the mouse to track coordinates and press:

- "A" or "a" to add a point at the current cursor location
- "D" or "d" to delete the last selected point
- "Enter" to confirm the selection and close the window

PARAMETER	DESCRIPTION
data	1D signal to display for point selection. This can be anything suitable for matplotlib.axes.Axes.plot. TYPE: array - like
nclic	Number of points to enforce selection before confirming. Default is -1, which means no limit. TYPE: int DEFAULT: -1
y_label	Label for the y-axis. TYPE: str DEFAULT: "Data"
title	Title shown above the plot. TYPE: str DEFAULT: "A to select, D to delete, Enter to continue"
title_fontsize	Font size of the title. TYPE: int or float DEFAULT: 10
title_fontweight	Font weight of the title text. This will be passed to matplotlib.text.Text.set_fontweight. TYPE: str DEFAULT: "bold"
parent	Optional Qt parent used when embedding the dialog. TYPE: QWidget or None DEFAULT: None

RETURNS	DESCRIPTION
points	A list of Lists containing the [x, y] coordinates of the selected points. TYPE: list of lists

Examples:

Free selection of points (no limit)

>>> import numpy as np
>>> from openhdemg.ui import run_point_selector
>>> signal = np.sin(np.linspace(0, 10, 500))
>>> selected_points = run_point_selector(signal, nclic=-1)
>>> print(selected_points)
[[70.22, 0.96], [222.14, -0.95], [314.93, 0.04]]

Select exactly 2 points and print the X coordinates.

>>> import numpy as np
>>> from openhdemg.ui import run_point_selector
>>> signal = np.random.randn(1000)
>>> selected = run_point_selector(signal, nclic=2)
>>> print(f"Start: {selected[0][0]}, End: {selected[1][0]}")
Start: 168.21717572391907, End: 713.5261404204681

CustomFileDialog

Custom file dialog for opening or saving a file.

It uses QSettings to remember the last accessed directory.

Check the implementation of run_custom_file_dialog() to see how it can be used. It is always suggested to call the CustomFileDialog from run_custom_file_dialog() instead of directly running its instance, as this is also managing the QApplication.

PARAMETER	DESCRIPTION
mode	Operation mode for the dialog. open Get the file path to load the selected file. save Get the file path where to save the selected file. TYPE: str {"open", "save"} DEFAULT: "open"
filesource	Description of the file type being handled. This is shown in the dialog title. TYPE: str DEFAULT: "file"
filetypes	A list of (description, extension) tuples specifying acceptable file types. TYPE: list of tuples DEFAULT: [("openhdemg files", "*.json"), ("All files", "*.*")]

METHOD	DESCRIPTION
get_filepath	Get the path to the file or None if the operation is cancelled.

See also

• run_custom_file_dialog : Opens a custom file dialog for opening or saving a file.

get_filepath()

Get the path to the file.

If the operation is completed, the directory is memorised for following uses.

RETURNS	DESCRIPTION
str or None	The selected file path if confirmed, or None if the dialog was canceled.

run_custom_file_dialog(mode='open', filesource='openhdemg', filetypes=[('openhdemg files', '*.json'), ('All files', '*.*')])

Opens a custom file dialog for opening or saving a file, remembering the last accessed directory.

Compared to directly creating a CustomFileDialog instance, this function automatically manages the app integration for the user.

PARAMETER	DESCRIPTION
mode	Operation mode for the dialog. open Get the file path to load the selected file. save Get the file path where to save the selected file. TYPE: str {"open", "save"} DEFAULT: "open"
filesource	Description of the file type being handled. This is shown in the dialog title. TYPE: str DEFAULT: "openhdemg"
filetypes	A list of (description, extension) tuples specifying acceptable file types. TYPE: list of tuples DEFAULT: [("openhdemg files", "*.json"), ("All files", "*.*")]

RETURNS	DESCRIPTION
str or None	The selected file path if confirmed, or None if the dialog was canceled.

Examples:

Get the path to a MATLAB file and visualise the full path, the file name and its directory.

>>> from openhdemg.ui import run_custom_file_dialog
>>> import os
>>> filepath = run_custom_file_dialog(
...     mode="open",
...     filesource="MATLAB",
...     filetypes=[("MATLAB files", "*.mat"), ("All files", "*.*")]
... )
>>> if filepath:
...     filename = os.path.basename(filepath)
...     directory = os.path.dirname(filepath)
...     print("Full path:", filepath)
...     print("File name:", filename)
...     print("Directory:", directory)
... else:
...     print("No file was selected.")

CustomDirectoryDialog

Custom dialog for selecting a directory.

It uses QSettings to remember the last accessed directory.

Check the implementation of run_custom_directory_dialog() to see how it can be used. It is always suggested to call the CustomDirectoryDialog from run_custom_directory_dialog() instead of directly running its instance, as this is also managing the QApplication.

PARAMETER	DESCRIPTION
window_title	Title of the dialog window. This should guide the user. TYPE: str DEFAULT: "Select a folder"

METHOD	DESCRIPTION
get_directory	Get the directory path.

See also

• run_custom_directory_dialog : Opens a custom dialog for selecting a directory.

get_directory(mode='open')

Get the directory path.

Allows selecting an existing directory or typing a new one. The new directory is created automatically if needed.

PARAMETER	DESCRIPTION
mode	Determines how the dialog behaves: open The dialog is used to select an existing directory. The user must choose a folder that already exists on the filesystem. save The dialog additionally allows the user to type a new directory name into the text bar. If the typed directory does not exist, it will be created automatically after the user confirms. TYPE: str {"open", "save"} DEFAULT: "open"

RETURNS	DESCRIPTION
str or None	The selected or created directory path.

run_custom_directory_dialog(window_title='Select a folder', mode='open')

Opens a custom dialog for selecting a directory, remembering the last accessed directory.

Compared to directly creating a CustomDirectoryDialog instance, this function automatically manages the app integration for the user.

PARAMETER	DESCRIPTION
window_title	Title of the dialog window. This should guide the user. TYPE: str DEFAULT: "Select a folder"
mode	Determines how the dialog behaves: open The dialog is used to select an existing directory. The user must choose a folder that already exists on the filesystem. save The dialog additionally allows the user to type a new directory name into the text bar. If the typed directory does not exist, it will be created automatically after the user confirms. TYPE: str {"open", "save"} DEFAULT: "open"

RETURNS	DESCRIPTION
str or None	The selected directory path if confirmed, or None if the dialog was canceled.

Examples:

Select a directory and print the path:

>>> from openhdemg.ui import run_custom_directory_dialog
>>> dirpath = run_custom_directory_dialog(
...     window_title="Select the output folder"
... )
>>> if dirpath:
...     print("Selected directory:", dirpath)
... else:
...     print("No directory was selected.")

Manual_EMGChannels_Selection_Dialog

Bases: QDialog

Modal dialog for manual selection of noisy EMG channels.

The dialog displays stacked EMG channels for visual inspection and allows the user to mark channels as valid or invalid using the keyboard (keys 1-8). Selected channels are stored in the GOOD_CHANNELS field of the EMG file upon confirmation.

PARAMETER	DESCRIPTION
emgfile	The dictionary containing the emgfile. TYPE: dict
manual_offset	Vertical spacing between channels. If 0, an automatic offset is computed from signal amplitude. TYPE: float DEFAULT: 0
path_to_icon	Path to a window icon file. TYPE: str or None DEFAULT: None
parent	Parent widget. TYPE: QWidget or None DEFAULT: None

_prepare_result()

Store channel selections before releasing the plotting state.

get_emgfile_with_good_channels()

Return the EMG file with updated GOOD_CHANNELS metadata.

Channel indices are stored as strings for saving compatibility.

cleanup(preserve_emgfile=False)

Release all memory-intensive Matplotlib, Qt, and EMG references.

done(result)

Handle every QDialog exit path through one cleanup path.

run_manual_emgchannels_selection_dialog(emgfile, manual_offset=0, parent=None)

Select noisy channels via visual inspection.

This function opens a modal graphical dialog that allows the user to visually inspect stacked EMG channels and mark noisy or unwanted channels. Channel selection is performed interactively; the calling code is blocked until the dialog is closed.

Compared to directly creating a Manual_EMGChannels_Selection_Dialog instance, this function automatically manages the app integration for the user.

PARAMETER	DESCRIPTION
emgfile	The dictionary containing the emgfile. TYPE: dict
manual_offset	This parameter sets the scaling of the channels. If 0 (default), the channels' amplitude is scaled automatically to fit the plotting window. If > 0, the channels will be scaled based on the specified value. TYPE: int or float DEFAULT: 0
parent	Optional Qt parent used when embedding the dialog. TYPE: QWidget or None DEFAULT: None

RETURNS	DESCRIPTION
edited_emgfile	The EMG file dictionary with an updated "GOOD_CHANNELS" entry (mapping channel indices as strings to booleans) if the user confirms the selection. Returns None if the dialog is cancelled. TYPE: dict or None

Examples:

See emg.select_bad_channels()