This release is a pre-release and may not be stable for production use.
clearscale
clearscale is a small dependency-free Python package for clear multiscale image metadata manipulation.
Features
- Zero dependencies, pure Python
- Compatible with Python 3.10+
- Read OME-Zarr metadata and even Neuroglancer Precomputed (very basic support)
- Read all OME-Zarr versions (0.1 to 0.6) using one code path - no version branching, future versions come for free
- Write OME-Zarr versions 0.4, 0.5 and 0.6
- Virtually no knowledge about OME-Zarr required
- Create, manipulate, save and load multiscale metadata
- Make sure metadata are correct for any scaling method
- Find out how exactly your scaling method resamples with characterization
- Read and write multiscale transformations into alternate coordinate systems
- Read and write transformations between multiscales using scenes
Minimal OME-Zarr example
The absolute minimum requirements for writing OME-Zarr:
- axis keys (
"zyx") - writing the data to a zarr array inside a zarr group (and recording the array sub-path)
zarr_format=3for OME-Zarrversion="0.5"
# Assuming you have numpy and zarr-python 3.* installed
import numpy as np
import zarr
import clearscale as cs
# You have some array
image = np.random.random((128, 1024, 1024)).astype(np.float32)
# 1. Data: Make a group and write the array into it
# (no clearscale involved)
group = zarr.open_group(
"demo-output/example1.ome.zarr",
mode="w",
zarr_format=3
)
array_path = "s0"
group.create_array(array_path, data=image)
# 2. Metadata: Scale -> Multiscale -> Group -> attrs
group.attrs.update(
cs.OmeZarrGroup
.from_single(
cs.Multiscale.from_single(
scale=cs.Scale.from_lists("zyx"),
scale_key=array_path
)
)
.to_attrs(version="0.5")
)
Zero dependencies
Being dependency-free means:
clearscalefits in any Python environment. Installing or uninstalling it will not modify any other installed packages.clearscaledoes not interact with data (numpy/zarr arrays). You implement data processing according to your needs, and useclearscaleto generate metadata that describes your processing.
This provides full flexibility for data processing, but it comes at the risk of desynchronization between data and metadata.
You can mitigate this by coupling data processing to the metadata, for example by using the generated metadata as the parameter for image scaling and data writing:
import clearscale as cs
# 1. Define operation plan as metadata
shape = cs.Shape(zip("tzyx", my_data.shape))
scaling_blueprint = cs.BlueprintShapes.downscale_powers_of_2_xyz(
base_shape=shape,
rounding="ceil",
limit_all=cs.Shape(z=8, y=128, x=128),
)
# 2. Scale data according to the blueprint.
# Metadata as parameter for data processing.
for scale_key, target_shape in scaling_blueprint.items():
# Target shape from blueprint
scaled_data = do_my_scaling(my_data, target_shape.values_tuple())
# Target array path from blueprint
zarr_group.create_array(scale_key, data=scaled_data)
# 3. Write metadata: Scale -> Multiscale -> Group -> attrs
pixel_size = cs.PixelSize(t=5.0, z=260.0, y=0.53, x=0.53)
unit = cs.Unit(t="s", z="micrometer", y="micrometer", x="micrometer")
base = cs.Scale(shape, pixel_size, unit)
ms = cs.Multiscale.from_single(base, blueprint=scaling_blueprint)
group_meta = cs.OmeZarrGroup.from_single(ms).to_attrs(version="0.6")
zarr_group.attrs.update(group_meta)
For example, if you use numpy, scikit-image and zarr-python, the placeholders above could look like:
import os, numpy, skimage, zarr
my_data = numpy.random.rand(3, 12, 512, 512)
do_my_scaling = skimage.transform.resize
zarr_group = zarr.open_group(os.path.expanduser("demo-output/sweet.ome.zarr"), mode="w")
# Now you can actually run the example snippet above and produce a valid `sweet.ome.zarr`
Install
clearscale is considered in "beta" status for a short time, with 1.0 release intended soon(TM), when we have some feedback from first users.
Please try it and let us know if you encounter anything unclear!
Install the 0.9.0 release candidate from PyPI:
python -m pip install clearscale==0.9.0rc1
Or add to your conda env.yaml:
dependencies:
- pip
- pip:
- clearscale==0.9.0rc1
Note that until we publish 1.0, the API is considered subject to change so we can ensure it "solidifies" with as much convenience and robustness as possible. Though we hope there won't be too many changes necessary at this point :)
Documentation
Rendered guides (OME-Zarr how-to, core concepts, metadata scaling, ...) and automatically generated API Reference are in the clearscale documentation.
The handwritten guides are also directly under docs/ in this repository.
End-to-end examples
Downsample a numpy array and save it as OME-Zarr
The previous example used a "metadata-first" approach (first compute metadata blueprint, then scale data according to it).
This example works the other way round (first scale data, then record what was done in blueprint).
# This example assumes numpy, scikit-image and zarr-python 3.* are installed
import numpy as np
import zarr
from skimage.transform import pyramid_gaussian
import clearscale as cs
# 1. Generate a pyramid
image = np.random.random((128, 1024, 1024)).astype(np.float32)
pyramid = [level.astype(np.float32) for level in pyramid_gaussian(image, downscale=2)]
# 2. Write arrays to zarr on disk and record scaled shapes
group = zarr.open_group("demo-output/example2.ome.zarr", mode="w")
scaled_shapes = []
for i, level in enumerate(pyramid):
scale_key = f"s{i}"
group.create_array(scale_key, data=level)
scaled_shapes.append(
(
scale_key,
cs.Shape(zip("zyx", level.shape))
)
)
# 3. Describe the full-resolution image
base = cs.Scale.from_lists(
keys="zyx",
shape=image.shape,
pixel_size=[25, 240, 240],
unit=["micrometer", "nanometer", "nanometer"],
)
# 4. Use the recorded scale shapes as a blueprint to expand a Multiscale
blueprint = cs.BlueprintShapes(scaled_shapes)
multiscale = cs.Multiscale.from_single(base, blueprint=blueprint)
# 5. Save OME-Zarr metadata
group_meta = cs.OmeZarrGroup.from_single(multiscale).to_attrs(version="0.5")
group.attrs.update(group_meta)
Download a single scale of a public OME-Zarr as a valid local OME-Zarr
from pathlib import Path
import zarr # This example assumes zarr-python 3.* is installed (plus fsspec, requests and aiohttp for https reading)
import clearscale as cs
URL = "https://s3.embl.de/i2k-2020/platy-raw.ome.zarr"
SCALE_KEY = "s6"
LOCAL_PATH = Path(f"demo-output/platy-raw-{SCALE_KEY}.ome.zarr")
# 1. Discover what's on the server
remote_group = zarr.open_group(URL)
remote_meta = cs.OmeZarrGroup.from_group(remote_group)
assert remote_meta.kind is cs.GroupKind.MULTISCALE, "This tells us there is exactly one Multiscale in this group"
assert remote_meta.version == "0.4", "OME-Zarr version is a property of the group, not of individual Multiscales"
remote_multiscale = remote_meta.multiscales[0]
assert SCALE_KEY in remote_multiscale, "Multiscale is dict-like, with the sub-paths to arrays as keys"
assert remote_multiscale[SCALE_KEY].shape == {"z": 357, "y": 405, "x": 430}
# 2. Create the local target and download the data
source_array = remote_group[SCALE_KEY]
local_group = zarr.open_group(str(LOCAL_PATH), mode="w", zarr_format=2) # OME-Zarr v0.4 must use zarr-format v2
print(f"Downloading {SCALE_KEY} data...")
local_array = local_group.create_array(SCALE_KEY, data=source_array)
# 3. Derive a new Multiscale from the chosen Scale entry in the existing Multiscale
local_multiscale = remote_multiscale.derive(SCALE_KEY)
# 4. Write the new metadata to the downloaded store
local_group_meta = cs.OmeZarrGroup.from_single(local_multiscale)
local_group.attrs.update(local_group_meta.to_attrs(version="0.4"))
Why clearscale?
The motivation behind clearscale is to make upgrading from
My tool/script does zarr
to
My tool/script does OME-Zarr
as easy as possible.
Why not use one of the existing libraries?
You should probably use one of the existing libraries, if they work for you :)
Check out the NGFF Tools page for some examples. Python libraries include e.g. bioio, ngff-zarr, ngio, ome-zarr-py, and yaozarrs. Several of these handle not only the metadata, but also data manipulation all in one.
Dependencies are hard
But maybe you can't, or don't want to, use any of the above.
- Technical reasons (dependency conflicts)
- Legal reasons (licensing conflicts, commercial use)
- You already have data processing in place that you don't want to reimplement or risk adapting inefficiently.
- You just want to minimise bloat.
clearscale is tiny, dependency-free, permissively licensed, and works around your existing data processing.
Zarr is complex enough
There are several backend packages your application or script might use for reading and writing zarr data. Implementing data processing in an efficient, chunk-wise (shard-wise) manner is complex on its own. You shouldn't need to learn the OME metadata specification on top to make your datasets accessible to others, or interoperable with other tools.
With clearscale, no matter how you handle zarr data, handling multiscale metadata like OME-Zarr looks the same.
Custom applications
There are thousands of ways to scale or otherwise transform an image. Maybe none of the existing libraries that can write OME-Zarr implements quite what you need, so you have to roll your own.
clearscale isn't tied to data processing. Whatever you're doing, clearscale can simplify metadata manipulation.
Should I use clearscale in my project right now?
If you're willing to adapt to future changes in the API: Yes, please do try it!
If you are looking for a stable API, please wait until the first formal release to PyPI. After that point, API changes will follow semver and deprecations will be avoided or give appropriate notice through DeprecationWarnings.
Contributing / Feature scope
Any form of feedback, issues, bug reports, feature requests, pull requests and other contributions are welcome! See CONTRIBUTING.md.
License
Licensed under either the MIT license or the Apache License, Version 2.0, at your option.
Metadata
Release files for clearscale 0.9.0rc2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| clearscale-0.9.0rc2.tar.gz | 300.7 kB | With provenance | Details for clearscale-0.9.0rc2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| clearscale-0.9.0rc2-py3-none-any.whl | Python 3 | none | any | Details for clearscale-0.9.0rc2-py3-none-any.whl |
Total release size: 448.3 kB
Release files / clearscale-0.9.0rc2.tar.gz
| Download URL | clearscale-0.9.0rc2.tar.gz |
|---|---|
| Size | 300.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cfcde4bcdde4a2140a00df54f32f4685f0e03dd9487c49ae568d0c9ceb185a1c
|
|
BLAKE2b-256 checksum How to use checksums |
d3c55832e0854809ebb20fa6e955c1ad9f239ca4d7a3551685115da505d56b1e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / clearscale-0.9.0rc2-py3-none-any.whl
| Download URL | clearscale-0.9.0rc2-py3-none-any.whl |
|---|---|
| Size | 147.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
01b7696ab1516e8eea6ff2f5bdccfc60e61c5cbe32aed09205df10203d395d8c
|
|
BLAKE2b-256 checksum How to use checksums |
e00a4685b5617cae98a71cbb5eb35b6927c8adb6b278327272110a5deb61b042
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logSecurity for clearscale 0.9.0rc2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for clearscale-0.9.0rc2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.