papylio.Movie#

class papylio.Movie(filepath, rot90=0)#

Base class for microscopy movie/image stack handling.

Provides abstract interface for loading, processing, and accessing image data from various microscopy file formats.

__init__(filepath, rot90=0)#

Initialize Movie object.

Parameters:

filepath (str or Path) – Path to the movie file
rot90 (int, optional) – Number of 90-degree rotations to apply to images (default: 0)

Methods

`__init__`(filepath[, rot90])	Initialize Movie object.
`apply_corrections`(frames, frame_indices)
`determine_general_background_correction`([...])
`determine_spatial_background_correction`([...])
`determine_temporal_background_correction`([...])
`flatten_channels`(frames)	Combine channel dimension back into spatial dimensions.
`frames_to_xarray_dataarray`(frames, frame_indices)	Convert frame array to xarray DataArray with coordinates.
`get_channel`(image[, channel])
`get_channel_from_name`(channel_name)	Get the channel index belonging to a specific channel (name) If
`get_channel_indices_from_names`(channel_names)
`get_channels_from_names`(channel_names)	Get the channel index belonging to a specific channel (name) If
`get_illumination_from_name`(illumination_name)	Get illumination object by name or index.
`get_illumination_indices_from_names`(...)	Get list of illumination indices by illumination names.
`get_illuminations_from_names`(illumination_names)	Get list of illumination objects by names.
`image_info_from_filename`(filename)	Extract image metadata from filename using regex patterns.
`image_info_to_filename`(filename[, ...])	Construct standardized filename from base name and image metadata.
`make_average_image`(**kwargs)	Construct an average image Determine average image for a number_of_frames starting at start_frame.
`make_maximum_projection`(**kwargs)	Construct a maximum projection image Determine maximum projection image for a number_of_frames starting at start_frame.
`make_projection_image`([projection_type, ...])	Construct a projection image Determine a projection image for a number_of_frames starting at start_frame.
`make_projection_images`([projection_type, ...])
`read_frame`(frame_index, **kwargs)	Read a single frame from the movie.
`read_frames`([frame_indices, ...])	Read multiple frames from the movie.
`read_header`()	Read and parse file header.
`reset_corrections`()
`save_corrections`(**kwargs)
`saveas_tif`()
`separate_channels`(frames)	Separate channels from spatial dimensions.
`show`()
`show_correction`(correction_name[, save])
`type_dict`()	Get dictionary mapping file extensions to Movie subclasses.

Attributes

`bitdepth`	Bit depth of the image data (e.g., 8, 16, 32)
`boundaries_metric`
`boundaries_stage`
`bytes_per_frame`	Number of bytes per frame
`channel_arrangement`
`channel_columns`	Number of channel columns in channel arrangement
`channel_indices`
`channel_rows`	Number of channel rows in channel arrangement
`configuration`
`corrections`
`corrections_filepath`
`data_type`
`frame_indices`
`height_metric`
`illumination_arrangement`
`illumination_index_per_frame`
`illumination_indices`
`illumination_indices_in_movie`
`illuminations`
`number_of_channels`	number of channels in the movie
`number_of_channels_per_frame`
`number_of_illuminations`	Number of illumination channels in the movie
`number_of_illuminations_in_movie`	number of channels in the movie
`pixel_to_stage_coordinates_transformation`
`pixels_per_frame`	Total number of pixels in one frame (width × height)
`time`	Time coordinate for each frame
`width_metric`

apply_corrections(frames, frame_indices)#

property bitdepth#

Bit depth of the image data (e.g., 8, 16, 32)

Type:: int

property boundaries_metric#

property boundaries_stage#

property bytes_per_frame#

Number of bytes per frame

Type:: int

property channel_arrangement#

property channel_columns#

Number of channel columns in channel arrangement

Type:: int

property channel_indices#

property channel_rows#

Number of channel rows in channel arrangement

Type:: int

property configuration#

property corrections#

property corrections_filepath#

property data_type#

determine_general_background_correction(method='median', frame_range=(0, 20), use_existing=False)#

determine_spatial_background_correction(method='median_filter', frame_range=(0, 20), use_existing=False, **kwargs)#

determine_temporal_background_correction(method='median', use_existing=False)#

flatten_channels(frames)#

Combine channel dimension back into spatial dimensions.

Parameters:: frames (np.ndarray or xr.DataArray) – Frames with channel as separate dimension
Returns:: np.ndarray or xr.DataArray – Frames with channels arranged spatially

property frame_indices#

frames_to_xarray_dataarray(frames, frame_indices)#

Convert frame array to xarray DataArray with coordinates.

Parameters:

frames (np.ndarray) – Frame array to convert
frame_indices (array-like) – Frame indices for coordinates

Returns:

xr.DataArray – DataArray with frame, channel, y, x dimensions and coordinates

get_channel(image, channel='d')#

get_channel_from_name(channel_name)#

Get the channel index belonging to a specific channel (name) If

Parameters:: channel (str or int) – The name or number of a channel
Returns:: i (int) – The index of the channel to which the channel name belongs

get_channel_indices_from_names(channel_names)#

get_channels_from_names(channel_names)#

Get the channel index belonging to a specific channel (name) If

Parameters:: channel (str or int) – The name or number of a channel
Returns:: i (int) – The index of the channel to which the channel name belongs

classmethod get_illumination_from_name(illumination_name)#

Get illumination object by name or index.

Parameters:: illumination_name (str or int) – The name, short name, or index of an illumination
Returns:: Illumination – The matching Illumination object
Raises:: ValueError – If illumination name is not found

classmethod get_illumination_indices_from_names(illumination_names)#

Get list of illumination indices by illumination names.

Parameters:: illumination_names (str, list, or None) – Illumination name(s)
Returns:: list – List of illumination indices

classmethod get_illuminations_from_names(illumination_names)#

Get list of illumination objects by names.

Parameters:: illumination_names (str, list, or None) – List of illumination names or ‘all’ for all illuminations
Returns:: list – List of Illumination objects matching the names

property height_metric#

property illumination_arrangement#

property illumination_index_per_frame#

property illumination_indices#

property illumination_indices_in_movie#

illuminations = [Illumination(green), Illumination(red)]#

classmethod image_info_from_filename(filename)#

Extract image metadata from filename using regex patterns.

Parses standardized filename format to extract FOV index, projection type, frame range, illumination index, and correction flags.

Parameters:: filename (str) – Image filename to parse
Returns:: dict – Dictionary containing extracted image metadata

Notes

Filename format patterns recognized: - _fov{N}: Field of view index - _ave/_max: Projection type - _f{start}-{end}-{interval}: Frame range - _i{N}: Illumination index - _raw: Indicates raw (uncorrected) image

classmethod image_info_to_filename(filename, fov_index=None, projection_type=None, frame_range=None, illumination=None, apply_corrections=None)#

Construct standardized filename from base name and image metadata.

Parameters:

filename (str) – Base filename
fov_index (int, optional) – Field of view index (default: None)
projection_type (str, optional) – Projection type: ‘average’, ‘maximum’, or None (default: None)
frame_range (tuple, optional) – (start, end) or (start, end, interval) frame indices (default: None)
illumination (int, optional) – Illumination index (default: None)
apply_corrections (bool, optional) – If False, appends ‘_raw’ to filename (default: None)

Returns:

str – Formatted filename with metadata embedded

make_average_image(**kwargs)#

Construct an average image Determine average image for a number_of_frames starting at start_frame. i.e. [start_frame, start_frame + number_of_frames)

Parameters:

start_frame (int) – Frame to start with
number_of_frames (int) – Number of frames to average over
write (bool) – If true, the a tif file will be saved in the writepath

Returns:

np.ndarray – 2d image array with the average image

make_maximum_projection(**kwargs)#

Construct a maximum projection image Determine maximum projection image for a number_of_frames starting at start_frame. i.e. [start_frame, start_frame + number_of_frames)

Parameters:

start_frame (int) – Frame to start with
number_of_frames (int) – Number of frames to average over
write (bool) – If true, the a tif file will be saved in the writepath

Returns:

np.ndarray – 2d image array with the maximum projection image

make_projection_image(projection_type='average', frame_range=(0, 20), apply_corrections=True, illumination=None, write=False, return_image=True, flatten_channels=True, intensity_range=None, color_map='gray')#

Construct a projection image Determine a projection image for a number_of_frames starting at start_frame. i.e. [start_frame, start_frame + number_of_frames)

Parameters:

projection_type (str) – ‘average’ for average image ‘maximum’ for maximum projection image
start_frame (int) – Frame to start with
number_of_frames (int) – Number of frames to average over
write (bool) – If true, a tif file will be saved in writepath

Returns:

np.ndarray – 2d image array with the projected image

make_projection_images(projection_type='average', frame_range=(0, 20))#

property number_of_channels#

number of channels in the movie

Setting the number of channels will divide the image horizontally in equally spaced channels.

Type:: int

property number_of_channels_per_frame#

property number_of_illuminations#

Number of illumination channels in the movie

Type:: int

property number_of_illuminations_in_movie#

number of channels in the movie

Setting the number of channels will divide the image horizontally in equally spaced channels.

Type:: int

property pixel_to_stage_coordinates_transformation#

property pixels_per_frame#

Total number of pixels in one frame (width × height)

Type:: int

read_frame(frame_index, **kwargs)#

Read a single frame from the movie.

Parameters:

frame_index (int) – Index of frame to read
**kwargs – Additional keyword arguments passed to read_frames()

Returns:

np.ndarray or xr.DataArray – Single frame image data

read_frames(frame_indices=None, apply_corrections=True, xarray=True, flatten_channels=False)#

Read multiple frames from the movie.

Parameters:

frame_indices (list or np.ndarray, optional) – Indices of frames to read. If None, reads all frames (default: None)
apply_corrections (bool, optional) – If True, apply flatfield/darkfield corrections (default: True)
xarray (bool, optional) – If True, return xarray DataArray; else return numpy array (default: True)
flatten_channels (bool, optional) – If True, combine channels back into spatial dimensions (default: False)

Returns:

np.ndarray or xr.DataArray – Array of image frames with shape (frame, channel, y, x)

read_header()#

Read and parse file header.

Calls the subclass-specific _read_header() method and applies image rotations if needed.

reset_corrections()#

save_corrections(**kwargs)#

saveas_tif()#

separate_channels(frames)#

Separate channels from spatial dimensions.

Splits frames from single image dimension into separate channel dimension based on channel_arrangement pattern.

Parameters:: frames (np.ndarray or xr.DataArray) – Input frames with channels arranged spatially
Returns:: np.ndarray or xr.DataArray – Frames with channel as separate dimension

show()#

show_correction(correction_name, save=True, **kwargs)#

property time#

Time coordinate for each frame

Type:: xr.DataArray

classmethod type_dict()#

Get dictionary mapping file extensions to Movie subclasses.

Returns:: dict – Dictionary with file extensions as keys and Movie subclasses as values

property width_metric#