Axes#

The following objects may be used to describe iteration over specific types of dimensions.

`Position` #

Define a position in 3D space.

Any of the attributes can be None to indicate that the position is not defined. This is useful for defining a position relative to the current position.

Attributes:

Name	Type	Description
`x`	`float \| None`	X position in microns.
`y`	`float \| None`	Y position in microns.
`z`	`float \| None`	Z position in microns.
`name`	`str \| None`	Optional name for the position.
`sequence`	`MDASequence \| None`	Optional MDASequence relative this position.

`Channel` #

Define an acquisition channel.

Attributes:

Name	Type	Description
`config`	`str`	Name of the configuration to use for this channel, (e.g. `"488nm"`, `"DAPI"`, `"FITC"`).
`group`	`str`	Optional name of the group to which this channel belongs. By default, `"Channel"`.
`exposure`	`float \| None`	Exposure time in milliseconds. Must be positive. If not provided, implies use current exposure time. By default, `None`.
`do_stack`	`bool`	If `True`, instructs engine to include this channel in any Z stacks being acquired. By default, `True`.
`z_offset`	`float`	Relative Z offset from current position, in microns. By default, `0`.
`acquire_every`	`int`	Acquire every Nth frame (if acquiring a time series). By default, `1`.
`camera`	`str \| None`	Name of the camera to use for this channel. If not provided, implies use current camera. By default, `None`.

Time Plans#

Ways to describe a temporal acquisition sequence.

`TIntervalDuration` #

Define temporal sequence using interval and duration.

Attributes:

Name	Type	Description
`interval`	`str \| timedelta`	Time between frames. Scalars are interpreted as seconds. Strings are parsed according to ISO 8601.
`duration`	`str \| timedelta`	Total duration of sequence.
`prioritize_duration`	`bool`	If `True`, instructs engine to prioritize duration over number of frames in case of conflict. By default, `True`.

`TIntervalLoops` #

Define temporal sequence using interval and number of loops.

Attributes:

Name	Type	Description
`interval`	`str \| timedelta \| float`	Time between frames. Scalars are interpreted as seconds. Strings are parsed according to ISO 8601.
`loops`	`int`	Number of frames.
`prioritize_duration`	`bool`	If `True`, instructs engine to prioritize duration over number of frames in case of conflict. By default, `False`.

`TDurationLoops` #

Define temporal sequence using duration and number of loops.

Attributes:

Name	Type	Description
`duration`	`str \| timedelta`	Total duration of sequence. Scalars are interpreted as seconds. Strings are parsed according to ISO 8601.
`loops`	`int`	Number of frames.
`prioritize_duration`	`bool`	If `True`, instructs engine to prioritize duration over number of frames in case of conflict. By default, `False`.

`TIntervalDuration` #

Define temporal sequence using interval and duration.

Attributes:

Name	Type	Description
`interval`	`str \| timedelta`	Time between frames. Scalars are interpreted as seconds. Strings are parsed according to ISO 8601.
`duration`	`str \| timedelta`	Total duration of sequence.
`prioritize_duration`	`bool`	If `True`, instructs engine to prioritize duration over number of frames in case of conflict. By default, `True`.

`MultiPhaseTimePlan` #

Time sequence composed of multiple phases.

Attributes:

Name	Type	Description
`phases`	`Sequence[TIntervalDuration \| TIntervalLoops \| TDurationLoops]`	Sequence of time plans.

Z Plans#

Ways to describe a z-stack acquisition sequence.

`ZTopBottom` #

Define Z using absolute top & bottom positions.

Note that bottom will always be visited, regardless of go_up, while top will always be encompassed by the range, but may not be precisely visited if the step size does not divide evenly into the range.

Attributes:

Name	Type	Description
`top`	`float`	Top position in microns (inclusive).
`bottom`	`float`	Bottom position in microns (inclusive).
`step`	`float`	Step size in microns.
`go_up`	`bool`	If `True`, instructs engine to start at bottom and move towards top. By default, `True`.

`ZAboveBelow` #

Define Z as asymmetric range above and below some reference position.

Note that below will always be visited, regardless of go_up, while above will always be encompassed by the range, but may not be precisely visited if the step size does not divide evenly into the range.

Attributes:

Name	Type	Description
`above`	`float`	Range above reference position in microns (inclusive).
`below`	`float`	Range below reference position in microns (inclusive).
`step`	`float`	Step size in microns.
`go_up`	`bool`	If `True`, instructs engine to start at bottom and move towards top. By default, `True`.

`ZAbsolutePositions` #

Define Z as a list of absolute positions.

Attributes:

Name	Type	Description
`relative`	`list[float]`	List of relative z positions.
`go_up`	`bool`	If `True` (the default), visits points in the order provided, otherwise in reverse.

`ZRangeAround` #

Define Z as a symmetric range around some reference position.

Note that -range / 2 will always be visited, regardless of go_up, while +range / 2 will always be encompassed by the range, but may not be precisely visited if the step size does not divide evenly into the range.

Attributes:

Name	Type	Description
`range`	`float`	Range in microns (inclusive). For example, a range of 4 with a step size of 1 would visit [-2, -1, 0, 1, 2].
`step`	`float`	Step size in microns.
`go_up`	`bool`	If `True`, instructs engine to start at bottom and move towards top. By default, `True`.

`ZRelativePositions` #

Define Z as a list of positions relative to some reference.

Typically, the "reference" will be whatever the current Z position is at the start of the sequence.

Attributes:

Name	Type	Description
`relative`	`list[float]`	List of relative z positions.
`go_up`	`bool`	If `True` (the default), visits points in the order provided, otherwise in reverse.

Grid Plans#

Ways to describe a grid acquisition sequence.

`GridRowsColumns` #

Yield relative delta increments to build a grid acquisition.

Attributes:

Name	Type	Description
`rows`	`int`	Number of rows.
`columns`	`int`	Number of columns.
`relative_to`	`RelativeTo`	Point in the grid to which the coordinates are relative. If "center", the grid is centered around the origin. If "top_left", the grid is positioned such that the top left corner is at the origin.
`overlap`	`float \| Tuple[float, float]`	Overlap between grid positions in percent. If a single value is provided, it is used for both x and y. If a tuple is provided, the first value is used for x and the second for y.
`mode`	`OrderMode`	Define the ways of ordering the grid positions. Options are row_wise, column_wise, row_wise_snake, column_wise_snake and spiral. By default, row_wise_snake.
`fov_width`	`Optional[float]`	Width of the field of view in microns. If not provided, acquisition engines should use current width of the FOV based on the current objective and camera. Engines MAY override this even if provided.
`fov_height`	`Optional[float]`	Height of the field of view in microns. If not provided, acquisition engines should use current height of the FOV based on the current objective and camera. Engines MAY override this even if provided.

`GridWidthHeight` #

Yield relative delta increments to build a grid acquisition.

Attributes:

Name	Type	Description
`width`	`float`	Minimum total width of the grid, in microns. (may be larger based on fov_width)
`height`	`float`	Minimum total height of the grid, in microns. (may be larger based on fov_height)
`relative_to`	`RelativeTo`	Point in the grid to which the coordinates are relative. If "center", the grid is centered around the origin. If "top_left", the grid is positioned such that the top left corner is at the origin.
`overlap`	`float \| Tuple[float, float]`	Overlap between grid positions in percent. If a single value is provided, it is used for both x and y. If a tuple is provided, the first value is used for x and the second for y.
`mode`	`OrderMode`	Define the ways of ordering the grid positions. Options are row_wise, column_wise, row_wise_snake, column_wise_snake and spiral. By default, row_wise_snake.
`fov_width`	`Optional[float]`	Width of the field of view in microns. If not provided, acquisition engines should use current width of the FOV based on the current objective and camera. Engines MAY override this even if provided.
`fov_height`	`Optional[float]`	Height of the field of view in microns. If not provided, acquisition engines should use current height of the FOV based on the current objective and camera. Engines MAY override this even if provided.

`GridFromEdges` #

Yield absolute stage positions to cover a bounded area.

The bounded area is defined by top, left, bottom and right edges in stage coordinates.

Attributes:

Name	Type	Description
`top`	`float`	Top stage position of the bounding area
`left`	`float`	Left stage position of the bounding area
`bottom`	`float`	Bottom stage position of the bounding area
`right`	`float`	Right stage position of the bounding area
`overlap`	`float \| Tuple[float, float]`	Overlap between grid positions in percent. If a single value is provided, it is used for both x and y. If a tuple is provided, the first value is used for x and the second for y.
`mode`	`OrderMode`	Define the ways of ordering the grid positions. Options are row_wise, column_wise, row_wise_snake, column_wise_snake and spiral. By default, row_wise_snake.
`fov_width`	`Optional[float]`	Width of the field of view in microns. If not provided, acquisition engines should use current width of the FOV based on the current objective and camera. Engines MAY override this even if provided.
`fov_height`	`Optional[float]`	Height of the field of view in microns. If not provided, acquisition engines should use current height of the FOV based on the current objective and camera. Engines MAY override this even if provided.

`RandomPoints` #

Yield random points in a specified geometric shape.

Attributes:

Name	Type	Description
`num_points`	`int`	Number of points to generate.
`max_width`	`float`	Maximum width of the bounding box.
`max_height`	`float`	Maximum height of the bounding box.
`shape`	`Shape`	Shape of the bounding box. Current options are "ellipse" and "rectangle".
`random_seed`	`Optional[int]`	Random numpy seed that should be used to generate the points. If None, a random seed will be used.
`allow_overlap`	`bool`	By defaut, True. If False and `fov_width` and `fov_height` are specified, points will not overlap and will be at least `fov_width` and `fov_height apart.

`RelativeTo` #

Where the coordinates of the grid are relative to.

Attributes:

Name	Type	Description
`center`	`Literal['center']`	Grid is centered around the origin.
`top_left`	`Literal['top_left']`	Grid is positioned such that the top left corner is at the origin.

`OrderMode` #

Order in which grid positions will be iterated.

Attributes:

Name	Type	Description
`row_wise`	`Literal['row_wise']`	Iterate row by row.
`column_wise`	`Literal['column_wise']`	Iterate column by column.
`row_wise_snake`	`Literal['row_wise_snake']`	Iterate row by row, but alternate the direction of the columns.
`column_wise_snake`	`Literal['column_wise_snake']`	Iterate column by column, but alternate the direction of the rows.
`spiral`	`Literal['spiral']`	Iterate in a spiral pattern, starting from the center.

`Shape` #

Shape of the bounding box for random points.

Attributes:

Name	Type	Description
`ELLIPSE`	`Literal['ellipse']`	The bounding box is an ellipse.
`RECTANGLE`	`Literal['rectangle']`	The bounding box is a rectangle.

Axes#

Position #

Channel #

Time Plans#

TIntervalDuration #

TIntervalLoops #

TDurationLoops #

TIntervalDuration #

MultiPhaseTimePlan #

Z Plans#

ZTopBottom #

ZAboveBelow #

ZAbsolutePositions #

ZRangeAround #

ZRelativePositions #

Grid Plans#

GridRowsColumns #

GridWidthHeight #

GridFromEdges #

RandomPoints #

RelativeTo #

OrderMode #

Shape #

`Position` #

`Channel` #

`TIntervalDuration` #

`TIntervalLoops` #

`TDurationLoops` #

`TIntervalDuration` #

`MultiPhaseTimePlan` #

`ZTopBottom` #

`ZAboveBelow` #

`ZAbsolutePositions` #

`ZRangeAround` #

`ZRelativePositions` #

`GridRowsColumns` #

`GridWidthHeight` #

`GridFromEdges` #

`RandomPoints` #

`RelativeTo` #

`OrderMode` #

`Shape` #