Component & Device API

Component Types

Component

Bases: _InstantiationTrackerMixin

Base class for components in a microfluidic device.

Components can contain shapes, ports, subcomponents, and labels.
Each component has a size, position, pixel size, and layer size.
Components can be translated, rotated, mirrored, and rendered.

init

__init__(
    size: tuple[int, int, int],
    position: tuple[int, int, int],
    px_size: float = 0.0076,
    layer_size: float = 0.01,
    hide_in_render: bool = False,
    quiet: bool = False,
)

Parameters:

size (tuple[int, int, int]): The size of the component in pixels (width, height, depth).
position (tuple[int, int, int]): The position of the component in 3D space (x, y, z).
px_size (float): The size of a pixel in mm. Default is 0.0076 m.
layer_size (float): The size of a layer in mm. Default is 0.01 m.
hide_in_render (bool): Whether to hide the component in renders (nessiary for complex components like TPMS). Default is False.
quiet (bool): Whether to suppress creation messages. Default is False.

add_bulk

add_bulk(name: str, shape: Shape, label: str)

Add a bulk shape to the component.

Parameters:

name (str): The name of the bulk shape (must be a unique python identifier).
shape (Shape): The bulk shape to be added.
label (str): The label for the bulk shape, which should be a key in the component's labels dictionary.

add_default_exposure_settings

add_default_exposure_settings(
    settings: ExposureSettings, label: str = "_default_"
)

Add default exposure settings to the component.

Parameters:

settings (ExposureSettings): The exposure settings to be added.
label (str): The label associated with the default exposure settings region. If not provided, it will create a new label with this name and a default color (red).

add_default_position_settings

add_default_position_settings(
    settings: PositionSettings, label: str = "_default_"
)

Add default position settings to the component.

Parameters:

settings (PositionSettings): The position settings to be added.
label (str): The label associated with the default position settings region. If not provided, it will create a new label with this name and a default color (red).

add_label

add_label(name: str, color: Color)

Add a label to the component.

Parameters:

name (str): The name of the label (must be a unique python identifier).
color (Color): The color of the label, which can be a Color object or a tuple of RGBA values.

add_labels

add_labels(mapping: dict[str, Color])

Add multiple labels to the component.

Parameters:

mapping (dict[str, Color]): A dictionary mapping label names to their colors.

add_port

add_port(name: str, port: Port)

Add a port to the component.

Parameters:

name (str): The name of the port (must be a unique python identifier).
port (Port): The port to be added.

add_regional_settings

add_regional_settings(
    name: str,
    shape: Shape,
    settings: Union[
        PositionSettings,
        ExposureSettings,
        MembraneSettings,
        SecondaryDoseSettings,
    ],
    label: str,
)

Add regional settings in a given shape to the component.

Parameters:

name (str): The name of the regional settings (must be a unique python identifier).
shape (Shape): The shape to which the regional settings apply.
settings (Union[PositionSettings, ExposureSettings, MembraneSettings, SecondaryDoseSettings]): The settings to be applied in the shape.
label (str): The label for the regional settings, which should be a key in the component's labels dictionary.

add_subcomponent

add_subcomponent(
    name: str,
    component: Component,
    subtract_bounding_box: bool = True,
    hide_in_render: bool = False,
)

Add a subcomponent to the component.

Parameters:

name (str): The name of the subcomponent (must be a unique python identifier).
component (Component): The subcomponent to be added.
subtract_bounding_box (bool): Whether to subtract the bounding box of the subcomponent from the parent component's shapes. Default is True.
hide_in_render (bool): Whether to hide the subcomponent in renders. Default is False.

add_void

add_void(name: str, shape: Shape, label: str)

Add a shape to the component.

Parameters:

name (str): The name of the shape (must be a unique python identifier).
shape (Shape): The shape to be added.
label (str): The label for the shape, which should be a key in the component's labels dictionary.

connect_port

connect_port(port: Port)

Label port as connected.

Parameters:

port (Port): Port to connect.

copy

copy() -> 'Component'

Create a copy of the component.

Returns: - Component: A new instance of the component with the same attributes.

get_labels

get_labels() -> dict[str, Color]

Get a dictionary of labels in the component.

Returns: - dict[str, Color]: A dictionary mapping label names to Color objects.

get_ports

get_ports() -> dict[str, Port]

Get a dictionary of ports in the component.

Returns: - dict[str, Port]: A dictionary mapping port names to Port objects.

get_position

get_position(
    px_size: float = None, layer_size: float = None
) -> tuple[int, int, int]

Get the position of the component in 3D space.

Parameters:

px_size (float, optional): The pixel size in mm. If not provided, uses the component's pixel size.
layer_size (float, optional): The layer size in mm. If not provided, uses the component's layer size.

Returns:

A tuple of three integers representing the position of the component (x, y, z).

get_shapes

get_shapes() -> dict[str, dict[str, Shape]]

Get a dictionary of shapes in the component.

Returns: - dict[str, dict[str, Shape]]: A dictionary with keys 'voids' and 'bulks' containing dictionaries of shape names.

get_size

get_size(
    px_size: float = None, layer_size: float = None
) -> tuple[int, int, int]

Get the size of the component.

Parameters:

px_size (float, optional): The pixel size in mm. If not provided, uses the component's pixel size.
layer_size (float, optional): The layer size in mm. If not provided, uses the component's layer size.

Returns:

A tuple of three integers representing the size of the component (width, height, depth).

get_subcomponents

get_subcomponents() -> dict[str, Component]

Get a dictionary of subcomponents in the component.

Returns: - dict[str, Component]: A dictionary mapping subcomponent names to Component objects.

mirror

mirror(
    mirror_x: bool = False,
    mirror_y: bool = False,
    in_place: bool = False,
    _bypass_lock: bool = False,
) -> Component

Mirror the component along the X and/or Y axes.

Parameters:

mirror_x (bool): If True, mirrors the component along the X axis. Default is False.
mirror_y (bool): If True, mirrors the component along the Y axis. Default is False.
in_place (bool): If True, performs the mirroring in place. Default is False.
_bypass_lock (bool): If True, bypasses lock checks for parent-driven transformations. Default is False.

Returns:

self: The mirrored component.

preview

preview(preview_dir: str = '_visualization')

Preview the component in a GLB file.

Parameters:

preview_dir (str): The directory where the preview GLB file will be saved. Default is "_visualization/".

Returns:

None: The rendered scene is exported to the specified file.

preview_components `classmethod`

preview_components(
    components: "Component | list[Component]",
    preview_dir: str = "_visualization",
)

Preview one or more components in GLB files.

Parameters:

components (Component | list[Component]): Components to preview. If a list is provided, each entry is exported with __vN suffixes (v1, v2, ...). If a single component is provided, no suffix is added.
preview_dir (str): The directory where the preview GLB file will be saved. Default is "_visualization/".

Returns:

None: The rendered scene is exported to the specified file.

relabel

relabel(
    mapping: dict[Union[Component, Shape, str], str],
    recursive=False,
    _color_mapping: dict[str, Color] = None,
)

Relabel listed shapes and labels with new labels.

Parameters:

mapping (dict[Union[Component, Shape, str], str]): A dictionary mapping shapes or labels (or their fully qualified names) to new label names.
recursive (bool): If True, relabel subcomponents recursively. Default is False.
_color_mapping (dict[str, Color], optional): Internal use only. A dictionary mapping new label names to their colors.

Raises: - ValueError: If a shape or label is not found in the component.

render

render(
    filename: str = "component.glb",
    do_bulk_difference: bool = True,
)

Render the component to a file.

Parameters:

filename (str): The name of the output file. Default is "component.glb".
do_bulk_difference (bool): If True, applies a difference operation for bulk shapes. Default is True.

Returns:

None: The rendered scene is exported to the specified file.

rotate

rotate(
    rotation: int,
    in_place: bool = False,
    _bypass_lock: bool = False,
) -> Component

Rotate the component around the Z axis by a given angle.

Parameters:

rotation (int): The angle in degrees to rotate the component. Must be a multiple of 90.
in_place (bool): If True, the component is rotated in place. Default is False.
_bypass_lock (bool): If True, bypasses lock checks for parent-driven transformations. Default is False.

Returns:

self: The rotated component.

set_burn_in_exposure

set_burn_in_exposure(
    exposure_times: list[float], label: str = "_default_"
)

Set burn-in exposure times for the component.

Parameters:

exposure_times (list[float]): List of exposure times in milliseconds for the burn-in process.
label (str): The label associated with the burn-in region. If not provided, it will create a new label with this name and a default color (red).

translate

translate(
    translation: tuple[int, int, int],
    _internal: bool = False,
    _bypass_lock: bool = False,
) -> Component

Translate the component by a given translation vector.

Parameters:

translation (tuple[int, int, int]): The translation vector in parent pixels/layers (dx, dy, dz) to apply to the component.
_internal (bool): If True, the translation uses the component's pixels/layers for internal calculations and opperates immediatly. Default is False.
_bypass_lock (bool): If True, bypasses lock checks for parent-driven transformations. Default is False.

Returns:

self: The translated component.

VariableLayerThicknessComponent

Bases: Component

A component with variable layer thickness, allowing for different layer sizes at each height.

init

__init__(
    size: tuple[int, int, int],
    position: tuple[int, int, int],
    px_size: float = 0.0076,
    layer_sizes: list[tuple[int, float]] = [(1, 0.01)],
    quiet: bool = False,
)

Initialize a VariableLayerThicknessComponent.

Parameters:

size (tuple[int, int, int]): The size of the component in pixels/layers (width, height, depth).
position (tuple[int, int, int]): The position of the component in parent pixels/layers (x, y, z).
px_size (float): The pixel size in mm. Default is 0.0076.
layer_sizes (list[tuple[int, float]]): A list of layer sizes (as tuples) where each tuple contains the number of duplicates and its size in mm.
quiet (bool): If True, suppresses informational output. Default is False.

Device Types

Device

Bases: Component

init

__init__(
    name: str,
    position: tuple[int, int, int],
    layers: int = 0,
    layer_size: float = 0.01,
    px_count: tuple[int, int] = (2560, 1600),
    px_size: float = 0.0076,
    quiet: bool = False,
)

Initialize a generic Device.

Parameters:

name (str): The name of the device.
position (tuple[int, int, int]): The position of the device in parent pixels/layers (x, y, z).
layers (int): The number of layers in the device.
layer_size (float): The layer size in mm.
px_count (tuple[int, int]): The pixel count of the device (width, height). Default is (2560, 1600).
px_size (float): The pixel size in mm. Default is 0.0076.
quiet (bool): If True, suppresses informational output. Default is False.

with_visitech_1x `classmethod`

with_visitech_1x(
    name: str,
    position: tuple[int, int, int],
    layers: int = 0,
    layer_size: float = 0.01,
    quiet: bool = False,
) -> Device

Create a Device with specifications for a Visitech light engine with LRS10 Lens.

Parameters:

name (str): The name of the device.
position (tuple[int, int, int]): The position of the device in parent pixels/layers (x, y, z).
layers (int): The number of layers in the device.
layer_size (float): The layer size in mm.
quiet (bool): If True, suppresses informational output. Default is False.

Returns:

Device: A Device instance with specifications for a Visitech light engine with LRS10 Lens.

with_visitech_2x `classmethod`

with_visitech_2x(
    name: str,
    position: tuple[int, int, int],
    layers: int = 0,
    layer_size: float = 0.01,
    quiet: bool = False,
) -> Device

Create a Device with specifications for a Visitech light engine with LRS20 Lens.

Parameters:

name (str): The name of the device.
position (tuple[int, int, int]): The position of the device in parent pixels/layers (x, y, z).
layers (int): The number of layers in the device.
layer_size (float): The layer size in mm.
quiet (bool): If True, suppresses informational output. Default is False.

Returns:

Device: A Device instance with specifications for a Visitech light engine with LRS20 Lens.

with_wintech `classmethod`

with_wintech(
    name: str,
    position: tuple[int, int, int],
    layers: int = 0,
    layer_size: float = 0.01,
    quiet: bool = False,
) -> Device

Create a Device with specifications for a Wintech light engine.

Parameters:

name (str): The name of the device.
position (tuple[int, int, int]): The position of the device in parent pixels/layers (x, y, z).
layers (int): The number of layers in the device.
layer_size (float): The layer size in mm.
quiet (bool): If True, suppresses informational output. Default is False.

Returns:

Device: A Device instance with specifications for a Wintech light engine.

StitchedDevice

Bases: Device

init

__init__(
    name: str,
    position: tuple[int, int, int],
    layers: int,
    layer_size: float,
    tiles_x: int,
    tiles_y: int,
    base_px_count: tuple[int, int] = (2560, 1600),
    overlap_px: int = 0,
    px_size: float = 0.0076,
    quiet: bool = False,
)

Initialize a StitchedDevice.

Parameters:

name (str): The name of the device.
position (tuple[int, int, int]): The position of the device in parent pixels/layers (x, y, z).
layers (int): The number of layers in the device.
layer_size (float): The layer size in mm.
tiles_x (int): The number of tiles in the X direction.
tiles_y (int): The number of tiles in the Y direction.
base_px_count (tuple[int, int]): The pixel count of a single tile (width, height). Default is (2560, 1600).
overlap_px (int): The number of overlapping pixels between tiles. Default is 0.
px_size (float): The pixel size in mm. Default is 0.0076.
quiet (bool): If True, suppresses informational output. Default is False.

with_visitech_1x `classmethod`

with_visitech_1x(
    name: str,
    position: tuple[int, int, int],
    layers: int = 0,
    layer_size: float = 0.01,
    tiles_x: int = 1,
    tiles_y: int = 1,
    overlap_px: int = 0,
    quiet: bool = False,
) -> StitchedDevice

Create a StitchedDevice with specifications for a Visitech light engine with LRS10 Lens.

Parameters:

name (str): The name of the device.
position (tuple[int, int, int]): The position of the device in parent pixels/layers (x, y, z).
layers (int): The number of layers in the device.
layer_size (float): The layer size in mm.
tiles_x (int): The number of tiles in the X direction.
tiles_y (int): The number of tiles in the Y direction.
overlap_px (int): The number of overlapping pixels between tiles. Default is 0.
quiet (bool): If True, suppresses informational output. Default is False.

Returns:

StitchedDevice: A StitchedDevice instance with specifications for a Visitech light engine with LRS10 Lens.

with_visitech_2x `classmethod`

with_visitech_2x(
    name: str,
    position: tuple[int, int, int],
    layers: int = 0,
    layer_size: float = 0.01,
    tiles_x: int = 1,
    tiles_y: int = 1,
    overlap_px: int = 0,
    quiet: bool = False,
) -> StitchedDevice

Create a StitchedDevice with specifications for a Visitech light engine with LRS20 Lens.

Parameters:

name (str): The name of the device.
position (tuple[int, int, int]): The position of the device in parent pixels/layers (x, y, z).
layers (int): The number of layers in the device.
layer_size (float): The layer size in mm.
tiles_x (int): The number of tiles in the X direction.
tiles_y (int): The number of tiles in the Y direction.
overlap_px (int): The number of overlapping pixels between tiles. Default is 0.
quiet (bool): If True, suppresses informational output. Default is False.

Returns:

StitchedDevice: A StitchedDevice instance with specifications for a Visitech light engine with LRS20 Lens.

with_wintech `classmethod`

with_wintech(
    name: str,
    position: tuple[int, int, int],
    layers: int = 0,
    layer_size: float = 0.01,
    tiles_x: int = 1,
    tiles_y: int = 1,
    overlap_px: int = 0,
    quiet: bool = False,
) -> StitchedDevice

Create a StitchedDevice with specifications for a Wintech light engine.

Parameters:

name (str): The name of the device.
position (tuple[int, int, int]): The position of the device in parent pixels/layers (x, y, z).
layers (int): The number of layers in the device.
layer_size (float): The layer size in mm.
tiles_x (int): The number of tiles in the X direction.
tiles_y (int): The number of tiles in the Y direction.
overlap_px (int): The number of overlapping pixels between tiles. Default is 0.
quiet (bool): If True, suppresses informational output. Default is False.

Returns:

StitchedDevice: A StitchedDevice instance with specifications for a Wintech light engine.

Component & Device API

Component Types

Component

__init__

add_bulk

add_default_exposure_settings

add_default_position_settings

add_label

add_labels

add_port

add_regional_settings

add_subcomponent

add_void

connect_port

copy

get_labels

get_ports

get_position

get_shapes

get_size

get_subcomponents

mirror

preview

preview_components classmethod

relabel

render

rotate

set_burn_in_exposure

translate

VariableLayerThicknessComponent

__init__

Device Types

Device

__init__

with_visitech_1x classmethod

with_visitech_2x classmethod

with_wintech classmethod

StitchedDevice

__init__

with_visitech_1x classmethod

with_visitech_2x classmethod

with_wintech classmethod

init

preview_components `classmethod`

init

init

with_visitech_1x `classmethod`

with_visitech_2x `classmethod`

with_wintech `classmethod`

init

with_visitech_1x `classmethod`

with_visitech_2x `classmethod`

with_wintech `classmethod`