owl.instruments.MCAM

class owl.instruments.MCAM(*, serial_number=None, **kwargs)[source]

Bases: object

The MCAM object.

This object allows you to interact with the MCAM as a whole, capturing images under various conditions and saving data.

Parameters:

  • serial_number (str, or None) –

    • If provided, the MCAM will open a particular serial number.

  • with_z_stage (bool, or None) –

    • If True, opening the MCAM will fail if no z-stage is found.

    • If None, then a warning will be issued if no z-stage is found.

    • If False, opening the MCAM will not attempt to open the z-stage.

  • with_y_stage (bool, or None) –

    • If True, opening the MCAM will fail if no y-stage is found.

    • If None, then a warning will be issued if no y-stage is found.

    • If False, opening the MCAM will not attempt to open the y-stage.

  • with_x_stage (bool, or None) –

    • If True, opening the MCAM will fail if no x-stage is found.

    • If None, then a warning will be issued if no x-stage is found.

    • If False, opening the MCAM will not attempt to open the x-stage.

  • with_x_sample_stage (bool, or None) –

    • If True, opening the MCAM will fail if no x sample stage is found.

    • If None, then a warning will be issued if no x sample stage is found.

    • If False, opening the MCAM will not attempt to open the x sample stage.

  • with_reflection_illumination (bool, or None) –

    • If True, opening the MCAM will fail if no reflection-illumination is found.

    • If None, then a warning will be issued if no reflection-illumination is found.

    • If False, opening the MCAM will not attempt to open the reflection-illumination.

  • with_transmission_illumination (bool, or None) –

    • If True, opening the MCAM will fail if no transmission-illumination is found.

    • If None, then a warning will be issued if no transmission-illumination is found.

    • If False, opening the MCAM will not attempt to open the transmission-illumination.

  • with_fluorescence_illumination (bool, or None) –

    • If True, opening the MCAM will fail if no fluorescence-illumination is found.

    • If None, then a warning will be issued if no fluorescence-illumination is found.

    • If False, opening the MCAM will not attempt to open the fluorescence-illumination.

  • with_temperature_monitor (bool, or None) –

    • If True, opening the MCAM will fail if no temperature_monitor is found.

    • If None, then a warning will be issued if no temperature_monitor is found.

    • If False, opening the MCAM will not attempt to open the temperature_monitor.

  • with_plate_tapper (bool, or None) –

    • If True, opening the MCAM will fail if no plate_tapper is found.

    • If None, then a warning will be issued if no plate_tapper is found.

    • If False, opening the MCAM will not attempt to open the plate_tapper.

  • with_solenoid_driver (bool, or None) –

    • If True, opening the MCAM will fail if no solenoid driver is found.

    • If None, then a warning will be issued if no solenoid driver is found.

    • If False, opening the MCAM will not attempt to open the solenoid driver.

  • with_incubator (bool, or None) –

    • If True, opening the MCAM will fail if no incubator is found.

    • If None, then a warning will be issued if no incubator is found.

    • If False, opening the MCAM will not attempt to open the incubator.

  • with_indicator_board (bool, or None) –

    • If True, opening the MCAM will fail if no indicator board is found.

    • If None, then a warning will be issued if no indicator board is found.

    • If False, opening the MCAM will not attempt to open the indicator board.

  • with_calibration (True, False, or None) –

    • If False, then no calibration file is loaded.

    • If None, then the default calibration file is loaded.

  • with_maximum_datarate_check (True, False) –

    • If False, then the MCAM will not check the data rate.

    • If True, the MCAM’s datarate is going to be checked against the recorded factory datarate. If it is too low, then an error will be raised prior to opening the instrument.

  • enusre_homed (True, False) –

    • If True, then all stages will be homed.

    • If False, then the stages will not be homed. Useful for troubleshooting only.

Notes

Changed in version 0.18.89: The keyword argument exif_orientation is formally deprecated and will be removed in a future version.

open(*)[source]

Open the MCAM for communication.

property available_mechanical_states

A list of mechanical states currently available for the MCAM.

For MCAM systems equipped with one or more motion stages, the MCAM may be defined with a set of pre-calibrated mechanical states.

This list reports the available states for the MCAM, taking into account the presently connected hardware so that the users may programmatically select the most appropriate state for their usecase.

property mechanical_state

The mechanical state of the MCAM system.

For MCAM systems equipped with one or more motion stages, the MCAM may be defined with a set of pre-calibrated mechanical states.

This variable reflects the current mechanical state of the system.

The initial state of the MCAM is undefined, as such, this property will return None upon opening the MCAM.

add_z_stage(stage=None, owndevice=None)[source]

Add a Z-stage to the MCAM.

The stage will be closed upon closing the MCAM or calling MCAM.remove_z_stage() if ownership of the stage is explicitly passed to the MCAM.

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

Parameters:

  • stage (owl.instruments.X_LSM_E) –

    Opened stage to attach to the MCAM. If no stage is provided, the MCAM will attempt to open the stage from the system settings.

    Changed in version 0.18.373: Providing a value of None is allowed.

  • owndevice (bool) – True if MCAM has permission to close the stage. If the stage is None, owndevice will be set to True by default.

add_y_stage(stage=None, owndevice=None)[source]

Add a Y-stage to the MCAM.

The stage will be closed upon closing the MCAM or calling MCAM.remove_y_stage() if ownership of the stage is explicitly passed to the MCAM.

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

Parameters:

  • stage (owl.instruments.X_LSM_E) –

    Opened stage to attach to the MCAM. If no stage is provided, the MCAM will attempt to open the stage from the system settings.

    Changed in version 0.18.373: Providing a value of None is allowed.

  • owndevice (bool) – True if MCAM has permission to close the stage. If the stage is None, owndevice will be set to True by default.

add_x_stage(stage=None, owndevice=None)[source]

Add an X-stage to the MCAM.

The stage will be closed upon closing the MCAM or calling MCAM.remove_x_stage() if ownership of the stage is explicitly passed to the MCAM.

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

Parameters:

  • stage (owl.instruments.X_LSM_E) –

    Opened stage to attach to the MCAM. If no stage is provided, the MCAM will attempt to open the stage from the system settings.

    Changed in version 0.18.373: Providing a value of None is allowed.

  • owndevice (bool) – True if MCAM has permission to close the stage. If the stage is None, owndevice will be set to True by default.

add_x_sample_stage(stage=None, owndevice=None)[source]

Add a sample side X stage to the MCAM.

The stage will be closed upon closing the MCAM or calling MCAM.remove_x_sample_stage() if ownership of the stage is explicitly passed to the MCAM.

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

Parameters:

  • stage (owl.instruments.X_LSM_E) –

    Opened stage to attach to the MCAM. If no stage is provided, the MCAM will attempt to open the stage from the system settings.

    Changed in version 0.18.373: Providing a value of None is allowed.

  • owndevice (bool) – True if MCAM has permission to close the stage. If the stage is None, owndevice will be set to True by default.

remove_z_stage()[source]

Remove the z-stage from the MCAM. If the MCAM has ownership of the stage, the stage will be closed.

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

remove_y_stage()[source]

Remove the y-stage from the MCAM. If the MCAM has ownership of the stage, the stage will be closed.

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

remove_x_stage()[source]

Remove the x-stage from the MCAM. If the MCAM has ownership of the stage, the stage will be closed.

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

remove_x_sample_stage()[source]

Remove the x-stage from the MCAM. If the MCAM has ownership of the stage, the stage will be closed.

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

add_illumination(light, illumination_device, *, owndevice=False)[source]

Add illumination board to the MCAM.

Once the board is added, the user should not attempt to independently close it. The board will close automatically upon closing the MCAM, or it can be closed by calling MCAM.remove_reflection_illumination()

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

Parameters:

light (owl.instruments.Illuminate) – Open illumination board to attach to the MCAM

remove_illumination(illumination_device)[source]

Remove and close illumination board.

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

add_reflection_illumination(light, *, owndevice=False)[source]

Add reflection illumination board to the MCAM.

Once the board is added, the user should not attempt to independently close it. The board will close automatically upon closing the MCAM, or it can be closed by calling MCAM.remove_reflection_illumination()

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

Parameters:

light (owl.instruments.Illuminate) – Open reflection illumination board to attach to the MCAM

add_transmission_illumination(light, *, owndevice=False)[source]

Add transmission illumination board to the MCAM.

Once the board is added, the user should not attempt to independently close it. The board will close automatically upon closing the MCAM, or it can be closed by calling MCAM.remove_transmission_illumination()

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

Parameters:

light (owl.instruments.Illuminate) – Open transmission illumination board to attach to the MCAM

remove_transmission_illumination()[source]

Remove and close transmission illumination board. Once the board is added, the user should not attempt to independently close it. The board will close automatically upon closing the MCAM, or it can be closed by calling MCAM.remove_transmission_illumination()

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

remove_reflection_illumination()[source]

Remove and close reflection illumination board. Once the board is added, the user should not attempt to independently close it. The board will close automatically upon closing the MCAM, or it can be closed by calling MCAM.remove_reflection_illumination()

Note

This function is not thread safe. Video or image acquisition should be stopped before calling this function.

property temperature_monitor

The MCAM temperature monitor subcomponent, if it is connected.

property plate_tapper

The MCAM plate tapper subcomponent, if it is connected.

property solenoid_driver

The MCAM solenoid driver subcomponent, if it is connected.

property incubator

The MCAM incubator subcomponent, if it is connected.

property indicator_board

The MCAM indicator board subcomponent, if it is connected.

property illumination_mode

The illumination mode of the MCAM at the present state.

property available_illumination

The available illumination hardware devices connected to the MCAM.

This property reports a tuple of strings containing the available illumination devices presently connected to the MCAM.

The capabilities of these devices, in conjunction with the MCAM determine the available illumination modes.

See also

available_illumination_modes, set_illumination_brightness

property available_illumination_modes

The available illumination modes of the MCAM.

This property reports a tuple of strings containing the available illumination modes of the MCAM given the presently connected illumination devices. .. seealso:: available_illumination, set_illumination_brightness

set_illumination_brightness(brightness, illumination_mode=None, **kwargs)[source]

Set the brightness of the chosen illumination mode.

Parameters:

  • brightness (float) – A number between 0 and 1 indicating the overall brightness of the illumination mode.

  • illumination_mode (str) – The illumination mode of the MCAM. This should be one of the reported available illumination modes.

See also

available_illumination_modes

get_illumination_brightness()[source]

The brightness of the present illumination mode as a fraction.

Returns:

brightness – The illumination brightness of the illumination modes as a number between 0. and 1.

Return type:

float

See also

set_illumination_brightness, illumination_mode

property calibration_filename

File containing calibration information specific to the MCAM device.

Returns:

calibration_filename – Path object pointing to the calibration file. This file may or may not exist.

Return type:

Path

property serial_number

The serial number of the MCAM.

save_calibration(calibration_data=None, calibration_filename=None)[source]

Save the given calibration data at the desired location.

Parameters:

  • calibration_data (Dict) – Data for alignment and photometric corrections as well as metadata.

  • calibration_filename (Path-like, optional) – Location to save the calibration data. If no location is given defaults to self.calibration_filename.

Returns:

calibration_filename – Returns the saved location of the calibration

Return type:

Path

allocate_video_buffer(N_frames, *, selection=None, garbage_collection=True, tqdm=None, cpu_count=None)[source]

Allocates a buffer for video frames.

Before allocating any new data, the reference to the old data will be released. Upon failure, there may be no video buffer in memory.

Parameters:

  • N_frames (int) – The number of frames to allocate memory for.

  • selection ([N_cameras_Y, N_cameras,X]) – A boolean array of the image sensors to acquire from.

  • tqdm (tqdm-like) – A tqdm-like progress bar manager.

  • garbage_collection (bool) – Passed to free_video_buffer if one needs to reallocate memory.

  • cpu_count (int) – The number of CPUs to use to allocate the memory. If None, all CPUs will be used.

See also

free_video_buffer, acquire_video

can_reuse_video_buffer(N_frames, selection=None)[source]

Checks if the video buffer can be reused for the next acquisition.

This function may be used for interactive applications to guide users in their navigation of the interface.

Returns:

video_buffer_reusable – If True, MCAM.allocate_video_buffer will return instantly since the previous video buffer will simply be reused.

Return type:

bool

property video_buffer_nbytes

The number of bytes allocated in the video acquisition buffer.

free_video_buffer(*, garbage_collection=True)[source]

Free the allocated video buffer to reclaim the allocated memory.

Parameters:

garbage_collection (bool) – If True, the system will call python’s gc.collect() to attempt gargabe collection on the unused memory.

acquire_high_speed_video(N_frames, *, selection_slice=None, tqdm=None, stop_event=None, data_buffers=None, **kwargs)[source]
Acquire a given number of video frames of all or a subset of cameras

at the maximum framerate.

Before calling this function, the user is expected to have allocated a video buffer using the MCAM.allocate_video_buffer.

>>> from owl.instruments import MCAM
>>> mcam = MCAM()
>>> mcam.bin_mode = 4
>>> mcam.frame_rate_setpoint = 30
>>> mcam.exposure = 30E-3
>>> mcam.allocate_video_buffer(N_frames=100, tqdm=tqdm)
>>> video_dataset = mcam.acquire_high_speed_video(100)
Parameters:

  • N_frames (int) – Number of frames to acquire.

  • selection_slice (slice) – Python slice in the MCAM array to acquire a video from

  • tqdm (tqdm object) – TQDM object used to monitor the amount of time to allocate memory.

  • start_event (threading.Event) –

    If provided, the method start_event.set() will be called after video setup has been completed. The call to the set() method should not be blocking otherwise it will incur additional delay on the video acquisition.

    Added in version 0.18.59: The start_event parameter was added.

  • stop_event (Event) –

    A threading.Event-like object used to stop the acquisition. Once the acquisition is stopped, None may be returned.

    Added in version 0.18.371: The stop_event parameter was added.

  • data_buffers (np.ndarray) – Optionally, the user may provide a pre-allocated array to store the acquired data. If not provided, the buffer will be allocated upon calling this function.

Returns:

mcam_dataset – Dataset containing the video data acquired.

Return type:

xarray.Dataset

See also

allocate_video_buffer, free_video_buffer, frame_rate_setpoint, exposure

Notes

Changed in version 0.18.29: In version 0.18.29 the metadata generate by this function no longer keeps track of the frame_number dimension for many of the properties as it is assumed that the properties are unchanging.

As of version 0.18.29, the returned software_timestamp is independent of the image indcies image_y and image_x.

acquire_video_to_multi_mp4(filename, N_frames, *, selection_slice=None, keypoints=None, include_timestamp=True, temporary_buffer_size=None, stop_event=None, tqdm=None, start_event=None, metadata=None, tqdm_save=None)[source]

Record a video from saving it directly to compressed MP4 file.

This function records a certain number of frames directly to a particular file. It uses the computer RAM as temporary storage in case the disk file is too busy to store the incoming frames.

A larger buffer enables larger durations of temporary slowdowns on the video encoding pipeline.

Added in version 0.18.242: First version of the method acquire_video_to_multi_mp4.

Parameters:

  • filename (Path) – The filename where the data should be saved. If the filename has no extension, then an '.nc' extension is added.

  • N_frames (int) – Number of frames to acquire.

  • selection_slice (slice) – Python slice in the MCAM array to acquire a video from

  • tqdm (tqdm object) – TQDM object used to monitor the amount of time to allocate memory.

  • start_event (threading.Event) – If provided, the method start_event.set() will be called after video setup has been completed. The call to the set() method should not be blocking otherwise it will incur additional delay on the video acquisition.

  • metadata – Metadata to join to the MCAM dataset upon saving.

  • keypoints – Well plate keypoints structure. If provided the data will be cropped according to the provided keypoints during the saving pipeline.

  • stop_event (threading.Event) –

    If provided, the method stop_event.is_set() will be polled to check if the video acquisition should be aborted.

    Added in version 0.18.371: First version where the parameter stop_event became an option.

  • tqdm_save – A TQDM object to specifically track the progress on the data saving portion of the acquisition. If video encoding is slightly slower than the acquisition frame rate, encoding the final few frames may happen after the acquisition is complete.

Returns:

filename – The filename where the data has been stored. It includes the optional timestamp, and the new suffix.

Return type:

Path-like

See also

acquire_high_speed_video

acquire_video_to_tiledmp4(filename, N_frames, *, selection_slice=None, keypoints=None, include_timestamp=True, temporary_buffer_size=None, stop_event=None, tqdm=None, start_event=None, metadata=None, tqdm_save=None)[source]

Record a video from saving it directly to compressed MP4 file.

This function records a certain number of frames directly to a particular file. It uses the computer RAM as temporary storage in case the disk file is too busy to store the incoming frames.

A larger buffer enables larger durations of temporary slowdowns on the video encoding pipeline.

Added in version 0.18.193: First version of the method acquire_video_to_tiledmp4.

Parameters:

  • filename (Path) – The filename where the data should be saved. If the filename has no extension, then an '.nc' extension is added.

  • N_frames (int) – Number of frames to acquire.

  • selection_slice (slice) – Python slice in the MCAM array to acquire a video from

  • tqdm (tqdm object) – TQDM object used to monitor the amount of time to allocate memory.

  • start_event (threading.Event) – If provided, the method start_event.set() will be called after video setup has been completed. The call to the set() method should not be blocking otherwise it will incur additional delay on the video acquisition.

  • metadata – Metadata to join to the MCAM dataset upon saving.

  • keypoints – Well plate keypoints structure. If provided the data will be cropped according to the provided keypoints during the saving pipeline.

  • stop_event (threading.Event) –

    If provided, the method stop_event.is_set() will be polled to check if the video acquisition should be aborted.

    Added in version 0.18.371: First version where the parameter stop_event became an option.

  • tqdm_save –

    A TQDM object to specifically track the progress on the data saving portion of the acquisition. If video encoding is slightly slower than the acquisition frame rate, encoding the final few frames may happen after the acquisition is complete.

    Added in version 0.18.224.

Returns:

filename – The filename where the data has been stored. It includes the optional timestamp, and the new suffix.

Return type:

Path-like

See also

acquire_high_speed_video

acquire_video_to_file(filename, N_frames, *, selection_slice=None, include_timestamp=True, temporary_buffer_size=None, stop_event=None, tqdm=None, start_event=None, metadata=None, keypoints=None, tqdm_save=None)[source]

Record a video from the MCAM saving it directly to a file.

This function records a certain number of frames directly to a particular file. It uses the computer RAM as temporary storage in case the disk file is too busy to store the incoming frames.

A larger buffer enables larger durations of temporary slowdowns on the disk.

Added in version 0.18.68: First version of the method acquire_video_to_file.

Parameters:

  • filename (Path) – The filename where the data should be saved. If the filename has no extension, then an '.nc' extension is added.

  • N_frames (int) – Number of frames to acquire.

  • selection_slice (slice) – Python slice in the MCAM array to acquire a video from

  • tqdm (tqdm object) – TQDM object used to monitor the amount of time to allocate memory.

  • start_event (threading.Event) – If provided, the method start_event.set() will be called after video setup has been completed. The call to the set() method should not be blocking otherwise it will incur additional delay on the video acquisition.

  • metadata –

    Additional metadata to add to the saved file after the acquisition is complete.

    Added in version 0.18.191.

  • keypoints –

    Well plate keypoints structure. If provided the data will be cropped according to the provided keypoints during the saving pipeline.

    Added in version 0.18.193.

  • stop_event (threading.Event) –

    If provided, the method stop_event.is_set() will be polled to check if the video acquisition should be aborted.

    Added in version 0.18.371: First version where the parameter stop_event became an option.

  • tqdm_save –

    A TQDM object to specifically track the progress on the data saving portion of the acquisition. If video encoding is slightly slower than the acquisition frame rate, encoding the final few frames may happen after the acquisition is complete.

    Added in version 0.18.224.

Returns:

filename – The filename where the data has been stored. It includes the optional timestamp, and the new suffix.

Return type:

Path-like

See also

acquire_high_speed_video

property image_shape: (<class 'int'>, <class 'int'>)

The image shape obtained from the acquisition of a single sensor.

The image shape is affected by the following imaging parameters:

  • bin_mode

  • start_pixel (defined by select_pixels)

  • end_pixel (defined by select_pixels)

See also

bin_mode, start_pixel, end_pixel

property sensor_shape: (<class 'int'>, <class 'int'>)

A tuple containing the physical number of pixels of the sensors.

This is an inherent property of the physical sensor and unaffected by the imaging parameters.

See also

sensor_height, sensor_width, image_shape

select_pixels(start_pixel, end_pixel, step=None)[source]

Set the pixel sub-selection and bin mode of the MCAM sensors.

When selecting pixels you must follow these constraints after binning: * The width must be greater than or equal to 320 and divisible by 8. * The height must be greater than or equal to 8 and divisible by 16. * The product or the width and the height must be divisible by 4096.

Calling this function is equivalent to invalidating all the data in the dataset. The data (and metadata) stored in MCAM.dataset should be considered invalid.

The exposure time is not guaranteed to stay constant after calling this function.

Parameters:

  • start_pixel ((int, int)) – The y and x start pixels, relative to how data is stored in software.

  • end_pixel ((int, int)) – The y and x end pixels, relative to how data is stored in software.

  • step (int) – The binning mode. Must be 1, 2, or 4. If None, the current bin mode is maintained.

select_center_pixels(shape, step=None)[source]

Select the desired pixels centered about the center of the sensor.

Parameters:

  • shape (int, int) – Image shape to capture

  • step (1, 2, 4, or None) – Bin mode to select. If None, the current bin mode is maintained.

See also

select_pixels

select_sensor_regions_of_interest(image_span, *, start_pixels, step=None)[source]

Per sensor region of interest selection.

Added in version 0.18.21.

Parameters:

  • image_span ((int, int)) – The image space across pixels in the imaging sensors. This span is common to all imaging sensors.

  • start_pixels (array-like [N_cameras, 2]) – Starting pixels for each sensor in the MCAM array.

  • step (1, 2, 4 or None) – A valid bin mode for the imaging sensor

Note

This feature is still experimental and does not maintain consistency across the entire metadata. This function’s API is also subject to change without notice.

See also

bin_mode, select_pixels

select_center_square_pixels(step=None, step_alignment=4)[source]

Select the largest center square pixels supported by the MCAM.

Currently, this is the same as selecting the center square (3072, 3072) pixels.

Parameters:

  • step (1, 2, 4, or None) – The binning mode used when selecting the sensors. If None, the current bin mode is used.

  • step_alignment (4) – Different bin modes may support slightly different shapes for the maximum supported square images. By default, we use image extents that are supported by the largest values for bin mode. This guarantees that they are supported by the smaller values as well.

See also

select_pixels

select_default_4_by_3_pixels(step=None)[source]

Select the default pixel selection supported by the MCAM.

Currently, this is the same as selecting the center (3120, 4096) pixels.

Parameters:

step (1, 2, 4, or None) – The binning mode used when selecting the sensors. If None, the current bin mode is used.

See also

select_pixels

property sensor_width: int

The width in pixels of an image from a single sensor.

This is an inherent property of the physical sensor and unaffected by the imaging parameters.

See also

sensor_shape, sensor_height, image_shape

property sensor_height: int

The height in pixels of an image from a single sensor.

This is an inherent property of the physical sensor and unaffected by the imaging parameters.

See also

sensor_shape, sensor_width, image_shape

property image_size: int

Size of image in pixels from a single sensor.

property start_pixel

Starting pixel position in the coordinate space of the physical sensor.

The value is returned as a tuple (start_pixel_y, start_pixel_x).

These values can be changed through a call to select_pixels.

See also

select_pixels, start_pixel, end_pixel

property end_pixel

Ending pixel position in the coordinate space of the physical sensor.

The value is returned as a tuple (end_pixel_y, end_pixel_x).

These values can be changed through a call to select_pixels.

See also

select_pixels, start_pixel, end_pixel

property image_nbytes: int

Size of image in bytes from a single sensor.

property N_cameras

Tuple containing the number of cameras in each direction.

property N_cameras_Y

The number of cameras in the Y direction.

property N_cameras_X

The number of cameras in the X direction.

property N_cameras_total

The total number of micro cameras in the array.

property micro_camera_separation

Separation between micro cameras in the array in meters.

property micro_camera_separation_y

Separation between micro cameras in the Y direction in meters.

property micro_camera_separation_x

Separation between micro cameras in the X direction in meters.

property sensor_pixel_pitch

Distance, in meters, between pixel centers in a sensor.

property sensor_pixel_width

Distance, in meters, between pixel centers in a sensor.

property pixel_width

The width of a pixel’s FOV in meters.

property exif_orientation

Image Orientation flag to facilitate image display.

Should be set to one of

1, 2, 3, 4, 5, 6, 7, or 8

depending on orientation of the MCAM relative to the sample [1].

Changing this parameter only has an effect on the next acquisition’s metadata.

References

property frame_rate

The sensor limited frame rate.

property frame_rate_setpoint

The current frame rate setpoint for high speed video acquisition.

Changing this value has a side effect of changing the exposure of the image sensors.

The true frame rate will be limited by both the frame rate setpoint, and the exposure of the image sensor.

See also

maximum_exposure, minimum_exposure, exposure, frame_rate

property exposure

Image sensor exposure in seconds.

property exposure2

Image sensor exposure in seconds used in iHDR acquisitions.

property interlaced_hdr

Interlaced HDR mode for the MCAM.

property maximum_datarate

The maximum acquisition datarate capable by the MCAM hardware.

property maximum_frame_rate_setpoint

The maximum frame rate setpoint as limited by the sensor hardware.

property minimum_frame_rate_setpoint

The minimum frame rate setpoint as limited by the sensor hardware.

optimize_sensor_timing(mode='stability')[source]

Optimize the senor timing for different acquisition modes.

Parameters:

mode ('stability' or 'frame_rate') – The desired sensor timing mode. For snapshot acquisition, ‘stability’ is recommended. Those requiring high frame rate acquisition are encouraged to contact Ramona Optics at info@ramonaoptics.com to discuss their application.

Notes

The primary use of this function is to enable high speed video acquisition. The goal is to deprecate the call to this function.

Users should contact Ramona Optics prior to using this function.

property maximum_exposure

The maximum exposure in seconds given the current imaging configuration.

property minimum_exposure

The minimum exposure in seconds given the current imaging configuration.

property maximum_digital_gain

The maximum value that the digital gain can be set to.

property minimum_digital_gain

The minimum value that the digital gain can be set to.

property maximum_analog_gain

The maximum value that the analog gain can be set to.

property minimum_analog_gain

The minimum value that the analog gain can be set to.

property use_hardware_trigger

Use trigger pulses to control image acquisition.

Using the hardware trigger will update minimum_exposure.

See also

minimum_exposure

property output_trigger_events

Events that cause an output trigger pulse to be generated.

This is only available for modules that have the hardware trigger option.

property valid_output_trigger_events

The valid output trigger events that can be set.

property bin_mode

The number of pixels binned in the X-axis and skipped in the Y-axis.

Changing the bin mode does not affect the image exposure.

The data property is updated when bin_mode is modified to accommodate the changing image resolution.

The data acquired in previous binning modes can still be retrieved by changing the binning mode back to its previous value.

Valid bin_mode values are either 1, 2, or 4.

property gain

Total gain of the sensor.

Equal to the product of analog_gain and digital_gain.

Note

This property cannot be set. To change the gain, you must change either the digital_gain or the analog_gain.

property digital_gain

Digital gain applied globally to all pixels of all sensors.

property digital_gain_color

Digital gain applied to each individual color in a bayer pixel.

You can assign to this property a tuple of four values (red_gain, green0_gain, blue_gain, green1_gain) or three values (red_gain, green_gain, blue gain).

Returns:

digital_gain_color – Digital gain values for each color in the form of the tuple.

Return type:

(red gain, green0_gain, blue_gain, green1 gain)

property analog_gain

Analog gain applied globally to all pixels of all sensors.

property sensor_chroma

The sensor chromaticity.

This property can take on one of 5 string values:

  • 'monochrome'

  • 'bayer_grbg', 'bayer_rggb', 'bayer_bggr' or, 'bayer_gbrg'

property white_light_transmission

LED color that provides white light to the MCAM in reflection.

These led values come from the photometric calibration data which models the response of our system when used in transmission.

The user should take care to normalize these LED values to a value that suits their application.

property white_light_reflection

LED color that provides white light to the MCAM in transmission.

These led values come from the photometric calibration data which models the response of our system when used in transmission.

The user should take care to normalize these LED values to a value that suits their application.

acquire_selection(selection, *, skip_bad_sensors=True, data=None)[source]

Acquires an image from the selected sensors.

After calling this method, the metadata included in the dataset attribute will be updated.

Parameters:

  • selection (np.array[bool]) – A boolean array of shape (N_cameras_X, N_cameras_Y) with the sensors selected for acquisition set to true.

  • data (array) – Buffer with shape (N_cameras_X, N_cameras_Y, sensor_width, sensor_height). to hold the acquired image. If set to None, then the data is stored in the built-in buffer MCAM.data.

  • skip_bad_sensors (bool) – Don’t acquire from non-functioning sensors.

Returns:

The dataset containing the MCAM metadata in addition to the image data. For more information about the metadata included, please see https://docs.ramonaoptics.com/python_metadata.html This dataset’s metadata will not change when the imaging parameters of the MCAM are modified. However the, data included within the dataset may change unless the data parameter is provided to this function.

Changed in version 0.18.85: In version 0.18.85 the return value was changed from a dictionary containing low level information from the MCAM to the full dataset.

Return type:

dataset

See also

acquire_full_field_of_view, acquire_image_from_sensor

acquire_full_field_of_view(*, skip_bad_sensors=True, data=None)[source]

Acquires an image from all sensors and updates the metadata.

Parameters:

  • data (array) –

    Buffer with shape (N_cameras_X, N_cameras_Y, sensor_width, sensor_height). to hold the acquired image. If set to None, then the data is stored in the built-in buffer MCAM.data.

    Added in version 0.18.85: In version 0.18.85 the data keyword argument was added.

  • skip_bad_sensors (bool) – Don’t acquire from non-functioning sensors.

Returns:

The dataset containing the MCAM metadata in addition to the image data. For more information about the metadata included, please see https://docs.ramonaoptics.com/python_metadata.html This dataset’s metadata will not change when the imaging parameters of the MCAM are modified. However the, data included within the dataset may change unless the data parameter is provided to this function.

Changed in version 0.18.85: In version 0.18.85 the return value was changed from a dictionary containing low level information from the MCAM to the full dataset.

Return type:

dataset

See also

acquire_selection, acquire_image_from_sensor

acquire_light_pulsed_video(*, number_of_pulses, pulse_period, illumination_warmup_time, illumination_mode, brightness, selection_slice=None, data_buffers=None, tqdm=None, stop_event=None)[source]

Acquire a sequence of single-shot frames with periodic light pulses.

At each call, the lights are pulsed number_of_pulses times with pulse_period spacing. A single frame is acquired illumination_warmup_time after each lights-on command.

Designed to be passed as func into run_xy_scan — the data_buffers and tqdm kwargs are injected by the scan loop.

Parameters:

  • number_of_pulses (int) – Number of light pulses (and single-shot frames) to acquire.

  • pulse_period (float) – Period between consecutive pulses in seconds. Must satisfy illumination_warmup_time + exposure + 0.5 <= pulse_period.

  • illumination_warmup_time (float) – Time to wait between switching the lights on and triggering the camera, in seconds.

  • illumination_mode (str) – Illumination mode applied during each pulse (e.g. 'fluorescence_brightfield_530nm_high_contrast').

  • brightness (float) – Illumination brightness during each pulse, as a fraction between 0.0 and 1.0. Matches the scale used by set_illumination_brightness().

  • selection_slice (tuple[slice, slice] or None) – Passthrough selection. If provided, the returned dataset’s image_y / image_x coordinates are sliced accordingly; acquisition still occurs on the full array.

  • data_buffers (np.ndarray, optional) – Pre-allocated buffer of shape (number_of_pulses, N_cameras_Y, N_cameras_X) + image_shape. Allocated internally when None. Reused by run_xy_scan.

  • tqdm (callable, optional) – Progress bar updater injected by run_xy_scan.

  • stop_event (threading.Event, optional) – Event used to abort the acquisition. Checked at each pulse boundary and honoured by sleep_from.

Returns:

Dataset with dims (frame_number, image_y, image_x, y, x). The illumination switch is guaranteed to be off on exit.

Return type:

xarray.Dataset

See also

acquire_full_field_of_view, acquire_high_speed_video

acquire_in_focus_video(*, z_positions, number_of_frames, valid_data=None, selection_slice=None, data_buffers=None, scratch_buffers=None, tqdm=None, stop_event=None)[source]

Acquire one video with every camera parked at its in-focus Z plane.

Each distinct plane among the valid entries of z_positions is visited once: at every plane a full-array video is captured, and per camera the frames recorded at that camera’s assigned plane are kept. This collapses the Z stack a naive capture would produce into a single in-focus video, so no out-of-focus planes are ever saved. A single shared plane takes the ordinary one-acquisition path with no extra Z motion.

Designed to be passed as func into run_xy_scan — the data_buffers and tqdm kwargs are injected by the scan loop.

Parameters:

  • z_positions (np.ndarray) – Per-camera physical stage Z positions in meters, shaped to match N_cameras and in this MCAM’s EXIF orientation. The Best Focus tool assigns every camera a finite plane, so a camera is excluded from acquisition through valid_data, not through a sentinel here.

  • number_of_frames (int) – Number of frames to acquire at each visited plane.

  • valid_data (np.ndarray, optional) – Per-camera boolean mask shaped like z_positions. Invalid cameras contribute no plane to visit, so an empty well never costs an extra Z move. When None every camera is considered valid.

  • selection_slice (tuple[slice, slice] or None) – Passthrough selection forwarded to acquire_high_speed_video().

  • data_buffers (np.ndarray, optional) – Pre-allocated buffer of shape (number_of_frames, N_cameras_Y, N_cameras_X) + image_shape. Allocated internally when None. Reused by run_xy_scan.

  • scratch_buffers (np.ndarray, optional) – A second buffer with the same shape as data_buffers, used only on the multi-plane path to hold each plane’s full capture before its in-focus frames are selected out. Allocated internally when None; pass one in to reuse it across positions.

  • tqdm (callable, optional) – Progress-bar factory. A single bar is created for this position’s acquisition and advanced per frame across every visited plane, using the nested child-bar mechanism of tqdm_base (each plane’s frame-acquisition loop becomes a child that contributes one plane’s worth of progress to the shared bar). The bar therefore fills smoothly during capture rather than jumping once per plane, and its description reports the plane being acquired.

  • stop_event (threading.Event, optional) – Event used to abort between planes, honoured by acquire_high_speed_video().

Returns:

Dataset with dims (frame_number, image_y, image_x, y, x) plus a per-camera z_stage variable recording the plane each camera was kept from. None if stop_event aborted the acquisition.

On the multi-plane path, acquisition-wide metadata that would otherwise be shared across cameras but genuinely differs between the separate plane captures – such as software_timestamp – gains image_y/image_x dims so each camera records the value from the acquisition its frames were kept from.

Return type:

xarray.Dataset or None

acquire_image_from_sensor(index, *, skip_bad_sensors=True, data=None)[source]

Acquires an image from a single sensor and updates the metadata.

Parameters:

  • index (tuple) – Tuple containing the index of the desired sensor, (row, column).

  • data (array) –

    Buffer with shape (N_cameras_X, N_cameras_Y, sensor_width, sensor_height). to hold the acquired image. If set to None, then the data is stored in the built-in buffer MCAM.data.

    Added in version 0.18.85: In version 0.18.85 the data keyword argument was added.

  • skip_bad_sensors (bool) – Don’t acquire from non-functioning sensors.

Returns:

The dataset containing the MCAM metadata in addition to the image data. For more information about the metadata included, please see https://docs.ramonaoptics.com/python_metadata.html This dataset’s metadata will not change when the imaging parameters of the MCAM are modified. However the, data included within the dataset may change unless the data parameter is provided to this function.

Changed in version 0.18.85: In version 0.18.85 the return value was changed from a dictionary containing low level information from the MCAM to the full dataset.

Return type:

dataset

See also

acquire_full_field_of_view, acquire_selection

acquire_new_image(index, *, skip_bad_sensors=True, data=None)

Acquires an image from a single sensor and updates the metadata.

Parameters:

  • index (tuple) – Tuple containing the index of the desired sensor, (row, column).

  • data (array) –

    Buffer with shape (N_cameras_X, N_cameras_Y, sensor_width, sensor_height). to hold the acquired image. If set to None, then the data is stored in the built-in buffer MCAM.data.

    Added in version 0.18.85: In version 0.18.85 the data keyword argument was added.

  • skip_bad_sensors (bool) – Don’t acquire from non-functioning sensors.

Returns:

The dataset containing the MCAM metadata in addition to the image data. For more information about the metadata included, please see https://docs.ramonaoptics.com/python_metadata.html This dataset’s metadata will not change when the imaging parameters of the MCAM are modified. However the, data included within the dataset may change unless the data parameter is provided to this function.

Changed in version 0.18.85: In version 0.18.85 the return value was changed from a dictionary containing low level information from the MCAM to the full dataset.

Return type:

dataset

See also

acquire_full_field_of_view, acquire_selection

property selection_all_cameras

The selection of sensors that corresponds to all cameras being used.

Returns:

selection – Array of bool corresponding to the selection of all sensors. In this array, all values are True. This array has shape MCMA.N_cameras.

Return type:

np.array[bool]

property selection_center_12

The selection of sensors that corresponds to the center 12 cameras.

The center 4 x 3 cameras are selected.

This property return an array of bools corresponding to the selection of the center 12 sensors.

Deprecated since version 0.18.4.

Notes

This function is only supported by by micro cameras of shape (9, 6).

close(*)[source]

Close the connection to the MCAM.

hold_state()[source]

Context manager to ensure the state isn’t mutated in a code block.

Example

>>> from owl.instruments import MCAM
>>> mcam = MCAM()
>>> mcam.exposure = 100E-3
>>> with mcam.hold_state():
...     mcam.exposure = 10E-3
...     print(f"The MCAM exposure is temporarily set to {mcam.exposure * 1000:.2f} ms")
>>> print(f"The MCAM exposure is {mcam.exposure * 1000:.2f} ms")
set_state(state, *, strict=True)[source]

Set the MCAM to a previously saved state.

Parameters:

  • state – The desired MCAM state.

  • strict (bool) – If True, the state will be validated for the appropriate serial numbers, and for the validity of all other parameters. If False, the serial numbers of the MCAM and the state will not be compared, and invalid parameters will be replaced by None and the MCAM will retain the previously applied state.