Task editor forms

Edit task dictionaries through a modal form selected by task_type.

mtc_gui.task_forms · Source

How it is used

MTCMainWindow calls open_task_form() with a task, its queue index, and the available poses. The helper selects one of the registered editors for 12 task types and returns the accepted task or None. Forms edit a deep copy and do not dispatch commands. Widget construction and editing run on the GUI thread.

Each form supplies build_form() and collect_values() through BaseTaskForm. Most editors preserve unrelated fields. Move To can return _inline_joint_pose metadata for the window to move into the document’s pose overrides; grid editors write a complete config override. These serialization details matter when adding a form or changing the task schema.

Start here

Callable	Purpose
open_task_form	Select a concrete editor by task_type, run it modally, and return only an accepted result.
BaseTaskForm.build_form	Subclass hook for adding task-specific controls during construction.
BaseTaskForm.collect_values	Subclass hook for converting the current controls into a task dictionary.
MoveToForm.collect_values	Serialize the selected Move To mode and remove fields from inactive modes.
_GridSelectorForm.collect_values	Validate grid directions and serialize the selected cell with a complete configuration override.

Example

# Requires PyQt6 and a configured Qt platform; no ROS or hardware.
# Use an existing QApplication in an application or test harness.
from mtc_gui.task_forms import MoveToForm

form = MoveToForm({"task_type": "moveto", "target": "moveit_home"}, 0, {})
form.mode_combo.setCurrentText("Relative move")
form.direction.setCurrentText("up")
form.distance.setValue(0.05)
assert form.collect_values() == {
    "task_type": "moveto", "direction": "up", "distance": 0.05
}
form.deleteLater()

Functions

`open_task_form()`

Select a concrete editor by task_type, run it modally, and return only an accepted result.

Entry point · Source

open_task_form(
    step,
    step_index,
    poses,
    parent = None,
    current_pose = None,
    preview_cb = None,
    end_preview_cb = None,
    viz_widget = None,
)

Parameter	Meaning
`step`	Task mapping to edit; BaseTaskForm deep-copies it.
`step_index`	Zero-based queue index used in the title as Step index + 1.
`poses`	Mapping of named poses to six joint angles in degrees; stored by reference.
`parent`	Optional parent QWidget.
`current_pose`	Optional current six-joint pose in degrees used by Read current pose; this is a snapshot, not a polling callback.
`preview_cb`	Optional callable receiving a six-angle degree list for visual preview only.
`end_preview_cb`	Optional zero-argument callback restoring normal viewer state.
`viz_widget`	Optional live viewer widget temporarily reparented into the editor and detached when the dialog ends.

Returns: Edited step mapping when accepted; None when canceled or no form exists.

Errors: Unknown task types show a warning. Constructor/modal-loop failures propagate; form-save validation catches only ValueError/KeyError.

Side effects: Creates and executes a modal dialog; only MoveTo receives current-pose/preview/viewer arguments. pause has no dispatch entry.

Internal callbacks and helpers

`_configured_grippers()`

Read declared gripper names from the active beamline configuration.

Internal helper · Source

_configured_grippers() -> list[str]

Returns: List of grippers mapping keys in configuration order, or [] on failure.

Errors: Catches all Exception failures, including missing configuration or malformed grippers.

Side effects: Reads beamline configuration through config_loader, which reuses its cached configuration after a successful load.

Referenced in source (1)

ToolExchangeForm.build_form — mtc_gui.task_forms

`_grippers_with_states()`

Read gripper names whose configuration contains a truthy states block.

Internal helper · Source

_grippers_with_states() -> list[str]

Returns: List of eligible gripper names in configuration order; [] on any failure.

Errors: Catches all Exception failures; a malformed entry can discard the entire result.

Side effects: Reads beamline configuration through config_loader, which reuses its cached configuration after a successful load.

Referenced in source (1)

EndEffectorForm.build_form — mtc_gui.task_forms

`_end_effector_actions()`

Collect unique truthy grasp/release action names across configured grippers, preserving first-seen order.

Internal helper · Source

_end_effector_actions() -> list[str]

Returns: List of action values, normally strings; [] on any failure. The result is a union, not filtered by the currently selected gripper.

Errors: Catches all Exception failures; action value types are not validated.

Side effects: Reads beamline configuration through config_loader, which reuses its cached configuration after a successful load.

Referenced in source (1)

EndEffectorForm.build_form — mtc_gui.task_forms

`_vision_target_config()`

Read one named vision target from the active beamline configuration.

Internal helper · Source

_vision_target_config(target_name: str) -> dict

Parameter	Meaning
`target_name`	vision_targets key, such as tip_rack or vial_rack.

Returns: Configured target value, conventionally a dict; {} if absent or loading fails.

Errors: Catches all Exception failures; a present nonmapping target value is returned unchanged.

Side effects: Reads beamline configuration through config_loader, which reuses its cached configuration after a successful load.

Referenced in source (1)

_GridSelectorForm.build_form — mtc_gui.task_forms

`BaseTaskForm`

Provide the modal dialog, working task copy, field helpers, and save handling. Subclasses implement build_form() and collect_values(); the constructor calls build_form() before returning.

Inherits from: QDialog.

`BaseTaskForm.build_form()`

Subclass hook for adding task-specific controls during construction.

Extension hook · Source

build_form(self)

Returns: None.

Errors: No validation or exception handling.

Side effects: None; this base implementation has no body beyond pass.

Referenced in source (1)

BaseTaskForm.__init__ — mtc_gui.task_forms

`BaseTaskForm.collect_values()`

Subclass hook for converting the current controls into a task dictionary.

Extension hook · Source

collect_values(self)

Returns: The deep-copied self.step mapping itself, not a second copy.

Errors: No validation.

Referenced in source (1)

BaseTaskForm._on_save — mtc_gui.task_forms

`BaseTaskForm.init()`

Copy the task, build the modal dialog, and call the subclass’s form builder.

Lifecycle · Source

__init__(self, step, step_index, poses, parent=None)

Parameter	Meaning
`step`	Task mapping to edit; BaseTaskForm deep-copies it.
`step_index`	Zero-based queue index used in the title as Step index + 1.
`poses`	Mapping of named poses to six joint angles in degrees; stored by reference.
`parent`	Optional parent QWidget.

Returns: None; result starts as None.

Errors: Deep-copy, Qt, and subclass build_form failures propagate.

Side effects: Stores step/poses, builds controls, invokes build_form, and connects Save/Cancel.

`BaseTaskForm.add_combo()`

Add a fixed-choice combo initialized from the task’s value when that text is present.

Method · Source

add_combo(self, label, key, options)

Parameter	Meaning
`label`	Form-row label.
`key`	Task field used to select current text.
`options`	Ordered list of string options; first entry is the fallback when a value is missing or unmatched.

Returns: Created QComboBox.

Errors: Qt/option-type errors propagate; unmatched saved values are silently replaced by the combo’s first choice.

Side effects: Adds a combo row to self.form.

`BaseTaskForm.add_text()`

Add a line edit initialized by stringifying a task field.

Method · Source

add_text(self, label, key, default='')

Parameter	Meaning
`label`	Form-row label.
`key`	Task field to display.
`default`	Fallback value when key is absent; also converted to str.

Returns: Created QLineEdit.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Adds a text-entry row to self.form.

`BaseTaskForm.add_float()`

Add a bounded decimal spin box initialized with float(task field).

Method · Source

add_float(self, label, key, default=0.0, min_val=-999.0, max_val=999.0, decimals=4)

Parameter	Meaning
`label`	Form-row label.
`key`	Task field to display.
`default`	Fallback numeric value.
`min_val`	Inclusive lower widget bound.
`max_val`	Inclusive upper widget bound.
`decimals`	Number of displayed/retained decimal places.

Returns: Created QDoubleSpinBox.

Errors: float conversion/Qt errors propagate; the widget clamps to its bounds.

Side effects: Adds a numeric row to self.form.

`BaseTaskForm.add_int()`

Add an integer spin box initialized with int(task field).

Method · Source

add_int(self, label, key, default=0, min_val=0, max_val=999)

Parameter	Meaning
`label`	Form-row label.
`key`	Task field to display.
`default`	Fallback integer value.
`min_val`	Inclusive lower widget bound.
`max_val`	Inclusive upper widget bound.

Returns: Created QSpinBox.

Errors: int conversion/Qt errors propagate; the widget clamps to its bounds.

Side effects: Adds an integer row to self.form.

`BaseTaskForm.add_check()`

Add a checkbox initialized using the task field’s Python truth value.

Method · Source

add_check(self, label, key, default=False)

Parameter	Meaning
`label`	Form-row label.
`key`	Task field to read.
`default`	Fallback value converted through bool; strings such as “false” remain truthy.

Returns: Created QCheckBox.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Adds a checkbox row to self.form.

`BaseTaskForm.add_section()`

Add a titled group with its own form layout.

Method · Source

add_section(self, title)

Parameter	Meaning
`title`	Group-box heading.

Returns: QFormLayout attached to the new QGroupBox.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Adds the group as a row in the parent form.

`BaseTaskForm.add_hint()`

Append small gray word-wrapped explanatory text to the form.

Method · Source

add_hint(self, text)

Parameter	Meaning
`text`	Hint text shown in a QLabel.

Returns: None.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Creates and adds the hint label.

`BaseTaskForm.add_offset_row()`

Add up to three X/Y/Z decimal offsets from named task fields.

Method · Source

add_offset_row(self, section, prefix, keys)

Parameter	Meaning
`section`	QFormLayout receiving the horizontal offset row.
`prefix`	Row label preceding the X/Y/Z fields.
`keys`	Sequence of task keys zipped with X/Y/Z; at most three are used.

Returns: Mapping from each used key to its QDoubleSpinBox.

Errors: float conversion/Qt errors propagate; values are constrained to −1…1 with four decimals.

Side effects: Adds bounded offset widgets; callers conventionally express distances in metres.

Internal callbacks and helpers

`BaseTaskForm._on_save()`

Collect the edited task and accept the dialog, or display a conversion error.

Callback · Source

_on_save(self)

Returns: None.

Errors: Catches ValueError and KeyError from collection or acceptance; other exceptions propagate.

Side effects: Sets result before accepting; on caught failure displays Invalid Input and leaves the dialog open.

Referenced in source (1)

BaseTaskForm.__init__ — mtc_gui.task_forms

`MoveToForm`

Edit named, relative, Cartesian, or explicit-joint Move To targets. Optional viewer callbacks preview joint goals without executing motion.

Inherits from: BaseTaskForm.

`MoveToForm.collect_values()`

Serialize the selected Move To mode and remove fields from inactive modes.

Extension hook · Source

collect_values(self)

Returns: A shallow copy of the working task. Named: target + planning_type=”joint”. Relative: direction + distance (m). Cartesian: planning_type, frame_id, and XYZ metres with RPY degrees appended only if any angle is nonzero. Joint: target + planning_type=”joint” + _inline_joint_pose={name, values}.

Errors: No validation that a named target is nonempty or a relative distance is positive; widget/type errors propagate.

Side effects: None beyond reading widgets. Joint mode reuses an existing six-value target name or generates moveto_joints_{step_index+1}; the caller must consume the temporary metadata into config.poses before dispatch.

`MoveToForm.init()`

Store the pose snapshot and viewer callbacks before building the editor.

Lifecycle · Source

__init__(
    self,
    step,
    step_index,
    poses,
    parent = None,
    current_pose = None,
    preview_cb = None,
    end_preview_cb = None,
    viz_widget = None,
)

Parameter	Meaning
`step`	Task mapping to edit; BaseTaskForm deep-copies it.
`step_index`	Zero-based queue index used in the title as Step index + 1.
`poses`	Mapping of named poses to six joint angles in degrees; stored by reference.
`parent`	Optional parent QWidget.
`current_pose`	Optional current six-joint pose in degrees used by Read current pose; this is a snapshot, not a polling callback.
`preview_cb`	Optional callable receiving a six-angle degree list for visual preview only.
`end_preview_cb`	Optional zero-argument callback restoring normal viewer state.
`viz_widget`	Optional live viewer widget temporarily reparented into the editor and detached when the dialog ends.

Errors: Base/dialog construction and malformed initial task errors propagate.

Side effects: Stores preview context and creates the move editor; build_form may invoke preview callbacks and reparent the supplied viewer.

`MoveToForm.build_form()`

Build named, relative, Cartesian, and six-joint move editors and connect visual previews.

Extension hook · Source

build_form(self)

Returns: None.

Errors: Malformed saved numeric/sequence fields or preview callbacks can raise. Widget bounds clamp distances to 0…2 m, Cartesian XYZ to ±2 m, and joint/RPY angles to ±360 degrees.

Side effects: Creates mode groups, editable named target list with moveit_home, planning/frame/direction controls, presets/current-pose controls; applies initial mode, emits visual preview, and optionally embeds the supplied viewer.

`MoveToForm.done()`

Restore viewer preview state and detach an embedded viewer before completing the modal dialog.

Lifecycle · Source

done(self, r)

Parameter	Meaning
`r`	Qt dialog result code passed to QDialog.done.

Returns: None.

Errors: Callback/Qt errors propagate and can prevent later cleanup calls.

Side effects: Calls end_preview_cb when present, removes viz_widget’s parent, then invokes the base done handler.

Internal callbacks and helpers

`MoveToForm._detect_mode()`

Choose the initial branch using relative, Cartesian, registered-joint, then named-target precedence.

Internal helper · Source

_detect_mode(self)

Returns: “Relative move” for truthy direction and nonzero float(distance); else “Cartesian target” for truthy cartesian_target; else “Joint values” for a target mapped to a truthy six-element value; else “Named target”.

Errors: Invalid distance conversions or unsized pose values propagate; the joint-value branch checks length, not numeric/list type.

Referenced in source (1)

MoveToForm.build_form — mtc_gui.task_forms

`MoveToForm._apply_joint_preset()`

Set each joint editor from the matching preset angle.

Callback · Source

_apply_joint_preset(self, values)

Parameter	Meaning
`values`	Joint-angle sequence in degrees; zip limits updates to six widgets.

Returns: None.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Updates joint spin boxes; their valueChanged connections may trigger preview callbacks repeatedly.

Referenced in source (1)

MoveToForm.build_form — mtc_gui.task_forms

`MoveToForm._read_current_pose()`

Copy the pose snapshot supplied when the dialog opened into the joint editors.

Callback · Source

_read_current_pose(self)

Returns: None.

Errors: When current_pose is None, shows No Pose and returns. Invalid values/Qt errors otherwise propagate.

Side effects: Changes joint values and may issue visual preview callbacks; does not query ROS.

Referenced in source (1)

MoveToForm.build_form — mtc_gui.task_forms

`MoveToForm._apply_mode()`

Show only the selected move branch and update the explanatory/preview display.

Callback · Source

_apply_mode(self, mode)

Parameter	Meaning
`mode`	One of the four mode labels; unknown text hides all groups and clears the explanation.

Returns: None.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Toggles named/relative/Cartesian/planning/joint groups, sets explanatory text, and calls _emit_preview.

Referenced in source (1)

MoveToForm.build_form — mtc_gui.task_forms

`MoveToForm._emit_preview()`

Preview explicit joint values or a known six-value named pose; end preview for unsupported goal representations.

Callback · Source

_emit_preview(self, _=None)

Parameter	Meaning
`_`	Ignored Qt signal payload, such as changed spin-box value or target text.

Returns: None.

Errors: Returns immediately without preview_cb. Callback/widget errors propagate; named targets must map to a list/tuple of length six.

Side effects: Invokes preview_cb with a new degree-valued list, or end_preview_cb for unknown named/relative/Cartesian modes. No robot motion is requested.

Referenced in source (2)

MoveToForm._apply_mode — mtc_gui.task_forms
MoveToForm.build_form — mtc_gui.task_forms

`_GridSelectorForm`

Share grid selection and target-configuration editing between rack forms. It merges beamline defaults with task overrides and serializes the complete edited configuration.

Inherits from: BaseTaskForm.

`_GridSelectorForm.collect_values()`

Validate grid directions and serialize the selected cell with a complete configuration override.

Extension hook · Source

collect_values(self)

Returns: Task copy with zero-based row/col, position label, and a replacement config={mode:”grid”, marker_id, scan_pose, grid:{rows,cols,row_pitch,col_pitch,row_offset,col_offset,row_direction,col_direction,row_increasing,col_increasing}, moves:[offset sentinels or {direction,distance}]}. Distances are metres.

Errors: Raises ValueError if row/column increasing directions are neither the corresponding base direction nor its opposite; unknown base directions can raise KeyError. Does not check whether row and column axes differ.

Side effects: None beyond reading widgets; unrepresented prior config keys are dropped from the returned config.

`_GridSelectorForm.build_form()`

Build the grid editor from beamline defaults merged with task overrides.

Extension hook · Source

build_form(self)

Returns: None.

Errors: Nonmapping target/override values are guarded, but malformed nested grids/dimensions can raise. Initial dimensions are converted directly before the later spin-box limits apply.

Side effects: Deep-copies target configuration, shallow-merges non-grid override keys, merges grid keys separately, builds cells/config widgets, wires resizing, and sizes the dialog.

Internal callbacks and helpers

`_GridSelectorForm._add_layout_hint()`

Add a small word-wrapped hint to a supplied form layout.

Internal helper · Source

@staticmethod
_add_layout_hint(layout, text)

Parameter	Meaning
`layout`	QFormLayout receiving the label.
`text`	Explanatory text to display.

Returns: None.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Creates a QLabel and adds it as a layout row.

Referenced in source (1)

_GridSelectorForm.build_form — mtc_gui.task_forms

`_GridSelectorForm._build_grid()`

Recreate labeled grid buttons and clamp the selected cell to the current dimensions.

Internal helper · Source

_build_grid(self)

Returns: None.

Errors: No positive-dimension validation here; zero dimensions can leave selected indices at −1. Qt errors propagate.

Side effects: Removes old layout widgets via deleteLater, resets button mapping, builds row letters/column numbers and click handlers, then styles the selected cell.

Referenced in source (2)

_GridSelectorForm._resize_grid — mtc_gui.task_forms
_GridSelectorForm.build_form — mtc_gui.task_forms

`_GridSelectorForm._resize_grid()`

Apply row/column count widget values and rebuild the position selector.

Callback · Source

_resize_grid(self)

Returns: None.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Sets dimensions, rebuilds cells, clamps selection through _build_grid, and refreshes the selected-cell label.

Referenced in source (1)

_GridSelectorForm.build_form — mtc_gui.task_forms

`_GridSelectorForm._distance_spin()`

Create a six-decimal metre-distance editor with a 0.001 increment.

Internal helper · Source

@staticmethod
_distance_spin(value, *, positive=False)

Parameter	Meaning
`value`	Initial numeric value converted with float.
`positive`	True selects a 0.000001 minimum; False selects −2.0. Both use a 2.0 maximum.

Returns: Created QDoubleSpinBox.

Errors: Numeric/Qt errors propagate; widget clamps out-of-range values.

Side effects: Allocates a spin box; caller inserts it in a layout.

Referenced in source (2)

_GridSelectorForm._add_move — mtc_gui.task_forms
_GridSelectorForm._build_config — mtc_gui.task_forms

`_GridSelectorForm._direction_combo()`

Create a combo for the six flange-direction names.

Internal helper · Source

_direction_combo(self, value)

Parameter	Meaning
`value`	Initial direction text; unmatched values leave the first option, forward, selected.

Returns: Created QComboBox.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Allocates and initializes the combo.

Referenced in source (2)

_GridSelectorForm._add_move — mtc_gui.task_forms
_GridSelectorForm._build_config — mtc_gui.task_forms

`_GridSelectorForm._build_config()`

Build marker/scan, grid geometry, axis-direction, and ordered movement controls from merged target settings.

Internal helper · Source

_build_config(self, target_cfg, grid_cfg)

Parameter	Meaning
`target_cfg`	Merged vision-target mapping containing marker_id, scan_pose, marker_offset, and moves.
`grid_cfg`	Grid mapping for dimensions, pitch/row_pitch/col_pitch, offsets, and axis directions/increasing directions.

Returns: None.

Errors: Malformed values raise. Row/column direction keys outside _OPPOSITE raise KeyError even when an increasing override is present, because the default expression is evaluated eagerly. Widget limits are rows 1…26, columns 1…99, distance ±2 m, and positive pitch/fixed distance at least 1e-6 m.

Side effects: Adds configuration groups and movement table. Offset defaults use absolute marker_offset y/x; pitch defaults to 0.009 m. Adds a default fixed move when moves is empty.

Referenced in source (1)

_GridSelectorForm.build_form — mtc_gui.task_forms

`_GridSelectorForm._add_move()`

Append a fixed or computed-offset movement row and select it.

Callback · Source

_add_move(self, move=None)

Parameter	Meaning
`move`	“column_offset” or “row_offset” sentinel, or {direction, distance} mapping for a fixed move. None and other values create forward 0.01 m, including a button’s false checked payload.

Returns: None.

Errors: Malformed numeric values/Qt errors propagate; fixed-distance widget clamps to 1e-6…2 m.

Side effects: Creates kind/direction/distance cell widgets and connects enablement to movement kind.

Referenced in source (2)

_GridSelectorForm._build_config — mtc_gui.task_forms
_GridSelectorForm._set_moves — mtc_gui.task_forms

`_GridSelectorForm._add_move.toggle_fixed()`

Enable direction and distance only for a fixed movement row.

Callback · Source

toggle_fixed(text)

Parameter	Meaning
`text`	Kind-combo text; only “Fixed move” enables editable motion values.

Returns: None.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Changes the two captured cell widgets’ enabled state.

Referenced in source (1)

_GridSelectorForm._add_move — mtc_gui.task_forms

`_GridSelectorForm._move_value()`

Read one movement row into the task configuration representation.

Internal helper · Source

_move_value(self, row)

Parameter	Meaning
`row`	Zero-based table row containing the three expected cell widgets.

Returns: “column_offset”, “row_offset”, or {“direction”: string, “distance”: metres_float}.

Errors: Invalid rows/missing widgets raise; no local guard.

Side effects: None beyond reading table widgets.

Referenced in source (2)

_GridSelectorForm._move_selected — mtc_gui.task_forms
_GridSelectorForm.collect_values — mtc_gui.task_forms

`_GridSelectorForm._set_moves()`

Replace every movement row from serialized movement values.

Internal helper · Source

_set_moves(self, moves)

Parameter	Meaning
`moves`	Iterable of offset sentinels or fixed-move mappings accepted by _add_move.

Returns: None.

Errors: Row-construction failures propagate after old rows have been cleared.

Side effects: Clears the table and appends new rows; the last appended row becomes current, and an empty iterable leaves no rows.

Referenced in source (1)

_GridSelectorForm._move_selected — mtc_gui.task_forms

`_GridSelectorForm._remove_move()`

Remove the selected movement while preserving at least one table row.

Callback · Source

_remove_move(self)

Returns: None.

Errors: Returns when the table has one or zero rows; Qt errors propagate.

Side effects: Removes selected row, or row zero when there is no selection, and selects the nearest remaining row.

Referenced in source (1)

_GridSelectorForm._build_config — mtc_gui.task_forms

`_GridSelectorForm._move_selected()`

Swap the selected movement with a row delta and rebuild the table.

Callback · Source

_move_selected(self, delta)

Parameter	Meaning
`delta`	Row offset, normally −1 for Up or +1 for Down; larger values swap directly rather than shifting intervening rows.

Returns: None.

Errors: No selected row or an out-of-bounds destination is a no-op; serialization/Qt errors propagate.

Side effects: Serializes rows, swaps two values, rebuilds widgets, and selects the destination.

Referenced in source (1)

_GridSelectorForm._build_config — mtc_gui.task_forms

`_GridSelectorForm._cell_name()`

Format a zero-based grid coordinate as a row letter and one-based column number.

Internal helper · Source

_cell_name(self, row, col)

Parameter	Meaning
`row`	Zero-based row; row 0 maps to A. Values above 25 continue Unicode characters rather than producing spreadsheet-style AA.
`col`	Zero-based column; displayed as col + 1.

Returns: Cell label such as A1 or B5.

Errors: No bounds checking; invalid numeric types or chr range errors propagate.

Referenced in source (5)

_GridSelectorForm._build_grid — mtc_gui.task_forms
_GridSelectorForm._resize_grid — mtc_gui.task_forms
_GridSelectorForm._select_cell — mtc_gui.task_forms
_GridSelectorForm.build_form — mtc_gui.task_forms
_GridSelectorForm.collect_values — mtc_gui.task_forms

`_GridSelectorForm._select_cell()`

Store a clicked grid coordinate and update its visible selection.

Callback · Source

_select_cell(self, row, col)

Parameter	Meaning
`row`	Zero-based selected row.
`col`	Zero-based selected column.

Returns: None.

Errors: No grid-bounds validation; Qt errors propagate.

Side effects: Updates selected indices, button styling/check states, and the cell-name label.

Referenced in source (1)

_GridSelectorForm._build_grid — mtc_gui.task_forms

`_GridSelectorForm._update_selection()`

Mark only the stored selected coordinate checked with green emphasis.

Internal helper · Source

_update_selection(self)

Returns: None.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Iterates grid buttons and updates their checked states/styles.

Referenced in source (2)

_GridSelectorForm._build_grid — mtc_gui.task_forms
_GridSelectorForm._select_cell — mtc_gui.task_forms

`SampleForm`

Share the Pick Sample and Place Sample editor. It switches between vision-based inputs and explicit approach/target poses.

Inherits from: BaseTaskForm.

`SampleForm.init()`

Select Pick Sample only for pick_sample; all other task types use Place Sample.

Lifecycle · Source

__init__(self, step, step_index, poses, parent=None)

Parameter	Meaning
`step`	Task mapping to edit; BaseTaskForm deep-copies it.
`step_index`	Zero-based queue index used in the title as Step index + 1.
`poses`	Mapping of named poses to six joint angles in degrees; stored by reference.
`parent`	Optional parent QWidget.

Errors: Base/dialog errors propagate.

Side effects: Sets mode/title and builds the shared vision-versus-hardcoded editor.

`SampleForm.build_form()`

Build the vision-guided and explicit-pose alternatives for sample handling.

Extension hook · Source

build_form(self)

Returns: None.

Errors: Malformed initial numeric/text fields and Qt errors propagate; widgets constrain tag ID 0…999, Z offset ±0.1 m, marker offsets ±1 m, and flange distance 0…1 m.

Side effects: Creates and initializes controls; connects a visibility toggle and applies it immediately. It does not expose an editor for every possible task field, including sample_index.

`SampleForm.collect_values()`

Serialize the selected sample approach and remove fields belonging to the disabled branch.

Extension hook · Source

collect_values(self)

Returns: Task copy with use_vision. Vision writes detection_type, tag_id, scan_pose, z_offset, nonzero marker offsets, and optional flange direction/distance, removing approach_pose/target_pose. Hardcoded writes approach_pose/target_pose and removes listed vision fields, including sample_index.

Errors: No pose-name or detection-target validation beyond widget constraints.

Side effects: None beyond reading widgets; unrelated source fields remain in the copy.

Internal callbacks and helpers

`SampleForm.build_form.toggle()`

Switch between the vision and hardcoded pose sections.

Callback · Source

toggle(checked)

Parameter	Meaning
`checked`	Boolean vision-enabled state produced from the checkbox.

Returns: None.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Shows vision_group when true and hardcoded_group when false.

Referenced in source (1)

SampleForm.build_form — mtc_gui.task_forms

`VisionScanForm`

Edit the ordered scan poses, capture count per pose, and timeout for a vision scan.

Inherits from: BaseTaskForm.

`VisionScanForm.build_form()`

Create multiline scan-pose entry and controls for scans per position and timeout.

Extension hook · Source

build_form(self)

Returns: None.

Errors: Malformed initial scan list/numbers and Qt errors propagate; scans are constrained to 1…20 and timeout to 1…120 seconds.

Side effects: Builds the pose-list text area and scan settings. Its hint identifies the scan server as the owner of averaged marker poses; building the form makes no camera/service call.

`VisionScanForm.collect_values()`

Normalize nonblank pose-name lines and serialize scan count and timeout.

Extension hook · Source

collect_values(self)

Returns: Task copy with scan_positions as trimmed nonempty strings, scans_per_position integer, and timeout seconds float.

Errors: No check that positions exist or the list is nonempty.

Side effects: None beyond reading widgets.

`ToolExchangeForm`

Edit the load or dock operation, configured gripper, dock number, and approach pose.

Inherits from: BaseTaskForm.

`ToolExchangeForm.build_form()`

Build load/dock operation, configured gripper, dock-number, and approach-pose controls.

Extension hook · Source

build_form(self)

Returns: None.

Errors: Configuration helper failures yield an empty gripper combo; numeric/Qt errors propagate. Dock number is constrained to 1…10.

Side effects: Creates controls and connects future operation changes to automatic approach-name replacement; does not call that replacement during initial construction.

`ToolExchangeForm.collect_values()`

Serialize operation, gripper selection, dock number, and approach pose.

Extension hook · Source

collect_values(self)

Returns: Task copy with operation, gripper, dock_number, and approach_pose.

Errors: No gripper/pose existence validation; empty gripper text is possible when configuration was unavailable.

Side effects: None beyond reading widgets.

Internal callbacks and helpers

`ToolExchangeForm.build_form.update_approach()`

Replace the approach pose with the conventional name when operation changes.

Callback · Source

update_approach(text)

Parameter	Meaning
`text`	Operation text; “load” sets load_approach, “dock” sets dock_approach, other strings leave the field unchanged.

Returns: None.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Overwrites approach line-edit text, including any previous custom entry.

Referenced in source (1)

ToolExchangeForm.build_form — mtc_gui.task_forms

`EndEffectorForm`

Choose a configured gripper with named states and an end-effector action. Offered actions are the union across configured grippers.

Inherits from: BaseTaskForm.

`EndEffectorForm.build_form()`

Offer configured state-bearing grippers and the union of all grasp/release actions.

Extension hook · Source

build_form(self)

Returns: None.

Errors: Configuration lookup failures yield empty option lists; Qt errors propagate.

Side effects: Creates two independent combos; changing the gripper does not filter the action combo.

`EndEffectorForm.collect_values()`

Serialize the chosen end-effector type and action strings.

Extension hook · Source

collect_values(self)

Returns: Task copy with end_effector_type and end_effector_action.

Errors: Does not validate that the selected action belongs to the chosen gripper; empty values remain possible.

Side effects: None beyond reading widgets.

`VisionMoveToForm`

Edit marker or sample-ROI detection options, offsets, and the detect-only flag for vision-guided Move To.

Inherits from: BaseTaskForm.

`VisionMoveToForm.build_form()`

Build detection, offset, timeout, and detect-only controls for vision-guided Move To.

Extension hook · Source

build_form(self)

Returns: None.

Errors: Malformed numeric fields and Qt errors propagate. Bounds include tag 0…999, edge inset 0…999 mm, Z ±0.1 m, timeout 1…120 s, marker offsets ±1 m, and flange distance 0…1 m.

Side effects: Creates widgets, connects detection-type visibility changes, and applies initial visibility; sends no detection or motion request.

`VisionMoveToForm.collect_values()`

Serialize detection options while removing the inactive detector’s fields and zero/disabled offsets.

Extension hook · Source

collect_values(self)

Returns: Task copy with detection_type, tag_id, z_offset (m), timeout (s), detect_only, optional nonzero marker offsets and flange direction/distance. sample_roi adds strategy/edge_inset_mm and removes marker_dictionary; marker adds marker_dictionary and removes strategy/edge_inset_mm.

Errors: No cross-field or target-existence validation beyond widget constraints.

Side effects: None beyond reading widgets.

Internal callbacks and helpers

`VisionMoveToForm._apply_detection_type()`

Show sample-ROI strategy/inset controls or the ArUco dictionary selector.

Callback · Source

_apply_detection_type(self, detection_type)

Parameter	Meaning
`detection_type`	“sample_roi” selects ROI controls; all other values show dictionary controls.

Returns: None.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Toggles dictionary label/combo and the sample-ROI group.

Referenced in source (1)

VisionMoveToForm.build_form — mtc_gui.task_forms

`PipettorForm`

Edit the pipettor operation, normalized volume, and LED color. The color preview only changes the editor’s display.

Inherits from: BaseTaskForm.

`PipettorForm.build_form()`

Build SUCK/EXPEL/EJECT_TIP/SET_LED controls, normalized volume, and RGB color preview.

Extension hook · Source

build_form(self)

Returns: None.

Errors: Malformed led_color/numbers and Qt errors propagate. Volume and each RGB channel are constrained to 0…1, despite the Volume % label.

Side effects: Creates operation/volume/color editors, initializes a swatch, and connects RGB changes to swatch repainting.

`PipettorForm.collect_values()`

Serialize the pipettor operation, normalized volume, and RGB color for every operation.

Extension hook · Source

collect_values(self)

Returns: Task copy with operation, volume_pct float 0…1, and led_color={r,g,b}, each 0…1.

Errors: No operation-specific validation or removal of unused volume/color fields.

Side effects: None beyond reading widgets.

Internal callbacks and helpers

`PipettorForm._update_preview()`

Convert normalized RGB widget values to integer 0–255 channels for the color swatch.

Callback · Source

_update_preview(self)

Returns: None.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Replaces the preview label stylesheet; does not command a physical LED.

Referenced in source (1)

PipettorForm.build_form — mtc_gui.task_forms

`PickupTipForm`

Specialize the grid editor for a tip rack and its selected pickup cell.

Inherits from: _GridSelectorForm.

`PickupTipForm.build_form()`

Build the tip_rack grid editor and explain the vision-aligned pickup.

Extension hook · Source

build_form(self)

Returns: None.

Errors: Inherited grid/config and Qt errors propagate; grid dimensions come from the configured target and task overrides.

Side effects: Creates grid/config controls and tip-specific explanatory text.

`PickupVialForm`

Specialize the grid editor for a vial rack and optional pipettor operations, including rinse count.

Inherits from: _GridSelectorForm.

`PickupVialForm.build_form()`

Build the vial_rack grid editor and optional SUCK/EXPEL/RINSE operation controls.

Extension hook · Source

build_form(self)

Returns: None.

Errors: Inherited grid and numeric/Qt errors propagate; volume is 0…1 and rinse count 1…100. Grid dimensions come from the configured target and task overrides.

Side effects: Creates operation/volume/rinse fields, connects their enablement, and adds vial-specific hints.

`PickupVialForm.collect_values()`

Extend the grid result with optional pipettor settings while removing obsolete operation fields.

Extension hook · Source

collect_values(self)

Returns: Grid-form task result plus pipettor_operation and volume_pct when operation is not “None”; rinse_count only for RINSE. “None” removes all three fields.

Errors: Inherited axis validation can raise ValueError/KeyError; widget errors propagate.

Side effects: None beyond reading widgets.

Internal callbacks and helpers

`PickupVialForm.build_form._toggle_volume()`

Enable volume for any requested operation and rinse count only for RINSE.

Callback · Source

_toggle_volume(text)

Parameter	Meaning
`text`	Operation combo text; “None” disables volume and every value other than “RINSE” disables rinse count.

Returns: None.

Errors: Qt/widget errors propagate; no local exception handler.

Side effects: Updates vial-volume and rinse-count enabled states.

Referenced in source (1)

PickupVialForm.build_form — mtc_gui.task_forms

`SpincoaterForm`

Share the Pick Spincoater and Place Spincoater editor, including scan/target poses, insertion distance, wrist correction, and placement-only release.

Inherits from: BaseTaskForm.

`SpincoaterForm.TITLE`

Select the pick/place title from the task variant.

Method · Source

@property
TITLE(self)

Access this as an instance property, without parentheses.

Returns: “Pick from Spincoater” or “Place on Spincoater”.

Errors: Requires self.step to have been initialized.

`SpincoaterForm.build_form()`

Build scan/target poses, forward insertion distance, wrist correction, and placement-only vacuum release.

Extension hook · Source

build_form(self)

Returns: None.

Errors: Numeric/Qt errors propagate; forward_distance is 0…0.05 m and k_offset is −90…90 degrees.

Side effects: Creates controls using pickup_pose for picks or place_pose for placements; both default target text to spincoater_place. Placement adds release=True by default.

`SpincoaterForm.collect_values()`

Serialize spincoater pose, forward-distance, and wrist-offset settings for the selected variant.

Extension hook · Source

collect_values(self)

Returns: Task copy with scan_pose, pickup_pose or place_pose, forward_distance in metres, k_offset in degrees, and placement-only release from its checkbox.

Errors: No pose-existence validation; widget errors propagate.

Side effects: None beyond reading widgets. Unrelated fields, including an old release field on a pick task, remain because the result starts from the task copy.

Internal callbacks and helpers

`SpincoaterForm._is_pick`

Determine whether this task uses the spincoater pickup variant.

Internal helper · Source

@property
_is_pick(self)

Access this as an instance property, without parentheses.

Returns: True only when task_type equals “pick_spincoater”.

Errors: No extra validation.

Referenced in source (3)

SpincoaterForm.TITLE — mtc_gui.task_forms
SpincoaterForm.build_form — mtc_gui.task_forms
SpincoaterForm.collect_values — mtc_gui.task_forms

Task editor forms

How it is used

Start here

Example

Functions

open_task_form()

Internal callbacks and helpers

_configured_grippers()

_grippers_with_states()

_end_effector_actions()

_vision_target_config()

BaseTaskForm

BaseTaskForm.build_form()

BaseTaskForm.collect_values()

BaseTaskForm.__init__()

BaseTaskForm.add_combo()

BaseTaskForm.add_text()

BaseTaskForm.add_float()

BaseTaskForm.add_int()

BaseTaskForm.add_check()

BaseTaskForm.add_section()

BaseTaskForm.add_hint()

BaseTaskForm.add_offset_row()

Internal callbacks and helpers

BaseTaskForm._on_save()

MoveToForm

MoveToForm.collect_values()

MoveToForm.__init__()

MoveToForm.build_form()

MoveToForm.done()

Internal callbacks and helpers

MoveToForm._detect_mode()

MoveToForm._apply_joint_preset()

MoveToForm._read_current_pose()

MoveToForm._apply_mode()

MoveToForm._emit_preview()

_GridSelectorForm

_GridSelectorForm.collect_values()

_GridSelectorForm.build_form()

Internal callbacks and helpers

_GridSelectorForm._add_layout_hint()

_GridSelectorForm._build_grid()

_GridSelectorForm._resize_grid()

_GridSelectorForm._distance_spin()

_GridSelectorForm._direction_combo()

_GridSelectorForm._build_config()

_GridSelectorForm._add_move()

_GridSelectorForm._add_move.toggle_fixed()

_GridSelectorForm._move_value()

_GridSelectorForm._set_moves()

_GridSelectorForm._remove_move()

_GridSelectorForm._move_selected()

_GridSelectorForm._cell_name()

_GridSelectorForm._select_cell()

_GridSelectorForm._update_selection()

SampleForm

SampleForm.__init__()

SampleForm.build_form()

SampleForm.collect_values()

Internal callbacks and helpers

SampleForm.build_form.toggle()

VisionScanForm

VisionScanForm.build_form()

VisionScanForm.collect_values()

ToolExchangeForm

ToolExchangeForm.build_form()

ToolExchangeForm.collect_values()

Internal callbacks and helpers

ToolExchangeForm.build_form.update_approach()

EndEffectorForm

EndEffectorForm.build_form()

EndEffectorForm.collect_values()

VisionMoveToForm

VisionMoveToForm.build_form()

VisionMoveToForm.collect_values()

Internal callbacks and helpers

VisionMoveToForm._apply_detection_type()

PipettorForm

PipettorForm.build_form()

PipettorForm.collect_values()

`open_task_form()`

`_configured_grippers()`

`_grippers_with_states()`

`_end_effector_actions()`

`_vision_target_config()`

`BaseTaskForm`

`BaseTaskForm.build_form()`

`BaseTaskForm.collect_values()`

`BaseTaskForm.init()`

`BaseTaskForm.add_combo()`

`BaseTaskForm.add_text()`

`BaseTaskForm.add_float()`

`BaseTaskForm.add_int()`

`BaseTaskForm.add_check()`

`BaseTaskForm.add_section()`

`BaseTaskForm.add_hint()`

`BaseTaskForm.add_offset_row()`

`BaseTaskForm._on_save()`

`MoveToForm`

`MoveToForm.collect_values()`

`MoveToForm.init()`

`MoveToForm.build_form()`

`MoveToForm.done()`

`MoveToForm._detect_mode()`

`MoveToForm._apply_joint_preset()`

`MoveToForm._read_current_pose()`

`MoveToForm._apply_mode()`

`MoveToForm._emit_preview()`

`_GridSelectorForm`

`_GridSelectorForm.collect_values()`

`_GridSelectorForm.build_form()`

`_GridSelectorForm._add_layout_hint()`

`_GridSelectorForm._build_grid()`

`_GridSelectorForm._resize_grid()`

`_GridSelectorForm._distance_spin()`

`_GridSelectorForm._direction_combo()`

`_GridSelectorForm._build_config()`

`_GridSelectorForm._add_move()`

`_GridSelectorForm._add_move.toggle_fixed()`

`_GridSelectorForm._move_value()`

`_GridSelectorForm._set_moves()`

`_GridSelectorForm._remove_move()`

`_GridSelectorForm._move_selected()`

`_GridSelectorForm._cell_name()`

`_GridSelectorForm._select_cell()`

`_GridSelectorForm._update_selection()`

`SampleForm`

`SampleForm.init()`

`SampleForm.build_form()`

`SampleForm.collect_values()`

`SampleForm.build_form.toggle()`

`VisionScanForm`

`VisionScanForm.build_form()`

`VisionScanForm.collect_values()`

`ToolExchangeForm`

`ToolExchangeForm.build_form()`

`ToolExchangeForm.collect_values()`

`ToolExchangeForm.build_form.update_approach()`

`EndEffectorForm`

`EndEffectorForm.build_form()`

`EndEffectorForm.collect_values()`

`VisionMoveToForm`

`VisionMoveToForm.build_form()`

`VisionMoveToForm.collect_values()`

`VisionMoveToForm._apply_detection_type()`

`PipettorForm`

`PipettorForm.build_form()`

`PipettorForm.collect_values()`

`PipettorForm._update_preview()`

`PickupTipForm`

`PickupTipForm.build_form()`

`PickupVialForm`

`PickupVialForm.build_form()`

`PickupVialForm.collect_values()`

`PickupVialForm.build_form._toggle_volume()`

`SpincoaterForm`

`SpincoaterForm.TITLE`

`SpincoaterForm.build_form()`

`SpincoaterForm.collect_values()`

`SpincoaterForm._is_pick`