npxpy.nodes.aligners.MarkerAligner

Bases: Node

Marker aligner class.

Attributes:

Name	Type	Description
image	Resources	Image object that the marker gets assigned.
name	str	Name of the marker aligner.
marker_size	List[float]	Size of markers in micrometers. Marker size must be greater than 0.
center_stage	bool	Centers stage if true.
action_upon_failure	str	'abort' or 'ignore' at failure (not yet implemented!).
laser_power	float	Laser power in mW.
scan_area_size	List[float]	Scan area size in micrometers.
scan_area_res_factors	List[float]	Resolution factors in scanned area.
detection_margin	float	Additional margin around marker imaging field in micrometers.
correlation_threshold	float	Correlation threshold below which abort is triggered in percent.
residual_threshold	float	Residual threshold of marker image.
max_outliers	int	Maximum amount of markers that are allowed to be outliers.
orthonormalize	bool	Whether to orthonormalize or not.
z_scan_sample_count	int	Number of z samples to be taken.
z_scan_sample_distance	float	Sampling distance in micrometers for z samples to be apart from each other.
z_scan_sample_mode	str	"correlation" or "intensity" for scan_z_sample_mode.
measure_z	bool	Whether to measure z or not.

Source code in npxpy/nodes/aligners.py

class MarkerAligner(Node):
    """
    Marker aligner class.

    Attributes:
        image (Resources): Image object that the marker gets assigned.
        name (str): Name of the marker aligner.
        marker_size (List[float]): Size of markers in micrometers. Marker size must be greater than 0.
        center_stage (bool): Centers stage if true.
        action_upon_failure (str): 'abort' or 'ignore' at failure (not yet implemented!).
        laser_power (float): Laser power in mW.
        scan_area_size (List[float]): Scan area size in micrometers.
        scan_area_res_factors (List[float]): Resolution factors in scanned area.
        detection_margin (float): Additional margin around marker imaging field in micrometers.
        correlation_threshold (float): Correlation threshold below which abort is triggered in percent.
        residual_threshold (float): Residual threshold of marker image.
        max_outliers (int): Maximum amount of markers that are allowed to be outliers.
        orthonormalize (bool): Whether to orthonormalize or not.
        z_scan_sample_count (int): Number of z samples to be taken.
        z_scan_sample_distance (float): Sampling distance in micrometers for z samples to be apart from each other.
        z_scan_sample_mode (str): "correlation" or "intensity" for scan_z_sample_mode.
        measure_z (bool): Whether to measure z or not.
    """

    def __init__(
        self,
        image: Image,
        name: str = "Marker aligner",
        marker_size: List[float] = [5.0, 5.0],
        center_stage: bool = True,
        action_upon_failure: str = "abort",
        laser_power: float = 0.5,
        scan_area_size: List[float] = [10.0, 10.0],
        scan_area_res_factors: List[float] = [2.0, 2.0],
        detection_margin: float = 5.0,
        correlation_threshold: float = 60.0,
        residual_threshold: float = 0.5,
        max_outliers: int = 0,
        orthonormalize: bool = True,
        z_scan_sample_count: int = 1,
        z_scan_sample_distance: float = 0.5,
        z_scan_sample_mode: str = "correlation",
        measure_z: bool = False,
    ):
        """
        Initializes the MarkerAligner with the provided parameters.
        """
        super().__init__(node_type="marker_alignment", name=name)

        # Set attributes via setters
        self.image = image
        self.marker_size = marker_size
        self.center_stage = center_stage
        self.action_upon_failure = action_upon_failure
        self.laser_power = laser_power
        self.scan_area_size = scan_area_size
        self.scan_area_res_factors = scan_area_res_factors
        self.detection_margin = detection_margin
        self.correlation_threshold = correlation_threshold
        self.residual_threshold = residual_threshold
        self.max_outliers = max_outliers
        self.orthonormalize = orthonormalize
        self.z_scan_sample_count = z_scan_sample_count
        self.z_scan_sample_distance = z_scan_sample_distance
        self.z_scan_sample_mode = z_scan_sample_mode
        self.measure_z = measure_z

        self.alignment_anchors = []

    # Property setters with validation
    @property
    def image(self) -> Image:
        return self._image

    @image.setter
    def image(self, value: Image):
        if not isinstance(value, Image):
            raise TypeError("image must be an instance of Image class.")
        self._image = value

    @property
    def marker_size(self) -> List[float]:
        return self._marker_size

    @marker_size.setter
    def marker_size(self, value: List[float]):
        if (
            not isinstance(value, list)
            or len(value) != 2
            or not all(isinstance(val, (float, int)) for val in value)
        ):
            raise TypeError(
                "marker_size must be a list of two positive numbers."
            )
        if value[0] <= 0 or value[1] <= 0:
            raise ValueError("marker_size must be greater than 0.")
        self._marker_size = value

    @property
    def center_stage(self) -> bool:
        return self._center_stage

    @center_stage.setter
    def center_stage(self, value: bool):
        if not isinstance(value, bool):
            raise TypeError("center_stage must be a boolean.")
        self._center_stage = value

    @property
    def action_upon_failure(self) -> str:
        return self._action_upon_failure

    @action_upon_failure.setter
    def action_upon_failure(self, value: str):
        if value not in ["abort", "ignore"]:
            raise ValueError(
                "action_upon_failure must be 'abort' or 'ignore'."
            )
        self._action_upon_failure = value

    @property
    def laser_power(self) -> float:
        return self._laser_power

    @laser_power.setter
    def laser_power(self, value: float):
        if not isinstance(value, (float, int)) or value < 0:
            raise ValueError("laser_power must be a non-negative number.")
        self._laser_power = value

    @property
    def scan_area_size(self) -> List[float]:
        return self._scan_area_size

    @scan_area_size.setter
    def scan_area_size(self, value: List[float]):
        if (
            not isinstance(value, list)
            or len(value) != 2
            or not all(isinstance(val, (float, int)) for val in value)
        ):
            raise TypeError("scan_area_size must be a list of two numbers.")
        self._scan_area_size = value

    @property
    def scan_area_res_factors(self) -> List[float]:
        return self._scan_area_res_factors

    @scan_area_res_factors.setter
    def scan_area_res_factors(self, value: List[float]):
        if (
            not isinstance(value, list)
            or len(value) != 2
            or not all(isinstance(val, (float, int)) for val in value)
        ):
            raise TypeError(
                "scan_area_res_factors must be a list of two numbers."
            )
        self._scan_area_res_factors = value

    @property
    def detection_margin(self) -> float:
        return self._detection_margin

    @detection_margin.setter
    def detection_margin(self, value: float):
        if not isinstance(value, (float, int)) or value < 0:
            raise ValueError("detection_margin must be a non-negative number.")
        self._detection_margin = value

    @property
    def correlation_threshold(self) -> float:
        return self._correlation_threshold

    @correlation_threshold.setter
    def correlation_threshold(self, value: float):
        if not isinstance(value, (float, int)) or not (0 <= value <= 100):
            raise ValueError(
                "correlation_threshold must be between 0 and 100."
            )
        self._correlation_threshold = value

    @property
    def residual_threshold(self) -> float:
        return self._residual_threshold

    @residual_threshold.setter
    def residual_threshold(self, value: float):
        if not isinstance(value, (float, int)) or value < 0:
            raise ValueError(
                "residual_threshold must be a non-negative number."
            )
        self._residual_threshold = value

    @property
    def max_outliers(self) -> int:
        return self._max_outliers

    @max_outliers.setter
    def max_outliers(self, value: int):
        if not isinstance(value, int) or value < 0:
            raise ValueError("max_outliers must be a non-negative integer.")
        self._max_outliers = value

    @property
    def orthonormalize(self) -> bool:
        return self._orthonormalize

    @orthonormalize.setter
    def orthonormalize(self, value: bool):
        if not isinstance(value, bool):
            raise TypeError("orthonormalize must be a boolean.")
        self._orthonormalize = value

    @property
    def z_scan_sample_count(self) -> int:
        return self._z_scan_sample_count

    @z_scan_sample_count.setter
    def z_scan_sample_count(self, value: int):
        if not isinstance(value, int) or value < 1:
            raise ValueError("z_scan_sample_count must be at least 1.")
        self._z_scan_sample_count = value

    @property
    def z_scan_sample_distance(self) -> float:
        return self._z_scan_sample_distance

    @z_scan_sample_distance.setter
    def z_scan_sample_distance(self, value: float):
        if not isinstance(value, (float, int)) or value <= 0:
            raise ValueError(
                "z_scan_sample_distance must be a positive number."
            )
        self._z_scan_sample_distance = value

    @property
    def z_scan_sample_mode(self) -> str:
        return self._z_scan_sample_mode

    @z_scan_sample_mode.setter
    def z_scan_sample_mode(self, value: str):
        if value not in ["correlation", "intensity"]:
            raise ValueError(
                'z_scan_sample_mode must be either "correlation" or "intensity".'
            )
        self._z_scan_sample_mode = value

    @property
    def measure_z(self) -> bool:
        return self._measure_z

    @measure_z.setter
    def measure_z(self, value: bool):
        if not isinstance(value, bool):
            raise TypeError("measure_z must be a boolean.")
        self._measure_z = value

    def add_marker(
        self, position: List[float], orientation: float, label: str
    ):
        """
        Adds a marker to the alignment anchors.
        """
        if not isinstance(label, str):
            raise TypeError("label must be a string.")
        if not isinstance(orientation, (float, int)):
            try:
                float(orientation)
            except:
                raise TypeError("orientation must be a float or an int.")
        if (
            not isinstance(position, list)
            or len(position) != 3
            or not all(isinstance(val, (float, int)) for val in position)
        ):
            raise TypeError("position must be a list of three numbers.")

        self.alignment_anchors.append(
            {"label": label, "position": position, "rotation": orientation}
        )
        return self

    def set_markers_at(
        self,
        positions: List[List[float]],
        orientations: List[float] = None,
        labels: List[str] = None,
    ):
        """
        Creates multiple markers at specified positions with given orientations.
        """
        if labels is None:
            labels = [f"marker_{i}" for i in range(len(positions))]
        if orientations is None:
            orientations = [0 for i in range(len(positions))]
        if len(labels) != len(positions) or len(labels) != len(orientations):
            raise ValueError(
                "The number of labels, positions, and orientations must match."
            )

        for label in labels:
            if not isinstance(label, str):
                raise TypeError("All labels must be strings.")

        for position in positions:
            if (
                not isinstance(position, list)
                or len(position) != 3
                or not all(isinstance(val, (float, int)) for val in position)
            ):
                raise TypeError(
                    "All positions must be lists of three numbers."
                )

        for label, orientation, position in zip(
            labels, orientations, positions
        ):
            self.add_marker(position, orientation, label)
        return self

    def to_dict(self) -> Dict:
        """
        Converts the current state of the object into a dictionary representation.
        """
        node_dict = super().to_dict()
        node_dict.update(
            {
                "marker": {"image": self.image.id, "size": self.marker_size},
                "center_stage": self.center_stage,
                "action_upon_failure": self.action_upon_failure,
                "laser_power": self.laser_power,
                "scan_area_size": self.scan_area_size,
                "scan_area_res_factors": self.scan_area_res_factors,
                "detection_margin": self.detection_margin,
                "correlation_threshold": self.correlation_threshold,
                "residual_threshold": self.residual_threshold,
                "max_outliers": self.max_outliers,
                "orthonormalize": self.orthonormalize,
                "z_scan_sample_count": self.z_scan_sample_count,
                "z_scan_sample_distance": self.z_scan_sample_distance,
                "z_scan_optimization_mode": self.z_scan_sample_mode,
                "measure_z": self.measure_z,
                "alignment_anchors": self.alignment_anchors,
            }
        )
        return node_dict

__init__(image, name='Marker aligner', marker_size=[5.0, 5.0], center_stage=True, action_upon_failure='abort', laser_power=0.5, scan_area_size=[10.0, 10.0], scan_area_res_factors=[2.0, 2.0], detection_margin=5.0, correlation_threshold=60.0, residual_threshold=0.5, max_outliers=0, orthonormalize=True, z_scan_sample_count=1, z_scan_sample_distance=0.5, z_scan_sample_mode='correlation', measure_z=False)

Initializes the MarkerAligner with the provided parameters.

Source code in npxpy/nodes/aligners.py

def __init__(
    self,
    image: Image,
    name: str = "Marker aligner",
    marker_size: List[float] = [5.0, 5.0],
    center_stage: bool = True,
    action_upon_failure: str = "abort",
    laser_power: float = 0.5,
    scan_area_size: List[float] = [10.0, 10.0],
    scan_area_res_factors: List[float] = [2.0, 2.0],
    detection_margin: float = 5.0,
    correlation_threshold: float = 60.0,
    residual_threshold: float = 0.5,
    max_outliers: int = 0,
    orthonormalize: bool = True,
    z_scan_sample_count: int = 1,
    z_scan_sample_distance: float = 0.5,
    z_scan_sample_mode: str = "correlation",
    measure_z: bool = False,
):
    """
    Initializes the MarkerAligner with the provided parameters.
    """
    super().__init__(node_type="marker_alignment", name=name)

    # Set attributes via setters
    self.image = image
    self.marker_size = marker_size
    self.center_stage = center_stage
    self.action_upon_failure = action_upon_failure
    self.laser_power = laser_power
    self.scan_area_size = scan_area_size
    self.scan_area_res_factors = scan_area_res_factors
    self.detection_margin = detection_margin
    self.correlation_threshold = correlation_threshold
    self.residual_threshold = residual_threshold
    self.max_outliers = max_outliers
    self.orthonormalize = orthonormalize
    self.z_scan_sample_count = z_scan_sample_count
    self.z_scan_sample_distance = z_scan_sample_distance
    self.z_scan_sample_mode = z_scan_sample_mode
    self.measure_z = measure_z

    self.alignment_anchors = []

add_marker(position, orientation, label)

Adds a marker to the alignment anchors.

Source code in npxpy/nodes/aligners.py

def add_marker(
    self, position: List[float], orientation: float, label: str
):
    """
    Adds a marker to the alignment anchors.
    """
    if not isinstance(label, str):
        raise TypeError("label must be a string.")
    if not isinstance(orientation, (float, int)):
        try:
            float(orientation)
        except:
            raise TypeError("orientation must be a float or an int.")
    if (
        not isinstance(position, list)
        or len(position) != 3
        or not all(isinstance(val, (float, int)) for val in position)
    ):
        raise TypeError("position must be a list of three numbers.")

    self.alignment_anchors.append(
        {"label": label, "position": position, "rotation": orientation}
    )
    return self

set_markers_at(positions, orientations=None, labels=None)

Creates multiple markers at specified positions with given orientations.

Source code in npxpy/nodes/aligners.py

def set_markers_at(
    self,
    positions: List[List[float]],
    orientations: List[float] = None,
    labels: List[str] = None,
):
    """
    Creates multiple markers at specified positions with given orientations.
    """
    if labels is None:
        labels = [f"marker_{i}" for i in range(len(positions))]
    if orientations is None:
        orientations = [0 for i in range(len(positions))]
    if len(labels) != len(positions) or len(labels) != len(orientations):
        raise ValueError(
            "The number of labels, positions, and orientations must match."
        )

    for label in labels:
        if not isinstance(label, str):
            raise TypeError("All labels must be strings.")

    for position in positions:
        if (
            not isinstance(position, list)
            or len(position) != 3
            or not all(isinstance(val, (float, int)) for val in position)
        ):
            raise TypeError(
                "All positions must be lists of three numbers."
            )

    for label, orientation, position in zip(
        labels, orientations, positions
    ):
        self.add_marker(position, orientation, label)
    return self

to_dict()

Converts the current state of the object into a dictionary representation.

Source code in npxpy/nodes/aligners.py

def to_dict(self) -> Dict:
    """
    Converts the current state of the object into a dictionary representation.
    """
    node_dict = super().to_dict()
    node_dict.update(
        {
            "marker": {"image": self.image.id, "size": self.marker_size},
            "center_stage": self.center_stage,
            "action_upon_failure": self.action_upon_failure,
            "laser_power": self.laser_power,
            "scan_area_size": self.scan_area_size,
            "scan_area_res_factors": self.scan_area_res_factors,
            "detection_margin": self.detection_margin,
            "correlation_threshold": self.correlation_threshold,
            "residual_threshold": self.residual_threshold,
            "max_outliers": self.max_outliers,
            "orthonormalize": self.orthonormalize,
            "z_scan_sample_count": self.z_scan_sample_count,
            "z_scan_sample_distance": self.z_scan_sample_distance,
            "z_scan_optimization_mode": self.z_scan_sample_mode,
            "measure_z": self.measure_z,
            "alignment_anchors": self.alignment_anchors,
        }
    )
    return node_dict