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

Image point selector

Show a Tk image window for pixel selection and return the result to the MCP process as JSON. Display configuration is probed by main(), not at import.

src.beambot.mcp_server.point_selector_gui Β· Source

Perception and mapping Β· Guide Β· Symbol index

How it is used

The MCP depth tool starts this script as a separate process when a person must confirm a pixel. main() reads the image and optional initial coordinates, runs the selector, and prints one JSON result to stdout. A Tk installation and usable display are required.

PointSelector.run() manages the window and input callbacks. The displayed image may be scaled down, but returned coordinates always refer to the original image.

Start here

Callable

Purpose

main

Fill missing display credentials, parse image path/title and an optional coordinate pair, run the selector and print its JSON result for the parent MCP process.

PointSelector.run

Show the selector window and wait for confirmation or cancellation. Mouse clicks choose original-image pixel coordinates; keyboard and window callbacks finish the selection.

Functions

main()

Fill missing display credentials, parse image path/title and an optional coordinate pair, run the selector and print its JSON result for the parent MCP process.

Entry point Β· Source

main()

Returns: None on normal selection/cancel; exits status 1 on a caught GUI/image Exception.

Errors: Argparse errors exit; GUI construction/run Exceptions produce {confirmed:false,error} on stdout before exit(1). A lone –x or –y is ignored.

Side effects: May probe the desktop session and set DISPLAY/XAUTHORITY, then reads the image and opens a GUI; prints a single result line.

Internal callbacks and helpers

_ensure_display()

Fill missing DISPLAY from a desktop-process environment probe or :1, then choose the first existing common Xauthority path.

Internal helper Β· Source

_ensure_display()

Returns: None.

Errors: The three-second shell probe catches all Exceptions and uses :1; other filesystem errors propagate.

Side effects: May spawn bash/read process environment and modifies this process’s DISPLAY/XAUTHORITY. Runs at import.

Referenced in source (1)
  • main β€” src.beambot.mcp_server.point_selector_gui

PointSelector

Display an image with a movable crosshair and return the selected original-image pixel coordinates together with a confirmation flag.

PointSelector.run()

Show the selector window and wait for confirmation or cancellation. Mouse clicks choose original-image pixel coordinates; keyboard and window callbacks finish the selection.

Method Β· Source

run(self) -> dict

Returns: {pixel_x,pixel_y,confirmed:true} after confirming a selected point; otherwise {confirmed:false}.

Errors: Tk/display exceptions propagate to main(); confirming without any selected point leaves the window open.

Side effects: Creates an interactive GUI and blocks; selection and result mutate in response to events.

PointSelector.__init__()

Open the image and prepare a resized display image while preserving original-pixel selection coordinates.

Lifecycle Β· Source

__init__(
    self,
    image_path: str,
    initial_point: tuple[int, int] | None = None,
    title: str = 'Point Selector',
)

Parameter

Meaning

image_path

Image file path accepted by Pillow.

initial_point

Optional (column,row) in original pixels; not clamped at construction.

title

Window title used later by run().

Returns: None; initializes scale/display dimensions/current_point/result.

Errors: Image decoding/I/O or invalid dimensions can propagate errors.

Side effects: Reads image data and allocates a scaled image; does not open the Tk window yet.

Referenced in source (1)
  • main β€” src.beambot.mcp_server.point_selector_gui

Internal callbacks and helpers

PointSelector._draw_crosshair()

Copy the scaled display image and draw a red crosshair plus original-coordinate label at the current selection, then wrap it for Tk.

Internal helper Β· Source

_draw_crosshair(self) -> ImageTk.PhotoImage

Returns: ImageTk.PhotoImage; must be retained by caller to keep it displayed.

Errors: Requires a live Tk interpreter; Pillow/Tk drawing errors propagate.

Side effects: Allocates a Tk image; leaves the base image unchanged.

Referenced in source (2)

PointSelector.run._update_display()

Redraw the crosshair into a retained PhotoImage and replace the canvas image item.

Internal helper Β· Source

_update_display()

Returns: None.

Errors: Pillow/Tk errors propagate through the event callback.

Side effects: Updates self._tk_photo and the live canvas.

Referenced in source (1)

PointSelector.run._on_click()

Convert click coordinates from the scaled canvas to original pixels, clamp to image bounds and redraw the selection.

Callback Β· Source

_on_click(event)

Parameter

Meaning

event

Tk mouse event whose x/y are canvas pixel coordinates.

Returns: None.

Errors: Invalid event/scale errors propagate.

Side effects: Updates current_point and refreshes the GUI.

Referenced in source (1)

PointSelector.run._on_confirm()

When a point exists, store its original pixel coordinates with confirmed=true and destroy the window.

Callback Β· Source

_on_confirm(event=None)

Parameter

Meaning

event

Optional Tk key event; ignored.

Returns: None; no operation when current_point is None.

Errors: Tk destroy errors propagate. Initial coordinates are not validated here.

Side effects: Sets result and closes the GUI when a selection exists.

Referenced in source (1)

PointSelector.run._on_cancel()

Mark selection unconfirmed and destroy the Tk window.

Callback Β· Source

_on_cancel(event=None)

Parameter

Meaning

event

Optional key/window event; ignored.

Returns: None.

Errors: Tk errors propagate.

Side effects: Sets result={confirmed:false} and closes the GUI.

Referenced in source (1)