aicsimageio.writers package

Submodules

aicsimageio.writers.ome_tiff_writer module

class aicsimageio.writers.ome_tiff_writer.OmeTiffWriter[source]

Bases: Writer

static build_ome(data_shapes: List[Tuple[int, ...]], data_types: List[dtype], dimension_order: Optional[List[Optional[str]]] = None, channel_names: Optional[List[Optional[List[str]]]] = None, image_name: Optional[List[Optional[str]]] = None, physical_pixel_sizes: Optional[List[PhysicalPixelSizes]] = None, channel_colors: Optional[List[Optional[List[List[int]]]]] = None) → OME[source]

Create the necessary metadata for an OME tiff image

Parameters

  • data_shapes – A list of 5- or 6-d tuples

  • data_types – A list of data types

  • dimension_order – The order of dimensions in the data array, using T,C,Z,Y,X and optionally S

  • channel_names – The names for each channel to be put into the OME metadata

  • image_name – The name of the image to be put into the OME metadata

  • physical_pixel_sizes – Z,Y, and X physical dimensions of each pixel, defaulting to microns

  • channel_colors – List of all images channel colors to be put into the OME metadata

  • is_rgb – is a S dimension present? S is expected to be the last dim in the data shape

Returns

An OME object that can be converted to a valid OME-XML string

Return type

OME

static save(data: Union[List[Union[ndarray, Array]], ndarray, Array], uri: Union[str, Path], dim_order: Optional[Union[str, List[Optional[str]]]] = None, ome_xml: Optional[Union[str, OME]] = None, channel_names: Optional[Union[List[str], List[Optional[List[str]]]]] = None, image_name: Optional[Union[str, List[Optional[str]]]] = None, physical_pixel_sizes: Optional[Union[PhysicalPixelSizes, List[PhysicalPixelSizes]]] = None, channel_colors: Optional[Union[List[List[int]], List[Optional[List[List[int]]]]]] = None, fs_kwargs: Dict[str, Any] = {}, **kwargs: Any) → None[source]

Write a data array to a file.

Parameters

  • data (Union[List[types.ArrayLike], types.ArrayLike]) – The array of data to store. Data arrays must have 2 to 6 dimensions. If a list is provided, then it is understood to be multiple images written to the ome-tiff file. All following metadata parameters will be expanded to the length of this list.

  • uri (types.PathLike) – The URI or local path for where to save the data. Note: OmeTiffWriter can only write to local file systems.

  • dim_order (Optional[Union[str, List[Union[str, None]]]]) – The dimension order of the provided data. Dimensions must be a list of T, C, Z, Y, Z, and S (S=samples for rgb data). Dimension strings must be same length as number of dimensions in the data. If S is present it must be last and its data count must be 3 or 4. Default: None. If None is provided for any data array, we will guess dimensions based on a TCZYX ordering. In the None case, data will be assumed to be scalar, not RGB.

  • ome_xml (Optional[Union[str, OME]]) – Provided OME metadata. The metadata can be an xml string or an OME object from ome-types. A provided ome_xml will override any other provided metadata arguments. Default: None The passed-in metadata will be validated against current OME_XML schema and raise exception if invalid. The ome_xml will also be compared against the dimensions of the input data. If None is given, then OME-XML metadata will be generated from the data array and any of the following metadata arguments.

  • channel_names (Optional[Union[List[str], List[Optional[List[str]]]]]) – Lists of strings representing the names of the data channels Default: None If None is given, the list will be generated as a 0-indexed list of strings of the form “Channel:image_index:channel_index”

  • image_names (Optional[Union[str, List[Union[str, None]]]]) – List of strings representing the names of the images Default: None If None is given, the list will be generated as a 0-indexed list of strings of the form “Image:image_index”

  • physical_pixel_sizes (Optional[Union[types.PhysicalPixelSizes,) – List[types.PhysicalPixelSizes]]] List of numbers representing the physical pixel sizes in Z, Y, X in microns Default: None

  • channel_colors (Optional[Union[List[List[int]], List[Optional[List[List[int]]]]]) – List of rgb color values per channel or a list of lists for each image. These must be values compatible with the OME spec. Default: None

  • fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}

Raises

ValueError: – Non-local file system URI provided.

Examples

Write a TCZYX data set to OME-Tiff

>>> image = numpy.ndarray([1, 10, 3, 1024, 2048])
... OmeTiffWriter.save(image, "file.ome.tif")

Write data with a dimension order into OME-Tiff

>>> image = numpy.ndarray([10, 3, 1024, 2048])
... OmeTiffWriter.save(image, "file.ome.tif", dim_order="ZCYX")

Write multi-scene data to OME-Tiff, specifying channel names

>>> image0 = numpy.ndarray([3, 10, 1024, 2048])
... image1 = numpy.ndarray([3, 10, 512, 512])
... OmeTiffWriter.save(
...     [image0, image1],
...     "file.ome.tif",
...     dim_order="CZYX",  # this single value will be repeated to each image
...     channel_names=[["C00","C01","C02"],["C10","C11","C12"]]
... )

aicsimageio.writers.ome_zarr_writer module

class aicsimageio.writers.ome_zarr_writer.OmeZarrWriter(uri: Union[str, Path])[source]

Bases: object

Constructor.

Parameters

uri (types.PathLike) – The URI or local path for where to save the data.

static build_ome(size_z: int, image_name: str, channel_names: List[str], channel_colors: List[int], channel_minmax: List[Tuple[float, float]]) → Dict[source]

Create the omero metadata for an OME zarr image

Parameters

  • size_z – Number of z planes

  • image_name – The name of the image

  • channel_names – The names for each channel

  • channel_colors – List of all channel colors

  • channel_minmax – List of all (min, max) pairs of channel intensities

Returns

An “omero” metadata object suitable for writing to ome-zarr

Return type

Dict

write_image(image_data: Union[ndarray, Array], image_name: str, physical_pixel_sizes: Optional[PhysicalPixelSizes], channel_names: Optional[List[str]], channel_colors: Optional[List[int]], chunk_dims: Optional[Tuple] = None, scale_num_levels: int = 1, scale_factor: float = 2.0, dimension_order: Optional[str] = None) → None[source]

Write a data array to a file. NOTE that this API is not yet finalized and will change in the future.

Parameters

  • image_data (types.ArrayLike) – The array of data to store. Data arrays must have 2 to 6 dimensions. If a list is provided, then it is understood to be multiple images written to the ome-tiff file. All following metadata parameters will be expanded to the length of this list.

  • image_name (str) – string representing the name of the image

  • physical_pixel_sizes (Optional[types.PhysicalPixelSizes]) – PhysicalPixelSizes object representing the physical pixel sizes in Z, Y, X in microns. Default: None

  • channel_names (Optional[List[str]]) – Lists of strings representing the names of the data channels Default: None If None is given, the list will be generated as a 0-indexed list of strings of the form “Channel:image_index:channel_index”

  • channel_colors (Optional[List[int]]) – List of rgb color values per channel or a list of lists for each image. These must be values compatible with the OME spec. Default: None

  • scale_num_levels (Optional[int]) – Number of pyramid levels to use for the image. Default: 1 (represents no downsampled levels)

  • scale_factor (Optional[float]) – The scale factor to use for the image. Only active if scale_num_levels > 1. Default: 2.0

  • dimension_order (Optional[str]) – The dimension order of the data. If None is given, the dimension order will be guessed from the number of dimensions in the data according to TCZYX order.

Examples

Write a TCZYX data set to OME-Zarr

>>> image = numpy.ndarray([1, 10, 3, 1024, 2048])
... writer = OmeZarrWriter("/path/to/file.ome.zarr")
... writer.write_image(image)

Write multi-scene data to OME-Zarr, specifying channel names

>>> image0 = numpy.ndarray([3, 10, 1024, 2048])
... image1 = numpy.ndarray([3, 10, 512, 512])
... writer = OmeZarrWriter("/path/to/file.ome.zarr")
... writer.write_image(image0, "Image:0", ["C00","C01","C02"])
... writer.write_image(image1, "Image:1", ["C10","C11","C12"])

aicsimageio.writers.timeseries_writer module

class aicsimageio.writers.timeseries_writer.TimeseriesWriter[source]

Bases: Writer

A writer for timeseries Greyscale, RGB, or RGBA image data. Primarily directed at formats: “gif”, “mp4”, “mkv”, etc.

Notes

To use this writer, install with: pip install aicsimageio[base-imageio].

DIM_ORDERS = {3: 'TYX', 4: 'TYXS'}
static save(data: Union[ndarray, Array], uri: Union[str, Path], dim_order: Optional[str] = None, fps: int = 24, fs_kwargs: Dict[str, Any] = {}, **kwargs: Any) → None[source]

Write a data array to a file.

Parameters

  • data (types.ArrayLike) – The array of data to store. Data must have either three or four dimensions.

  • uri (types.PathLike) – The URI or local path for where to save the data.

  • dim_order (str) – The dimension order of the provided data. Default: None. Based off the number of dimensions, will assume the dimensions – three dimensions: TYX and four dimensions: TYXS.

  • fps (int) – Frames per second to attach as metadata. Default: 24

  • fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}

Examples

Data is the correct shape and dimension order

>>> image = dask.array.random.random((50, 100, 100))
... TimeseriesWriter.save(image, "file.gif")

Data provided with current dimension order

>>> image = numpy.random.rand(100, 3, 1024, 2048)
... TimeseriesWriter.save(image, "file.mkv", "TSYX")

Save to remote

>>> image = numpy.random.rand(300, 100, 100, 3)
... TimeseriesWriter.save(image, "s3://my-bucket/file.png")
Raises

IOError – Cannot write FFMPEG formats to remote storage.

Notes

This writer can also be useful when wanting to create a timeseries image using a non-time dimension. For example, creating a timeseries image where each frame is a Z-plane from a source volumetric image as seen below.

>>> image = AICSImageIO("some_z_stack.ome.tiff")
... TimeseriesWriter.save(
...     data=image.get_image_data("ZYX", T=0, C=0),
...     uri="some_z_stack.mp4",
...     # Overloading the Z dimension as the Time dimension
...     # Technically not needed as it would have been assumed due to three dim
...     dim_order="TYX",
... )

aicsimageio.writers.two_d_writer module

class aicsimageio.writers.two_d_writer.TwoDWriter[source]

Bases: Writer

A writer for image data is only 2 dimension with samples (RGB / RGBA) optional. Primarily directed at formats: “png”, “jpg”, etc.

This is primarily a passthrough to imageio.imwrite.

Notes

To use this writer, install with: pip install aicsimageio[base-imageio].

DIM_ORDERS = {2: 'YX', 3: 'YXS'}
static save(data: Union[ndarray, Array], uri: Union[str, Path], dim_order: Optional[str] = None, fs_kwargs: Dict[str, Any] = {}, **kwargs: Any) → None[source]

Write a data array to a file.

Parameters

  • data (types.ArrayLike) – The array of data to store. Data must have either two or three dimensions.

  • uri (types.PathLike) – The URI or local path for where to save the data.

  • dim_order (str) – The dimension order of the provided data. Default: None. Based off the number of dimensions, will assume the dimensions similar to how aicsimageio.readers.default_reader.DefaultReader reads in data. That is, two dimensions: YX and three dimensions: YXS.

  • fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}

Examples

Data is the correct shape and dimension order

>>> image = dask.array.random.random((100, 100, 4))
... TwoDWriter.save(image, "file.png")

Data provided with current dimension order

>>> image = numpy.random.rand(3, 1024, 2048)
... TwoDWriter.save(image, "file.png", "SYX")

Save to remote

>>> image = numpy.random.rand(100, 100, 3)
... TwoDWriter.save(image, "s3://my-bucket/file.png")

aicsimageio.writers.writer module

class aicsimageio.writers.writer.Writer[source]

Bases: ABC

A small class to build standardized image writer functions.

abstract static save(data: Union[ndarray, Array], uri: Union[str, Path], dim_order: str = 'TCZYX', **kwargs: Any) → None[source]

Write a data array to a file.

Parameters

  • data (types.ArrayLike) – The array of data to store.

  • uri (types.PathLike) – The URI or local path for where to save the data.

  • dim_order (str) – The dimension order of the data.

Examples

>>> image = numpy.ndarray([1, 10, 3, 1024, 2048])
... DerivedWriter.save(image, "file.ome.tif", "TCZYX")

>>> image = dask.array.ones((4, 100, 100))
... DerivedWriter.save(image, "file.png", "CYX")

Module contents