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.

• 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!

For more information, see the documentation.

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]"

An example dataset can be obtained from Zenodo.

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
   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())
   arrays = list(group.arrays())
   _, array = arrays[0]

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

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

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

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

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.

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

If you believe you have found a security issue, please responsibly disclose by contacting us at [email protected].