GUI

class castalign.gui.GraphViewer(*args: Any, **kwargs: Any)[source]

Bases: Viewer

Napari viewer with graph-aware image and point loading.

This viewer can be used just like a normal Napari viewer, except images can be node names in the graph, and images will be automatically transformed to a shared display space using graph transforms.

Examples

>>> gv = GraphViewer(graph=g, space="session1")
>>> gv.add_image("session1") # Display image for session1 directly
>>> gv.add_image("session2") # Transform to session1 space and then display
__init__(graph, space=None, *args, **kwargs)[source]

Create a graph-aware napari viewer.

Parameters:

  • graph (castalign.graph.Graph) – Graph used to load node images and transforms.

  • space (str or None, optional) – Initial display space. If set, incoming data from other spaces is transformed into this space. Otherwise, the space is set as the first image displayed.

  • *args, **kwargs – Forwarded to napari.Viewer.

add_image(data, space=None, name=None, **kwargs)[source]

Add image data to the viewer and transform if necessary.

Parameters:

  • data (ndarray, ndarray_shifted, or str) – Image data or graph node name.

  • space (str or None, optional) – Space/node for data.

  • name (str or None, optional) – Layer name.

  • **kwargs – Forwarded to napari.Viewer.add_image.

add_labels(data, space=None, name=None, **kwargs)[source]

Add label data to the viewer and transform if necessary.

Parameters:

  • data (ndarray, ndarray_shifted, or str) – Label data or graph node name.

  • space (str or None, optional) – Space/node for data.

  • name (str or None, optional) – Layer name.

  • **kwargs – Forwarded to napari.Viewer.add_labels.

add_points(data, space=None, **kwargs)[source]

Add points and transform if necessary.

Parameters:

  • data (array-like) – Point coordinates in (z, y, x) order.

  • space (str or None, optional) – Space/node associated with data.

  • **kwargs – Forwarded to napari.Viewer.add_points.

castalign.gui.alignment_gui(movable_image, base_image, transform=None, graph=None, references=[], crop=False, transform_type=None)[source]

Align images with a specific transform using a GUI.

This function uses a GUI to specify a given transform. All parameters can be set using sliders and text boxes on the side of the GUI, and translation parameters can be set by holding Ctrl+Shift to drag and drop the image. If it is a point-based transform, tools will be shown to select corresponding points in the two images. (Left clicking selects the point at the cursor, and right clicking selects the nearest local maximum of a low pass filtered image.) The transform can be applied in real-time with each change, or applied by clicking a button. When the GUI is closed, this function returns the most recent transform to be applied. (So, if you have selected additional points but not yet visualised them by clicking “Apply transform”, the most recently added points will not be included.)

The base image(s) and movable image(s( can be any of the following:

  • 2D or 3D arrays (2D arrays will be interpreted as (1, Y, X) 3D arrays)

  • The name of a node on the graph (given by the graph argument)

  • Multichannel images, specified as a tuple, with with each channel as an element of the tuple

  • Multichannel images from the graph, specified as a tuple of node names. They will all be transformed to the space of the first element of the tuple.

When there are multiple base or movable images, the coordinate system of the returned transform will always be from the first image in the tuple.

Additional images can be used as landmarks (“references”). These are transformed to the base image’s coordinate system and can be easily toggled on and off. They can be any of the following:

  • A list of 2D or 3D arrays (2D arrays will be interpreted as (1, Y, X) 3D arrays)

  • A list of tuples of length 2, where the first element is a 2D or 3D array and the second element is a transform. The arrays will be transformed according to the transform before being displayed. (I.e., the transform puts the array into the base coordinate system.)

  • A list of node names in the graph.

As some images can be large, the “crop” argument allows displaying a smaller region to increase speed and save memory. The resulting transform will be applied to the full image, not just the cropped region.

“crop” allows you to reduce the drawn area of the transformed image, making transforms faster and use less memory. If True, it will only show the area of the movable image that intersects with the first base image. If a tuple of numbers, it will show the region (zmax,ymax,xmax). If a tuple of tuples, it will show the region ((zmin,zmax),(ymin,ymax),(xmin,xmax)).

Parameters:

  • movable_image (ndarray, str, tuple, or list) – Movable image input. Accepted forms:

    • 2D or 3D ndarray (2D is treated as (1, Y, X) where needed)

    • tuple/list of ndarrays for multichannel display

    • node name (str), or tuple/list of node names, when graph is provided

  • base_image (ndarray, str, tuple, or list) – Base/fixed image input. Accepted forms are the same as movable_image.

  • transform (Transform subclass, Transform instance, or None, optional) – Starting transform for alignment:

    • Transform subclass: start from default parameters for that transform

    • Transform instance: continue editing an existing transform

    • None: use graph transform (if available), else Identity()

  • graph (castalign.graph.Graph or None, optional) – Graph context used for node-name image lookup and transform chaining. Required when passing node names in base_image, movable_image, or references.

  • references (list, optional) – Additional landmark overlays. Accepted forms:

    • list of 2D/3D ndarrays (2D treated as (1, Y, X) where needed)

    • list of (image, transform) tuples

    • list of node names when graph is provided

  • crop (bool or tuple, optional) – Display crop for transformed movable image:

    • False: do not crop

    • True: crop to the boundaries of the first base image

    • (zmax, ymax, xmax): crop from from 0 to these coordinates

    • ((zmin, zmax), (ymin, ymax), (xmin, xmax)): crop to these intervals

  • transform_type (Transform subclass or None, optional) – Deprecated alias for transform. Used only when transform is None.

Returns:

Final transform after interactive editing.

Return type:

Transform

Notes

If multiple base/movable images are provided, the returned transform is in the coordinate system of the first image in each list/tuple.

Crop affects only what is displayed for speed/memory, not the coordinate system of the returned transform.

castalign.gui.align_interactive_text(nodes_movable, nodes_fixed, graph=None, transform=None, references=[], start=None, crop=False)[source]

Run command-line interactive alignment.

Identical to align_interactive(), but using a command-line interface.

Parameters:

  • nodes_movable (ndarray, str, or sequence) – Movable image(s) or node name(s). Image arrays can be 2D or 3D; 2D arrays are promoted to 3D single-slice volumes where needed.

  • nodes_fixed (ndarray, str, or sequence) – Fixed image(s) or node name(s). Image arrays can be 2D or 3D; 2D arrays are promoted to 3D single-slice volumes where needed.

  • graph (castalign.graph.Graph or None, optional) – Graph used for node-name lookup and optional save actions.

  • transform (Transform, str, or None, optional) – Starting transform, or node name to resolve via graph.

  • references (list, optional) – Reference overlays as node names or (image, transform) tuples.

  • start (Transform or None, optional) – Deprecated alias for transform.

  • crop (bool or tuple, optional) – Cropping option forwarded to alignment_gui for preview rendering. Supports the same values as alignment_gui (False, True, (zmax, ymax, xmax), or full min/max bounds per axis).

Returns:

Final transform selected in the text workflow.

Return type:

Transform

castalign.gui.align_interactive(nodes_movable, nodes_fixed, graph=None, transform=None, references=[], start=None, crop=False)[source]

Align images with a GUI using chains of transforms

This is the primary tool used to align images in CASTalign. It can be used to visually create or edit chains of transforms from a buffet of options, either by setting points, dragging and dropping images, or chosing parameters. Transforms are updated in real time during editing.

On a practical level, the workflow is:

  1. Start with an initial transform (from transform, from the graph, or Identity by default).

  2. In the main dialog, choose a transform type (button or keyboard shortcut). This opens the lower-level alignment_gui editor for that stage.

  3. In the editor, adjust parameters and/or corresponding points, then close the editor to return to this dialog with the updated transform chain. Note that when selecting points, you can left click to select the point under the cursor, or right click to select the nearest local maximum near the cursor.

  4. Use “Modify / other actions” to edit/view/remove/undo/flip/toggle references or save.

  5. For point-based transforms, use extend (x prefix) or convert (c prefix) actions to refine/replace the current point-based stage.

  6. Quit to return the current transform.

The main dialog keeps an undo history and supports keyboard shortcuts for all major actions. If a graph is provided, transforms can be written back to the graph and optionally saved to disk.

Parameters:

  • nodes_movable (ndarray, str, or sequence) – Movable image(s) or node name(s). Image arrays can be 2D or 3D; 2D arrays are promoted to 3D single-slice volumes where needed.

  • nodes_fixed (ndarray, str, or sequence) – Fixed image(s) or node name(s). Image arrays can be 2D or 3D; 2D arrays are promoted to 3D single-slice volumes where needed.

  • graph (castalign.graph.Graph or None, optional) – Graph used for node-name lookup and save actions.

  • transform (Transform, str, or None, optional) – Starting transform, or node name to resolve via graph.

  • references (list, optional) – Reference overlays as node names or (image, transform) tuples.

  • start (Transform or None, optional) – Deprecated alias for transform.

  • crop (bool or tuple, optional) – Cropping option forwarded to alignment_gui for preview rendering. Supports the same values as alignment_gui (False, True, (zmax, ymax, xmax), or full min/max bounds per axis).

Returns:

Final transform selected in the GUI workflow.

Return type:

Transform