API¶

class pytools.HedwigZarrImage(zarr_grp: Group, _ome_info: OMEInfo, _ome_idx: int | None = None, *, compute_args: Dict[str, str] | None = mappingproxy({'scheduler': 'threads'}))¶

Represents a OME-NGFF Zarr pyramidal image. The members provide information useful for the Hedwig imaging pipelines.

property dims: str¶

The Hedwig dimension of the image XY, XYC, XYZCT etc.

Collapses ZCT dimensions if of size 1.

Note: this is the reverse order of axis for numpy/zarr/dask.

extract_2d(target_size_x: int, target_size_y: int, *, size_factor: float = 1.5, auto_uint8: bool = False) → Image¶

Extracts a 2D SimpleITK Image from an OME-NGFF pyramid structured with ZARR array that is 2D-like.

The OME-NGFF pyramid structured ZARR array is assumed to have the following structure:

The axes spacial dimensions must be labeled as “X”, “Y”, and optionally “Z”.
If a “Z” space dimension exists then it must be of size 1.
If a time dimension exists then it must be if of size 1.
If a channel dimension exists all channels are extracted.

The extracted subvolume will be resized to the target size while maintaining the aspect ratio.

The resized extracted subvolume with be the same pixel type as the OME-NGFF pyramid structured ZARR array.

Parameters:

target_size_x – The target size of the extracted subvolume in the x dimension.
target_size_y – The target size of the extracted subvolume in the y dimension.
size_factor – The size of the subvolume to extract will be increased by this factor so that the extracted subvolume can have antialiasing applied to it.
auto_uint8 – If True the output image will be automatically linearly shifted and scaled to fit into uint8 component pixel types.

Returns:

The extracted subvolume as a SimpleITK image.

neuroglancer_shader_parameters(*, mad_scale=3, middle_quantile: Tuple[float, float] | None = None) → dict¶

Produces the “shaderParameters” portion of the metadata for Neuroglancer.

Determines which shader type to use to render the image. The shader type is one of: RGB, Grayscale, or MultiChannel. The shader parameters are computed from the full resolution Zarr image. Dask is used for parallel reading and statistics computation. The global scheduler is used for all operations which can be changed with standard Dask configurations.

For the MultiChannel shader type the default algorithm for the range is to compute the robust median absolute deviation (MAD) about the median to produce the minimum and maximum range. If the middle_quantile is not None then the range is computed from the provided quantiles of the image data.

Parameters:

mad_scale – The scale factor for the robust median absolute deviation (MAD) about the median to produce the minimum and maximum range that is used to select the visible pixel intensities.
middle_quantile – If not None then the range is computed from the provided quantiles of the image data. The middle_quantile is a tuple of two floats that are between 0.0 and 1.0. The first value is the lower quantile and the second value is the upper quantile. The range is computed from the lower and upper quantiles.

Returns:

The dictionary of the shader parameters suitable for JSON serialization

ome_roi_model() → Iterable[OMEROIModel]¶

Get the OME ROI models for the current image, if they exist.

Parses the OME-XML file and returns the ROI models. The OME ROI model is generically union of annotations such: as labels and rectangles.

Returns:: The ROI model as an iterable of OMEROIModels, which may be empty.

property path: Path¶: Returns full path to the ZARR group suitable for Neuroglancer.

rechunk(chunk_size: int, compressor=None, *, in_memory=False) → None¶

Change the chunk size of each ZARR array inplace in the pyramid.

The chunk_size is applied to all spacial dimension, and other dimension (CT) are the full size.

The ImageZarrImage need write access to the ZARR.

Parameters:

chunk_size – The size as an integer to resize the chunk sizes.
compressor – The output arrays will be written with the provided compressor, if None then the compressor of the input arrays will be used.
in_memory – If true the entire arrays will be loaded into memory uncompressed, before writing to the

rechunked size, otherwise the arrays will be written directly to the rechunked size. The former is faster but requires enough memory to hold the arrays.

property shader_type: str¶: Produces the shader type one of: RGB, Grayscale, or MultiChannel.

property shape: Tuple[int, ...]¶

The size of the dimensions of the full resolution image.

This is in numpy/zarr/dask order.

property spacing: Tuple[float, ...]¶

The size of the dimensions of the full resolution image.

This is in numpy/zarr/dask order.

property units: Tuple[str, ...]¶

The units of the dimensions of the full resolution image.

This is in numpy/zarr/dask order.

class pytools.HedwigZarrImages(zarr_path: Path, read_only=True, *, compute_args: Dict[str, str] | None = mappingproxy({'scheduler': 'threads', 'num_workers': 4}))¶

Represents the set of images in a OME-NGFF ZARR structure.

get_series_keys() → Iterable[str]¶: Returns an iterable of strings of the names or labels of the images. Will be extracted from the OME-XML if available otherwise the ZARR group names. e.g. “label_image”

group(name: str) → HedwigZarrImage¶: Returns a HedwigZarrImage from the given ZARR group name or path.

property ome_info: AnyStr | None¶: Returns OME XML as string is if exists.

property ome_xml_path: Path | None¶: Returns the path to the OME-XML file, if it exists.

series() → Iterable[Tuple[str, HedwigZarrImage]]¶: An Iterable of key and HedwigZarrImages stored in the ZARR structure.

pytools.visual_min_max(input_image: Path | str, mad_scale: float, clamp: bool = True) → Dict[str, int]¶

Reads a path to an input_image file or a directory of zarr array to estimate minimum and maximum ranges to be used for visualization of the data set in Neuroglancer.

Dask is used for parallel reading and statistics computation. The global scheduler is used for all operations which can be changed with standard Dask configurations.

Parameters:

input_image – If an image file then SimpleITK is used to perform the IO. SimpleITK support formats such as mrc, mii, png, tiff etc.A zarr array is detected by a directory containing a “.zarray” file. For an OME-NGFF structured ZARR a subdirectory such as “0” commonly contains the full resolution ZARR array. Such a case would be specified by “dirname.zarr/0”.
mad_scale – The scale factor for the robust median absolute deviation (MAD) about the median to produce the “minimum and maximum range.”
clamp – If True then the minimum and maximum range will be clamped to the computed floor and limit values.

Returns:

The resulting dictionary will contain the following data elements with integer values as strings: - “neuroglancerPrecomputedMin” - “neuroglancerPrecomputedMax” - “neuroglancerPrecomputedFloor” - “neuroglancerPrecomputedLimit”

pytools.zarr_extract_2d(input_zarr: Path | str, target_size_x: int, target_size_y: int, *, size_factor: float = 1.5, output_filename: Path | str | None = None) → Image | None¶

Extracts a 2D image from an OME-NGFF pyramid structured with ZARR array that is 2D-like.

The OME-NGFF pyramid structured ZARR array is assumed to have the following structure:

The axes spacial dimensions must be labeled as “X”, “Y”, and optionally “Z”.
If a “Z” space dimension exists then it must be of size 1.
If a time dimension exists then it must be if of size 1.
If a channel dimension exists all channels are extracted.

The extracted subvolume will be resized to the target size while maintaining the aspect ratio.

The resized extracted subvolume with be the sample pixel type as the OME-NGFF pyramid structured ZARR array.

If output_filename is not None then the extracted subvolume will be written to this file. The output ITK ImageIO used to write the file may place additional contains on the image which can be written. Such as JPEG only supporting uint8 pixel types and 1, 3, or 4 components.

Parameters:

input_zarr – The path to an OME-NGFF structured ZARR array.
target_size_x – The target size of the extracted subvolume in the x dimension.
target_size_y – The target size of the extracted subvolume in the y dimension.
size_factor – The size of the subvolume to extract will be increased by this factor so that the extracted subvolume can have antialiasing applied to it.
output_filename – If not None then the extracted subvolume will be written to this file.

Returns:

The extracted subvolume as a SimpleITK image.

pytools.meta.is_16bit(file_path: str | Path) → bool¶

Read an image file header to inspect meta-data.

Supported file formats include TIFF, and others supported by SimpleITK and the Insight toolkit.

Parameters:: file_path – The path to an image file.
Returns:: True if the pixel type is a 16-bit integer (signed or unsigned), False otherwise.

pytools.meta.is_int16(file_path: str | Path) → bool¶

Read an image file header to inspect meta-data.

Supported file formats include TIFF, and others supported by SimpleITK and the Insight toolkit.

Parameters:: file_path – The path to an image file.
Returns:: True if the pixel type is a signed 16-bit integer, False otherwise.

pytools.utils.zarr.bin_shrink(img, shrink_dim=None)¶

Reduces image by a factor of 2 in xyz and performs averaging.

Parameters:

img – an array-like object of 3 dimensions
shrink_dim – an iterable for dimensions to perform operation on. Recommended to order from the fastest axis to slowest for performance.

pytools.utils.zarr.build_pyramid(zarr_path, components: List[str], chunks=None, shrink=(-1, -2), overwrite=False)¶

Iteratively generate multiple resolutions of zarr arrays.

The input array is named by the first items in the components. The remaining components are iteratively generated by reducing the resolution in the “shrink” dimensions, by a factor of 2.

class pytools.utils.histogram.DaskHistogramHelper(arr: <module 'dask.array' from '/opt/hostedtoolcache/Python/3.9.21/x64/lib/python3.9/site-packages/dask/array/__init__.py'>)¶

compute_histogram(histogram_bin_edges=None, density=False, *, compute_args=None) → Tuple[array, array]¶

Compute the histogram of the array.

Parameters:

histogram_bin_edges – The edges of the bins. If None, the edges are computed from the array, with integers of 16 bits or less, the edges are computed from the dtype for exact bins.
density – If True, the histogram is normalized to form a probability density, otherwise the count of samples in each bin.
compute_args – Additional arguments to pass to the dask compute method.

class pytools.utils.histogram.HistogramBase¶

class pytools.utils.histogram.ZARRHistogramHelper(filename)¶

pytools.utils.histogram.histogram_robust_stats(hist, bin_edges)¶

Computes the “median” and “mad” (Median Absolute Deviation).

Parameters:

hist – The histogram weights ( density or count ).
bin_edges – The edges of the bins. This array should be one greater than the hist.

pytools.utils.histogram.histogram_stats(hist, bin_edges)¶

Computes the “mean”, “var” (variance), and “sigma” (standard deviation) from the provided histogram.

Parameters:

hist – The histogram weights ( density or count ).
bin_edges – The edges of the bins. This array should be one greater than the hist.

pytools.utils.histogram.weighted_quantile(values, quantiles, sample_weight=None, values_sorted=False, old_style=False)¶

Very close to numpy.percentile, but supports weights.

Note

quantiles should be in [0, 1]!

Parameters:

values – numpy.array with data
quantiles – array-like with many quantiles needed
sample_weight – array-like of the same length as array
values_sorted – bool, if True, then will avoid sorting of initial array
old_style – if True, will correct output to be consistent with numpy.percentile.

Returns:

numpy.array with computed quantiles.

pytools.convert.file_to_uint8(in_file_path: str | Path, out_file_path: str | Path) → None¶

Read an image file, scale the input pixel intensity range to 0-255, and write an image as an unsigned 8-bit integer.

Supported file formats include TIFF, and others supported by SimpleITK and the Insight toolkit.

Parameters:

in_file_path – The file path for the source image.
out_file_path – The file path to the output, the extension will be used to automatically determine the Image format used. The out_file_path must be different that the input_file_path.

Returns:

None

Note

The conversion from to uint16 is done with floating point operations with truncation rounding. This is considered an implementation detail that may change.

API¶

Table of Contents

Previous topic

This Page