dcnum 0.17.1__tar.gz → 0.18.0__tar.gz

{dcnum-0.17.1 → dcnum-0.18.0}/.github/workflows/check.yml

@@ -29,6 +29,8 @@ jobs:
         python -m pip install coverage flake8 pytest
     - name: Install dcnum
       run: |
+        # https://github.com/luispedro/mahotas/issues/144
+        pip install mahotas==1.4.13
         pip install -e .
     - name: List installed packages
       run: |

{dcnum-0.17.1 → dcnum-0.18.0}/CHANGELOG

@@ -1,3 +1,34 @@
+0.18.0
+ - BREAKING CHANGE: mask postprocessing did a morphological opening instead
+   of a morphological closing, failing to remove spurious noise
+ - BREAKING CHANGE: perform first fill_holes and then closing_disk in mask
+   postprocessing
+ - feat: allow to specify ranges when creating an HDF5Data instance to
+   enable e.g. processing only a portion of an input file
+ - feat: volume computation via contour revolve algorithm
+ - feat: background offset (flickering) correction via the
+   "offset_correction" keyword for the "sparsemed" background computer
+   and "bg_off" everywhere else
+ - enh: allow creating HDF5Writer from h5py.File
+ - fix: mask postprocessing did a morphological opening instead
+   of a morphological closing, failing to remove spurious noise
+ - fix: remove mask ppid part for segmenters that do not use it
+ - fix: mask postprocessing with "fill_holes" using `cv2.floodFill`
+   sometimes segmented the entire frame if the upper left pixel was not
+   set to background
+ - enh: perform first fill_holes and then closing_disk in mask
+   postprocessing
+ - enh: pop read-cache items before adding a new one
+ - enh: allow to request the raw contour from `moments_based_features`
+ - ref: increment DCNUM_PPID_GENERATION to 8
+ - ref: added new super class `BaseImageChunkCache`
+ - ref: use HDF5Writer in Background class
+ - ref: minor cleanup
+ - ref: rename submodule `feat_moments` to `feat_contour`
+ - ref: remove unused `name` property from `Background` class
+0.17.2
+ - fix: make sure unsupported features are not propagated in
+   `concatenated_hdf5_data` (#27)
 0.17.1
  - ref: remove "bg_med" and "index_online" from protected scalar features,
    because "bg_med" may change due to a different background computation
@@ -8,7 +39,8 @@
  - ref: remove deprecated `preselect` and `ptp_median` keyword
    arguments from `QueueEventExtractor`
  - ref: remove deprecated "key" from `get_class_method_info` info dict
- - ref: issue UserWarning instead of DeprecationWarning when
+ - ref: issue UserWarning instead of DeprecationWarning when checking
+   segmenter keyword arguments
  - ref: remove pixel size check for HDF5 data
  - ref: remove unused `_get_model_file` from GPUSegmenter
 0.16.8

{dcnum-0.17.1 → dcnum-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dcnum
-Version: 0.17.1
+Version: 0.18.0
 Summary: numerics toolbox for imaging deformability cytometry
 Author: Maximilian Schlögel, Paul Müller
 Maintainer-email: Paul Müller <dev@craban.de>

{dcnum-0.17.1 → dcnum-0.18.0}/src/dcnum/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.17.1'
-__version_tuple__ = version_tuple = (0, 17, 1)
+__version__ = version = '0.18.0'
+__version_tuple__ = version_tuple = (0, 18, 0)

{dcnum-0.17.1 → dcnum-0.18.0}/src/dcnum/feat/__init__.py

@@ -1,6 +1,6 @@
 # flake8: noqa: F401
 """Feature computation"""
-from . import feat_background, feat_brightness, feat_moments, feat_texture
+from . import feat_background, feat_brightness, feat_contour, feat_texture
 from .event_extractor_manager_thread import EventExtractorManagerThread
 from .queue_event_extractor import (
     QueueEventExtractor, EventExtractorThread, EventExtractorProcess

{dcnum-0.17.1 → dcnum-0.18.0}/src/dcnum/feat/feat_background/base.py

@@ -3,14 +3,12 @@ import functools
 import inspect
 import multiprocessing as mp
 import pathlib
-import uuid
 
 import h5py
-import numpy as np
 
 from ...meta import ppid
 from ...read import HDF5Data
-from ...write import create_with_basins, set_default_filter_kwargs
+from ...write import HDF5Writer, create_with_basins, set_default_filter_kwargs
 
 
 # All subprocesses should use 'spawn' to avoid issues with threads
@@ -93,8 +91,6 @@ class Background(abc.ABC):
         else:
             self.input_data = input_data
 
-        #: unique identifier
-        self.name = str(uuid.uuid4())
         #: shape of event images
         self.image_shape = self.input_data[0].shape
         #: total number of events
@@ -109,25 +105,17 @@ class Background(abc.ABC):
             # "a", because output file already exists
             self.h5out = h5py.File(output_path, "a", libver="latest")
 
-        # Initialize background data
-        ds_kwargs = set_default_filter_kwargs(compression=compress)
-        h5bg = self.h5out.require_dataset(
-            "events/image_bg",
-            shape=self.input_data.shape,
-            dtype=np.uint8,
-            chunks=(min(100, self.image_count),
-                    self.image_shape[0],
-                    self.image_shape[1]),
-            **ds_kwargs,
+        # Initialize writer
+        self.writer = HDF5Writer(
+            obj=self.h5out,
+            ds_kwds=set_default_filter_kwargs(compression=compress),
         )
-        h5bg.attrs.create('CLASS', np.string_('IMAGE'))
-        h5bg.attrs.create('IMAGE_VERSION', np.string_('1.2'))
-        h5bg.attrs.create('IMAGE_SUBCLASS', np.string_('IMAGE_GRAYSCALE'))
 
     def __enter__(self):
         return self
 
     def __exit__(self, type, value, tb):
+        self.writer.close()
         # Close h5in and h5out
         if self.hdin is not None:  # we have an input file
             self.hdin.close()  # this closes self.h5in
@@ -200,12 +188,20 @@ class Background(abc.ABC):
             return self.image_proc.value / self.image_count
 
     def process(self):
+        # Delete any old background data
+        for key in ["image_bg", "bg_off"]:
+            if key in self.h5out["events"]:
+                del self.h5out["events"][key]
+        # Perform the actual background computation
         self.process_approach()
         bg_ppid = self.get_ppid()
-        # Store pipeline information in the image_bg feature
-        self.h5out["events/image_bg"].attrs["dcnum ppid background"] = bg_ppid
-        self.h5out["events/image_bg"].attrs["dcnum ppid generation"] = \
-            ppid.DCNUM_PPID_GENERATION
+        # Store pipeline information in the image_bg/bg_off feature
+        for key in ["image_bg", "bg_off"]:
+            if key in self.h5out["events"]:
+                self.h5out[f"events/{key}"].attrs["dcnum ppid background"] = \
+                    bg_ppid
+                self.h5out[F"events/{key}"].attrs["dcnum ppid generation"] = \
+                    ppid.DCNUM_PPID_GENERATION
 
     @abc.abstractmethod
     def process_approach(self):

{dcnum-0.17.1 → dcnum-0.18.0}/src/dcnum/feat/feat_background/bg_copy.py

@@ -4,17 +4,14 @@ from .base import Background
 
 
 class BackgroundCopy(Background):
-
     @staticmethod
     def check_user_kwargs():
         pass
 
-    def process_approach(self):
+    def process(self):
         """Perform median computation on entire input data"""
         if self.h5in != self.h5out:
             hin = self.hdin.image_bg.h5ds
-            if "image_bg" in self.h5out["events"]:
-                del self.h5out["events/image_bg"]
             h5py.h5o.copy(src_loc=hin.parent.id,
                           src_name=b"image_bg",
                           dst_loc=self.h5out["events"].id,
@@ -23,3 +20,10 @@ class BackgroundCopy(Background):
 
         # set progress to 100%
         self.image_proc.value = self.image_count
+
+    def process_approach(self):
+        # We do the copying in `process`, because we do not want to modify
+        # any metadata or delete datasets as is done in the base class.
+        # But we still have to implement this method, because it is an
+        # abstractmethod in the base class.
+        pass

{dcnum-0.17.1 → dcnum-0.18.0}/src/dcnum/feat/feat_background/bg_roll_median.py

@@ -172,11 +172,18 @@ class BackgroundRollMed(Background):
         num_steps = int(np.ceil(self.image_count / self.batch_size))
         for ii in range(num_steps):
             self.process_next_batch()
-        # Set the remaining kernel_size median values to the last one
-        last_image = self.h5out["events/image_bg"][-self.kernel_size-1]
-        for ii in range(self.kernel_size):
-            self.h5out["events/image_bg"][self.image_count-ii-1] = last_image
-        self.image_proc.value = self.image_count
+
+        # Set the remaining median bg images to the last one.
+        num_remaining = (self.input_data.shape[0]
+                         - self.h5out["events/image_bg"].shape[0])
+        if num_remaining:
+            last_image = self.h5out["events/image_bg"][-1]
+            last_chunk = np.repeat(
+                last_image[np.newaxis],
+                num_remaining,
+                axis=0)
+            self.writer.store_feature_chunk("image_bg", last_chunk)
+            self.image_proc.value += num_remaining
 
     def process_next_batch(self):
         """Process one batch of input data"""
@@ -208,9 +215,11 @@ class BackgroundRollMed(Background):
             # TODO:
             #  Do this in a different thread so workers can keep going
             #  and use a lock somewhere in case the disk is too slow.
-            self.h5out["events/image_bg"][cur_slice_out] = \
+            self.writer.store_feature_chunk(
+                "image_bg",
                 self.shared_output[:output_size].reshape(output_size,
-                                                         *self.image_shape)
+                                                         *self.image_shape),
+            )
 
         self.current_batch += 1
         self.image_proc.value += self.batch_size

{dcnum-0.17.1 → dcnum-0.18.0}/src/dcnum/feat/feat_background/bg_sparse_median.py

@@ -15,6 +15,7 @@ logger = logging.getLogger(__name__)
 class BackgroundSparseMed(Background):
     def __init__(self, input_data, output_path, kernel_size=200,
                  split_time=1., thresh_cleansing=0, frac_cleansing=.8,
+                 offset_correction=True,
                  compress=True, num_cpus=None):
         """Sparse median background correction with cleansing
 
@@ -57,6 +58,21 @@ class BackgroundSparseMed(Background):
             Fraction between 0 and 1 indicating how many background images
             must still be present after cleansing (in case the cleansing
             factor is too large). Set to 1 to disable cleansing altogether.
+        offset_correction: bool
+            The sparse median background correction produces one median
+            image for multiple input frames (BTW this also leads to very
+            efficient data storage with HDF5 data compression filters). In
+            case the input frames are subject to frame-by-frame brightness
+            variations (e.g. flickering of the illumination source), it
+            is useful to have an offset value per frame that can then be
+            used in a later step to perform a more accurate background
+            correction. This offset is computed here by taking a 20px wide
+            slice from each frame (where the channel wall is located)
+            and computing the median therein relative to the computed
+            background image. The data are written to the "bg_off" feature
+            in the output file alongside "image_bg". To obtain the
+            corrected background image, add "image_bg" and "bg_off".
+            Set this to False if you don't need the "bg_off" feature.
         compress: bool
             Whether to compress background data. Set this to False
             for faster processing.
@@ -72,7 +88,9 @@ class BackgroundSparseMed(Background):
             kernel_size=kernel_size,
             split_time=split_time,
             thresh_cleansing=thresh_cleansing,
-            frac_cleansing=frac_cleansing)
+            frac_cleansing=frac_cleansing,
+            offset_correction=offset_correction,
+        )
 
         if kernel_size > len(self.input_data):
             logger.warning(
@@ -88,6 +106,8 @@ class BackgroundSparseMed(Background):
         self.thresh_cleansing = thresh_cleansing
         #: keep at least this many background images from the series
         self.frac_cleansing = frac_cleansing
+        #: offset/flickering correction
+        self.offset_correction = offset_correction
 
         # time axis
         self.time = None
@@ -175,11 +195,13 @@ class BackgroundSparseMed(Background):
                           kernel_size: int = 200,
                           split_time: float = 1.,
                           thresh_cleansing: float = 0,
-                          frac_cleansing: float = .8):
+                          frac_cleansing: float = .8,
+                          offset_correction: bool = True,
+                          ):
         """Initialize user-defined properties of this class
 
         This method primarily exists so that the CLI knows which
-        keyword arguements can be passed to this class.
+        keyword arguments can be passed to this class.
 
         Parameters
         ----------
@@ -197,6 +219,21 @@ class BackgroundSparseMed(Background):
             Fraction between 0 and 1 indicating how many background images
             must still be present after cleansing (in case the cleansing
             factor is too large). Set to 1 to disable cleansing altogether.
+        offset_correction: bool
+            The sparse median background correction produces one median
+            image for multiple input frames (BTW this also leads to very
+            efficient data storage with HDF5 data compression filters). In
+            case the input frames are subject to frame-by-frame brightness
+            variations (e.g. flickering of the illumination source), it
+            is useful to have an offset value per frame that can then be
+            used in a later step to perform a more accurate background
+            correction. This offset is computed here by taking a 20px wide
+            slice from each frame (where the channel wall is located)
+            and computing the median therein relative to the computed
+            background image. The data are written to the "bg_off" feature
+            in the output file alongside "image_bg". To obtain the
+            corrected background image, add "image_bg" and "bg_off".
+            Set this to False if you don't need the "bg_off" feature.
         """
         assert kernel_size > 0
         assert split_time > 0
@@ -300,8 +337,19 @@ class BackgroundSparseMed(Background):
         while pos < self.image_count:
             stop = min(pos + step, self.image_count)
             cur_slice = slice(pos, stop)
-            self.h5out["events/image_bg"][cur_slice] = \
-                bg_images[bg_idx[cur_slice]]
+            cur_bg_data = bg_images[bg_idx[cur_slice]]
+            self.writer.store_feature_chunk("image_bg", cur_bg_data)
+            if self.offset_correction:
+                # Record background offset correction "bg_off". We take a
+                # slice of 20px from the top of the image (there are normally
+                # no events here, only the channel walls are visible).
+                sh, sw = self.input_data.shape[1:]
+                roi_full = (slice(None), slice(0, 20), slice(0, sw))
+                roi_cur = (cur_slice, slice(0, 20), slice(0, sw))
+                val_bg = np.mean(cur_bg_data[roi_full], axis=(1, 2))
+                val_dat = np.mean(self.input_data[roi_cur], axis=(1, 2))
+                # background image = image_bg + bg_off
+                self.writer.store_feature_chunk("bg_off", val_dat - val_bg)
             pos += step
 
     def process_second(self,

{dcnum-0.17.1 → dcnum-0.18.0}/src/dcnum/feat/feat_brightness/bright_all.py

@@ -4,16 +4,38 @@ import numpy as np
 from .common import brightness_names
 
 
-def brightness_features(image,
-                        mask,
-                        image_bg=None,
-                        image_corr=None):
+def brightness_features(image: np.ndarray[np.uint8],
+                        mask: np.ndarray[np.bool_],
+                        image_bg: np.ndarray[np.uint8] = None,
+                        image_corr: np.ndarray[np.int16] = None,
+                        bg_off: float = None,
+                        ):
+    """Compute brightness features
+
+    Parameters
+    ----------
+    image: np.ndarray
+        2D array of "image" of shape (H, W)
+    mask: np.ndarray
+        3D array containing the N masks of shape (N, H, W)
+    image_bg: np.ndarray
+        2D array of "image_bg" of shape (H, W), required for computing
+        the "bg_med" feature.
+    image_corr: np.ndarray
+        2D array of (image - image_bg), which can be optionally passed
+        to this method. If not given, will be computed.
+    bg_off: float
+        Systematic offset value for correcting the brightness of the
+        background data which has an effect on "bright_bc_avg",
+        "bright_perc_10", "bright_perc_90", and "bg_med" (`bg_off` is
+        generated by sparsemed background correction).
+    """
     mask = np.array(mask, dtype=bool)
     size = mask.shape[0]
 
     br_dict = {}
-    for key in brightness_names:
-        br_dict[key] = np.full(size, np.nan, dtype=np.float64)
+    for mkey in brightness_names:
+        br_dict[mkey] = np.full(size, np.nan, dtype=np.float64)
 
     avg_sd = compute_avg_sd_masked_uint8(image, mask)
     br_dict["bright_avg"][:] = avg_sd[:, 0]
@@ -36,6 +58,19 @@ def brightness_features(image,
         br_dict["bright_perc_10"][:] = percentiles[:, 0]
         br_dict["bright_perc_90"][:] = percentiles[:, 1]
 
+    if bg_off is not None:
+        # subtract the background offset for all values that are computed
+        # from background-corrected images
+        for mkey in ["bright_bc_avg", "bright_perc_10", "bright_perc_90"]:
+            if mkey in br_dict:
+                br_dict[mkey] -= bg_off
+
+        # add the background offset to all values that were computed from
+        # the background only
+        for pkey in ["bg_med"]:
+            if pkey in br_dict:
+                br_dict[pkey] += bg_off
+
     return br_dict
 
 

dcnum-0.18.0/src/dcnum/feat/feat_contour/__init__.py

@@ -0,0 +1,4 @@
+# flake8: noqa: F401
+"""Feature computation: OpenCV moments-based features"""
+from .moments import moments_based_features
+from .volume import volume_from_contours

dcnum-0.17.1/src/dcnum/feat/feat_moments/mt_legacy.py → dcnum-0.18.0/src/dcnum/feat/feat_contour/moments.py

@@ -2,11 +2,27 @@ import cv2
 import numpy as np
 
 
-from .ct_opencv import contour_single_opencv
-
-
-def moments_based_features(mask, pixel_size):
+from .contour import contour_single_opencv
+
+
+def moments_based_features(
+        mask: np.ndarray,
+        pixel_size: float,
+        ret_contour: bool = False,
+        ):
+    """Compute moment-based features for a mask image
+
+    Parameters
+    ----------
+    mask: np.ndarray
+        3D stack of 2D boolean mask images to analyze
+    pixel_size: float
+        pixel size of the mask image in µm
+    ret_contour: bool
+        whether to also return the raw contour
+    """
     assert pixel_size is not None and pixel_size != 0
+    raw_contours = []
 
     size = mask.shape[0]
 
@@ -42,9 +58,13 @@ def moments_based_features(mask, pixel_size):
     for ii in range(size):
         # raw contour
         cont_raw = contour_single_opencv(mask[ii])
-        if len(cont_raw.shape) < 2:
-            continue
-        if cv2.contourArea(cont_raw) == 0:
+        # only continue if the contour is valid
+        not_valid = len(cont_raw.shape) < 2 or cv2.contourArea(cont_raw) == 0
+
+        if ret_contour:
+            raw_contours.append(None if not_valid else cont_raw)
+
+        if not_valid:
             continue
 
         mu_raw = cv2.moments(cont_raw)
@@ -53,6 +73,7 @@ def moments_based_features(mask, pixel_size):
 
         # convex hull
         cont_cvx = np.squeeze(cv2.convexHull(cont_raw))
+
         mu_cvx = cv2.moments(cont_cvx)
         arc_cvx = np.float64(cv2.arcLength(cont_cvx, True))
 
@@ -110,7 +131,7 @@ def moments_based_features(mask, pixel_size):
         # specify validity
         valid[ii] = True
 
-    return {
+    data = {
         "area_msd": feat_area_msd,
         "area_ratio": feat_area_ratio,
         "area_um": feat_area_um,
@@ -131,3 +152,6 @@ def moments_based_features(mask, pixel_size):
         "tilt": feat_tilt,
         "valid": valid,
     }
+    if ret_contour:
+        data["contour"] = raw_contours
+    return data

dcnum-0.18.0/src/dcnum/feat/feat_contour/volume.py

@@ -0,0 +1,174 @@
+from typing import List
+
+import numpy as np
+
+
+def volume_from_contours(
+        contour: List[np.ndarray],
+        pos_x: np.ndarray,
+        pos_y: np.ndarray,
+        pixel_size: float):
+    """Calculate the volume of a polygon revolved around an axis
+
+    The volume estimation assumes rotational symmetry.
+
+    Parameters
+    ----------
+    contour: list of ndarrays of shape (N,2)
+        One entry is a 2D array that holds the contour of an event
+    pos_x: float ndarray of length N
+        The x coordinate(s) of the centroid of the event(s) [µm]
+    pos_y: float ndarray of length N
+        The y coordinate(s) of the centroid of the event(s) [µm]
+    pixel_size: float
+        The detector pixel size in µm.
+
+    Returns
+    -------
+    volume: float ndarray
+        volume in um^3
+
+    Notes
+    -----
+    The computation of the volume is based on a full rotation of the
+    upper and the lower halves of the contour from which the
+    average is then used.
+
+    The volume is computed radially from the center position
+    given by (`pos_x`, `pos_y`). For sufficiently smooth contours,
+    such as densely sampled ellipses, the center position does not
+    play an important role. For contours that are given on a coarse
+    grid, as is the case for deformability cytometry, the center position
+    must be given.
+
+    References
+    ----------
+    - https://de.wikipedia.org/wiki/Kegelstumpf#Formeln
+    - Yields identical results to the Matlab script by Geoff Olynyk
+      <https://de.mathworks.com/matlabcentral/fileexchange/36525-volrevolve>`_
+    """
+    # results are stored in a separate array initialized with nans
+    v_avg = np.zeros_like(pos_x, dtype=np.float64) * np.nan
+
+    for ii in range(pos_x.shape[0]):
+        # If the contour has less than 4 pixels, the computation will fail.
+        # In that case, the value np.nan is already assigned.
+        cc = contour[ii]
+        if cc is not None and cc.shape[0] >= 4:
+            # Center contour coordinates with given centroid
+            contour_x = cc[:, 0] - pos_x[ii] / pixel_size
+            contour_y = cc[:, 1] - pos_y[ii] / pixel_size
+            # Switch to r and z to follow notation of vol_revolve
+            # (In RT-DC the axis of rotation is x, but for vol_revolve
+            # we need the axis vertically)
+            contour_r = contour_y
+            contour_z = contour_x
+
+            # Compute right volume
+            # Which points are at negative r-values (r<0)?
+            inx_neg = np.where(contour_r < 0)
+            # These points will be shifted up to r=0 directly on the z-axis
+            contour_right = np.copy(contour_r)
+            contour_right[inx_neg] = 0
+            vol_right = vol_revolve(r=contour_right,
+                                    z=contour_z,
+                                    point_scale=pixel_size)
+
+            # Compute left volume
+            # Which points are at positive r-values? (r>0)?
+            idx_pos = np.where(contour_r > 0)
+            # These points will be shifted down to y=0 to build an x-axis
+            contour_left = np.copy(contour_r)
+            contour_left[idx_pos] = 0
+            # Now we still have negative r values, but vol_revolve needs
+            # positive values, so we flip the sign...
+            contour_left[:] *= -1
+            # ... but in doing so, we have switched to clockwise rotation,
+            # and we need to pass the array in reverse order
+            vol_left = vol_revolve(r=contour_left[::-1],
+                                   z=contour_z[::-1],
+                                   point_scale=pixel_size)
+
+            # Compute the average
+            v_avg[ii] = (vol_right + vol_left) / 2
+
+    return {"volume": v_avg}
+
+
+def vol_revolve(r, z, point_scale=1.):
+    r"""Calculate the volume of a polygon revolved around the Z-axis
+
+    This implementation yields the same results as the volRevolve
+    Matlab function by Geoff Olynyk (from 2012-05-03)
+    https://de.mathworks.com/matlabcentral/fileexchange/36525-volrevolve.
+
+    The difference here is that the volume is computed using (a much
+    more approachable) implementation using the volume of a truncated
+    cone (https://de.wikipedia.org/wiki/Kegelstumpf).
+
+    .. math::
+
+      V = \frac{h \cdot \pi}{3} \cdot (R^2 + R \cdot r + r^2)
+
+    Where :math:`h` is the height of the cone and :math:`r` and
+    `R` are the smaller and larger radii of the truncated cone.
+
+    Each line segment of the contour resembles one truncated cone. If
+    the z-step is positive (counter-clockwise contour), then the
+    truncated cone volume is added to the total volume. If the z-step
+    is negative (e.g. inclusion), then the truncated cone volume is
+    removed from the total volume.
+
+    Parameters
+    ----------
+    r: 1d np.ndarray
+        radial coordinates (perpendicular to the z axis)
+    z: 1d np.ndarray
+        coordinate along the axis of rotation
+    point_scale: float
+        point size in your preferred units; The volume is multiplied
+        by a factor of `point_scale**3`.
+
+    Notes
+    -----
+    The coordinates must be given in counter-clockwise order,
+    otherwise the volume will be negative.
+    """
+    r = np.atleast_1d(r)
+    z = np.atleast_1d(z)
+
+    # make sure we have a closed contour
+    if (r[-1] != r[0]) or (z[-1] != z[0]):
+        # We have an open contour - close it.
+        r = np.resize(r, len(r) + 1)
+        z = np.resize(z, len(z) + 1)
+
+    rp = r[:-1]
+
+    # array of radii differences: R - r
+    dr = np.diff(r)
+    # array of height differences: h
+    dz = np.diff(z)
+
+    # If we expand the function in the doc string with
+    # dr = R - r and dz = h, then we get three terms for the volume
+    # (as opposed to four terms in Olynyk's script). Those three terms
+    # all resemble area slices multiplied by the z-distance dz.
+    a1 = 3 * rp ** 2
+    a2 = 3 * rp * dr
+    a3 = dr ** 2
+
+    # Note that the formula for computing the volume is symmetric
+    # with respect to r and R. This means that it does not matter
+    # which sign dr has (R and r are always positive). Since this
+    # algorithm assumes that the contour is ordered counter-clockwise,
+    # positive dz means adding to the contour while negative dz means
+    # subtracting from the contour (see test functions for more details).
+    # Conveniently so, dz only appears one time in this formula, so
+    # we can take the sign of dz as it is (Otherwise, we would have
+    # to take the absolute value of every truncated cone volume and
+    # multiply it by np.sign(dz)).
+    v = np.pi / 3 * dz * np.abs(a1 + a2 + a3)
+    vol = np.sum(v) * point_scale ** 3
+
+    return vol