Skip to content

Axes#

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

Position = AbsolutePosition module-attribute #

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 #

Grid plan based on number of rows and columns.

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 #

Grid plan based on total width and height.

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 in microns.
max_height float

Maximum height of the bounding box in microns.
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.
order TraversalOrder

Order in which the points will be visited. If None, order is simply the order in which the points are generated (random). Use 'nearest_neighbor' or 'two_opt' to order the points in a more structured way.
start_at int | RelativePosition

Position or index of the point to start at. This is only used if order is 'nearest_neighbor' or 'two_opt'. If a position is provided, it will always be included in the list of points. If an index is provided, it must be less than the number of points, and corresponds to the index of the (randomly generated) points; this likely only makes sense when random_seed is provided.

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.

generate_indices #

Generate indices for the given grid size.

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.