numpyimage 1.2.0__tar.gz → 1.3.0__tar.gz

numpyimage-1.3.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.1
+Name: numpyimage
+Version: 1.3.0
+Summary: Load, save, and manipulate image files as numpy arrays
+Home-page: https://github.com/jasper-tms/npimage
+Author: Jasper Phelps
+Author-email: jasper.s.phelps@gmail.com
+License: GNU GPL v3
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: tifffile
+Requires-Dist: pynrrd
+Requires-Dist: matplotlib
+Requires-Dist: opencv-python-headless
+
+# npimage
+Need to load pixel values from image files as numpy arrays, and hate having to remember whether you should use PIL, tifffile, matplotlib, or something else? Hate having to deal with the fact that those libraries all use different function names and syntaxes? Wish you could just provide a filename and get back a numpy array? This library's `core.py` does that, with `array = load(filename)`, `save(array, filename)`, and `show(array)` functions that let you easily handle a number of common image file formats without having to remember library-specific syntax. (Another choice of library to consider for accomplishing similar goals is [imageio](https://pypi.org/project/imageio/), which also supports loading videos through the FFmpeg wrapper library [pyav](https://pypi.org/project/av/).)
+
+Want to draw simple shapes like lines, triangles, and circles into 3D numpy arrays? Frustrated that the python libraries you can find online like `opencv` and `skimage.draw` work on 2D arrays but not 3D? I wrote some functions in `graphics.py` that do the trick in 3D. (If you know of another library that can do this, please let me know!)
+
+
+### Documentation
+- `core.py`: load, save, or show images.
+- `graphics.py`: draw points, lines, triangles, circles, or spheres into 2D or 3D numpy arrays representing image volumes.
+- `nrrd_utils.py`: compress or read metadata from `.nrrd` files.
+- `operations.py`: perform operations on images.
+
+For now, check each function's docstring for more. A jupyter notebook demonstrating this package's functions will come later.
+
+
+### Installation
+
+As is always the case in python, consider making a virtual environment (using your preference of conda, virtualenv, or virtualenvwrapper) before installing.
+
+**Option 1:** `pip install` from PyPI:
+
+    pip install numpyimage
+
+(Unfortunately the name `npimage` was already taken on PyPI, so `pip install npimage` will get you a different package.)
+
+**Option 2:** `pip install` directly from GitHub:
+    
+    pip install git+https://github.com/jasper-tms/npimage.git
+
+**Option 3:** First `git clone` this repo and then `pip install` it from your clone:
+
+    cd ~/repos  # Or wherever on your computer you want to download this code to
+    git clone https://github.com/jasper-tms/npimage.git
+    cd npimage
+    pip install .
+
+**After installing,** you can import this package in python using `import npimage` (not `import numpyimage`!)

numpyimage-1.3.0/npimage/__init__.py

@@ -0,0 +1,4 @@
+from .core import *
+from .operations import *
+from .align import *
+from .graphics import *

numpyimage-1.3.0/npimage/align.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""
+Functions for aligning images.
+"""
+
+import numpy as np
+import cv2 as cv
+
+
+def find_landmark(image: np.ndarray,
+                  landmark: np.ndarray,
+                  search_bbox=None,
+                  metric=cv.TM_CCOEFF_NORMED):
+    """
+    Find the region in an image that most resembles a particular landmark.
+
+    Implementation leverages OpenCV functions, following tutorial at
+    https://docs.opencv.org/4.x/d4/dc6/tutorial_py_template_matching.html
+
+    Parameters
+    ----------
+    image : np.ndarray
+        The image in which to search for the landmark.
+
+    landmark : np.ndarray
+        The landmark to search for in the image.
+
+    search_bbox : list/tuple, optional
+        The bounding box in which to search for the landmark. If you know
+        the landmark you're searching for is in a subset of the image then
+        specifying a search region will save time.
+        If None, the entire image will be searched. If not None, search_bbox
+        should be a list/tuple with two elements. Each element should be either
+        a slice object or a list/tuple of two integers that specify the min and
+        max values of the range.
+        For example, search_bbox=(slice(0, 100), slice(0, 200)) or
+        search_box=([0, 100], [0, 200]) would search the top-left
+        100x200 region of the image.
+
+    metric : cv.TemplateMatchModes, optional
+        The metric to use to compare the landmark to the image. Options are
+        cv.TM_SQDIFF, cv.TM_SQDIFF_NORMED, cv.TM_CCORR, cv.TM_CCORR_NORMED,
+        cv.TM_CCOEFF, cv.TM_CCOEFF_NORMED. Default is cv.TM_CCOEFF_NORMED.
+
+    Returns
+    -------
+    (top_left, match_score) : tuple
+        top_left : tuple
+            The top-left corner of the bounding box in the image that
+            is most similar to the landmark.
+        score : float
+            The score of the match, from 0 to 1. A score of 1 indicates
+            a perfect match.
+    """
+    if search_bbox is not None:
+        if all(isinstance(el, slice) for el in search_bbox):
+            img_to_search = image[search_bbox[0], search_bbox[1]]
+            offset = (search_bbox[0].start, search_bbox[1].start)
+        elif all(isinstance(el, (list, tuple)) and len(el) == 2
+                 for el in search_bbox):
+            img_to_search = image[search_bbox[0][0]:search_bbox[0][1],
+                                  search_bbox[1][0]:search_bbox[1][1]]
+            offset = (search_bbox[0][0], search_bbox[1][0])
+        else:
+            raise ValueError(f"Invalid search_bbox: {search_bbox}. Must "
+                             "be two slices or two (min, max) pairs.")
+    else:
+        img_to_search = image
+        offset = (0, 0)
+
+    # Perform template matching
+    scores = cv.matchTemplate(img_to_search, landmark, metric)
+
+    # TODO implement subpixel max_loc finding.
+    # Perhaps fitting a gaussian peak?
+    min_val, max_val, min_loc, max_loc = cv.minMaxLoc(scores)
+    if metric in [cv.TM_SQDIFF, cv.TM_SQDIFF_NORMED]:
+        top_left = min_loc[::-1]  # Includes a flip from (x, y) to (y, x)
+        match_score = 1 - min_val
+    else:
+        top_left = max_loc[::-1]  # Includes a flip from (x, y) to (y, x)
+        match_score = max_val
+    top_left = (top_left[0] + offset[0], top_left[1] + offset[1])
+    return top_left, match_score

{numpyimage-1.2.0 → numpyimage-1.3.0}/npimage/core.py

@@ -1,15 +1,28 @@
 #!/usr/bin/env python3
+"""
+Functions for reading, writing, and showing images.
+
+Function list:
+- load(filename) -> numpy.ndarray
+- save(data, filename) -> Saves a numpy array as an nD image file
+- save_video(data, filename) -> Saves a 3D numpy array as a video
+- show(np_array) -> Displays a numpy array of pixel values as an image
+"""
 
 import os
 import glob
+from builtins import open as builtin_open
 
 import numpy as np
 
+from . import utils
+
 supported_extensions = [
     'tif', 'tiff', 'jpg', 'jpeg', 'png', 'pbm',
-    'nrrd', 'zarr', 'raw', 'vol'
+    'nrrd', 'zarr', 'raw', 'vol', 'ng'
 ]
 
+
 def load(filename, dim_order='zyx', **kwargs):
     """
     Open a 2D or 3D image file and return its pixel values as a numpy array.
@@ -21,11 +34,19 @@ def load(filename, dim_order='zyx', **kwargs):
      xyz for 3D image volumes, xy for 1-channel 2D images, or
      xyc for multi-channel 2D images.
     """
-
+    filename = str(filename)
     while filename.endswith('/'):
         filename = filename[:-1]
-    extension = filename.split('.')[-1]
-    assert extension in supported_extensions, f'Filetype {extension} not supported'
+    if 'format' in kwargs:
+        extension = kwargs['format'].lower()
+    elif '.' in filename:
+        extension = filename.split('.')[-1].lower()
+    else:
+        raise ValueError('Could not determine file format from filename'
+                         f' "{filename}". Please specify the file type via'
+                         ' the `format` argument, e.g. format="tif"')
+    if extension not in supported_extensions:
+        raise ValueError(f'File format "{extension}" not supported/recognized.')
 
     data = None
 
@@ -39,21 +60,22 @@ def load(filename, dim_order='zyx', **kwargs):
 
     if extension == 'pbm':
         from .filetypes import pbm
-        data = pbm.load(filename)  #pbm.load returns zyx
+        data = pbm.load(filename)  # pbm.load returns zyx
 
     if extension == 'nrrd':
         import nrrd  # pip install pynrrd
         # Specify C-style ordering to get zyx ordering from nrrd.read
-        # https://pynrrd.readthedocs.io/en/latest/user-guide.html#index-ordering
+        # https://pynrrd.readthedocs.io/en/stable/background/index-ordering.html
         data, metadata = nrrd.read(filename, index_order='C')
+        # Metadata is in Fortran order, so flip it to C order
+        utils.transpose_metadata(metadata, inplace=True)
 
     if extension in ['raw', 'vol']:
         dtype = kwargs.get('dtype', np.uint8)
-        with open(filename, 'rb') as f:
-            if shape in kwargs:
-                im = np.fromfile(f, dtype=dtype).reshape(*shape)
-            else:
-                im = np.fromfile(f, dtype=dtype)
+        with builtin_open(filename, 'rb') as f:
+            data = np.fromfile(f, dtype=dtype)
+        if 'shape' in kwargs:
+            data = data.reshape(*kwargs['shape'])
 
     if extension == 'zarr':
         if 'dataset' not in kwargs:
@@ -94,6 +116,9 @@ def load(filename, dim_order='zyx', **kwargs):
         else:
             data = data.T
 
+        if extension == 'nrrd':  # TODO check if other formats need this
+            utils.transpose_metadata(metadata, inplace=True)
+
     if any([kwargs.get(key, False) for key in
             ['metadata', 'get_metadata', 'return_metadata']]):
         try:
@@ -110,7 +135,14 @@ read = load  # Function name alias
 imread = load  # Function name alias
 
 
-def save(data, filename, overwrite=False, dim_order='zyx', metadata=None, compress=False):
+def save(data,
+         filename,
+         overwrite=False,
+         dim_order='zyx',
+         pixel_size=None,
+         units=None,
+         compress=None,
+         metadata=None):
     """
     Save a numpy array to file with a file type specified by the
     filename extension.
@@ -122,16 +154,18 @@ def save(data, filename, overwrite=False, dim_order='zyx', metadata=None, compre
      a 1-channel 2D image in xy order, or a multi-channel 2D image
      in xyc order.
 
-    `compress` only matters when saving in `.nrrd` format
+    Currently `pixel_size`, `units`, and `compress` are only recognized
+    when saving to .nrrd and .ng files, and ignored otherwise.
     """
+    filename = str(filename)
     filename = filename.rstrip('/')
     if os.path.exists(filename) and not overwrite:
-        raise Exception(f'File {filename} already exists. '
-                        'Set overwrite=True to overwrite.')
+        raise FileExistsError(f'File {filename} already exists. '
+                              'Set overwrite=True to overwrite.')
     extension = filename.split('.')[-1]
     assert extension in supported_extensions, f'Filetype {extension} not supported'
 
-    if compress and extension != 'nrrd':
+    if compress and extension not in ['nrrd', 'ng']:
         print('WARNING: compress argument is ignored because not saving as '
               '.nrrd. Whether or not compression occurs now will depend on '
               'the format you are saving to.')
@@ -163,13 +197,50 @@ def save(data, filename, overwrite=False, dim_order='zyx', metadata=None, compre
         import nrrd  # pip install pynrrd
         if metadata is None:
             metadata = {}
-        if 'encoding' not in metadata:
-            if compress:
-                metadata.update({'encoding': 'gzip'})
+        else:
+            metadata = metadata.copy()
+        if compress is True:
+            metadata.update({'encoding': 'gzip'})
+        if compress is False or 'encoding' not in metadata:
+            metadata.update({'encoding': 'raw'})
+        if pixel_size is not None:
+            try:
+                iter(pixel_size)
+            except TypeError:
+                pixel_size = [pixel_size] * data.ndim
+
+            if 'xy' in dim_order:
+                pixel_size = np.flip(pixel_size)
+            metadata.update({'space directions': np.flip(np.diag(pixel_size),
+                                                         axis=-1)})
+        if 'space dimension' not in metadata and 'space' not in metadata:
+            # If the number of spatial dimensions is not specified, assume
+            # it's the number of dimensions in the data array, minus the
+            # channel axis if it's present.
+            if is_rgb_or_rgba(data):
+                metadata.update({'space dimension': data.ndim - 1})
             else:
-                metadata.update({'encoding': 'raw'})
-        # Specify C-style ordering when writing zyx-ordered array using nrrd.write
-        # https://pynrrd.readthedocs.io/en/latest/user-guide.html#index-ordering
+                metadata.update({'space dimension': data.ndim})
+        if units is not None:
+            metadata.update({'space units': [units] * data.ndim})
+
+        # From https://pynrrd.readthedocs.io/en/stable/background/index-ordering.html
+        # "C-order is the index order used in Python and many Python libraries
+        #  (e.g. NumPy, scikit-image, PIL, OpenCV). pynrrd recommends using
+        #  C-order indexing to be consistent with the Python community. However,
+        #  as of this time, the default indexing [in the nrrd.write command] is
+        #  Fortran-order to maintain backwards compatibility."
+        # "All header fields are specified in Fortran order, per the NRRD
+        #  specification, regardless of the index order. For example, a
+        #  C-ordered array with shape (60, 800, 600) would have a sizes field
+        #  of (600, 800, 60)."
+        #
+        # We expect users of this save function to pass in metadata that has
+        # header fields ordered in the same order as their data, so in addition
+        # to effectively flipping the order of the data's axes by specifying
+        # index_order='C' to the nrrd.write command below, we also need to flip
+        # the order of any per-axis metadata fields.
+        utils.transpose_metadata(metadata, inplace=True)
         nrrd.write(filename, data, header=metadata, index_order='C')
 
     if extension in ['raw', 'vol']:
@@ -178,6 +249,54 @@ def save(data, filename, overwrite=False, dim_order='zyx', metadata=None, compre
     if extension == 'zarr':
         raise NotImplementedError
 
+    if extension == 'ng':
+        from cloudvolume import CloudVolume
+
+        # CloudVolume expects data in Fortran order
+        if is_rgb_or_rgba(data):
+            data = data.swapaxes(0, 1)
+        else:
+            data = data.T
+
+        resolution = 1
+        if pixel_size is not None:
+            resolution = pixel_size
+        try:
+            iter(resolution)
+        except TypeError:
+            resolution = [resolution] * data.ndim
+        if compress is True or compress == 'lossy':
+            encoding = 'jpeg'
+            gzip = True
+        elif compress == 'lossless':
+            encoding = 'raw',
+            gzip = True
+        elif compress is False or compress is None:
+            encoding = 'raw'
+            gzip = False
+        else:
+            raise ValueError('For .ng format, compress must be True, False,'
+                             f' "lossy", or "lossless" but was {compress}')
+
+        info = CloudVolume.create_new_info(
+            num_channels=1,
+            layer_type='image',
+            data_type=data.dtype,
+            encoding=encoding,
+            resolution=resolution,
+            voxel_offset=[0, 0, 0],
+            chunk_size=[64, 64, 64],
+            volume_size=data.shape
+        )
+
+        if not any(filename.startswith(prefix)
+                   for prefix in ['file://', 'gs://', 's3://']):
+            filename = 'file://' + filename
+        vol = CloudVolume(filename, info=info, compress=gzip)
+        vol.commit_info()
+
+        vol[:] = data
+
 
 write = save  # Function name alias
 to_file = save  # Function name alias
@@ -190,6 +309,11 @@ def save_video(data, filename, overwrite=False, dim_order='yx', time_axis=0,
 
     Follows the PyAV cookbook section on generating video from numpy arrays:
     https://pyav.basswood-io.com/docs/develop/cookbook/numpy.html#generating-video
+
+    Parameters
+    ----------
+    data : numpy.ndarray or list of filenames
+        A 3D numpy array of pixel values, with the time axis as the first axis.
     """
     if not data.ndim == 3:
         raise ValueError('Input data must be a 3D numpy array.')
@@ -203,9 +327,11 @@ def save_video(data, filename, overwrite=False, dim_order='yx', time_axis=0,
         data = data.swapaxes(1, 2)
     n_frames = data.shape[0]
 
+    if filename.split('.')[-1] not in ['mp4', 'mkv', 'avi', 'mov']:
+        filename += '.mp4'
     if os.path.exists(filename) and not overwrite:
-        raise Exception(f'File {filename} already exists. '
-                        'Set overwrite=True to overwrite.')
+        raise FileExistsError(f'File {filename} already exists. '
+                              'Set overwrite=True to overwrite.')
     container = av.open(filename, mode='w')
 
     stream = container.add_stream('libx264', rate=framerate)

{numpyimage-1.2.0 → numpyimage-1.3.0}/npimage/filetypes/pbm.py

@@ -27,7 +27,6 @@ def load(filename):
         data = data.reshape((h, w)).view(bool)
 
     return data
-    
 
 
 def save(data, filename, comments=None):