copick

copick is a cross-platform, storage-agnostic and server-less dataset API for cryoET datasets. Access to the data is provided through an object-oriented API that abstracts away the underlying storage using the fsspec-family of libraries.

Why copick?

• storage-agnostic: Access data on local or shared filesystems, via SSH or on the cloud with the same API. No need for your own boilerplate!
• cloud-ready: Access image data quickly and in parallel thanks to multiscale OME-Zarr!
• server-less: No need for a dedicated server or database to access your data, just point copick to your data and go!
• cross-platform: copick works on any platform that supports Python. Compute on Linux, visualize on Windows or Mac, all with the same dataset API!
• ecosystem: Using the copick API allows visualizing and curating data in ChimeraX and Napari right away!

Documentation

For more information, see the documentation.

Installation

copick can be installed using pip. Using the all extra installs necessary requirements for all tested filesystem implementations from the fsspec family (local, s3fs, smb, sshfs). A separate smb extra is available.

pip install "copick[all]"

[!NOTE] copick>=1.2.0 will fail to install with pip~=25.1.0. We recommend using pip>=25.2 or uv pip when installing copick.

[!IMPORTANT] copick 2.0 creates and rebuilds image pyramids as OME-Zarr 0.5 backed by Zarr v3. Existing Zarr v2 projects remain readable, and whole-store copy operations preserve their original format and layout.

Example dataset

An example dataset can be obtained from Zenodo. The migration-test archive contains both the legacy Zarr v2 project and its Zarr v3 twin, so it is larger than the earlier single-format example.

To test with the example dataset:

1. Download and unpack the example dataset

2. Add the location of the sample_project-directory in the unpacked dataset to filesystem_overlay_only.json

   {
       "name": "test",
       "description": "A test project.",
       "version": "1.0.0",
   
       "pickable_objects": [
           {
               "name": "proteasome",
               "is_particle": true,
               "pdb_id": "3J9I",
               "label": 1,
               "color": [255, 0, 0, 255],
               "radius": 60,
               "map_threshold": 0.0418
           },
           {
               "name": "ribosome",
               "is_particle": true,
               "pdb_id": "7P6Z",
               "label": 2,
               "color": [0, 255, 0, 255],
               "radius": 150,
               "map_threshold": 0.037
   
           },
           {
               "name": "membrane",
               "is_particle": false,
               "label": 3,
               "color": [0, 0, 0, 255]
           }
       ],
   
       // Change this path to the location of sample_project
       "overlay_root": "local:///PATH/TO/EXTRACTED/PROJECT/",
   
       "overlay_fs_args": {
           "auto_mkdir": true
       }
   }
   

3. Start copick with the configuration file

   from copick.impl.filesystem import CopickRootFSSpec
   root = CopickRootFSSpec.from_file('path/to/filesystem_overlay_only.json')
   

4. Access the data using the copick API

   import zarr
   
   from copick.impl.filesystem import CopickRootFSSpec
   from copick.util.ome import get_level_path
   root = CopickRootFSSpec.from_file('path/to/filesystem_overlay_only.json')
   
   # Get a run by name
   run = root.get_run("TS_001")
   
    # Get a tomogram by name
   tomogram = run.get_voxel_spacing(10).get_tomogram("wbp")
   
   # Access the data
   group = zarr.open(tomogram.zarr(), mode="r")
   
   # Inspect every stored array without assuming numeric names or iteration order
   for path, candidate in group.arrays():
       print(path, candidate.shape)
   
   # Select OME pyramid levels from metadata
   array = group[get_level_path(group, 0)]
   

Contributing

We welcome contributions to copick! Here's how to get started:

Development Setup

1. Clone the repository and install with development dependencies:

   git clone https://github.com/copick/copick.git
   cd copick
   pip install -e ".[dev,test]"
   

2. Install pre-commit hooks:

   pre-commit install
   

3. Run tests to ensure everything is working:

   pytest
   

Code Quality

We use several tools to maintain code quality:

• Black for code formatting
• Ruff for linting and import sorting
• Pre-commit hooks to enforce standards

Before submitting a PR, ensure your code passes all checks:

black src/ tests/
ruff check --fix src/ tests/
pytest

Conventional Commits

All pull requests must use Conventional Commits for commit messages. This helps us automatically generate changelogs and determine version bumps.

Examples:

• feat: add support for new tomogram format
• fix: resolve memory leak in zarr loading
• docs: update installation instructions
• test: add unit tests for mesh operations

Plugin System

Copick supports a plugin system that allows external Python packages to register CLI commands. Commands can be added to the main CLI or organized into groups like inference, training, evaluation, process, and convert.

See the CLI documentation for detailed plugin development instructions and the copick-plugin-demo repository for a complete example.

Code of Conduct

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com.

Reporting Security Issues

If you believe you have found a security issue, please responsibly disclose by contacting us at security@chanzuckerberg.com.