PyOPIA 2.16.0__tar.gz → 2.16.2__tar.gz

{pyopia-2.16.0 → pyopia-2.16.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyOPIA
-Version: 2.16.0
+Version: 2.16.2
 Summary: A Python Ocean Particle Image Analysis toolbox.
 Project-URL: Repository, https://github.com/sintef/pyopia
 Project-URL: Documentation, https://pyopia.readthedocs.io
@@ -86,6 +86,74 @@ 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`:
+
+```bash
+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
+
+```toml
+[steps.classifier]
+pipeline_class = "pyopia.classify_torch.Classify"
+model_path = "/home/you/models/classifier.pt"
+```
+
+the invocation becomes
+
+```bash
+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:
+
+```bash
+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.
+
+```yaml
+    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`:
+
+```bash
+PYOPIA_CONFIG=my_run.toml docker compose run --rm pyopia
+```
+
 # Documentation:
 
 [![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://pyopia.readthedocs.io) [![Documentation](https://readthedocs.org/projects/pyopia/badge/?version=latest)](https://pyopia.readthedocs.io/en/latest/?badge=latest)

{pyopia-2.16.0 → pyopia-2.16.2}/README.md

@@ -34,6 +34,74 @@ 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`:
+
+```bash
+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
+
+```toml
+[steps.classifier]
+pipeline_class = "pyopia.classify_torch.Classify"
+model_path = "/home/you/models/classifier.pt"
+```
+
+the invocation becomes
+
+```bash
+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:
+
+```bash
+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.
+
+```yaml
+    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`:
+
+```bash
+PYOPIA_CONFIG=my_run.toml docker compose run --rm pyopia
+```
+
 # Documentation:
 
 [![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://pyopia.readthedocs.io) [![Documentation](https://readthedocs.org/projects/pyopia/badge/?version=latest)](https://pyopia.readthedocs.io/en/latest/?badge=latest)

pyopia-2.16.2/pyopia/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.16.2"

{pyopia-2.16.0 → pyopia-2.16.2}/pyopia/instrument/holo.py

@@ -668,7 +668,8 @@ def generate_config(raw_files: str, model_path: str, outfolder: str, output_pref
             'segmentation': {
                 'pipeline_class': 'pyopia.process.Segment',
                 'threshold': 0.9,
-                'segment_source': 'im_focussed'
+                'segment_source': 'im_focussed',
+                'segmentation_method': 'fast'
             },
             'statextract': {
                 'pipeline_class': 'pyopia.process.CalculateStats',

{pyopia-2.16.0 → pyopia-2.16.2}/pyopia/instrument/silcam.py

@@ -341,7 +341,8 @@ def generate_config(raw_files: str, model_path: str, outfolder: str, output_pref
             'segmentation': {
                 'pipeline_class': 'pyopia.process.Segment',
                 'threshold': 0.85,
-                'segment_source': 'im_minimum'
+                'segment_source': 'im_minimum',
+                'segmentation_method': 'fast'
             },
             'statextract': {
                 'pipeline_class': 'pyopia.process.CalculateStats',

{pyopia-2.16.0 → pyopia-2.16.2}/pyopia/instrument/uvp.py

@@ -110,7 +110,8 @@ def generate_config(raw_files: str, model_path: str, outfolder: str, output_pref
             'segmentation': {
                 'pipeline_class': 'pyopia.process.Segment',
                 'threshold': 0.95,
-                'segment_source': 'imraw'
+                'segment_source': 'imraw',
+                'segmentation_method': 'fast'
             },
             'statextract': {
                 'pipeline_class': 'pyopia.process.CalculateStats',

{pyopia-2.16.0 → pyopia-2.16.2}/pyopia/process.py

@@ -376,7 +376,7 @@ def measure_particles(imbw, max_particles=5000):
     return region_properties
 
 
-def segment(img, threshold=0.98, minimum_area=12, fill_holes=True):
+def segment(img, threshold=0.98, minimum_area=12, fill_holes=True, segmentation_method='fast'):
     '''Create a binary image from a background-corrected image.
 
     Parameters
@@ -389,6 +389,9 @@ def segment(img, threshold=0.98, minimum_area=12, fill_holes=True):
         minimum number of pixels to be considered a particle, by default 12
     fill_holes : bool, optional
         runs ndi.binary_fill_holes if True, by default True
+    segmentation_method : str, optional
+        Segmentation function to use. Supports ``'fast'`` and ``'accurate'``.
+        By default ``'fast'``.
 
     Returns
     -------
@@ -397,7 +400,12 @@ def segment(img, threshold=0.98, minimum_area=12, fill_holes=True):
     '''
     logger.info('segment')
 
-    imbw = image2blackwhite_fast(img, threshold)
+    if segmentation_method == 'fast':
+        imbw = image2blackwhite_fast(img, threshold)
+    elif segmentation_method == 'accurate':
+        imbw = image2blackwhite_accurate(img, threshold)
+    else:
+        raise ValueError(f"Unknown segmentation_method '{segmentation_method}'. Supported values are 'fast' and 'accurate'.")
 
     logger.info('clean')
 
@@ -493,6 +501,9 @@ class Segment():
     segment_source: (str, optional)
         The key in Pipeline.data of the image to be segmented.
         Defaults to 'im_corrected'
+    segmentation_method: (str, optional)
+        Segmentation method to use: ``'fast'`` or ``'accurate'``.
+        Defaults to ``'fast'``.
 
     Returns
     -------
@@ -506,16 +517,18 @@ class Segment():
                  minimum_area=12,
                  threshold=0.98,
                  fill_holes=True,
-                 segment_source='im_corrected'):
+                 segment_source='im_corrected',
+                 segmentation_method='fast'):
 
         self.minimum_area = minimum_area
         self.threshold = threshold
         self.fill_holes = fill_holes
         self.segment_source = segment_source
+        self.segmentation_method = segmentation_method
 
     def __call__(self, data):
         data['imbw'] = segment(data[self.segment_source], threshold=self.threshold, fill_holes=self.fill_holes,
-                               minimum_area=self.minimum_area)
+                               minimum_area=self.minimum_area, segmentation_method=self.segmentation_method)
         return data
 
 

pyopia-2.16.2/pyopia/tests/test_process.py

@@ -0,0 +1,64 @@
+import numpy as np
+import pytest
+
+from pyopia.pipeline import Pipeline
+import pyopia.process
+
+
+def test_segment_selects_accurate_method(monkeypatch):
+    img = np.ones((4, 4), dtype=float)
+    call_state = {"fast": 0, "accurate": 0}
+
+    def fake_fast(_img, _threshold):
+        call_state["fast"] += 1
+        return np.zeros_like(_img, dtype=bool)
+
+    def fake_accurate(_img, _threshold):
+        call_state["accurate"] += 1
+        return np.ones_like(_img, dtype=bool)
+
+    monkeypatch.setattr(pyopia.process, "image2blackwhite_fast", fake_fast)
+    monkeypatch.setattr(pyopia.process, "image2blackwhite_accurate", fake_accurate)
+    monkeypatch.setattr(pyopia.process, "clean_bw", lambda imbw, _minimum_area: imbw)
+
+    pyopia.process.segment(img, segmentation_method="accurate")
+
+    assert call_state["fast"] == 0
+    assert call_state["accurate"] == 1
+
+
+def test_segment_raises_on_unknown_method():
+    img = np.ones((4, 4), dtype=float)
+
+    with pytest.raises(ValueError, match="Unknown segmentation_method"):
+        pyopia.process.segment(img, segmentation_method="unknown")
+
+
+def test_pipeline_segmentation_step_accepts_segmentation_method_config(monkeypatch):
+    captured = {}
+
+    def fake_segment(img, threshold, minimum_area, fill_holes, segmentation_method):
+        captured["segmentation_method"] = segmentation_method
+        return np.zeros_like(img, dtype=bool)
+
+    monkeypatch.setattr(pyopia.process, "segment", fake_segment)
+
+    config = {
+        "general": {"raw_files": []},
+        "steps": {
+            "segmentation": {
+                "pipeline_class": "pyopia.process.Segment",
+                "threshold": 0.9,
+                "minimum_area": 5,
+                "fill_holes": True,
+                "segment_source": "im_corrected",
+                "segmentation_method": "accurate",
+            }
+        },
+    }
+
+    pipeline = Pipeline(config, initial_steps=[])
+    pipeline.data["im_corrected"] = np.ones((4, 4), dtype=float)
+    pipeline.run_step("segmentation")
+
+    assert captured["segmentation_method"] == "accurate"

pyopia-2.16.0/pyopia/__init__.py

@@ -1 +0,0 @@
-__version__ = "2.16.0"