Skip to content

stage#

zen_api_utils.stage #

Classes:

  • PosXYZ –

    PosXYZ is a data class that represents a position in 3D space with coordinates

  • StageMark –

    Represents a stage mark with coordinates and an optional conversion to zero-based indexing and meters.

  • StageXYPosition –

    Represents a position on a stage with X and Y coordinates.

Functions:

  • parse_stage_marks –

    Parses an XML file to extract StageMark elements and their attributes.

  • get_stageXY_position_simple –

    Get the current stage position using the simple stage service.

  • move_to_stageXY_position_simple –

    Move the stage to a specified XY position using the simple stage service.

  • move_xyz –

    Asynchronously moves the stage and focus to specified X, Y, and Z positions and retrieves the updated positions.

PosXYZ dataclass #

PosXYZ(x_meter: float, y_meter: float, z_meter: Optional[float] = None)

PosXYZ is a data class that represents a position in 3D space with coordinates specified in meters and automatically calculates their equivalent values in microns.

Attributes:

  • x_meter (float) –

    The x-coordinate in meters.

  • y_meter (float) –

    The y-coordinate in meters.

  • z_meter (float) –

    The z-coordinate in meters. Defaults to None if not provided.

  • x_micron (float) –

    The x-coordinate in microns, calculated from x_meter.

  • y_micron (float) –

    The y-coordinate in microns, calculated from y_meter.

  • z_micron (float) –

    The z-coordinate in microns, calculated from z_meter.

Methods: post_init(): Automatically converts the meter values (x_meter, y_meter, z_meter) to micron values (x_micron, y_micron, z_micron) after initialization.

StageMark #

StageMark(item_index, x, y, z, convert_to_zero_based=True, convert_to_meter=True)

Represents a stage mark with coordinates and an optional conversion to zero-based indexing and meters. Attributes: index (int): The index of the item, adjusted to zero-based indexing if specified. x (float): The x-coordinate of the stage mark, optionally converted to meters. y (float): The y-coordinate of the stage mark, optionally converted to meters. z (float): The z-coordinate of the stage mark, optionally converted to meters. Args: item_index (int): The original index of the item. x (float): The x-coordinate of the stage mark. y (float): The y-coordinate of the stage mark. z (float): The z-coordinate of the stage mark. convert_to_zero_based (bool, optional): Whether to convert the index to zero-based. Defaults to True. convert_to_meter (bool, optional): Whether to convert the coordinates to meters. Defaults to True.

StageXYPosition #

StageXYPosition(x, y)

Represents a position on a stage with X and Y coordinates. This class encapsulates the coordinates of a position on a stage system, typically used for microscopy or other precision positioning applications. Attributes: x (float): The X coordinate position in meters. y (float): The Y coordinate position in meters. Example: >>> position = StagePosition(10.5, 20.3) >>> print(position) (X: 10.5 m; Y: 20.3 m)

parse_stage_marks #

parse_stage_marks(file_path: str | Path) -> list[StageMark]

Parses an XML file to extract StageMark elements and their attributes.

Parameters:

  • file_path (str | Path) –

    The path to the XML file to be parsed. Can be a string or Path object.

Returns:

  • list[StageMark] –

    list[StageMark]: A list of StageMark objects, each representing a StageMark element from the XML file. Each object contains the attributes: - index (int): The ItemIndex attribute (converted to zero-based). - x (float): The X coordinate in meters. - y (float): The Y coordinate in meters. - z (float): The Z coordinate in meters.

Raises:

  • FileNotFoundError –

    If the XML file does not exist.

  • ParseError –

    If the XML file is malformed.

Example File Content

get_stageXY_position_simple async #

get_stageXY_position_simple(simple_stage_service: SimpleStageServiceStub) -> StageXYPosition

Get the current stage position using the simple stage service. Args: simple_stage_service (SimpleStageServiceStub): The simple stage service stub used to communicate with the stage hardware. Returns: StageXYPosition: An object containing the current X and Y coordinates of the stage position. Raises: Any exceptions that may be raised by the simple_stage_service.get_position() call.

move_to_stageXY_position_simple async #

move_to_stageXY_position_simple(simple_stage_service: SimpleStageServiceStub, stage_positionXY: StageXYPosition) -> None

Move the stage to a specified XY position using the simple stage service.

Parameters:

  • simple_stage_service (SimpleStageServiceStub) –

    The gRPC service stub for controlling the simple stage.

  • stage_positionXY (StageXYPosition) –

    The target position containing x and y coordinates to move to.

Returns:

  • None –

    None

Raises:

  • RpcError –

    If the gRPC call fails or the stage movement encounters an error.

move_xyz async #

move_xyz(channel, metadata, pos_xyz: PosXYZ) -> PosXYZ

Asynchronously moves the stage and focus to specified X, Y, and Z positions and retrieves the updated positions. Args: channel: The gRPC channel used for communication with the services. metadata: Metadata for the gRPC requests. xpos (float): The target X-coordinate in microns. ypos (float): The target Y-coordinate in microns. zpos (float): The target Z-coordinate in microns. Returns: PosXYZ: An object containing the updated X, Y, and Z positions in meters. Raises: Any exceptions raised by the gRPC services during movement or position retrieval.