PyOPIA 1.1.12__tar.gz → 2.0.0__tar.gz

{pyopia-1.1.12 → pyopia-2.0.0}/PKG-INFO

@@ -1,20 +1,21 @@
 Metadata-Version: 2.1
 Name: PyOPIA
-Version: 1.1.12
+Version: 2.0.0
 Summary: A Python Ocean Particle Image Analysis toolbox.
 Home-page: https://github.com/sintef/pyopia
 Keywords: Ocean,Particles,Imaging,Measurement,Size distribution
 Author: Emlyn Davies
 Author-email: emlyn.davies@sintef.no
-Requires-Python: >=3.10,<3.11
+Requires-Python: >=3.12,<4.0
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
 Provides-Extra: classification
 Provides-Extra: classification-arm64
 Requires-Dist: cmocean (>=3.0.3,<4.0.0)
 Requires-Dist: dask (>=2024.8.1)
 Requires-Dist: flake8 (>=6.1.0,<7.0.0)
 Requires-Dist: gdown (>=4.7.1,<5.0.0)
+Requires-Dist: h5netcdf (>=1.3.0)
 Requires-Dist: h5py (>=3.9.0,<4.0.0)
 Requires-Dist: imageio (>=2.31.3,<3.0.0)
 Requires-Dist: ipykernel (>=6.19.4)
@@ -22,6 +23,7 @@ Requires-Dist: jupyter-book (>=0.15.1,<0.16.0)
 Requires-Dist: matplotlib (>=3.7)
 Requires-Dist: myst-nb (>=0.17.2,<0.18.0)
 Requires-Dist: nbclient (==0.7)
+Requires-Dist: nbconvert (>=7.16.4,<8.0.0)
 Requires-Dist: numpy (>=1.24.0,<2.0.0)
 Requires-Dist: pandas[computation] (>=2.1.1,<3.0.0)
 Requires-Dist: poetry-version-plugin (>=0.2.0,<0.3.0)
@@ -35,9 +37,8 @@ Requires-Dist: sphinx-copybutton (>=0.5.2,<0.6.0)
 Requires-Dist: sphinx-rtd-theme (>=0.5.0)
 Requires-Dist: sphinx-togglebutton (>=0.3.2,<0.4.0)
 Requires-Dist: sphinxcontrib-napoleon (>=0.7)
-Requires-Dist: tensorflow-cpu (==2.11.0) ; extra == "classification"
-Requires-Dist: tensorflow-io-gcs-filesystem (>=0.31.0) ; extra == "classification-arm64" or extra == "classification"
-Requires-Dist: tensorflow-macos (==2.11.0) ; (sys_platform == "darwin" and platform_machine == "arm64") and (extra == "classification-arm64")
+Requires-Dist: tensorflow-cpu (>=2.16.2,<3.0.0) ; extra == "classification"
+Requires-Dist: tensorflow-macos (>=2.16.2,<3.0.0) ; (sys_platform == "darwin" and platform_machine == "arm64") and (extra == "classification-arm64")
 Requires-Dist: toml (>=0.10.2,<0.11.0)
 Requires-Dist: tqdm (>=4.66.1,<5.0.0)
 Requires-Dist: typer[all] (>=0.9.0,<0.10.0)
@@ -143,12 +144,23 @@ or for arm/silicon systems:
 poetry install --extras "classification-arm64"
 ```
 
+Note: If poetry spends ages resolving dependencies, you can install a development environment with pip, like this: `pip install -e ".[classification]"` or for arm/silicon: `pip install -e ".[classification-arm64]"`
+
+
 3. (optional) Run local tests:
 
 ```bash
 poetry 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
 
 ```

{pyopia-1.1.12 → pyopia-2.0.0}/README.md

@@ -94,12 +94,23 @@ or for arm/silicon systems:
 poetry install --extras "classification-arm64"
 ```
 
+Note: If poetry spends ages resolving dependencies, you can install a development environment with pip, like this: `pip install -e ".[classification]"` or for arm/silicon: `pip install -e ".[classification-arm64]"`
+
+
 3. (optional) Run local tests:
 
 ```bash
 poetry 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
 
 ```

pyopia-2.0.0/pyopia/__init__.py

@@ -0,0 +1 @@
+__version__ = '2.0.0'

{pyopia-1.1.12 → pyopia-2.0.0}/pyopia/background.py

@@ -1,10 +1,7 @@
 '''
 Background correction module (inherited from PySilCam)
 '''
-
 import numpy as np
-from glob import glob
-from pyopia.pipeline import get_load_function
 
 
 def ini_background(bgfiles, load_function):
@@ -86,19 +83,21 @@ def correct_im_accurate(imbg, imraw):
     highlights if the background or raw images are very poorly obtained
 
     Args:
-      imbg (uint8 or float64)  : background averaged image
-      imraw (uint8 or float64) : raw image
+      imbg (float64)  : background averaged image
+      imraw (float64) : raw image
+      imbg (float64)  : background averaged image
+      imraw (float64) : raw image
 
     Returns:
-      imc (uint8 or float64)   : corrected image, same type as input
+      im_corrected (float64)   : corrected image, same type as input
     '''
 
-    imc = np.float64(imraw) - np.float64(imbg)
-    imc += (255 / 2 - np.percentile(imc, 50))
+    im_corrected = imraw - imbg
+    im_corrected += (1 / 2 - np.percentile(im_corrected, 50))
 
-    imc += 255 - imc.max()
+    im_corrected += 1 - im_corrected.max()
 
-    return imc
+    return im_corrected
 
 
 def correct_im_fast(imbg, imraw):
@@ -110,20 +109,18 @@ def correct_im_fast(imbg, imraw):
     highlights, especially if the background or raw images are not properly obtained
 
     Args:
-      imbg (uint8)  : background averaged image
-      imraw (uint8) : raw image
+      imraw (float64) : raw image
+      imbg (float64)  : background averaged image
 
     Returns:
-      imc (uint8)   : corrected image
+      im_corrected (float64)   : corrected image
     '''
-    imc = imraw - imbg
+    im_corrected = imraw - imbg
 
-    imc += 215
-    imc[imc < 0] = 0
-    imc[imc > 255] = 255
-    imc = np.uint8(imc)
+    im_corrected += 215/255
+    im_corrected = np.clip(im_corrected, 0, 1)
 
-    return imc
+    return im_corrected
 
 
 def shift_and_correct(bgstack, imbg, imraw, stacklength, real_time_stats=False):
@@ -135,162 +132,26 @@ def shift_and_correct(bgstack, imbg, imraw, stacklength, real_time_stats=False):
 
     Args:
         bgstack (list)                  : list of all images in the background stack
-        imbg (uint8)                    : background image
-        imraw (uint8)                   : raw image
+        imbg (float64)                  : background image
+        imraw (float64)                 : raw image
         stacklength (int)               : unsed int here - just there to maintain the same behaviour as
                                           shift_bgstack_fast()
         real_time_stats=False (Bool)    : if True use fast functions, if False use accurate functions
 
     Returns:
         bgstack (list)                  : list of all images in the background stack
-        imbg (uint8)                    : background averaged image
-        imc (uint8)                     : corrected image
+        imbg (float64)                  : background averaged image
+        im_corrected (float64)          : corrected image
     '''
 
     if real_time_stats:
-        imc = correct_im_fast(imbg, imraw)
+        im_corrected = correct_im_fast(imbg, imraw)
         bgstack, imbg = shift_bgstack_fast(bgstack, imbg, imraw, stacklength)
     else:
-        imc = correct_im_accurate(imbg, imraw)
+        im_corrected = correct_im_accurate(imbg, imraw)
         bgstack, imbg = shift_bgstack_accurate(bgstack, imbg, imraw, stacklength)
 
-    return bgstack, imbg, imc
-
-
-def backgrounder(av_window, acquire, bad_lighting_limit=None,
-                 real_time_stats=False):
-    '''
-    Generator which interacts with acquire to return a corrected image
-    given av_window number of frame to use in creating a moving background
-
-    Args:
-        av_window (int)               : number of images to use in creating the background
-        acquire (generator object)    : acquire generator object created by the Acquire class
-        bad_lighting_limit=None (int) : if a number is supplied it is used for throwing away raw images that have a
-                                        standard deviation in colour which exceeds the given value
-
-    Yields:
-        timestamp (timestamp)         : timestamp of when raw image was acquired
-        imc (uint8)                   : corrected image ready for analysis or plotting
-        imraw (uint8)                 : raw image
-
-    Example:
-
-    .. code-block:: python
-
-        avwind = 10 # number of images used for background
-        imgen = backgrounder(avwind,acquire,bad_lighting_limit) # setup generator
-
-        n = 10 # acquire 10 images and correct them with a sliding background:
-        for i in range(n):
-            imc = next(imgen)
-            print(i)
-    '''
-
-    # Set up initial background image stack
-    bgstack, imbg = ini_background(av_window, acquire)
-    stacklength = len(bgstack)
-
-    # Aquire images, apply background correction and yield result
-    for timestamp, imraw in acquire:
-
-        if bad_lighting_limit is not None:
-            bgstack_new, imbg_new, imc = shift_and_correct(bgstack, imbg,
-                                                           imraw, stacklength, real_time_stats)
-
-            # basic check of image quality
-            r = imc[:, :, 0]
-            g = imc[:, :, 1]
-            b = imc[:, :, 2]
-            s = np.std([r, g, b])
-            # ignore bad images
-            if s <= bad_lighting_limit:
-                bgstack = bgstack_new
-                imbg = imbg_new
-                yield timestamp, imc, imraw
-            else:
-                print('bad lighting, std={0}'.format(s))
-        else:
-            bgstack, imbg, imc = shift_and_correct(bgstack, imbg, imraw,
-                                                   stacklength, real_time_stats)
-            yield timestamp, imc, imraw
-
-
-def subtract_background(imbg, imraw):
-    ''' simple background substraction
-
-    Returns
-    -------
-    np.array : image
-        image corrected by simple subtraction (imraw - imbw)
-    '''
-    return imraw - imbg
-
-
-class CreateBackground():
-    '''
-    :class:`pyopia.pipeline` compatible class that calls: :func:`pyopia.background.ini_background`.
-    This runs by default in the pipeline initial steps if named as 'createbackground'.
-
-    Pipeline input data:
-    --------------------
-    :class:`pyopia.pipeline.Data`
-
-        containing the following keys:
-
-        :attr:`pyopia.pipeline.Data.raw_files`
-
-        :attr:`pyopia.pipeline.Data.imc`
-
-        :attr:`pyopia.pipeline.Data.bgstack`
-
-        :attr:`pyopia.pipeline.Data.imraw`
-
-        :attr:`pyopia.pipeline.Data.imbg`
-
-    Parameters:
-    -----------
-    average_window : int
-        number of images to use in the background image stack
-
-    instrument_module: (str, optional)
-        Defaults to 'imread' if not defined
-        Other alternatives are: 'holo' or 'silcam' if you want to use the `load_image`functions
-        implemented within the {mod}`pyopia.instrument` submodule.
-
-    Returns:
-    --------
-    :class:`pyopia.pipeline.Data`
-        containing the following new keys:
-
-        :attr:`pyopia.pipeline.Data.bgstack`
-
-        :attr:`pyopia.pipeline.Data.imbg`
-
-    Example pipeline uses:
-    ----------------------
-
-    .. code-block:: python
-
-        [steps.createbackground]
-        pipeline_class = 'pyopia.background.CreateBackground'
-        average_window = 10
-        instrument_module = 'holo'
-    '''
-
-    def __init__(self, average_window, instrument_module='imread'):
-        self.average_window = average_window
-        self.load_function = get_load_function(instrument_module)
-        pass
-
-    def __call__(self, data):
-        files = glob(data['raw_files'])
-        bgfiles = files[:self.average_window]
-        bgstack, imbg = ini_background(bgfiles, self.load_function)
-
-        data['bgstack'] = bgstack
-        data['imbg'] = imbg
-        return data
+    return bgstack, imbg, im_corrected
 
 
 class CorrectBackgroundAccurate():
@@ -298,18 +159,18 @@ class CorrectBackgroundAccurate():
     :class:`pyopia.pipeline` compatible class that calls: :func:`pyopia.background.correct_im_accurate`
     and will shift the background using a moving average function if given.
 
+    The background stack and background image are created during the first 'average_window' (int) calls
+    to this class, and the skip_next_steps flag is set in the pipeline Data. No background correction
+    is performed during these steps.
+
     Pipeline input data:
     --------------------
     :class:`pyopia.pipeline.Data`
 
         containing the following keys:
 
-        :attr:`pyopia.pipeline.Data.bgstack`
-
         :attr:`pyopia.pipeline.Data.imraw`
 
-        :attr:`pyopia.pipeline.Data.imbg`
-
     Parameters:
     -----------
     bgshift_function : (string, optional)
@@ -320,18 +181,25 @@ class CorrectBackgroundAccurate():
 
         :func:`pyopia.background.shift_bgstack_fast`
 
+    average_window : int
+        number of images to use in the background image stack
+
+    image_source: (str, optional)
+        The key in Pipeline.data of the image to be background corrected.
+        Defaults to 'imraw'
+
     Returns:
     --------
     :class:`pyopia.pipeline.Data`
         containing the following new keys:
 
-        :attr:`pyopia.pipeline.Data.imc`
+        :attr:`pyopia.pipeline.Data.im_corrected`
+        :attr:`pyopia.pipeline.Data.im_corrected`
 
         :attr:`pyopia.pipeline.Data.bgstack`
 
         :attr:`pyopia.pipeline.Data.imbg`
 
-
     Example pipeline uses:
     ----------------------
     Apply moving average using :func:`pyopia.background.shift_bgstack_accurate` :
@@ -341,6 +209,7 @@ class CorrectBackgroundAccurate():
         [steps.correctbackground]
         pipeline_class = 'pyopia.background.CorrectBackgroundAccurate'
         bgshift_function = 'accurate'
+        average_window = 5
 
     Apply static background correction:
 
@@ -349,18 +218,42 @@ class CorrectBackgroundAccurate():
         [steps.correctbackground]
         pipeline_class = 'pyopia.background.CorrectBackgroundAccurate'
         bgshift_function = 'pass'
-
+        average_window = 5
 
     If you do not want to do background correction, leave this step out of the pipeline.
     Then you could use :class:`pyopia.pipeline.CorrectBackgroundNone` if you need to instead.
     '''
 
-    def __init__(self, bgshift_function='pass'):
+    def __init__(self, bgshift_function='pass', average_window=1, image_source='imraw'):
         self.bgshift_function = bgshift_function
-        pass
+        self.average_window = average_window
+        self.image_source = image_source
+
+    def _build_background_step(self, data):
+        '''Add one layer to the background stack from the raw image in data pipeline, and update the background image.'''
+        if 'bgstack' not in data:
+            data['bgstack'] = []
+
+        init_complete = True
+        if len(data['bgstack']) < self.average_window:
+            data['bgstack'].append(data[self.image_source])
+            data['imbg'] = np.mean(data['bgstack'], axis=0)
+            init_complete = False
+
+        return init_complete
 
     def __call__(self, data):
-        data['imc'] = correct_im_accurate(data['imbg'], data['imraw'])
+        # Initialize the background while required bgstack size not reached
+        init_complete = self._build_background_step(data)
+
+        # If we are still building the bgstack, return without doing image correction and bgstack update
+        if not init_complete:
+            # Flag to the pipeline that remaining steps should be skipped since we are still building the background
+            data['skip_next_steps'] = True
+            return data
+
+        data['im_corrected'] = correct_im_accurate(data['imbg'], data[self.image_source])
+        data['im_corrected'] = correct_im_accurate(data['imbg'], data[self.image_source])
 
         match self.bgshift_function:
             case 'pass':
@@ -368,18 +261,19 @@ class CorrectBackgroundAccurate():
             case 'accurate':
                 data['bgstack'], data['imbg'] = shift_bgstack_accurate(data['bgstack'],
                                                                        data['imbg'],
-                                                                       data['imraw'])
+                                                                       data[self.image_source])
             case 'fast':
                 data['bgstack'], data['imbg'] = shift_bgstack_fast(data['bgstack'],
                                                                    data['imbg'],
-                                                                   data['imraw'])
+                                                                   data[self.image_source])
         return data
 
 
 class CorrectBackgroundNone():
     '''
     :class:`pyopia.pipeline` compatible class for use when no background correction is required.
-    This simply makes `data['imc'] = data['imraw'] in the pipeline.
+    This simply makes `data['im_corrected'] = data['imraw'] in the pipeline.
+    This simply makes `data['im_corrected'] = data['imraw'] in the pipeline.
 
     Pipeline input data:
     --------------------
@@ -398,7 +292,7 @@ class CorrectBackgroundNone():
     :class:`pyopia.pipeline.Data`
         containing the following new keys:
 
-        :attr:`pyopia.pipeline.Data.imc`
+        :attr:`pyopia.pipeline.Data.im_corrected`
 
 
     Example pipeline uses:
@@ -416,6 +310,6 @@ class CorrectBackgroundNone():
         pass
 
     def __call__(self, data):
-        data['imc'] = data['imraw']
+        data['im_corrected'] = data['imraw']
 
         return data

pyopia-2.0.0/pyopia/classify.py

@@ -0,0 +1,182 @@
+'''
+Module containing tools for classifying particle ROIs
+'''
+
+import os
+import numpy as np
+import pandas as pd
+
+import logging
+logger = logging.getLogger()
+
+# import tensorflow here. It must be imported on the processor where it will be used!
+# import is therefore here instead of at the top of file.
+# consider # noqa: E(?) for flake8 / linting
+try:
+    from tensorflow import keras
+    import tensorflow as tf
+except ImportError:
+    info_str = 'ERROR: Could not import Keras. Classify will not work'
+    info_str += ' until you install tensorflow.\n'
+    info_str += 'Use: pip install pyopia[classification]\n'
+    info_str += ' or: pip install pyopia[classification-arm64]'
+    info_str += ' for tensorflow-macos (silicon chips)'
+    raise ImportError(info_str)
+
+
+class Classify():
+    '''
+    A classifier class for PyOPIA workflow.
+    This is intended as a parent class that can be used as a template for flexible classification methods
+
+    Args:
+        model_path=model_path (str)        : path to particle-classifier e.g.
+                                '/testdata/model_name/particle_classifier.h5'
+
+    Example:
+
+    .. code-block:: python
+
+        cl = Classify(model_path='/testdata/model_name/particle_classifier.h5')
+
+        prediction = cl.proc_predict(roi) # roi is an image roi to be classified
+
+    Note that :meth:`Classify.load_model()`
+    is run when the :class:`Classify` class is initialised.
+    If this is used in combination with multiprocessing then the model must be loaded
+    on the process where it will be used and not passed between processers
+    (i.e. cl must be initialised on that process).
+
+    The config setup looks like this:
+
+    .. code-block:: python
+
+        [steps.classifier]
+        pipeline_class = 'pyopia.classify.Classify'
+        model_path = 'keras_model.h5' # path to trained nn model
+
+    If `[steps.classifier]`is not defined, the classification will be skipped and no probabilities reported.
+
+    If you want to use an example trained model for SilCam data
+    (no guarantee of accuracy for other applications), you can get it using `exampledata`
+    within the notebooks folder (https://github.com/SINTEF/pyopia/blob/main/notebooks/exampledata.py):
+
+    .. code-block:: python
+
+        model_path = exampledata.get_example_model()
+
+    '''
+    def __init__(self, model_path=None):
+        self.model_path = model_path
+        self.load_model()
+
+        # Enable this to perform whitebalance correction in the preprocessing step
+        self.correct_whitebalance = False
+
+    def __call__(self):
+        return self
+
+    def load_model(self):
+        '''
+        Load a trained Keras model into the Classify class.
+
+        self.model (tf model object) : loaded Keras model
+        self.class_names (list) : names for the model output classes
+        '''
+        model_path = self.model_path
+
+        os.environ['TF_CPP_MIN_LOG_LEVEL'] = '2'
+        keras.backend.clear_session()
+
+        # Instantiate Keras model from file
+        path, filename = os.path.split(model_path)
+        self.model = keras.models.load_model(model_path)
+
+        # Try to create model output class name list from last model layer name
+        class_labels = None
+        try:
+            class_labels = self.model.layers[-1].name.split('.')
+        except:  # noqa E722
+            logger.info('Could not get class names from model layer name, reverting to old method with header file.')
+
+        # If we could not create correct class names above, revert to old header file method
+        expected_class_number = self.model.layers[-1].output.shape[1]
+        if class_labels is None or len(class_labels) != expected_class_number:
+            header = pd.read_csv(os.path.join(path, 'header.tfl.txt'))
+            class_labels = header.columns
+
+        self.class_labels = class_labels
+        logger.info(self.class_labels)
+
+    def preprocessing(self, img_input):
+        '''
+        Preprocess ROI ready for prediction. example here based on the pysilcam network setup
+
+        Args:
+            img_input (float)        : a particle ROI before preprocessing with range 0-1
+
+        Returns:
+            img_preprocessed (float) : a particle ROI with range 0.-255., corrected and preprocessed, ready for prediction
+        '''
+
+        whitebalanced = np.copy(img_input).astype(np.float64)
+
+        # Do white-balance correction as a per-channel histogram shift
+        if self.correct_whitebalance:
+            p = 99
+            for c in range(3):
+                whitebalanced[:, :, c] += (p/100) - np.percentile(whitebalanced[:, :, c], p)
+            whitebalanced[whitebalanced > 1] = 1
+            whitebalanced[whitebalanced < 0] = 0
+
+        # convert back to 0-255 scaling (because of this layer in the network:
+        # layers.Rescaling(1./255, input_shape=(img_height, img_width, 3)))
+        # This is useful because it allows training to use tf.keras.utils.image_dataset_from_directory,
+        # which loads images in 0-255 range
+        img = keras.utils.img_to_array(whitebalanced * 255)
+
+        # Get config for image resizing from the model
+        _, img_height, img_width, _ = self.model.get_config()['layers'][0]['config']['batch_shape']
+        pad_to_aspect_ratio = getattr(self.model.layers[0], 'pad_to_aspect_ratio', False)
+
+        # resize to match the dimentions expected by the network
+        img = tf.image.resize(img, [img_height, img_width],
+                              method=tf.image.ResizeMethod.BILINEAR,
+                              preserve_aspect_ratio=pad_to_aspect_ratio)
+
+        img_array = tf.keras.utils.img_to_array(img)
+        img_preprocessed = tf.expand_dims(img_array, 0)  # Create a batch
+        return img_preprocessed
+
+    @tf.function
+    def predict(self, img_preprocessed):
+        '''
+        Use tensorflow model to classify particles. example here based on the pysilcam network setup.
+
+        Args:
+            img_preprocessed (float) : a particle ROI arry, corrected and preprocessed using :meth:`Classify.preprocessing`,
+                                       ready for prediction using :meth:`Classify.predict`
+
+        Returns:
+            prediction (array)       : the probability of the roi belonging to each class
+        '''
+
+        prediction = self.model(img_preprocessed, training=False)
+        prediction = tf.nn.softmax(prediction[0])
+        return prediction
+
+    def proc_predict(self, img_input):
+        '''
+        Run pre-processing (:meth:`Classify.preprocessing`) and prediction (:meth:`Classify.predict`)
+        using tensorflow model to classify particles. example here based on the pysilcam network setup.
+
+        Args:
+            img_input (float)  : a particle ROI with range 0-1 before preprocessing
+
+        Returns:
+            prediction (array) : the probability of the roi belonging to each class
+        '''
+        img_preprocessed = self.preprocessing(img_input)
+        prediction = self.predict(img_preprocessed)
+
+        return prediction