PyOPIA
A Python Ocean Particle Image Analysis toolbox
Quick tryout of PyOPIA
- Install uv
- Initialize PyOPIA project with a small example image dataset and run processing
uvx --python 3.12 --from pyopia[classification] pyopia init-project pyopiatest --example-data
cd pyopiatest
uvx --python 3.12 --from pyopia[classification] pyopia process config.toml
- Inspect the processed particle statistics in the processed/ folder
- Merge the individual processed image STATS files into a single STATS.nc file, then create a montage of the processed STATS.nc
uvx --python 3.12 --from pyopia[classification] pyopia merge-mfdata processed
uvx --python 3.12 --from pyopia[classification] pyopia make-montage processed\pyopiatest-STATS.nc
- Visualise the monatge of all processed singular particle images in one
montage.png
Will show you a montage of all the processed particle images in one.
See the documentation for more information on how to install and use PyOPIA.
Running with Docker
A prebuilt container image is published to GitHub Container Registry on every release, for users who prefer not to install PyOPIA's dependencies directly.
One-off invocation
From any directory that contains a config.toml:
docker run --rm \
--user $(id -u):$(id -g) \
-v "$PWD:$PWD" -w "$PWD" \
ghcr.io/sintef/pyopia:latest \
process config.toml
The 1:1 volume mount (-v "$PWD:$PWD") makes the container see your current directory at the same path as the host, so an existing config.toml with absolute paths under $PWD works unchanged.
If your config references paths outside $PWD — most commonly a classifier weights file — add a matching bind mount for each of them.
The target (right of the colon) must equal the source (left) so the path in the config resolves unchanged.
For a config like
[steps.classifier]
pipeline_class = "pyopia.classify_torch.Classify"
model_path = "/home/you/models/classifier.pt"
the invocation becomes
docker run --rm \
--user $(id -u):$(id -g) \
-v "$PWD:$PWD" -w "$PWD" \
-v /home/you/models:/home/you/models:ro \
ghcr.io/sintef/pyopia:latest \
process config.toml
Any PyOPIA CLI command works, e.g. docker run --rm ghcr.io/sintef/pyopia:latest --help.
Using docker compose
Each GitHub release attaches a compose.yaml as an asset.
Download it once per project:
curl -LO https://github.com/SINTEF/pyopia/releases/latest/download/compose.yaml
docker compose run --rm pyopia # runs `pyopia process config.toml`
docker compose run --rm pyopia --help # or any other CLI argument
The compose file has commented-out stubs for paths that live outside $PWD — in particular the classifier weights file.
Edit compose.yaml to uncomment the line and point it at your actual host path, e.g.
volumes:
- ${PWD}:${PWD}
- /home/you/models:/home/you/models:ro # classifier weights
The target must match the source so the config-referenced path resolves unchanged.
Override the default config filename with PYOPIA_CONFIG:
PYOPIA_CONFIG=my_run.toml docker compose run --rm pyopia
Documentation:
Current status:
- Under development. See/regester issues, here
Development targets for PyOpia:
- Allow nonfamiliar users to install and use PyOpia, and to contribute & commit code changes
- Not hardware specific
- Smaller dependency list than PySilCam -Eventual optional dependencies (e.g. for classification)
- Can be imported by pysilcam or other hardware-specific tools
- Work on a single-image basis (...primarily, with options for multiprocess to be considered later)
- No use of settings/config files within the core code - pass arguments directly. Eventual use of settings/config files should be handled by high-level wrappers that provide arguments to functions.
- Github workflows
- Tests
Normal functions within PyOpia should:
- take inputs
- return new outputs
- don't modify state of input
- minimum possible disc IO during processing
Contributions
We welcome additions and improvements to the code! We request that you follow a few guidelines. These are in place to make sure the code improves over time.
- All code changes must be submitted as pull requests, either from a branch or a fork.
- Good documentation of the code is needed for PyOpia to succeed and so please include up-to-date docstrings as you make changes, so that the auto-build on readthedocs is complete and useful for users. (A version of the new docs will complie when you make a pull request and a link to this can be found in the pull request checks)
- All pull requests are required to pass all tests before merging. Please do not disable or remove tests just to make your branch pass the pull request.
- All pull requests must be reviewed by a person. The benefits from code review are plenty, but we like to emphasise that code reviews help spreading the awarenes of code changes. Please note that code reviews should be a pleasant experience, so be plesant, polite and remember that there is a human being with good intentions on the other side of the screen.
- All contributions are linted with flake8. We recommend that you run flake8 on your code while developing to fix any issues as you go. We recommend using autopep8 to autoformat your Python code (but please check the code behaviour is not affected by autoformatting before pushing). This makes flake8 happy, and makes it easier for us all to maintain a consistent and readable code base.
Docstrings
Use the NumPy style in docstrings. See style guide here
Installing
For users
Users are expected to be familiar with Python. Please refer to the recommended installation instructions provided on the documentation pages, here
For developers from source
Install (uv)[https://docs.astral.sh/uv/getting-started/installation/]
- Navigate to the folder where you want to install pyopia using the 'cd' command.
If you use git: Download repository from github, and move into the new directory:
git clone https://github.com/SINTEF/pyopia.git
cd pyopia
For the next steps, you need to be located in the PyOPIA root directory that contains the file 'pyproject.toml'.
- Install all requirements with
uv sync --all-extras
- (optional) Run local tests:
uv run pytest
Version numbering
The version number of PyOPIA is split into three sections: MAJOR.MINOR.PATCH
- MAJOR: Changes in high-level pipeline use and/or data output that are not backwards-compatible.
- MINOR: New features that are backwards-compatible.
- PATCH: Backwards-compatible bug fixes or enhancements to existing functionality
Build docs locally
sphinx-apidoc -f -o docs/source docs/build --separate
sphinx-build -b html ./docs/ ./docs/build
License
PyOpia is licensed under the BSD3 license. See LICENSE. All contributors should be recognised & aknowledged.
1 maintainer
Release files for PyOPIA 2.16.13
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pyopia-2.16.13.tar.gz | 79.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pyopia-2.16.13-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 173.6 kB
Release files / pyopia-2.16.13.tar.gz
| Download URL | pyopia-2.16.13.tar.gz |
|---|---|
| Size | 79.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9c1f6dcd3a18236df3552981251d1719719b76169c8b514b8a1166202b23d6fa
|
|
BLAKE2b-256 checksum How to use checksums |
cfad4913914bf3ee66f2ac653e9696ac29664c6d8c81316f5e0c670cedfcd508
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Jul 30, 2026.
Transparency logRelease files / pyopia-2.16.13-py3-none-any.whl
| Download URL | pyopia-2.16.13-py3-none-any.whl |
|---|---|
| Size | 93.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4ed0390fbf6e05264a2a30c9c3620a7411b77e54691004a8a7758c1faf2274f7
|
|
BLAKE2b-256 checksum How to use checksums |
238aaca0160ac91cc163b14cb6bc771fa73c0d016ef5c16762148bcda869dee7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Jul 30, 2026.
Transparency log
