npxpy.nodes.aligners.InterfaceAligner

Bases: Node

A class representing an interface aligner node, responsible for managing alignment settings and grid patterns for various operations.

Attributes:

Name	Type	Description
alignment_anchors	List[Dict]	Stores the measurement locations (or interface anchors) for interface alignment.
count	List[int]	The number of grid points in [x, y] direction.
size	List[float]	The size of the grid in [width, height].
pattern	str	The pattern used for grid or custom alignment.

Source code in npxpy/nodes/aligners.py

class InterfaceAligner(Node):
    """
    A class representing an interface aligner node, responsible for managing
    alignment settings and grid patterns for various operations.

    Attributes:
        alignment_anchors (List[Dict]): Stores the measurement locations (or interface anchors) for interface alignment.
        count (List[int]): The number of grid points in [x, y] direction.
        size (List[float]): The size of the grid in [width, height].
        pattern (str): The pattern used for grid or custom alignment.
    """

    def __init__(
        self,
        name: str = "Interface aligner",
        signal_type: str = "auto",
        detector_type: str = "auto",
        measure_tilt: bool = False,
        area_measurement: bool = False,
        center_stage: bool = True,
        action_upon_failure: str = "abort",
        laser_power: float = 0.5,
        scan_area_res_factors: List[float] = [1.0, 1.0],
        scan_z_sample_distance: float = 0.1,
        scan_z_sample_count: int = 51,
    ):
        """
        Initializes an InterfaceAligner node with specified settings.

        Parameters:
            name (str): Name of the interface aligner. Defaults to "Interface aligner".
            signal_type (str): The type of signal. Can be 'auto', 'fluorescence', or 'reflection'. Defaults to 'auto'.
            detector_type (str): The type of detector. Can be 'auto', 'confocal', 'camera', or 'camera_legacy'. Defaults to 'auto'.
            measure_tilt (bool): Whether to measure tilt. Defaults to False.
            area_measurement (bool): Whether to measure the area. Defaults to False.
            center_stage (bool): Whether to center the stage. Defaults to True.
            action_upon_failure (str): Action upon failure, can be 'abort' or 'ignore'. Defaults to 'abort'.
            laser_power (float): The power of the laser. Must be a positive number. Defaults to 0.5.
            scan_area_res_factors (List[float]): Resolution factors for the scan area. Defaults to [1.0, 1.0].
            scan_z_sample_distance (float): Distance between samples in the z-direction. Defaults to 0.1.
            scan_z_sample_count (int): Number of samples in the z-direction. Must be greater than 0. Defaults to 51.

        Raises:
            ValueError: If any input is not valid (e.g., invalid types or constraints like negative values).
        """
        super().__init__("interface_alignment", name)

        # Use setters for validation
        self.signal_type = signal_type
        self.detector_type = detector_type
        self.measure_tilt = measure_tilt
        self.area_measurement = area_measurement
        self.center_stage = center_stage
        self.action_upon_failure = action_upon_failure
        self.laser_power = laser_power
        self.scan_area_res_factors = scan_area_res_factors
        self.scan_z_sample_distance = scan_z_sample_distance
        self.scan_z_sample_count = scan_z_sample_count

        self.alignment_anchors = []
        self.count = [5, 5]
        self.size = [200.0, 200.0]
        self.pattern = "Origin"

    # Setters with validation for various attributes

    @property
    def signal_type(self):
        return self._signal_type

    @signal_type.setter
    def signal_type(self, value: str):
        valid_types = ["auto", "fluorescence", "reflection"]
        if value not in valid_types:
            raise ValueError(f"signal_type must be one of {valid_types}.")
        self._signal_type = value

    @property
    def detector_type(self):
        return self._detector_type

    @detector_type.setter
    def detector_type(self, value: str):
        valid_detectors = ["auto", "confocal", "camera", "camera_legacy"]
        if value not in valid_detectors:
            raise ValueError(
                f"detector_type must be one of {valid_detectors}."
            )
        self._detector_type = value

    @property
    def measure_tilt(self):
        return self._measure_tilt

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

    @property
    def area_measurement(self):
        return self._area_measurement

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

    @property
    def center_stage(self):
        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):
        return self._action_upon_failure

    @action_upon_failure.setter
    def action_upon_failure(self, value: str):
        valid_actions = ["abort", "ignore"]
        if value not in valid_actions:
            raise ValueError(
                f"action_upon_failure must be one of {valid_actions}."
            )
        self._action_upon_failure = value

    @property
    def laser_power(self):
        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 positive number.")
        self._laser_power = value

    @property
    def scan_area_res_factors(self):
        return self._scan_area_res_factors

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

    @property
    def scan_z_sample_distance(self):
        return self._scan_z_sample_distance

    @scan_z_sample_distance.setter
    def scan_z_sample_distance(self, value: float):
        if not isinstance(value, (float, int)):
            raise TypeError(
                "scan_z_sample_distance must be a float or an int."
            )
        self._scan_z_sample_distance = value

    @property
    def scan_z_sample_count(self):
        return self._scan_z_sample_count

    @scan_z_sample_count.setter
    def scan_z_sample_count(self, value: int):
        if not isinstance(value, int) or value < 1:
            raise ValueError(
                "scan_z_sample_count must be an integer greater than 0."
            )
        self._scan_z_sample_count = value

    @property
    def count(self):
        return self._count

    @count.setter
    def count(self, value: List[int]):
        if len(value) != 2 or not all(isinstance(c, int) for c in value):
            raise ValueError("count must be a list of two integers.")
        self._count = value

    @property
    def size(self):
        return self._size

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

    @property
    def pattern(self):
        return self._pattern

    @pattern.setter
    def pattern(self, value: str):
        if value not in ["Grid", "Custom", "Origin"]:
            raise ValueError("pattern must be 'Grid', 'Custom', or 'Origin'.")
        self._pattern = value

    def set_grid(self, count: List[int], size: List[float]):
        """
        Sets the grid point count and grid size for alignment operations.

        Parameters:
            count (List[int]): Number of grid points in [x, y] direction. Must contain exactly two integers.
            size (List[float]): Size of the grid in [width, height]. Must contain exactly two numbers.

        Returns:
            self: The instance of the InterfaceAligner class.

        Raises:
            ValueError: If count or size does not contain exactly two elements.
            TypeError: If elements in count or size are not numbers.
        """
        self.count = count
        self.size = size
        self.pattern = "Grid"
        return self

    def add_interface_anchor(
        self,
        position: List[float],
        label: str,
        scan_area_size: List[float] = None,
    ):
        """
        Adds a custom interface anchor with a label, position, and optional scan area size.

        Parameters:
            label (str): The label for the anchor. Must be a string.
            position (List[float]): The position of the anchor [x, y]. Must contain exactly two numbers.
            scan_area_size (List[float], optional): The scan area size [width, height]. Defaults to [10.0, 10.0].

        Raises:
            ValueError: If position does not contain exactly two elements.
            TypeError: If label is not a string or elements in position or scan_area_size are not numbers.
        """
        if not isinstance(position, list) or len(position) != 2:
            try:
                position = list(position)
                position = position[:2]
                assert len(position) == 2
            except:
                raise ValueError("position must be a list of two elements.")
        if not all(isinstance(p, (float, int)) for p in position):
            try:
                position = [float(p) for p in position]
            except:
                raise TypeError("All position elements must be numbers.")
        if scan_area_size is None:
            scan_area_size = [10.0, 10.0]

        self.pattern = "Custom"
        self.alignment_anchors.append(
            {
                "label": label,
                "position": position,
                "scan_area_size": scan_area_size,
            }
        )
        return self

    def set_interface_anchors_at(
        self,
        positions: List[List[float]],
        labels: List[str] = None,
        scan_area_sizes: List[List[float]] = None,
    ):
        """
        Creates multiple custom interface anchors at specified positions.

        Parameters:
            labels (List[str]): List of labels for the measurement locations.
            positions (List[List[float]]): List of positions for the measurement locations, each position is [x, y].
            scan_area_sizes (List[List[float]], optional): List of scan area sizes for the measurement locations,
                                                           each scan area size is [width, height]. Defaults to [10.0, 10.0]
                                                           for each anchor.

        Returns:
            self: The instance of the InterfaceAligner class.

        Raises:
            ValueError: If the number of labels does not match the number of positions.
            TypeError: If elements in labels, positions, or scan_area_sizes are not of the correct types.
        """
        if scan_area_sizes is None:
            scan_area_sizes = [[10.0, 10.0]] * len(positions)
        if labels is None:
            labels = [f"anchor_{i}" for i in range(len(positions))]
        for label, position, scan_area_size in zip(
            labels, positions, scan_area_sizes
        ):
            self.add_interface_anchor(position, label, scan_area_size)

        return self

    def to_dict(self) -> Dict:
        """
        Converts the current state of the object into a dictionary representation.

        Returns:
            dict: Dictionary representation of the current state of the object, including
                  alignment anchors, grid settings, and signal properties.
        """
        node_dict = super().to_dict()
        if self.signal_type == "auto" or self.detector_type == "camera_legacy":
            node_dict["interface_finder_type"] = self.signal_type
        else:
            node_dict["interface_finder_type"] = (
                f"{self.signal_type}_{self.detector_type}"
            )
        node_dict["properties"] = {
            "signal_type": self.signal_type,
            "detector_type": self.detector_type,
        }
        node_dict["alignment_anchors"] = self.alignment_anchors
        node_dict["grid_point_count"] = self.count
        node_dict["grid_size"] = self.size
        node_dict["pattern"] = self.pattern
        node_dict["measure_tilt"] = self.measure_tilt
        node_dict["area_measurement"] = self.area_measurement
        node_dict["center_stage"] = self.center_stage
        node_dict["action_upon_failure"] = self.action_upon_failure
        node_dict["laser_power"] = self.laser_power
        node_dict["scan_area_res_factors"] = self.scan_area_res_factors
        node_dict["scan_z_sample_distance"] = self.scan_z_sample_distance
        node_dict["scan_z_sample_count"] = self.scan_z_sample_count
        return node_dict

__init__(name='Interface aligner', signal_type='auto', detector_type='auto', measure_tilt=False, area_measurement=False, center_stage=True, action_upon_failure='abort', laser_power=0.5, scan_area_res_factors=[1.0, 1.0], scan_z_sample_distance=0.1, scan_z_sample_count=51)

Initializes an InterfaceAligner node with specified settings.

Parameters:

Name	Type	Description	Default
name	str	Name of the interface aligner. Defaults to "Interface aligner".	'Interface aligner'
signal_type	str	The type of signal. Can be 'auto', 'fluorescence', or 'reflection'. Defaults to 'auto'.	'auto'
detector_type	str	The type of detector. Can be 'auto', 'confocal', 'camera', or 'camera_legacy'. Defaults to 'auto'.	'auto'
measure_tilt	bool	Whether to measure tilt. Defaults to False.	False
area_measurement	bool	Whether to measure the area. Defaults to False.	False
center_stage	bool	Whether to center the stage. Defaults to True.	True
action_upon_failure	str	Action upon failure, can be 'abort' or 'ignore'. Defaults to 'abort'.	'abort'
laser_power	float	The power of the laser. Must be a positive number. Defaults to 0.5.	0.5
scan_area_res_factors	List[float]	Resolution factors for the scan area. Defaults to [1.0, 1.0].	[1.0, 1.0]
scan_z_sample_distance	float	Distance between samples in the z-direction. Defaults to 0.1.	0.1
scan_z_sample_count	int	Number of samples in the z-direction. Must be greater than 0. Defaults to 51.	51

Raises:

Type	Description
ValueError	If any input is not valid (e.g., invalid types or constraints like negative values).

Source code in npxpy/nodes/aligners.py

def __init__(
    self,
    name: str = "Interface aligner",
    signal_type: str = "auto",
    detector_type: str = "auto",
    measure_tilt: bool = False,
    area_measurement: bool = False,
    center_stage: bool = True,
    action_upon_failure: str = "abort",
    laser_power: float = 0.5,
    scan_area_res_factors: List[float] = [1.0, 1.0],
    scan_z_sample_distance: float = 0.1,
    scan_z_sample_count: int = 51,
):
    """
    Initializes an InterfaceAligner node with specified settings.

    Parameters:
        name (str): Name of the interface aligner. Defaults to "Interface aligner".
        signal_type (str): The type of signal. Can be 'auto', 'fluorescence', or 'reflection'. Defaults to 'auto'.
        detector_type (str): The type of detector. Can be 'auto', 'confocal', 'camera', or 'camera_legacy'. Defaults to 'auto'.
        measure_tilt (bool): Whether to measure tilt. Defaults to False.
        area_measurement (bool): Whether to measure the area. Defaults to False.
        center_stage (bool): Whether to center the stage. Defaults to True.
        action_upon_failure (str): Action upon failure, can be 'abort' or 'ignore'. Defaults to 'abort'.
        laser_power (float): The power of the laser. Must be a positive number. Defaults to 0.5.
        scan_area_res_factors (List[float]): Resolution factors for the scan area. Defaults to [1.0, 1.0].
        scan_z_sample_distance (float): Distance between samples in the z-direction. Defaults to 0.1.
        scan_z_sample_count (int): Number of samples in the z-direction. Must be greater than 0. Defaults to 51.

    Raises:
        ValueError: If any input is not valid (e.g., invalid types or constraints like negative values).
    """
    super().__init__("interface_alignment", name)

    # Use setters for validation
    self.signal_type = signal_type
    self.detector_type = detector_type
    self.measure_tilt = measure_tilt
    self.area_measurement = area_measurement
    self.center_stage = center_stage
    self.action_upon_failure = action_upon_failure
    self.laser_power = laser_power
    self.scan_area_res_factors = scan_area_res_factors
    self.scan_z_sample_distance = scan_z_sample_distance
    self.scan_z_sample_count = scan_z_sample_count

    self.alignment_anchors = []
    self.count = [5, 5]
    self.size = [200.0, 200.0]
    self.pattern = "Origin"

add_interface_anchor(position, label, scan_area_size=None)

Adds a custom interface anchor with a label, position, and optional scan area size.

Parameters:

Name	Type	Description	Default
label	str	The label for the anchor. Must be a string.	required
position	List[float]	The position of the anchor [x, y]. Must contain exactly two numbers.	required
scan_area_size	List[float]	The scan area size [width, height]. Defaults to [10.0, 10.0].	None

Raises:

Type	Description
ValueError	If position does not contain exactly two elements.
TypeError	If label is not a string or elements in position or scan_area_size are not numbers.

Source code in npxpy/nodes/aligners.py

def add_interface_anchor(
    self,
    position: List[float],
    label: str,
    scan_area_size: List[float] = None,
):
    """
    Adds a custom interface anchor with a label, position, and optional scan area size.

    Parameters:
        label (str): The label for the anchor. Must be a string.
        position (List[float]): The position of the anchor [x, y]. Must contain exactly two numbers.
        scan_area_size (List[float], optional): The scan area size [width, height]. Defaults to [10.0, 10.0].

    Raises:
        ValueError: If position does not contain exactly two elements.
        TypeError: If label is not a string or elements in position or scan_area_size are not numbers.
    """
    if not isinstance(position, list) or len(position) != 2:
        try:
            position = list(position)
            position = position[:2]
            assert len(position) == 2
        except:
            raise ValueError("position must be a list of two elements.")
    if not all(isinstance(p, (float, int)) for p in position):
        try:
            position = [float(p) for p in position]
        except:
            raise TypeError("All position elements must be numbers.")
    if scan_area_size is None:
        scan_area_size = [10.0, 10.0]

    self.pattern = "Custom"
    self.alignment_anchors.append(
        {
            "label": label,
            "position": position,
            "scan_area_size": scan_area_size,
        }
    )
    return self

set_grid(count, size)

Sets the grid point count and grid size for alignment operations.

Parameters:

Name	Type	Description	Default
count	List[int]	Number of grid points in [x, y] direction. Must contain exactly two integers.	required
size	List[float]	Size of the grid in [width, height]. Must contain exactly two numbers.	required

Returns:

Name	Type	Description
self		The instance of the InterfaceAligner class.

Raises:

Type	Description
ValueError	If count or size does not contain exactly two elements.
TypeError	If elements in count or size are not numbers.

Source code in npxpy/nodes/aligners.py

def set_grid(self, count: List[int], size: List[float]):
    """
    Sets the grid point count and grid size for alignment operations.

    Parameters:
        count (List[int]): Number of grid points in [x, y] direction. Must contain exactly two integers.
        size (List[float]): Size of the grid in [width, height]. Must contain exactly two numbers.

    Returns:
        self: The instance of the InterfaceAligner class.

    Raises:
        ValueError: If count or size does not contain exactly two elements.
        TypeError: If elements in count or size are not numbers.
    """
    self.count = count
    self.size = size
    self.pattern = "Grid"
    return self

set_interface_anchors_at(positions, labels=None, scan_area_sizes=None)

Creates multiple custom interface anchors at specified positions.

Parameters:

Name	Type	Description	Default
labels	List[str]	List of labels for the measurement locations.	None
positions	List[List[float]]	List of positions for the measurement locations, each position is [x, y].	required
scan_area_sizes	List[List[float]]	List of scan area sizes for the measurement locations, each scan area size is [width, height]. Defaults to [10.0, 10.0] for each anchor.	None

Returns:

Name	Type	Description
self		The instance of the InterfaceAligner class.

Raises:

Type	Description
ValueError	If the number of labels does not match the number of positions.
TypeError	If elements in labels, positions, or scan_area_sizes are not of the correct types.

Source code in npxpy/nodes/aligners.py

def set_interface_anchors_at(
    self,
    positions: List[List[float]],
    labels: List[str] = None,
    scan_area_sizes: List[List[float]] = None,
):
    """
    Creates multiple custom interface anchors at specified positions.

    Parameters:
        labels (List[str]): List of labels for the measurement locations.
        positions (List[List[float]]): List of positions for the measurement locations, each position is [x, y].
        scan_area_sizes (List[List[float]], optional): List of scan area sizes for the measurement locations,
                                                       each scan area size is [width, height]. Defaults to [10.0, 10.0]
                                                       for each anchor.

    Returns:
        self: The instance of the InterfaceAligner class.

    Raises:
        ValueError: If the number of labels does not match the number of positions.
        TypeError: If elements in labels, positions, or scan_area_sizes are not of the correct types.
    """
    if scan_area_sizes is None:
        scan_area_sizes = [[10.0, 10.0]] * len(positions)
    if labels is None:
        labels = [f"anchor_{i}" for i in range(len(positions))]
    for label, position, scan_area_size in zip(
        labels, positions, scan_area_sizes
    ):
        self.add_interface_anchor(position, label, scan_area_size)

    return self

to_dict()

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

Returns:

Name	Type	Description
dict	Dict	Dictionary representation of the current state of the object, including alignment anchors, grid settings, and signal properties.

Source code in npxpy/nodes/aligners.py

def to_dict(self) -> Dict:
    """
    Converts the current state of the object into a dictionary representation.

    Returns:
        dict: Dictionary representation of the current state of the object, including
              alignment anchors, grid settings, and signal properties.
    """
    node_dict = super().to_dict()
    if self.signal_type == "auto" or self.detector_type == "camera_legacy":
        node_dict["interface_finder_type"] = self.signal_type
    else:
        node_dict["interface_finder_type"] = (
            f"{self.signal_type}_{self.detector_type}"
        )
    node_dict["properties"] = {
        "signal_type": self.signal_type,
        "detector_type": self.detector_type,
    }
    node_dict["alignment_anchors"] = self.alignment_anchors
    node_dict["grid_point_count"] = self.count
    node_dict["grid_size"] = self.size
    node_dict["pattern"] = self.pattern
    node_dict["measure_tilt"] = self.measure_tilt
    node_dict["area_measurement"] = self.area_measurement
    node_dict["center_stage"] = self.center_stage
    node_dict["action_upon_failure"] = self.action_upon_failure
    node_dict["laser_power"] = self.laser_power
    node_dict["scan_area_res_factors"] = self.scan_area_res_factors
    node_dict["scan_z_sample_distance"] = self.scan_z_sample_distance
    node_dict["scan_z_sample_count"] = self.scan_z_sample_count
    return node_dict