4. Python examples

These examples are all shipped with the owl python package. To find them, navigate to the owl directory of your installation and look for them in the examples directory.

The examples are located inside:

/home/ramona/falcongui/lib/python3.1/site-packages/owl/examples

Synchronous acquisition

"""This script shows you how to acquire an image and save it to a folder
using the built in transmission illumination board for illumination.

Ramona Optics, Inc.
Copyright 2018-2025
"""
from owl import mcam_data
from owl.instruments import MCAM
from owl.util import sys_info as owl_sys_info

print(owl_sys_info())

# Open the mcam
mcam = MCAM(serial_number='Kestrel0101R')

# 100 ms is the default exposure
mcam.exposure = 0.1
mcam.set_illumination_brightness(.5)

dataset = mcam.acquire_full_field_of_view()
# Save the data
raw_data_file = mcam_data.save(dataset, 'demo')

# Close after the data has been acquired and saved
mcam.close()

Controlling Fluorescence Units Programmatically

"""
This script shows how to control the fluorescence illumination controlled
digitally in a script.
It requires owl version 0.9.30 or greater

Copyright Ramona Optics Inc, 2019-2025. All rights reserved.
"""
from owl.instruments import MCAM

mcam = MCAM(serial_number='Kestrel0053R')
fluorescence = mcam.fluorescence_illumination

# Enable the first LED (or the only LED if only one is connected)
fluorescence.led_selected = 0

# Set to 25 percent power
fluorescence.led_power_percentage = 25

# Set to 60 percent power
fluorescence.led_power_percentage = 60

# Set to 0 percent power
# This makes the LEDs appear off.
# Power below 10 percent may also manifest itself as being off
fluorescence.led_power_percentage = 0

# Turn off and deselect the LEDs (safer, more proper way of turning off LEDs)
fluorescence.clear()

# Read the temperature recorded by all the temperature sensors in the system
temperatures = fluorescence.temperatures

Z Stack acquisition with Web API

"""Z stack acquisition with the Ramona Optics MCAM using the web API.

This example demonstrates how to acquire a Z stack acquisition using the MCAM web API.

The Z stack assay allows for the acquisition of a series of images at different focal planes.
The assay is configured using json with the following parameters.

The `save_location` parameter specifies the location where the data will be saved on the
MCAM computer or NAS (Network Attached Storage).

The `metadata` parameter is a dictionary that can be used to store any additional information
you would like to associate with the assay.

The `parameters` parameter is a dictionary that contains the parameters for the assay.
A full list of parameters can be found in the MCAM documentation.
https://docs.ramonaoptics.com/models.html#z-stack-assay

The `configuration` parameter is a string that specifies the file path to a configuration file
generated by the MCAM software.
This file contains the parameters for the assay and is generally stored on the MCAM computer
or on a NAS.

Ramona Optics, Inc. Copyright 2023-2025
"""
import requests

# Change the serial number to the one provided to you by Ramona Optics
serial_number = "Kestrel0001"
url = "http://localhost:8800"

# Connect to the MCAM device using the webAPI endpoint
requests.post(f"{url}/v1/mcam/{serial_number}", timeout=10)

# Set the MCAM device to sample loading state, which will extend the plate nest
requests.post(
    f"{url}/v1/mcam/{serial_number}/state",
    json={"state": "sample_loading"},
    timeout=10,
)

# Set the MCAM device to the acquisition state, which will insert the plate nest
requests.post(
    f"{url}/v1/mcam/{serial_number}/state",
    json={"state": "acquisition"},
    timeout=10,
)

assay_parameters = {
    "save_location": "/MCAM_data/my_z_stack_acquisition/",
    "metadata": {
        "operator": "Mike Roscopy"
    },
    "parameters": {
        "save_mode": "export",
        "z_positions": [1E-3, 2E-3, 3E-3]
    }
}
# Start the Z stack plate scan acquisition
response = requests.post(
    f"{url}/v1/mcam/{serial_number}/assay/z_stack",
    json=assay_parameters,
    # This assay can take more than 10 seconds if saving to slow storage
    timeout=30,
)

# Set the MCAM device to sample loading state, which will extend the plate nest
requests.post(
    f"{url}/v1/mcam/{serial_number}/state",
    json={"state": "sample_loading"},
    timeout=10
)

# Disconnect from the MCAM device
requests.delete(
    f"{url}/v1/mcam/{serial_number}",
    timeout=10
)

Exporting Analysis Masks from Zebrafish Segmentation Metadata

"""
This script loads an MCAM dataset containing masks and exports
each mask as a separate compressed TIFF file.

The output filenames are automatically
generated based on the dataset structure (wells or image grid positions).

Masks are saved with zlib compression to reduce file size while maintaining
lossless quality and imageJ compatibility.
"""
from pathlib import Path

import numpy as np
import tifffile
from tqdm import tqdm

from owl import mcam_data
from owl.analysis.util import parse_multi_overlapping_mask_array

dataset_path = Path("/path/to/your/dataset/segmentation_results/segmentation_dataset.nc")
output_path = Path("/path/to/output/directory/")

dataset = mcam_data.load(dataset_path)

assert 'segmentation_regions' in dataset, "No mask data found in the dataset."

# masks are stored in a compressed format, make sure to
# decompress with parse_multi_overlapping_mask_array here
masks = parse_multi_overlapping_mask_array(dataset['segmentation_regions'])
mask_names = dataset['segmentation_region_names']


def get_mask_filename(dataset, image_idx):
    has_wells = mcam_data.is_well_dataset(dataset)

    if has_wells:
        well_id = dataset.well_id[image_idx].data
        return f'well_{well_id}_mask.tif'
    else:
        image_y, image_x = image_idx
        return f'{image_y}_{image_x}_mask.tif'


N_masks = masks.shape[0]
array_shape = masks.shape[1:3]
N_images = np.prod(array_shape)

# make a progress bar combining the number of masks and number of images
tqdm = tqdm(total=N_masks * N_images, desc="Exporting masks")

for mask_idx in range(N_masks):
    mask_name = str(mask_names[mask_idx].data)
    mask_directory = output_path / mask_name
    mask_directory.mkdir(parents=True, exist_ok=True)

    for image_idx in np.ndindex(array_shape):
        filename = get_mask_filename(dataset, image_idx)
        mask_data = np.asarray(masks[(mask_idx,) + image_idx])
        tifffile.imwrite(mask_directory / filename, mask_data, compression='zlib')

        tqdm.update(1)

Exporting Analysis Masks from Vireo Segmentation Metadata

"""
This script loads an MCAM dataset containing masks and exports
each mask as a separate compressed TIFF file.

The output filenames are automatically
generated based on the dataset structure (wells/fields or image grid positions).

Masks are saved with zlib compression to reduce file size while maintaining
lossless quality and imageJ compatibility.
"""

from pathlib import Path

import numpy as np
import tifffile
from tqdm import tqdm

from owl import mcam_data

dataset_path = Path("path/to/your/dataset/analysis_metadata.nc")
output_path = Path("path/to/output/directory/")
output_path.mkdir(parents=True, exist_ok=True)

# The settings type of your masks can be found in the protocol file of your analysis
# in the "__owl_settings_type__" key.
settings_type = 'automatic_segmentation'

dataset = mcam_data.load(dataset_path)

assert f'{settings_type}_masks' in dataset, "No mask data found in the dataset."
masks = dataset[f'{settings_type}_masks']


def get_mask_filename(dataset, idx):
    has_wells = mcam_data.is_well_dataset(dataset)
    has_fields = mcam_data.using_field_id(dataset)

    if has_wells and has_fields:
        well_id = dataset.well_id[idx].data
        field_id = int(dataset.field_id[idx].data)
        return f'well_{well_id}_field_{field_id}_mask.tif'
    elif has_wells:
        well_id = dataset.well_id[idx].data
        return f'well_{well_id}_mask.tif'
    else:
        image_y, image_x = idx
        return f'{image_y}_{image_x}_mask.tif'


image_tiles = list(np.ndindex(masks.shape[:2]))
for idx in tqdm(image_tiles, desc="Exporting masks"):
    filename = get_mask_filename(dataset, idx)
    mask_data = np.asarray(masks[idx])
    tifffile.imwrite(output_path / filename, mask_data, compression='zlib')

Creating a Timelapse Dataset from Individual Acquisitions

from pathlib import Path

import click
import xarray as xr
from tqdm import tqdm

"""
This script creates a timelapse metadata file from individual acquisition metadata files
in a specified directory. It renames acquisition directories to a standardized format
and concatenates their metadata into a single file. Timepoints will be organized by
acquisitions names in alphabetical order. Acquisition directory names will be over
written to `acquisition_0`, `acquisition_1`, `acquisition_2`, and so on with the
necessary padding so that files are organized in chronological order when sorted
alphabetically.

WARNING: This will rename directories
and overwrite any existing metadata.nc file in the target directory, so please make a copy
of the original files before running this script if needed. To avoid accidental overwriting,
the script will prompt for user confirmation if directories need to be renamed.

Usage:
    python create_timelapse_from_single_acquisitions.py /path/to/timelapse_directory
"""


@click.command()
@click.argument(
    "timelapse_dir", type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path)
)
@click.help_option('-h', '--help')
def create_timelapse_metadata(timelapse_dir):
    """
    Create a metadata file for a timelapse dataset.

    Parameters
    ----------
    timelapse_dir : Path
        Path to the timelapse directory.
    """
    # check if timelapse metadata file already exists
    if (timelapse_dir / 'metadata.nc').exists():
        raise ValueError(
            f"The metadata file {timelapse_dir / 'metadata.nc'} would be overwritten. "
            "Please remove it or rename it."
        )

    # Check if the directory contains metadata files
    metadata_files = list(timelapse_dir.glob('*/metadata.nc'))
    if not metadata_files:
        raise ValueError(f"No metadata files found in the directory {timelapse_dir}.")
    metadatas = []

    acquisition_dirs = sorted([d.parent.stem for d in metadata_files])

    p = len(str(len(acquisition_dirs)))

    will_rename_files = False
    for i, acquisition_dir in enumerate(acquisition_dirs):
        new_acquisition_dir = timelapse_dir / f'acquisition_{i:0{p}d}'
        if new_acquisition_dir != timelapse_dir / acquisition_dir and new_acquisition_dir.exists():
            raise ValueError(
                f"Directory {new_acquisition_dir} would be overwritten. "
                "Please remove it or rename it."
            )
        if new_acquisition_dir != timelapse_dir / acquisition_dir:
            will_rename_files = True

    if will_rename_files:
        # get user consent to continue
        proceed = input("directories will be renamed. Do you want to continue? (y/n): ")
        if proceed.lower() != 'y':
            print("Exiting without making any changes.")
            return

    for i, acquisition_dir in enumerate(tqdm(acquisition_dirs)):
        new_acquisition_dir = timelapse_dir / f'acquisition_{i:0{p}d}'
        (timelapse_dir / acquisition_dir).rename(new_acquisition_dir)
        metadata_filename = new_acquisition_dir / 'metadata.nc'
        dataset = xr.open_dataset(metadata_filename).compute()
        dataset.coords['timelapse_index'] = i
        dataset['software_timestamp'] = dataset['software_timestamp'].expand_dims('timelapse_index')
        metadatas.append(dataset)

    final = xr.concat(
        metadatas, dim='timelapse_index', coords='minimal', data_vars='minimal', compat='override'
    )
    final.attrs['images_dims'] = ['timelapse_index'] + final.attrs['images_dims']
    final.attrs['image_export_tile_dims'] = [
        'timelapse_index',
    ] + final.attrs['image_export_tile_dims']
    final.attrs['imagename_format'] = (
        'acquisition_{timelapse_index:0' + str(p) + 'd}/' + final.attrs['imagename_format']
    )
    final.to_netcdf(timelapse_dir / 'metadata.nc', engine='h5netcdf')


if __name__ == '__main__':
    create_timelapse_metadata()