Position

This module contains classes and functions for dealing with positioning in a robotic set up.

ATTRIBUTE	DESCRIPTION
MTP_DIMENSIONS	Microtiter plate dimensions in mm TYPE: tuple[float]
OBB_DIMENSIONS	Optical Breadboard dimensions in mm TYPE: tuple[float]

CLASS	DESCRIPTION
Position	represents a 3D position with orientation
Well	represents a single well in a Labware object
Labware	represents a single Labware object
Slot	represents a single Slot object on a Deck object or another Labware object (for stackable Labware)
Deck	represents a Deck object
BoundingVolume	represents a 3D bounding volume
BoundingBox	represents a 3D bounding box

FUNCTION	DESCRIPTION
convert_to_position	Convert a value to a Position object
get_transform	Get transformation matrix from initial to final points, with the first point in each set being the center of rotation

Documentation last updated: 2025-06-11

MTP_DIMENSIONS module-attribute

MTP_DIMENSIONS = (127.76, 85.48, 0)

Microtiter plate dimensions in mm

OBB_DIMENSIONS module-attribute

OBB_DIMENSIONS = (300, 300, 0)

Optical Breadboard dimensions in mm

BoundingBox dataclass

BoundingBox(
    *,
    parametric_function: dict[
        str, Callable[[Sequence[float], Any], bool]
    ],
    reference: Position = Position(),
    dimensions: Sequence[float] | ndarray = (0, 0, 0),
    buffer: Sequence[Sequence[float]] | ndarray = (
        (0, 0, 0),
        (0, 0, 0),
    ),
)

Bases: BoundingVolume

BoundingBox represents a single BoundingBox object

ATTRIBUTE	DESCRIPTION
reference	reference point TYPE: Position
dimensions	x,y,z dimensions TYPE: ndarray
buffer	lower and upper buffer TYPE: ndarray
bounds	lower and upper bounds TYPE: ndarray

METHOD	DESCRIPTION
contains	check if point is within BoundingBox

bounds property

bounds

Lower and upper bounds

__add__

__add__(
    other: BoundingVolume | BoundingBox | None,
) -> BoundingVolume | BoundingBox

Add two BoundingVolumes together

PARAMETER	DESCRIPTION
other	another BoundingVolume or BoundingBox object TYPE: BoundingVolume | BoundingBox | None

RETURNS	DESCRIPTION
BoundingVolume | BoundingBox	BoundingVolume|BoundingBox: new BoundingVolume or BoundingBox object

BoundingVolume dataclass

BoundingVolume(
    *,
    parametric_function: dict[
        str, Callable[[Sequence[float], Any], bool]
    ],
)

BoundingVolume represents a single BoundingVolume object

ATTRIBUTE	DESCRIPTION
parametric_function	name, parametric function TYPE: dict[str, Callable[[Sequence[float],Any], bool]

METHOD	DESCRIPTION
contains	check if point is within BoundingVolume

__add__

__add__(other: BoundingVolume | None) -> BoundingVolume

Add two BoundingVolumes together

PARAMETER	DESCRIPTION
other	another BoundingVolume object TYPE: BoundingVolume | None

RETURNS	DESCRIPTION
BoundingVolume	new BoundingVolume object TYPE: BoundingVolume

contains

contains(point: Sequence[float] | ndarray) -> bool

Check if point is within BoundingVolume

PARAMETER	DESCRIPTION
point	x,y,z coordinates TYPE: Sequence[float] | ndarray

RETURNS	DESCRIPTION
bool	whether point is within BoundingVolume TYPE: bool

Deck dataclass

Deck(
    name: str,
    _details: dict[str, Any],
    parent: Deck | None = None,
    _nesting_lineage: tuple[Path] = (None,),
)

Deck represents a single Deck object

ATTRIBUTE	DESCRIPTION
name	name of Deck TYPE: str
native	native Deck object (i.e. without parent) TYPE: Deck
details	dictionary read from Deck file TYPE: dict[str, Any]
parent	parent Deck object TYPE: Deck | None
reference	reference point of Deck TYPE: Position
x	x offset TYPE: float
y	y offset TYPE: float
z	z offset TYPE: float
offset	Deck offset from parent Deck reference point TYPE: ndarray
center	center of Deck TYPE: ndarray
bottom_left_corner	bottom left corner of Deck TYPE: Position
dimensions	size of Deck TYPE: ndarray
exclusion_zone	exclusion zones to avoid TYPE: dict[str, BoundingBox]
slots	contained Slot objects TYPE: dict[str, Slot]
zones	nested Deck objects TYPE: dict[str, Deck]
entry_waypoints	entry waypoints for Deck TYPE: list[Position]
at	namespace of all Slots TYPE: SimpleNamespace
on	namespace of all nested Decks TYPE: SimpleNamespace

METHOD	DESCRIPTION
fromConfigs	factory method to load Deck details from dictionary
fromFile	factory method to load Deck from file
getAllPositions	get all positions in Deck
getSlot	get Slot using its name or index
isExcluded	checks and returns whether the coordinates are in an excluded region
loadNestedDeck	load nested Deck object from dictionary
loadLabware	load Labware into Slot
removeLabware	remove Labware from Slot using its name or index
transferLabware	transfer Labware between Slots
show	show Deck on matplotlib axis

at property

at: SimpleNamespace

Namespace of all Slots

center property

center: ndarray

Center of Deck

dimensions property

dimensions: ndarray

Size of Deck

exclusion_zone property

exclusion_zone: dict[str, BoundingBox]

Exclusion zones to avoid

native property

native: Deck

Native Deck object (i.e. without parent)

offset property

offset: ndarray

Deck offset from parent Deck reference point

on property

on: SimpleNamespace

Namespace of all nested Decks

reference property

reference: Position

Reference point of Deck

slots property

slots: dict[str, Slot]

Contained Slot objects

zones property

zones: dict[str, Deck]

Nested Deck objects

fromConfigs classmethod

fromConfigs(
    details: dict[str, Any],
    parent: Deck | None = None,
    _nesting_lineage: Sequence[Path | None] = (None,),
) -> Deck

Factory method to load Deck details from dictionary

PARAMETER	DESCRIPTION
details	dictionary read from Deck file TYPE: dict
parent	parent Deck object. Defaults to None. TYPE: Deck | None DEFAULT: None
_nesting_lineage	lineage of nested decks. Defaults to (None,). TYPE: Sequence[Path | None] DEFAULT: (None,)

RETURNS	DESCRIPTION
Deck	Deck object TYPE: Deck

fromFile classmethod

fromFile(
    deck_file: str,
    parent: Deck | None = None,
    from_repo: bool = True,
) -> Deck

Factory method to load Deck from file

PARAMETER	DESCRIPTION
deck_file	filepath of Deck file TYPE: str
parent	parent Deck object. Defaults to None. TYPE: Deck | None DEFAULT: None
from_repo	whether to load from repo. Defaults to True. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
Deck	Deck object TYPE: Deck

getAllPositions

getAllPositions() -> dict[str, tuple[float] | dict]

Get all positions in Deck

RETURNS	DESCRIPTION
dict[str, tuple[float] | dict]	dict[str, tuple[float]]: dictionary of all positions

getSlot

getSlot(value: int | str) -> Slot | None

Get Labware in slot using slot id or name

PARAMETER	DESCRIPTION
value	slot id or name TYPE: int | str

RETURNS	DESCRIPTION
Slot	Slot object TYPE: Slot | None

isExcluded

isExcluded(coordinates: Sequence[float] | ndarray) -> bool

Checks and returns whether the coordinates are in an excluded region

PARAMETER	DESCRIPTION
coordinates	x,y,z coordinates TYPE: Sequence[float] | ndarray

RETURNS	DESCRIPTION
bool	whether coordinates are in an excluded region TYPE: bool

loadLabware

loadLabware(dst_slot: Slot, labware: Labware)

Load Labware into Slot

PARAMETER	DESCRIPTION
dst_slot	destination Slot object TYPE: Slot
labware	Labware object TYPE: Labware

loadNestedDeck

loadNestedDeck(name: str, details: dict[str, Any])

Load nested Deck object from dictionary

PARAMETER	DESCRIPTION
name	name of nested Deck TYPE: str
details	dictionary read from Deck file TYPE: dict

removeLabware

removeLabware(src_slot: Slot) -> Labware

Remove Labware from Slot using its name or index

PARAMETER	DESCRIPTION
src_slot	source Slot object TYPE: Slot

RETURNS	DESCRIPTION
Labware	Labware object TYPE: Labware

show

show(zoom_out: bool = False) -> tuple[Figure, Axes]

Show Deck on matplotlib axis

PARAMETER	DESCRIPTION
zoom_out	whether to use zoomed out view. Defaults to False. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
tuple[Figure, Axes]	tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]: matplotlib figure, axes

transferLabware

transferLabware(src_slot: Slot, dst_slot: Slot)

Transfer Labware between Slots

PARAMETER	DESCRIPTION
src_slot	source Slot object TYPE: Slot
dst_slot	destination Slot object TYPE: Slot

Labware dataclass

Labware(
    name: str,
    _details: dict[str, Any],
    parent: Slot | None = None,
)

Labware represents a single Labware object

ATTRIBUTE	DESCRIPTION
name	name of Labware TYPE: str
native	native Labware object (i.e. without parent) TYPE: Labware
details	dictionary read from Labware file TYPE: dict[str, Any]
parent	parent Slot object TYPE: Slot | None
reference	reference point of Slot TYPE: Position
x	x offset TYPE: float
y	y offset TYPE: float
z	z offset TYPE: float
offset	Labware offset from Slot reference point TYPE: ndarray
center	center of Labware TYPE: ndarray
top	top of Labware TYPE: ndarray
bottom_left_corner	bottom left corner of Labware TYPE: Position
dimensions	size of Labware TYPE: ndarray
exclusion_zone	exclusion zone to avoid TYPE: BoundingBox
wells	wells by columns (alias for wells_columns) TYPE: dict[str, Well]
wells_columns	wells by columns TYPE: dict[str, Well]
wells_rows	wells by rows TYPE: dict[str, Well]
columns	columns and wells in columns TYPE: dict[int, list[str]]
rows	rows and wells in rows TYPE: dict[str, list[str]]
at	namespace of all Wells TYPE: SimpleNamespace
is_stackable	whether Labware is stackable TYPE: bool
is_tiprack	whether Labware is a tiprack TYPE: bool
slot_above	Slot above (for stackable Labware) TYPE: Slot | None

METHOD	DESCRIPTION
fromConfigs	factory method to load Labware details from dictionary
fromFile	factory method to load Labware from file
fromTop	offset from top of Labware
getAllPositions	get all positions in Labware
getWell	get Well using its name
listColumns	list wells by columns
listRows	list wells by rows
listWells	list wells, by columns or rows
show	show Labware on matplotlib axis

at property

at: SimpleNamespace

Namespace of all wells

bottom_left_corner property

bottom_left_corner: Position

Bottom left corner of Labware

center property

center: ndarray

Center of Labware

columns property

columns: dict[int, list[str]]

Columns and wells in columns

details property

details: dict[str, str | float | tuple[float]]

Dictionary read from Labware file

dimensions property

dimensions: ndarray

Size of Labware

is_stackable property writable

is_stackable: bool

Whether Labware is stackable

native property

native: Labware

Native Labware object (i.e. without parent)

offset property

offset: ndarray

Labware offset from Slot reference point

reference property

reference: Position

Reference point of Slot

rows property

rows: dict[str, list[str]]

Rows and wells in rows

top property

top: ndarray

Top of Labware

wells property

wells: dict[str, Well]

Wells by columns (alias for wells_columns)

wells_columns property

wells_columns: dict[str, Well]

Wells by columns

wells_rows property

wells_rows: dict[str, Well]

Wells by rows

fromConfigs classmethod

fromConfigs(
    details: dict[str, Any], parent: Slot | None = None
) -> Labware

Factory method to load Labware details from dictionary

PARAMETER	DESCRIPTION
details	dictionary read from Labware file TYPE: dict
parent	parent Slot object. Defaults to None. TYPE: Slot | None DEFAULT: None

RETURNS	DESCRIPTION
Labware	Labware object TYPE: Labware

fromFile classmethod

fromFile(
    labware_file: str | Path,
    parent: Slot | None = None,
    from_repo: bool = True,
)

Factory method to load Labware from file

PARAMETER	DESCRIPTION
labware_file	filepath of Labware file TYPE: str | Path
parent	parent Slot object. Defaults to None. TYPE: Slot | None DEFAULT: None
from_repo	whether to load from repo. Defaults to True. TYPE: bool DEFAULT: True

fromTop

fromTop(offset: Sequence[float] | ndarray) -> ndarray

Offset from top of Labware

PARAMETER	DESCRIPTION
offset	x,y,z offset TYPE: Sequence[float] | ndarray

RETURNS	DESCRIPTION
tuple	top of Labware with offset TYPE: ndarray

getAllPositions

getAllPositions() -> dict[
    str, tuple[float] | dict[str, tuple[float] | float]
]

Get all positions in Labware

RETURNS	DESCRIPTION
dict[str, tuple[float] | dict[str, tuple[float] | float]]	dict[str, tuple[float]: dictionary of all positions

getWell

getWell(name: str) -> Well

Get Well using its name

PARAMETER	DESCRIPTION
name	name of well TYPE: str

RETURNS	DESCRIPTION
Well	Well object TYPE: Well

listColumns

listColumns() -> list[list[str]]

List wells by columns

listRows

listRows() -> list[list[str]]

List wells by rows

listWells

listWells(by: str = 'col') -> list[Well]

List wells, by columns or rows

PARAMETER	DESCRIPTION
by	'columns' or 'rows'. Defaults to 'col'. TYPE: str DEFAULT: 'col'

RETURNS	DESCRIPTION
list[Well]	list[Well]: list of Well objects

show

show(zoom_out: bool = False) -> tuple[Figure, Axes]

Show Labware on matplotlib axis

PARAMETER	DESCRIPTION
zoom_out	whether to use zoomed out view. Defaults to False. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
tuple[Figure, Axes]	tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]: matplotlib figure, axes

Position dataclass

Position(
    _coordinates: Sequence[float] | ndarray = (0, 0, 0),
    Rotation: Rotation = from_euler(
        "zyx", (0, 0, 0), degrees=True
    ),
    rotation_type: str = "euler",
    degrees: bool = True,
)

Position represents a 3D position with orientation

ATTRIBUTE	DESCRIPTION
coordinates	X,Y,Z coordinates TYPE: ndarray
degrees	whether to use degrees for euler angles TYPE: bool
Rotation	scipy.spatial.transform.Rotation object TYPE: Rotation
rotation	rotation in preferred representation TYPE: ndarray
rotation_type	preferred representation of rotation TYPE: str
rot_matrix	rotation matrix TYPE: ndarray
x	X coordinate TYPE: float
y	Y coordinate TYPE: float
z	Z coordinate TYPE: float
a	euler angle a (rotation about x-axis) TYPE: float
b	euler angle b (rotation about y-axis) TYPE: float
c	euler angle c (rotation about z-axis) TYPE: float

METHOD	DESCRIPTION
fromJSON	create a Position object from string
toJSON	convert Position to string
apply	apply Position to another Position
invert	invert vector and rotation
orientate	orientate self by a rotation
translate	translate self by a vector

a property

a: float

Euler angle a (rotation about x-axis)

b property

b: float

Euler angle b (rotation about y-axis)

c property

c: float

Euler angle c (rotation about z-axis)

coordinates property writable

coordinates: ndarray[float]

X,Y,Z coordinates

rot_matrix property

rot_matrix: ndarray

Rotation matrix

rotation property writable

rotation: ndarray

Rotation in preferred representation

x property

x: float

X coordinate

y property

y: float

Y coordinate

z property

z: float

Z coordinate

apply

apply(other: Position) -> Position

Apply self to other Position, first translating and then orientating

PARAMETER	DESCRIPTION
other	other Position TYPE: Position

RETURNS	DESCRIPTION
Position	other Position transformed by self TYPE: Position

fromJSON staticmethod

fromJSON(value: str) -> Position

Create a Position object from string

PARAMETER	DESCRIPTION
value	string representation of Position TYPE: str

RETURNS	DESCRIPTION
Position	Position object TYPE: Position

invert

invert() -> Position

Invert vector and rotation

RETURNS	DESCRIPTION
Position	inverted Position TYPE: Position

orientate

orientate(by: Rotation, inplace: bool = True) -> Position

Orientate self by a rotation

PARAMETER	DESCRIPTION
by	rotation to orientate by TYPE: Rotation
inplace	whether to update self in place. Defaults to True. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
Position	updated Position, self if inplace=True TYPE: Position

translate

translate(
    by: Sequence[float], inplace: bool = True
) -> Position

Translate self by a vector

PARAMETER	DESCRIPTION
by	translation vector TYPE: Sequence[float]
inplace	whether to update self in place. Defaults to True. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
Position	updated Position, self if inplace=True TYPE: Position

Slot dataclass

Slot(
    name: str,
    _details: dict[str, Any],
    parent: Deck | Labware,
)

Slot represents a single Slot object on a Deck object or another Labware object (for stackable Labware)

ATTRIBUTE	DESCRIPTION
name	name of Slot TYPE: str
details	dictionary read from Slot file TYPE: dict[str, Any]
parent	parent Deck or Labware object TYPE: Deck | Labware
reference	reference point of parent Deck or Labware TYPE: Position
x	x offset TYPE: float
y	y offset TYPE: float
z	z offset TYPE: float
offset	Slot offset from parent reference point TYPE: ndarray
center	center of Slot TYPE: ndarray
bottom_left_corner	bottom left corner of Slot TYPE: Position
dimensions	size of Slot TYPE: ndarray
exclusion_zone	exclusion zone of loaded Labware to avoid TYPE: BoundingBox
loaded_labware	Labware loaded in Slot TYPE: Labware | None
slot_above	Slot above TYPE: Slot | None
slot_below	Slot below TYPE: Slot | None

METHOD	DESCRIPTION
fromCenter	offset from center of Slot
getAllPositions	get all positions in Slot
loadLabware	load Labware in Slot
loadLabwareFromConfigs	load Labware from dictionary
loadLabwareFromFile	load Labware from file
removeLabware	remove Labware from Slot

center property

center: ndarray

Center of Slot

details property

details: dict[str, str | float | tuple[float]]

Dictionary read from Deck file

dimensions property

dimensions: ndarray

Size of Slot

exclusion_zone property

exclusion_zone: BoundingBox | None

Exclusion zone of loaded Labware to avoid

offset property

offset: ndarray

Slot offset from parent reference point

reference property

reference: Position

Reference point of parent Deck or Labware

stack property

stack: dict[str, Slot]

Stack of Labware in Slot, including Slot above

fromCenter

fromCenter(offset: Sequence[float] | ndarray) -> ndarray

Offset from center of Slot

PARAMETER	DESCRIPTION
offset	x,y,z offset TYPE: Sequence[float] | ndarray

RETURNS	DESCRIPTION
tuple	center of Slot with offset TYPE: ndarray

getAllPositions

getAllPositions() -> dict[str, tuple[float] | dict]

Get all positions in Slot

RETURNS	DESCRIPTION
dict[str, tuple[float] | dict]	dict[str, tuple[float]]: dictionary of all positions

loadLabware

loadLabware(labware: Labware)

Load Labware in Slot

PARAMETER	DESCRIPTION
labware	Labware object TYPE: Labware

loadLabwareFromConfigs

loadLabwareFromConfigs(details: dict[str, Any])

Load Labware from dictionary

PARAMETER	DESCRIPTION
details	dictionary read from Labware file TYPE: dict

loadLabwareFromFile

loadLabwareFromFile(
    labware_file: str, from_repo: bool = True
)

Load Labware from file

PARAMETER	DESCRIPTION
labware_file	filepath of Labware file TYPE: str
from_repo	whether to load from repo. Defaults to True. TYPE: bool DEFAULT: True

removeLabware

removeLabware() -> Labware

Remove Labware from Slot

RETURNS	DESCRIPTION
Labware	Labware object TYPE: Labware

Well dataclass

Well(
    name: str,
    _details: dict[str, str | float | tuple[float]],
    parent: Labware,
)

Well represents a single well in a Labware object

ATTRIBUTE	DESCRIPTION
name	name of well TYPE: str
details	dictionary read from Labware file TYPE: dict[str, str | float | tuple[float]]
parent	parent Labware object TYPE: Labware
reference	reference point of Labware TYPE: Position
x	x offset TYPE: float
y	y offset TYPE: float
z	z offset TYPE: float
offset	well offset from Labware reference point TYPE: ndarray
center	center of well base TYPE: ndarray
bottom	bottom of well TYPE: ndarray
middle	middle of well TYPE: ndarray
top	top of well TYPE: ndarray
shape	shape of well TYPE: str
depth	well depth TYPE: float
volume	volume of contents in well TYPE: float
capacity	total liquid capacity TYPE: float
dimensions	dimensions of base in mm TYPE: tuple[float]
base_area	base area of well in mm^2 TYPE: float
level	height level of contents in well TYPE: float

METHOD	DESCRIPTION
fromBottom	offset from bottom of well
fromMiddle	offset from middle of well
fromTop	offset from top of well

base_area property

base_area: float

Base area in mm^2

bottom property

bottom: ndarray

Bottom of well

center property

center: ndarray

Center of well base

details property

details: dict[str, str | float | tuple[float]]

Dictionary read from Labware file

level property

level: float

Height level of contents in well

middle property

middle: ndarray

Middle of well

offset property

offset: ndarray

Well offset from Labware reference point

reference property

reference: Position

Reference point of Labware

top property

top: ndarray

Top of well

fromBottom

fromBottom(offset: Sequence[float] | ndarray) -> ndarray

Offset from bottom of well

PARAMETER	DESCRIPTION
offset	x,y,z offset TYPE: Sequence[float] | ndarray

RETURNS	DESCRIPTION
tuple	bottom of well with offset TYPE: ndarray

fromMiddle

fromMiddle(offset: Sequence[float] | ndarray) -> ndarray

Offset from middle of well

PARAMETER	DESCRIPTION
offset	x,y,z offset TYPE: Sequence[float] | ndarray

RETURNS	DESCRIPTION
tuple	middle of well with offset TYPE: ndarray

fromTop

fromTop(offset: Sequence[float] | ndarray) -> ndarray

Offset from top of well

PARAMETER	DESCRIPTION
offset	x,y,z offset TYPE: Sequence[float] | ndarray

RETURNS	DESCRIPTION
tuple	top of well with offset TYPE: ndarray

convert_to_position

convert_to_position(value: Sequence | ndarray) -> Position

Convert a value to a Position object

PARAMETER	DESCRIPTION
value	value to convert TYPE: Sequence[float] | ndarray | Position

RETURNS	DESCRIPTION
Position	converted Position object TYPE: Position

get_transform

get_transform(
    initial_points: ndarray, final_points: ndarray
) -> tuple[Position, float]

Get transformation matrix from initial to final points, with the first point in each set being the center of rotation.

PARAMETER	DESCRIPTION
initial_points	initial points TYPE: ndarray
final_points	final points TYPE: ndarray

RETURNS	DESCRIPTION
tuple[Position, float]	tuple[Position,float]: transformation Position (i.e. vector and rotation) and scale factor