Metadata-Version: 2.4
Name: cryosparc-tools
Version: 5.0.0
Summary: Toolkit for interfacing with CryoSPARC
Author-email: "Structura Biotechnology Inc." <info@structura.bio>
License: Copyright 2025 Structura Biotechnology Inc.
        
        Redistribution and use in source and binary forms, with or without modification,
        are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its contributors
           may be used to endorse or promote products derived from this software without
           specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
        ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
        (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
        ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://tools.cryosparc.com
Project-URL: Documentation, https://tools.cryosparc.com
Project-URL: Repository, https://github.com/cryoem-uoft/cryosparc-tools
Project-URL: Changelog, https://github.com/cryoem-uoft/cryosparc-tools/blob/main/CHANGELOG.md
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C
Classifier: Programming Language :: Python
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0,>=1.17
Requires-Dist: httpx~=0.25
Requires-Dist: pydantic~=2.8
Requires-Dist: typing-extensions>=4.0
Provides-Extra: dev
Requires-Dist: autodocsumm; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: cython; extra == "dev"
Requires-Dist: jupyter-book<2.0; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pyright==1.1.404; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-benchmark; extra == "dev"
Requires-Dist: pytest-xdist[psutil]; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Provides-Extra: build
Requires-Dist: build; extra == "build"
Requires-Dist: autodocsumm; extra == "build"
Requires-Dist: cython; extra == "build"
Requires-Dist: jupyter-book<2.0; extra == "build"
Dynamic: license-file

# cryosparc-tools

[![PyPI](https://badgen.net/pypi/v/cryosparc-tools)](https://pypi.org/project/cryosparc-tools/)
[![Python package](https://github.com/cryoem-uoft/cryosparc-tools/actions/workflows/python-package.yml/badge.svg?branch=main)](https://github.com/cryoem-uoft/cryosparc-tools/actions/workflows/python-package.yml)

Toolkit for interfacing with CryoSPARC. Read the documentation at
[tools.cryosparc.com](https://tools.cryosparc.com)

## Getting Help and Reporting Bugs

For usage questions and general discussion about `cryosparc-tools` scripts and functions, please post to the [CryoSPARC discussion forum](https://discuss.cryosparc.com/c/scripting) under the Scripting category.

If you would like to request or propose a feature, change or fix for `cryosparc-tools` source code, please either [report an issue](https://github.com/cryoem-uoft/cryosparc-tools/issues/new) or [submit a pull request](https://github.com/cryoem-uoft/cryosparc-tools/compare).

See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.

## Development

### Prerequisites

- Git and Git LFS
- Python >= 3.8
- C compiler such as GCC or Clang

### Set Up

1. Clone this repository
   ```sh
   git clone --recursive https://github.com/cryoem-uoft/cryosparc-tools.git
   cd cryosparc-tools
   git lfs pull
   ```
2. (Optional) Create and activate a virtual environment
   ```sh
   python3 -m venv .venv
   source .venv/bin/activate  # macOS / Linux
   # OR
   .venv\Scripts\activate.bat  # Windows
   ```
3. Install dev dependencies and build native modules
   ```sh
   pip install -U pip wheel
   pip install -e ".[dev]"
   ```
4. Install pre-commit hooks
   ```
   pre-commit install
   ```

### Re-compile native module

Recompile native modules after making changes to C code:

```sh
python -m setup build_ext -i
```

## Build Packages for Publishing

Install build dependencies

```sh
pip install -e ".[build]"
```

Run the build

```sh
python -m build
```

Packages for the current architecture and python version are added to the
`dist/` directory.

## Build Documentation

Documentation is located in the `docs` directory and is powered by [Jupyter Book](https://jupyterbook.org/en/stable/intro.html).

To build the docs, install build dependencies

```sh
pip install -e ".[build]"
```

Then run Jupyter Book

```sh
jupyter-book build docs
```

Site will be be built into the `docs/_build/html` directory.

**Note:** Jupyter Book is not configured to re-run example notebooks upon build
since the notebooks require an active CryoSPARC instance to run.

See the [Run Example Notebooks](#run-example-notebooks) section for instructions
on how to run the notebooks.

Inline source documentation is compiled to HTML via [Sphinx](https://www.sphinx-doc.org/en/master/index.html) and uses [Google Style Python docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google).

## Run Example Notebooks

The Jupyter notebooks in the example documentation require additional
dependencies to execute, including the following system configuration:

- Nvidia GPU and driver
- [Miniconda](https://docs.conda.io/en/latest/miniconda.html) or [Miniforge](https://conda-forge.org/download/) installed
- CryoSPARC running at `localhost:40000` or `cryoem0:40000` (can alias `cryoem0` to localhost)

Clean previous build artefacts:

```sh
rm -rf cryosparc/*.so build dist *.egg-info
```

Install dependencies into a new conda environment:

```sh
conda create -n cryosparc-tools-example -c conda-forge python=3 numpy=1.18.5 \
    pyqt=5 libtiff wxPython=4.1.1 adwaita-icon-theme 'setuptools<66'  # exclude these dependencies if you don't need cryolo
conda activate cryosparc-tools-example
pip install cryosparc-tools matplotlib~=3.4.0 pandas~=1.1.0 notebook
pip install 'cryolo[c11]' --extra-index-url https://pypi.ngc.nvidia.com   # optional, only if you want to use cryolo
```

Before you run the notebook server, you may need to set the `LD_LIBRARY_PATH` variable to include the location of CUDA Toolkit and cuDNN runtime libraries. e.g.,

```bash
export LD_LIBRARY_PATH="$HOME/miniconda3/envs/tools/lib/python3.8/site-packages/nvidia/*/lib"
```

Run the notebook server

```
jupyter notebook
```

Find examples in `docs/examples` directory

## License

cryosparc-tools is licensed under the BSD-3-Clause license.
