magmap.io.importer module

Imports image stacks using Bioformats.

Bioformats is access through Python-Bioformats and Javabridge. Images will be imported into a 4/5D Numpy array.

ivar PIXEL_DTYPE:

Dictionary of corresponding data types for output given by Bioformats library. Alternatively, should detect pixel data type directly using parse_ome_raw().

ivar IMAGE5D_NP_VER:

image5d Numpy saved array version number, which should be incremented with any change to the image5d or its support “info” save array format.

magmap.io.importer.CHANNEL_SEPARATOR = '_ch_'

String preceding channel number for multi-channel image import.

Type:

str

magmap.io.importer.DEFAULT_IMG_STACK_NAME = 'myvolume'

Default filename base for directory import image output.

Type:

str

magmap.io.importer.assign_metadata(md)

Assign values from a metadata dictionary to module variables.

Values are also added to magmap.settings.config.MetaKeys entries.

Parameters:

md (Dict[Union[str, MetaKeys], Any]) – Dictionary of metadata.

magmap.io.importer.calc_intensity_bounds(image5d, lower=0.5, upper=99.5, dim_channel=4)

Calculate image intensity boundaries for the given percentiles, including boundaries for each channel in multichannel images.

Assume that the image will be small enough to load entirely into memory rather than calculating bounds plane-by-plane, but can also be given an individual plane. Also assume that bounds for all channels will be calculated.

Parameters:

• image5d – Image as a 5D (t, z, y, x, c) array, or a 4D array if only 1 channel is present.

• lower (default: 0.5) – Lower bound as a percentile; defaults to 0.5.

• upper (default: 99.5) – Upper bound as a percentile; defaults to 99.5.

• dim_channel (default: 4) – Axis number of channel; defaults to 4, where the channel value is collapsed into the x-axis.

Returns:

Tuple of lows and highs, each of which is a list of the low and high values at the given percentile cutoffs for each channel.

magmap.io.importer.calc_scaling(image5d, scaled, image5d_shape=None, scaled_shape=None)

Calculate the exact scaling between two images where one image had been scaled from the other.

Parameters:

• image5d (Optional[ndarray]) – Original image in 5D (time included, channel optional) format. Can be None if image5d_shape is given.

• scaled (Optional[ndarray]) – Scaled image, assumed to be in either 3D or 5D format (3D with channel not currently supported). Can be None if scaled_shape is given.

• image5d_shape (Optional[Sequence[int]], default: None) – image5d shape, which can be given if image5d is None; defaults to None.

• scaled_shape (Optional[Sequence[int]], default: None) – scaled shape, which can be given if scaled is None; defaults to None.

Return type:

ndarray

Returns:

Array of z,y,x scaling factors from the original to the scaled image.

magmap.io.importer.deconstruct_img_name(np_filename, sep='_', keep_subimg=False)

Deconstruct an image filename to its original name.

MagellanMapper adds suffixes to an original image filename when generating derivatives, such as the _image5d.npy imported Numpy image. This function parses Numpy and registered image filenames back to these original names. Also parses sub-image offset and shape information if the filename is in sub-image format as generated by magmap.cv.stack_detect.make_subimg_name().

Parameters:

• np_filename (str) – Numpy image filename.

• sep (str, default: '_') – Separator for any registration suffixes; defaults to “_”.

• keep_subimg (bool, default: False) – True to keep the sub-image part of the name.

Returns:

• filename: the deconstructed filename, without suffixes Ends in a period unless base_suffix is not None. If no matching suffix is found, simply returns np_filename

• offset: the sub-image offset, of None if not a sub-image.

• size: the sub-image shape, or None if not a sub-image

• reg_suffixes: a dictionary of config.RegSuffixes to config.RegNames values if np_filename is a registered image path. The registered suffix in this path is assigned to the config.RegSuffixes.ATLAS suffix.

• base_suffix: additional suffix to filename, eg, “scale[XptY” for rescaled files

Return type:

Tuple of

magmap.io.importer.filename_to_base(filename, series=None, modifier='', keep_ext=False)

Convert an image path to a base path with an optional modifier.

Parameters:

• filename (str) – Path to original image.

• series (Optional[int], default: None) – Series (eg tile) within image; defaults to None. Currently ignored, but may be implemented in the future to track different tiles or timepoints.

• modifier (str, default: '') – Modifier string prior to series; defaults to an empty string.

• keep_ext (bool, default: False) – True to keep the filename extension; defaults to False.

Return type:

str

Returns:

Base path.

magmap.io.importer.find_sizes(filename)

Finds image size information using the ImageReader using Bioformats’ wrapper to access a small subset of image properities.

Parameters:

filename – Image file, assumed to have metadata in OME XML format.

Returns:

array of tuples with dimensions for each series. Dimensions

will be given as (time, z, y, x, channels).

Return type:

sizes

magmap.io.importer.import_multiplane_images(chl_paths, prefix, import_md, series=None, offset=0, channel=None, fn_feedback=None)

Imports single or multiplane file(s) into Numpy format.

For multichannel images, this import currently supports either a single file with multiple channels or multiple files each containing a single channel. Files will be loaded by Bioformats, with fallback by Numpy as RAW files. Output files are written plane-by-plane to memory-mapped files to bypass keeping the full input or output image in RAM.

Parameters:

• chl_paths (dict[Any, List[str]]) – Ordered dictionary of channel numbers to sequences of image file paths to import.

• prefix (str) – Ouput base path.

• import_md (dict[config.MetaKeys]) – Import metadata dictionary, used to set up the shape, data type (for RAW file import), and output image metadata (resolutions, zoom, magnification).

• series (int) – Series index to load. Defaults to None, which will use 0.

• offset (int) – z-plane offset from which to start importing. Defaults to 0.

• channel (List[int]) – Sequence of channel indices to import; defaults to None to import all channels.

• fn_feedback (func) – Callback function to give feedback strings during import; defaults to None.

Returns:

obj:`np_io.Image5d: The 5D image object.

magmap.io.importer.import_planes_to_stack(chl_paths, prefix, import_md, rgb_to_grayscale=True, fn_feedback=None)

Import single plane image files into a single volumetric image stack.

Each file in chl_paths is assumed to be a 2D plane in a volumetric image with either a single channel or an RGB channel.

Parameters:

• chl_paths (dict[int, List[str]]) – Ordered dictionary of channel numbers to sequences of image file paths to import.

• prefix (str) – Ouput base path; defaults to None to output to the path directory, also using the directory name as the image filename.

• import_md (dict[config.MetaKeys]) – Import metadata dictionary, used for output image metadata (resolutions, zoom, magnification). Shape and data type are ignored since they are determined during import in case these values may have changed.

• rgb_to_grayscale (bool) – Files with a three value third dimension are assumed to be RGB and will be converted to grayscale; defaults to True.

• fn_feedback (func) – Callback function to give feedback strings during import; defaults to None.

Returns:

obj:`np_io.Image5d: The 5D image object.

magmap.io.importer.is_javabridge_loaded()

Check if Javabridge and Python-Bioformats have been loaded.

Returns:

True if the modules have both been loaded, False otherwise.

Return type:

bool

magmap.io.importer.load_metadata(path, check_ver=False, assign=True)

Load image info, such as saved microscopy data and image ranges.

Parameters:

• path (str) – Path to image info file.

• check_ver (bool, default: False) – True to stop loading if the archive’s version number is less than :const:IMAGE5D_NP_VER; defaults to False.

• assign (bool, default: True) – True to assign values to module-level settings.

Return type:

Tuple[Optional[Dict[Union[str, MetaKeys], Any]], int]

Returns:

Tuple of output, the dictionary with image info, and image5d_ver_num, the version number of the info file, which is -1 if the key could not be found.

magmap.io.importer.make_filenames(filename, series=None, modifier='', keep_ext=False)

Make MagellanMapper-oriented image and image metadata filenames.

Parameters:

• filename (str) – Original path from which MagellanMapper-oriented filenames will be derived.

• series (Optional[int], default: None) – Image series; defaults to None.

• modifier (str, default: '') – Separator for image series; defaults to an empty string.

• keep_ext (bool, default: False) – True to keep the filename extension; defaults to False.

Return type:

Tuple[str, str]

Returns:

Tuple of path to the main image and path to metadata.

magmap.io.importer.parse_deconstructed_name(filename, offset, size, reg_suffixes, suffix=None)

Parse deconstructed image name into :module:`config` settings.

Typically, takes input from deconstruct_img_name().

Parameters:

• filename (str) – Deconstructed image path.

• offset (Sequence[int]) – Deconstructed sub-image offset.

• size (Sequence[int]) – Deconstructed sub-image size.

• reg_suffixes (Dict[RegSuffixes, Union[str, Sequence[str], None]]) – Registered image suffixes.

• suffix (Optional[str], default: None) – Suffix for filename. If given, filename will be set as the prefix, and the filename will become the combination of filename and suffix.

Returns:

• set_subimg: True if the sub-image parameters were set

• set_reg_suffixes: True if the registered suffixes were set

Return type:

Tuple of

magmap.io.importer.parse_ome(filename)

Parses metadata for image name and size information using Bioformats’ OME XML wrapper.

Parameters:

filename – Image file, assumed to have metadata in OME XML format.

Returns:

array of names of seriess within the file. sizes: array of tuples with dimensions for each series. Dimensions

will be given as (time, z, y, x, channels).

Return type:

names

Deprecated: 1.6.0

Use parse_ome_raw() instead.

magmap.io.importer.parse_ome_raw(metadata)

Parse Open Microscopy Environment XML to extract key metadata.

Parameters:

metadata (str) – Metadata as a string in OME XML format.

Returns:

• names: an array of names of seriess within the file

• sizes: an array of tuples with dimensions for each series, where dimensions are given as (time, z, y, x, channels); and

• md: a dictionary of metadata containing magmap.settings.config.MetaKeys.RESOLUTIONS, an array of resolutions/scaling, in the same dimensions as sizes; magmap.settings.config.MetaKeys.MAGNIFICATION, the objective magnification; magmap.settings.config.MetaKeys.ZOOM, the zoom level; and magmap.settings.config.MetaKeys.DTYPE, the pixel data type as a string.

Return type:

Tuple of

magmap.io.importer.read_file(filename, series=None, offset=None, size=None, update_info=True)

Read an image file in Numpy format.

An offset and size can be given to load an only an ROI of the image.

Parameters:

• filename (str) – Image file, assumed to have metadata in OME XML format.

• series (Optional[int], default: None) – Series index to load. Defaults to None, which will use 0.

• offset (Optional[int], default: None) – Tuple of offset given as (x, y, z) from which to start loading z-plane (x, y ignored for now). If Numpy image info already exists, this tuple will be used to load only an ROI of the image. If importing a new Numpy image, offset[2] will be used an a z-offset from which to start importing. Defaults to None.

• size (Optional[int], default: None) – Tuple of ROI size given as (x, y, z). If Numpy image info already exists, this tuple will be used to load only an ROI of the image. Defaults to None.

• update_info (bool, default: True) – True if the associated image5d info file should be updated; defaults to True.

Return type:

Image5d

Returns:

The image object.

Raises:

• FileNotFoundError – If metadata was set to be updated, but the

• main image could not be found to update the metadata. –

magmap.io.importer.roi_to_image5d(roi)

Convert from ROI image to image5d format, which simply adds a time dimension as the first dimension.

Parameters:

roi – ROI as a 3D (or 4D if channel dimension) array.

Returns:

ROI with additional time dimension prepended.

magmap.io.importer.save_image_info(filename_info_npz, names, sizes, resolutions, magnification, zoom, near_min, near_max, scaling=None, plane=None)

Save image metadata to YAML file format.

Parameters:

• filename_info_npz (str) – Output path.

• names (Sequence) – Sequence of names for each series.

• sizes (Sequence) – Sequence of sizes for each series.

• resolutions (Sequence) – Sequence of resolutions for each series.

• magnification (float) – Objective magnification.

• zoom (float) – Objective zoom.

• near_min (list[float]) – Sequence of near minimum intensities, with each element in turn holding a sequence with values for each channel.

• near_max (list[float]) – Sequence of near maximum intensities, with each element in turn holding a sequence with values for each channel.

• scaling (float) – Rescaling value for up/downsampled images; defaults to None.

• plane (str) – Planar orientation compared with original for transposed images; defaults to None.

Returns:

The saved metadata as a dictionary.

Return type:

dict

magmap.io.importer.save_np_image(image, filename, series=None)

Save Numpy image to file.

Assumes that the image or another image with similar parameters has already been loaded so that the info file can be constructed from the currently set parameters. Near min/max values are generated from the entire image.

Parameters:

• image – Numpy array.

• filename – Filename of original file, which will be passed to :func:make_filenames to create output filenames.

• series (default: None) – Image series; defaults to None.

magmap.io.importer.setup_import_dir(path)

Setup import of image files in an entire directory.

All files in the folder will be gathered. Files from different channesl should have _ch_<n> just before the extension, where n is the channel number. Files without these channel designators will be assumed to be in channel 0.

Parameters:

path (str) – Path to directory.

Returns:

Ordered dictionary of channel numbers to sequences of image file paths to import and dictionary of metadata.

Return type:

dict[int, List[str]], dict[config.MetaKeys]

Raises:

FileNotFoundError – if no file from the directory can be loaded as an image.

magmap.io.importer.setup_import_metadata(chl_paths, channel=None, series=None, z_max=-1)

Extract metadata and determine output image shape for importing multipage file(s).

Parameters:

• chl_paths (dict[Any, List[str]]) – Ordered dictionary of channel numbers to sequences of image file paths to import.

• channel (List[int]) – Sequence of channel indices to import; defaults to None to import all channels.

• series (int) – Series index to load. Defaults to None, which will use 0.

• z_max (int) – Number of z-planes to load; defaults to -1 to load all.

Returns:

Dictionary of metadata. RAW files will simply return a metadata dictionary populated with None values.

Return type:

dict[config.MetaKeys]

magmap.io.importer.setup_import_multipage(filename)

Find matching files for multipage image import.

Multiple channels are assumed to be stored in separate files with :const:CHANNEL_SEPARATOR followed by an integer corresponding to the channel number (0-based indexing), eg /path/to/image_ch_0.tif. If any such file is found, only files with these channel designators will be taken. If none are found, filename will be taken directly.

Parameters:

• filename (Union[str, Sequence[str]]) – Path(s) to image file to import. If a non-sequence,

• added. (any matching paths for different channels will also be)

Return type:

Tuple[Dict[Union[int, str], List[str]], str]

Returns:

Ordered dictionary of channel numbers to sequences of image file paths to import, and the base path of the extracted files.

Raises:

• FileNotFoundError – No existing files related to filename could

• be found. –

magmap.io.importer.start_jvm(heap_size='8G')

Starts the JVM for Python-Bioformats.

Can only start Javabridge once per session. Calling this function repeatedly without stopping the JVM will have no effect, however. To use the JVM in differ threads, use jb.attach() and jb.detach().

Parameters:

heap_size (str) – JVM heap size, defaulting to 8G.

magmap.io.importer.stop_jvm()

Stop the Javabridge JVM.

Javabridge should only be started/stopped once per session.