🚧 Work in progress: this documentation is still being written and reviewed. Check details against the source code.

Pose browser and registry

Load, browse, and update the GUI’s shared pose registry.

mtc_gui.poses_panel · Source

Operator GUI · Guide · Symbol index

How it is used

MTCMainWindow loads the registry through load_from_beamline_config(); load_from_file() accepts a registry path directly. pose_clicked reports a selection, pose_activated requests a Move To queue entry, and poses_loaded announces a reload. Selecting or dragging a pose does not execute it.

Use save_pose() and delete_pose() to change the registry: both read the latest file, write it atomically, then reload the panel. Comment-derived groups are display metadata and are lost on rewrite. There is no interprocess lock between GUI and other registry writers.

Start here

Callable	Purpose
PosesPanel.load_from_beamline_config	Read poses_file from a beamline YAML and search ancestor directories for the referenced registry.
PosesPanel.load_from_file	Load six-element pose lists and extract display groups from # — group — comments.
PosesPanel.get_poses	Return a shallow copy of the loaded pose mapping.
PosesPanel.save_pose	Merge one pose into the latest on-disk registry, atomically write it, then reload.
PosesPanel.delete_pose	Remove a name from the latest on-disk registry and reload the persisted result.

PosesPanel

Own the loaded registry, file path, filters, and pose signals. The main window and pose dialogs use this panel as their registry access point.

Inherits from: QWidget.

PosesPanel.load_from_beamline_config()

Read poses_file from a beamline YAML and search ancestor directories for the referenced registry.

Method · Source

load_from_beamline_config(self, config_path: str | Path)

Parameter	Meaning
config_path	Beamline YAML path. A relative poses_file is resolved by walking upward from this path’s parent; the filesystem-root directory is not checked by the loop.

Returns: None.

Errors: Missing config, absent/false poses_file, or unresolved registry silently returns. YAML/I/O and nonmapping-config errors propagate.

Side effects: Reads the beamline config and, when found, loads the registry through load_from_file.

PosesPanel.load_from_file()

Load six-element pose lists and extract display groups from # — group — comments.

Method · Source

load_from_file(self, path: str | Path)

Parameter	Meaning
path	Registry YAML path to become the active persistence destination.

Returns: None.

Errors: A missing file updates the count label and leaves previously loaded registry state intact. Other read/parse/display errors propagate; _poses_file is assigned before read_poses completes.

Side effects: Replaces poses/groups/path, reads the file twice, refreshes the list/source label, and emits poses_loaded with a shallow mapping copy.

Referenced in source (4)

• PosesPanel._reload — mtc_gui.poses_panel
• PosesPanel.delete_pose — mtc_gui.poses_panel
• PosesPanel.load_from_beamline_config — mtc_gui.poses_panel
• PosesPanel.save_pose — mtc_gui.poses_panel

PosesPanel.get_poses()

Return a shallow copy of the loaded pose mapping.

Method · Source

get_poses(self) -> dict[str, list]

Returns: A shallow dict copy; contained joint-angle lists remain shared with the panel.

PosesPanel.save_pose()

Merge one pose into the latest on-disk registry, atomically write it, then reload.

Method · Source

save_pose(self, name: str, values: list) -> bool

Parameter	Meaning
name	Pose key to insert or overwrite without duplicate-name confirmation.
values	Joint-angle list, conventionally six degrees values; no validation is performed before writing.

Returns: False if no registry path is set; True after successful write and reload.

Errors: I/O/YAML/display errors propagate. The reload filters non-six-element lists, so malformed lengths may be written but then disappear from the visible registry.

Side effects: Reads current disk state, writes the merged registry, and reloads/emits poses_loaded. YAML comments are lost; read/merge/write is not protected by a cross-process lock.

PosesPanel.delete_pose()

Remove a name from the latest on-disk registry and reload the persisted result.

Method · Source

delete_pose(self, name: str) -> bool

Parameter	Meaning
name	Pose key to remove; absent keys are tolerated.

Returns: False if no registry path is set; otherwise True after write/reload, even when the name was absent.

Errors: I/O/YAML/display errors propagate.

Side effects: Rewrites the registry and reloads/emits poses_loaded; comments are lost even when the requested key did not exist.

PosesPanel.__init__()

Create an empty pose browser with no registry selected.

Lifecycle · Source

__init__(self, parent=None)

Parameter	Meaning
parent	Optional parent widget.

Errors: Qt construction errors propagate.

Side effects: Initializes in-memory state and widgets; reads no file.

Referenced in source (1)

• MTCMainWindow._build_sidebar — mtc_gui.main_window

PosesPanel.get_pose()

Return one pose’s angle list from the in-memory registry.

Method · Source

get_pose(self, name: str) -> list | None

Parameter	Meaning
name	Registry key to retrieve.

Returns: Stored joint-angle list by reference, or None when absent.

Errors: Unhashable names raise TypeError.

Side effects: None; mutating the returned list would change in-memory values without persistence or signals.

PosesPanel.get_poses_file()

Expose the active registry’s filesystem path.

Method · Source

get_poses_file(self) -> Path | None

Returns: Path, or None before a registry has been selected.

Internal callbacks and helpers

PosesPanel._build_ui()

Build name/group filtering, reload, drag-enabled pose list, six joint-value labels, and source status.

Internal helper · Source

_build_ui(self)

Returns: None.

Errors: Qt construction/connection errors propagate.

Side effects: Creates widgets and connects filters, clicks, double-clicks, and reload; installs no ROS connection itself.

Referenced in source (1)

• PosesPanel.__init__ — mtc_gui.poses_panel

PosesPanel._refresh_list()

Rebuild the sorted pose list using a case-insensitive substring match on name or group.

Internal helper · Source

_refresh_list(self)

Returns: None.

Errors: Nonnumeric values and nonstring/unorderable pose names may raise; no local validation.

Side effects: Clears list/selection, creates visible PoseListItems, and updates total or visible/total count text.

Referenced in source (2)

• PosesPanel._apply_filter — mtc_gui.poses_panel
• PosesPanel.load_from_file — mtc_gui.poses_panel

PosesPanel._apply_filter()

Refresh visible poses using the current filter-edit text.

Callback · Source

_apply_filter(self)

Returns: None.

Errors: Refresh errors propagate.

Side effects: Rebuilds the list and count label.

Referenced in source (1)

• PosesPanel._build_ui — mtc_gui.poses_panel

PosesPanel._on_click()

Show a clicked pose’s joint angles and emit its informational selection signal.

Callback · Source

_on_click(self, item: PoseListItem)

Parameter	Meaning
item	PoseListItem providing pose_name and pose_values.

Returns: None.

Errors: Malformed/nonnumeric values propagate; zip updates only matching label/value pairs.

Side effects: Updates joint labels and emits pose_clicked(name, values); does not enqueue or execute a move.

Referenced in source (1)

• PosesPanel._build_ui — mtc_gui.poses_panel

PosesPanel._on_double_click()

Emit the selected pose as a requested queue addition.

Callback · Source

_on_double_click(self, item: PoseListItem)

Parameter	Meaning
item	Activated PoseListItem containing pose_name and pose_values.

Returns: None.

Errors: Attribute/signal errors propagate.

Side effects: Emits pose_activated(name, values); the connected main-window slot appends a Move To step.

Referenced in source (1)

• PosesPanel._build_ui — mtc_gui.poses_panel

PosesPanel._reload()

Reload the active registry path when one has been selected.

Callback · Source

_reload(self)

Returns: None.

Errors: No loaded path is a no-op; load_from_file handles missing files and propagates other errors.

Side effects: Reads and redisplays the registry and emits poses_loaded on a successful reload.

Referenced in source (1)

• PosesPanel._build_ui — mtc_gui.poses_panel

PoseListItem

Store one pose’s name, degree-valued angles, and optional display group in the browser list.

Inherits from: QListWidgetItem.

PoseListItem.__init__()

Create a pose list item carrying its name, angle list, and display group.

Lifecycle · Source

__init__(self, name: str, values: list, group: str='')

Parameter	Meaning
name	Pose label and exported drag name.
values	Joint-angle list in degrees; stored by reference and formatted to two decimals in the tooltip.
group	Optional display/filter group label parsed from YAML comments.

Errors: Nonnumeric values can fail tooltip formatting; Qt errors propagate.

Side effects: Sets item text, tooltip, attributes, and UserRole {name, values, group}.

Referenced in source (1)

• PosesPanel._refresh_list — mtc_gui.poses_panel

_PoseDragListWidget

Implement the browser’s drag payload. Qt calls mimeData() to export a pose name for the task queue.

Inherits from: QListWidget.

Internal callbacks and helpers

_PoseDragListWidget.mimeData()

Export the first dragged PoseListItem as custom pose-name MIME data and plain text.

Callback · Source

mimeData(self, items)

Parameter	Meaning
items	Selected list items; only the first is considered, and it must be a PoseListItem.

Returns: QMimeData containing application/x-mtc-pose-name UTF-8 bytes and text, or empty QMimeData when no compatible first item exists.

Errors: Encoding/Qt errors propagate.

Side effects: Creates a drag payload; does not mutate registry data.