OME-ZARR conversion plugin
Write any array or image file to a pyramidal OME-ZARR store, add resolution
levels to an existing store, or store a label image inside an OME-ZARR under
the NGFF labels/ group. Uses only the core dependencies for arrays and
.zarr inputs; reading other file formats needs the optional bioio extra
(pip install "patchworks[bioio]").
Pyramids downsample X and Y only — Z (and channel/time) are kept at full
resolution, matching anisotropic microscopy stacks.
to_ome_zarr
patchworks.plugins.ome_zarr.to_ome_zarr(source: Union[da.Array, np.ndarray, str, Path], out_path: Union[str, Path], *, axes: Union[str, None] = None, pixel_size: Union[PixelSize, tuple, None] = None, scene: int = 0, sequence_pattern: Union[str, None] = None, n_levels: int = 5, downscale: int = 2, chunks: Union[tuple[int, ...], None] = None, shard: ShardSpec = False, reuse_pyramid: bool = False, progress: bool = True, overwrite: bool = False, ngff_version: Union[str, None] = 'auto', compression: Union[str, None] = None, downsample: str = 'mean') -> str
Write source as a pyramidal, calibrated OME-ZARR store.
source may be a dask/NumPy array, a .zarr store, an Imaris .ims
file, any image format readable by bioio (CZI, LIF, ND2, OME-TIFF, …), or
(with sequence_pattern set) a glob over a folder of single-plane TIFFs.
File inputs are read lazily; the pyramid is built level-by-level from disk
with bounded chunks, so the full volume never needs to fit in RAM. Only
x/y are downsampled; z (and channel/time) stay full-resolution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
(Array, ndarray, str or Path)
|
Array or path to convert. |
required |
out_path
|
str or Path
|
Destination |
required |
axes
|
str
|
One character per array dimension, e.g. |
None
|
pixel_size
|
(dict, tuple or None)
|
Physical voxel size in micrometers, as |
None
|
scene
|
int
|
Scene index for multi-scene bioio files. |
0
|
sequence_pattern
|
str
|
When given, source is treated as a glob pattern over a folder of
single-plane TIFFs (e.g. |
None
|
n_levels
|
int
|
Maximum number of pyramid levels including full resolution. |
5
|
downscale
|
int
|
Per-level X/Y downsampling factor (default 2). |
2
|
chunks
|
tuple of int
|
Chunk shape for the written levels. |
None
|
shard
|
bool or tuple of int
|
Pack many chunks into one shard file (zarr v3), cutting the file count
~100× on huge arrays. |
False
|
progress
|
bool
|
Show a per-level dask progress bar (default |
True
|
reuse_pyramid
|
bool
|
Imaris |
False
|
overwrite
|
bool
|
Overwrite an existing store at out_path. |
False
|
ngff_version
|
str or None
|
NGFF version (and therefore zarr format) to write: |
'auto'
|
downsample
|
('mean', 'mode', 'nearest')
|
How the pyramid's X/Y levels are made from the one above: |
"mean"
|
compression
|
str
|
Codec for the arrays written ( |
None
|
Returns:
| Type | Description |
|---|---|
str
|
The path to the written store ( |
Examples:
>>> from patchworks.plugins.ome_zarr import to_ome_zarr
>>> to_ome_zarr("scan.ims", "scan.zarr", n_levels=4)
'scan.zarr'
>>> to_ome_zarr(
... "ZT18_Male4_Left/*.tif",
... "ZT18_Male4_Left.zarr",
... sequence_pattern=r"_T(?P<T>\d+)_Z(?P<Z>\d+)_C(?P<C>\d+)_V\d+",
... shard=True,
... )
'ZT18_Male4_Left.zarr'
Source code in src/patchworks/plugins/ome_zarr.py
3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 | |
add_pyramid
patchworks.plugins.ome_zarr.add_pyramid(group_path: Union[str, Path], *, base: str = '0', axes: Union[str, None] = None, pixel_size: Union[PixelSize, tuple, None] = None, n_levels: int = 5, downscale: int = 2, chunks: Union[tuple[int, ...], None] = None, shard: ShardSpec = False, progress: bool = True, ngff_version: Union[str, None] = 'auto', compression: Union[str, None] = None, downsample: Union[str, None] = None, translation: Union[PixelSize, None] = None) -> str
Add downsampled pyramid levels to an existing single-resolution zarr.
Reads the full-resolution array already at group_path/base, writes the
missing levels next to it (lazily, from disk), and (re)writes the NGFF
multiscales metadata. Existing calibration is preserved; pass
pixel_size to set it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
group_path
|
str or Path
|
Zarr group containing the full-resolution array at base. |
required |
base
|
str
|
Component name of the existing full-resolution level (default
|
'0'
|
axes
|
str
|
One letter per axis, e.g. |
None
|
pixel_size
|
(dict, tuple or None)
|
Physical voxel size in micrometers. |
None
|
n_levels
|
int
|
Maximum number of levels including the existing full-resolution one (default 5). |
5
|
downscale
|
int
|
Per-level X/Y downsampling factor (default 2). |
2
|
chunks
|
tuple of int
|
Chunk shape for the written levels. |
None
|
shard
|
bool or tuple of int
|
Sharding request (see :func: |
False
|
progress
|
bool
|
Show a per-level dask progress bar (default |
True
|
ngff_version
|
str or None
|
NGFF version (and therefore zarr format) to write: |
'auto'
|
downsample
|
('mean', 'mode', 'nearest')
|
How each level is made from the one above (see :func: |
"mean"
|
translation
|
dict
|
Physical offset |
None
|
compression
|
str
|
Codec for the arrays written ( |
None
|
Returns:
| Type | Description |
|---|---|
str
|
The path to the updated group. |
Examples:
Source code in src/patchworks/plugins/ome_zarr.py
3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 | |
write_labels
patchworks.plugins.ome_zarr.write_labels(image_store: Union[str, Path], labels: Union[da.Array, np.ndarray], *, name: str = 'labels', axes: Union[str, None] = None, pixel_size: Union[PixelSize, tuple, None] = None, n_levels: Union[int, None] = None, downscale: int = 2, chunks: Union[tuple[int, ...], None] = None, shard: ShardSpec = False, progress: bool = True, overwrite: bool = False, n_objects: Union[int, None] = None, ngff_version: Union[str, None] = 'auto', compression: Union[str, None] = None, level: int = 0, provenance: Union[dict, None] = None) -> str
Store labels inside image_store under the NGFF labels/ group.
The labels are written as their own multi-scale pyramid at
image_store/labels/<name>/ and registered in
image_store/labels/.zattrs, so the image and its segmentation live in a
single OME-ZARR store. Calibration is inherited from the parent image
unless pixel_size is given.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image_store
|
str or Path
|
OME-ZARR store this label image belongs to. |
required |
labels
|
Array or ndarray
|
Integer label array (0 = background), same spatial shape as the image. |
required |
name
|
str
|
Label image name under |
'labels'
|
axes
|
str
|
One letter per axis. |
None
|
pixel_size
|
(dict, tuple or None)
|
Physical voxel size in micrometers. |
None
|
n_levels
|
int
|
Pyramid levels when the image has no pyramid to follow (default 5); otherwise exactly as many as the image, as the OME-Zarr spec requires of a label image. |
None
|
downscale
|
int
|
Per-level X/Y downsampling factor (default 2). |
2
|
chunks
|
tuple of int
|
Chunk shape for the written levels. |
None
|
shard
|
bool or tuple of int
|
Sharding request (see :func: |
False
|
progress
|
bool
|
Show a per-level dask progress bar (default |
True
|
overwrite
|
bool
|
Replace an existing label image of the same name (default
|
False
|
n_objects
|
int or None
|
Exact non-background object count, if known — forwarded to
:func: |
None
|
level
|
int
|
The image pyramid level labels were segmented at (default 0);
their calibration and offset are taken from that level. See
:func: |
0
|
ngff_version
|
str or None
|
NGFF version (and therefore zarr format) to write: |
'auto'
|
compression
|
str
|
Codec for the arrays written ( |
None
|
provenance
|
dict
|
How the labels were made (see :func: |
None
|
Returns:
| Type | Description |
|---|---|
str
|
Path to the written label group ( |
Examples:
>>> from patchworks import merge_tile_labels
>>> merged, n = merge_tile_labels(
... "stage.zarr",
... input_component="staged",
... write_to="merged.zarr",
... sequential_labels=True,
... return_count=True,
... )
>>> write_labels(
... "scan.zarr", merged, name="cells", n_objects=n
... )
'scan.zarr/labels/cells'
Source code in src/patchworks/plugins/ome_zarr.py
3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 | |
register_labels
patchworks.plugins.ome_zarr.register_labels(image_store: Union[str, Path], name: str = 'labels', *, axes: Union[str, None] = None, pixel_size: Union[PixelSize, tuple, None] = None, n_levels: Union[int, None] = None, downscale: int = 2, chunks: Union[tuple[int, ...], None] = None, shard: ShardSpec = False, progress: bool = True, n_objects: Union[int, None] = None, ngff_version: Union[str, None] = 'auto', compression: Union[str, None] = None, level: int = 0, provenance: Union[dict, None] = None) -> str
Pyramidalise and register an existing labels/<name>/0 base level.
Assumes the full-resolution label array already exists at
image_store/labels/<name>/0. Adds the downsampled levels, tags the
group with NGFF image-label metadata, lists name in
labels/.zattrs, and inherits the parent image's pixel calibration
(unless pixel_size is given).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image_store
|
str or Path
|
OME-ZARR store path containing the image this label belongs to. |
required |
name
|
str
|
Label image name under |
'labels'
|
axes
|
str
|
One letter per axis. |
None
|
pixel_size
|
(dict, tuple or None)
|
Physical voxel size in micrometers. |
None
|
n_levels
|
int
|
Pyramid levels including full resolution, when the image has no pyramid to follow (default 5). With one, the labels get exactly as many levels as the image -- the OME-Zarr spec requires it of a label image -- whatever is asked here. |
None
|
downscale
|
int
|
Per-level X/Y downsampling factor (default 2). |
2
|
chunks
|
tuple of int
|
Chunk shape for the written levels. |
None
|
shard
|
bool or tuple of int
|
Sharding request (see :func: |
False
|
progress
|
bool
|
Show a per-level dask progress bar (default |
True
|
level
|
int
|
The image pyramid level the labels were segmented at (default 0). Their voxel size and offset are that level's, not level 0's: taking level 0's for labels made at level 1 draws them at half size, drifting further off the image the further from the origin. |
0
|
n_objects
|
int or None
|
Exact non-background object count, if known (e.g. from
:func: |
None
|
ngff_version
|
str or None
|
NGFF version (and therefore zarr format) to write: |
'auto'
|
compression
|
str
|
Codec for the arrays written ( |
None
|
provenance
|
dict
|
How the labels were made (see :func: |
None
|
Returns:
| Type | Description |
|---|---|
str
|
Path to the label group ( |
Examples:
Source code in src/patchworks/plugins/ome_zarr.py
3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 | |
reshard_level
patchworks.plugins.ome_zarr.reshard_level(group_path: Union[str, Path], component: str = '0', shard: ShardSpec = True, progress: bool = True) -> str
Rewrite an existing array in place, sharded, via one dask pass.
For an array that had to be written unsharded because many writers
filled it a chunk at a time -- a label group's level 0, written tile by
tile by concurrent segment jobs, or by the merge's own worker pool -- a
shard cannot be produced while those writers are running: they would
read-modify-write the same shard file and silently lose each other's
chunks. Doing it afterwards, single-threaded through
:func:_to_zarr_level, is safe because one writer owns every shard.
The cost is one extra full read+write of the level, which is why this is
opt-in rather than implied by shard.
Array attributes are carried across. That matters for a label level 0: the merge records how far it got there, and losing that would let a re-run merge already-merged ids and collide unrelated objects.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
group_path
|
str or Path
|
Path of the zarr group holding the array. |
required |
component
|
str
|
Array name within the group (default |
'0'
|
shard
|
bool or tuple of int
|
Sharding request; see :func: |
True
|
progress
|
bool
|
Show a dask progress bar for the rewrite. |
True
|
Returns:
| Type | Description |
|---|---|
str
|
The path of the array that was rewritten. |
Source code in src/patchworks/plugins/ome_zarr.py
1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 | |
read_pixel_size
patchworks.plugins.ome_zarr.read_pixel_size(store: Union[str, Path], level: int = 0) -> PixelSize
Physical voxel size recorded in an OME-ZARR's metadata for level.
The calibration the conversion carried over from the source file, as
{"z": .., "y": .., "x": ..} in micrometers. Axes left at scale 1.0
(uncalibrated) are omitted, so an empty dict means the store carries no
usable calibration.
Use this instead of retyping voxel sizes into a config: a deconvolution told the wrong voxel size produces a plausible-looking but wrong result.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
store
|
str or Path
|
Path of the OME-ZARR group. |
required |
level
|
int
|
Pyramid level (default 0, full resolution). Anything segmented or measured at a coarser level must use that level's voxel size. |
0
|
Returns:
| Type | Description |
|---|---|
dict
|
|
Examples:
>>> read_pixel_size("scan.zarr")
{'z': 0.2, 'y': 0.1, 'x': 0.1}
>>> read_pixel_size("scan.zarr", level=1)
{'z': 0.2, 'y': 0.2, 'x': 0.2}
Source code in src/patchworks/plugins/ome_zarr.py
NGFF metadata layout
NGFF 0.4 is defined over zarr v2 and puts its keys at the top level; 0.5 is
the zarr-v3 revision and nests them under ome. patchworks writes whichever
matches the store, and reads both.
patchworks.plugins.ome_zarr.ngff_version() -> str
NGFF version currently being written.
Inside a write call this reflects that call's ngff_version=;
outside one it is the version an "auto" write would produce.
Source code in src/patchworks/plugins/ome_zarr.py
Every writer takes an ngff_version= keyword: "auto" (default) follows the
installed zarr (0.5, since patchworks requires zarr-python 3) and "0.4" pins the older, zarr-v2
layout. Writing into an existing store always follows that store's format,
so a label pyramid added later can never disagree with the image it sits in.
NGFF 0.6 is released but not written: RFC-5 replaces axes with
coordinateSystems and requires input/output on every coordinate
transformation, and no reader supports it yet.
patchworks.plugins.ome_zarr.read_ngff_attr(attrs, key: str, default=None)
Read an NGFF key from either layout.
Accepts both the 0.4 top-level placement and the 0.5 ome nesting, so
stores written by any patchworks version (or another tool) still load.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs
|
Mapping
|
A zarr group's attributes. |
required |
key
|
str
|
NGFF key, e.g. |
required |
default
|
Any
|
Returned when the key is absent from both layouts. |
None
|
Source code in src/patchworks/plugins/ome_zarr.py
patchworks.plugins.ome_zarr.write_ngff_attrs(group, **entries) -> None
Write NGFF keys in the layout matching the store's zarr version.
On zarr v3 the keys are merged into the ome attribute (0.5); on v2
they go to the top level (0.4). Merging matters because several keys are
written at different times onto the same group -- multiscales by the
pyramid, then image-label when the labels are registered.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
group
|
Group
|
The group to write to. |
required |
**entries
|
The NGFF keys and their values, e.g. |
{}
|