repository·main·Indexed 41 days ago
https://github.com/micro-manager/pycro-managerA Python library for customized microscope hardware control and integration with image processing. It serves as a bridge to Micro-Manager and Micro-Magellan or as a standalone backend. Key features include multi-dimensional acquisitions (MDA), adaptive 'smart microscopy' workflows using AcquisitionFuture, acquisition hooks for custom code injection, and support for large datasets via Dask and napari visualization.
pycromanager is a Python package designed for microscope hardware automation and image acquisition. It is built to be flexible, providing various components that can be used independently or combined to support a wide range of microscopy applications.
To begin using the library, users should refer to the user_guide for foundational knowledge, or the tutorials section for Jupyter Notebook-based examples of specific applications.
Pycro-Manager can execute Java code from within Python using the PyJavaZ library. This enables several advanced workflows:
For most microscopy tasks, use the Acquisition class. It is designed to simplify complex experiments and data handling.
Key capabilities include:
Dataset class as numpy or dask arrays.ExploreAcquisition extends XYTiledAcquisition by providing a graphical user interface. This interface allows for interactive selection of imaging locations and provides tools for XY and Z stage navigation.An image processor can return multiple images by returning a list of (image, metadata) tuples. When doing this, you must modify the metadata['Axes'] field to uniquely identify each image (e.g., by changing the channel name) so that the saving and viewing logic can distinguish them.
import numpy as np
import copy
def img_process_fn(image, metadata):
# Create a second image and metadata copy
image_2 = np.array(image, copy=True)
metadata_2 = copy.deepcopy(metadata)
# Update Axes to uniquely identify the new image
metadata_2['Axes']['channel'] = 'New_channel'
metadata['Axes']['channel'] = 'Old_channel'
return [(image, metadata), (image_2, metadata_2)]Pycro-Manager provides several extension points to modify how acquisitions behave. These processes run asynchronously (on different threads) to maximize performance:
acq_events): Define custom acquisition instructions.acq_hooks): Inject custom code at specific points in the acquisition lifecycle.img_processors): Modify or process image data on-the-fly during acquisition.image_saved_callbacks): Execute custom code immediately after an image is saved and displayed.Pycro-Manager provides a consistent Python API that works across three distinct operational modes. The choice of backend depends on whether you need the Micro-Manager GUI and your specific performance requirements for data handling.
Acquisition class performs acquisition and saving within the Java layer for maximum speed.Pycro-Manager can operate in two distinct modes depending on your needs:
If you need granular control over specific hardware components, you can interact directly with the Micro-Manager Core. This is useful for tasks such as:
event object passed to hook functions is not a single event, but a list of dict objects representing the entire sequence. Hooks are called once for the whole sequence rather than once per individual event.An acquisition event is a dictionary that defines the parameters for an image acquisition. To trigger an image acquisition, the event must contain either the 'channel' key within 'axes' or the 'axes' key itself. If these are missing, the event is used for hardware control only.
Key fields include:
'axes': A dictionary of positions along various axes.'channel': A special axis name that overlays different positions in different colors in the viewer.'row' and 'column': Special values used by XYTiledAcquisition to convert to stage coordinates for grid layouts.'config_group': A list ['group_name', 'preset_name'] to control hardware properties.'z': Controls the default z stage device (e.g., Core-Focus) in $\mu m$.'stage_positions': A list of dictionaries to control multiple specific devices by name and position in $\mu m$.'x', 'y': XY stage positions in $\mu m$.'exposure': Exposure time in ms.'camera': The name of the camera device to use (if not the default 'Core-camera').'properties': A list of ['DeviceName', 'PropertyName', 'PropertyValue'] for arbitrary hardware settings.'tags': Custom metadata that will be added to the resultant image's metadata.event = {
'axes': {
'axis1_name': 1,
'axis2_name': 'first_position',
'channel': 'DAPI',
'row': 1,
'column': 0,
},
'config_group': ['name_of_config_group', 'name_of_preset'],
'exposure': 10.6,
'z': 123.45,
'stage_positions':
[{'z_stage1_name': 12.34},
{'z_stage2_name': 1234.566}],
'min_start_time': 100,
'x': 123.4,
'y': 567.8,
'camera': 'a_camera_device_name',
'properties': [['DeviceName', 'PropertyName', 'PropertyValue'],
['OtherDeviceName', 'OtherPropertyName', 'OtherPropertyValue']],
'tags': {
'whatever_you_want_here': 54,
'something_else': 'here'}
}