numpyimage 3.2.0__tar.gz → 3.3.0__tar.gz

{numpyimage-3.2.0/numpyimage.egg-info → numpyimage-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 3.2.0
+Version: 3.3.0
 Summary: Load, save, & manipulate image files as numpy arrays
 Author-email: Jasper Phelps <jasper.s.phelps@gmail.com>
 License: MIT License

{numpyimage-3.2.0 → numpyimage-3.3.0}/npimage/imageio.py

@@ -239,6 +239,7 @@ def save(data,
             try:
                 iter(pixel_size)
                 if len(pixel_size) == data.ndim - 1 and channel_axis is not None:
+                    pixel_size = list(pixel_size)
                     pixel_size.insert(channel_axis, np.nan)
             except TypeError:
                 if channel_axis is not None:

{numpyimage-3.2.0 → numpyimage-3.3.0}/npimage/operations.py

@@ -12,11 +12,11 @@ Function list:
 """
 
 from typing import Iterable, Literal, Union, Optional, Tuple, List
-import gc
 
 import numpy as np
+from tqdm import tqdm
 
-from .utils import iround, eq, isint
+from .utils import iround, eq, isint, find_channel_axis
 
 
 def squeeze_dtype(image: np.ndarray, minimum_bits=1):
@@ -233,29 +233,50 @@ def downsample(image: np.ndarray,
     image : np.ndarray
         The image to downsample.
 
-    factor : int or iterable of ints
+    factor : int or iterable of ints, default 2
         An iterable with length matching the number of axes in the image,
         specifying a downsampling factor along each axis.
         If factor is provided as an int, that int will be used for each axis.
-        If the image is rgb or rgba (that is, the final axis has length 3 or
-        4), it is not necessary to specify a factor for that axis and so the
-        'factor' iterable can be one element shorter than the number of axes in
-        the image.
+        If the image has a channel axis (RGB/RGBA), it is not necessary to
+        specify a factor for that axis and so the 'factor' iterable can be
+        one element shorter than the number of axes in the image.
 
-    keep_input_dtype : bool
+    keep_input_dtype : bool, default True
         If True, the output image will have the same dtype as the input image.
         If False, the output image will have dtype float64 to keep full precision.
+
+    Returns
+    -------
+    np.ndarray
+        The downsampled image.
+
+    Examples
+    --------
+    Downsample a shape (2, 4) array using default settings of factor=2, keep_input_dtype=True
+
+    >>> downsample(np.array([[1, 2, 3, 4],
+    ...                      [5, 6, 7, 8]]))
+    array([[4, 6]])
+
+    Note that the output dtype is kept as int, which loses some precision. Compare to:
+
+    >>> downsample(np.array([[1, 2, 3, 4],
+    ...                      [5, 6, 7, 8]]),
+    ...            keep_input_dtype=False)
+    array([[3.5, 5.5]])
     """
+    channel_axis = find_channel_axis(image)
     if isinstance(factor, int):
-        if image.shape[-1] in [3, 4]:
+        if channel_axis is not None:
             # If RGB/RGBA image, don't downsample the colors axis
             factor = (factor,) * (len(image.shape) - 1)
         else:
             factor = (factor,) * len(image.shape)
-    if len(factor) == len(image.shape) - 1 and image.shape[-1] in [3, 4]:
+    if len(factor) == len(image.shape) - 1 and channel_axis is not None:
         if verbose:
-            print('RGB/RGBA image detected - not downsampling last axis.')
-        factor = (*factor, 1)
+            print('RGB/RGBA image detected - not downsampling channel axis.')
+        factor = list(factor)
+        factor.insert(channel_axis, 1)
     if any([f > l > 1 for f, l in zip(factor, image.shape)]):
         raise ValueError('Downsampling factor must be <= image size along each axis')
 
@@ -306,10 +327,10 @@ def offset(image: np.ndarray,
            distance: Union[float, Iterable[float]],
            axis: int = None,
            expand_bounds: bool = False,
-           edge_mode: Literal['extend', 'wrap',
-                              'reflect', 'constant'] = 'extend',
-           edge_fill_value=0,
-           fill_transparent=False) -> np.ndarray:
+           fill_empty_with: float = 0,
+           keep_input_dtype: bool = True,
+           fill_transparent: bool = False,
+           verbose: bool = False) -> np.ndarray:
     """
     Offset an image by a given distance.
 
@@ -321,7 +342,7 @@ def offset(image: np.ndarray,
 
     If edge_mode is set to 'constant', the pixels no longer occupied by the
     original image as a result of the offset will be filled in with
-    'edge_fill_value'.
+    'fill_empty_value'.
 
     See also scipy.ndimage.shift, which performs a very similar operation
     """
@@ -333,19 +354,21 @@ def offset(image: np.ndarray,
                              ' did a mix of those two.')
     except TypeError:
         distance_iter = [0] * len(image.shape)
+        if len(distance_iter) == 1 and axis is None:
+            axis = 0
         if axis is None:
             raise ValueError('Must specify axis when giving distance as a'
                              ' single number.')
         distance_iter[axis] = distance
         distance = distance_iter
-    if edge_mode not in ['extend', 'wrap', 'reflect', 'constant']:
-        raise ValueError("edge_mode must be one of 'extend', 'wrap', 'reflect', or 'constant'")
-    if edge_mode in ['wrap', 'reflect']:
-        raise NotImplementedError("edge_mode '{}' not yet implemented".format(edge_mode))
 
-    if len(image.shape) == len(distance) + 1 and image.shape[-1] in [1, 3, 4]:
-        # Specify no offset along the channels axis, if not specified by user
-        distance = (*distance, 0)
+    if len(image.shape) == len(distance) + 1:
+        channel_axis = find_channel_axis(image)
+        if channel_axis is not None:
+            # Specify no offset along the channels axis, if not specified by user
+            distance = list(distance)
+            distance.insert(channel_axis, 0)
+            distance = tuple(distance)
 
     if len(image.shape) != len(distance):
         m = (f'distance must have length {len(image.shape)} to specify an'
@@ -353,29 +376,41 @@ def offset(image: np.ndarray,
              f' {len(distance)}')
         raise ValueError(m)
 
-    if not expand_bounds:
-        new_image = np.full_like(image, edge_fill_value)
-    else:
-        new_shape = np.array(image.shape) + np.array([int(max(0, d)) for d in distance])
-        new_image = np.full(new_shape, edge_fill_value, dtype=image.dtype)
-
-    if image.shape[-1] == 4 and not fill_transparent:
-        # If rgba, set alpha channel value to max
-        # The line below means new_image[:, :, :, ..., :, -1] = 255
-        new_image[tuple([slice(None, None)] * (len(image.shape)-1) + [-1])] = 255
-
-    distance_int = [int(x) for x in distance]
-
-    source_range = [slice(max(0, -d), min(s, s-d)) for d, s in zip(distance_int, new_image.shape)]
-    target_range = [slice(max(0, d), min(s, s+d)) for d, s in zip(distance_int, new_image.shape)]
+    new_dtype = (image.dtype if keep_input_dtype or all(eq(d, int(d)) for d in distance)
+                 else np.float64)
+    distance_int = [int(d) for d in distance]
+    new_shape = (image.shape if not expand_bounds else
+                 np.array(image.shape) + np.array([int(max(0, d)) for d in distance]))
+    new_image = np.full(new_shape, fill_empty_with, dtype=new_dtype)
+
+    if fill_transparent:
+        raise NotImplementedError('fill_transparent not yet implemented')
+    # Previous implementation of fill_transparent:
+    #if image.shape[-1] == 4 and not fill_transparent:
+    #    # If rgba, set alpha channel value to max
+    #    # The line below means new_image[:, :, :, ..., :, -1] = 255
+    #    new_image[tuple([slice(None, None)] * (len(image.shape)-1) + [-1])] = 255
+
+    source_range = [slice(max(0, -d), min(s, s-d))
+                    for d, s in zip(distance_int, new_image.shape)]
+    target_range = [slice(max(0, d), min(s, s+d))
+                    for d, s in zip(distance_int, new_image.shape)]
 
+    if verbose:
+        print('Performing integer offset...')
+    # This is the line that does the main operation
     new_image[tuple(target_range)] = image[tuple(source_range)]
 
     for i, d in enumerate(distance):
+        progress_msg = f'Performing subpixel offset along axis {i}' if verbose else None
         if not eq(d, int(d)):
             _offset_subpixel(new_image, d - int(d), i,
-                             edge_fill_value=edge_fill_value,
-                             fill_transparent=fill_transparent, inplace=True)
+                             edge_mode='constant',
+                             constant_edge_value=fill_empty_with,
+                             keep_input_dtype=True,
+                             fill_transparent=fill_transparent,
+                             inplace=True,
+                             progress_msg=progress_msg)
 
     return new_image
 
@@ -385,9 +420,11 @@ def _offset_subpixel(image: np.ndarray,
                      axis: int,
                      edge_mode: Literal['extend', 'wrap',
                                         'reflect', 'constant'] = 'extend',
-                     edge_fill_value=0,
-                     fill_transparent=False,
-                     inplace=False):
+                     constant_edge_value: Optional[float] = None,
+                     keep_input_dtype: bool = True,
+                     fill_transparent: bool = False,
+                     inplace: bool = False,
+                     progress_msg: Optional[str] = None):
     """
     Offset an image by a fraction of a pixel along a single specified axis.
 
@@ -402,61 +439,80 @@ def _offset_subpixel(image: np.ndarray,
     The pixels no longer occupied by the original image as a result of the
     offset will be filled in with 'edge_fill_value'.
     """
-    assert -1 < distance and distance < 1
-
-    one_pix_offset = [0] * len(image.shape)
-    one_pix_offset[axis] = 1 if distance >= 0 else -1
-    image_1pix_shifted = offset(image, one_pix_offset,
-                                edge_fill_value=edge_fill_value,
-                                fill_transparent=fill_transparent)
-    distance = abs(distance)
-
-    if np.issubdtype(image.dtype, np.integer):
-        # If the input array is an integer type, we should avoid creating a
-        # float version of the array during calculations, because float arrays
-        # can take up an unacceptable amount of memory. (e.g. If I write lazy
-        # code that ends up multiplying a uint8 array by a fractional value
-        # like 0.5, a float64 array is created which takes up 8x the amount of
-        # memory as the source array. And we need to make two of these!).
-        # Instead, we will do a trick of increasing the bit-depth of the source
-        # array by 1 byte (or a few bytes, since numpy only works with bit
-        # depths that are a power of 2, e.g. uint24 isn't a thing), use that
-        # additional range to keep some accuracy during the weighted average
-        # calculation, then cast back to the original dtype.
-
-        upcast_dtype = np.dtype(f'{image.dtype.kind}{image.dtype.itemsize * 2}')
-        image_upcast = image.astype(upcast_dtype)
-        image_1pix_shifted_upcast = image_1pix_shifted.astype(upcast_dtype)
-
-        # We'll use the extra bit of precision to enable us to use integer
-        # weights from 0 to 255 instead of float weights from 0.0 to 1.0
-        image_weight = int(256 * (1 - distance))
-        image_1pix_shifted_weight = int(256 * distance)
-        # Adding 127 before dividing by 256 means we round to the nearest
-        # integer instead of truncating (which we'd get without the 127)
-        image_subpix_shifted = (
-            (image_upcast * image_weight)
-            + (image_1pix_shifted_upcast * image_1pix_shifted_weight)
-            + 127
-        ) // 256
-        del image_upcast, image_1pix_shifted_upcast, image_1pix_shifted
-        gc.collect()
-
-        # Now cast back to the original dtype
-        image_subpix_shifted = image_subpix_shifted.astype(image.dtype)
-
-    elif np.issubdtype(image.dtype, np.floating):
-        image_subpix_shifted = image * (1 - distance) + image_1pix_shifted * distance
-
-    if inplace:
-        image[:] = image_subpix_shifted
-    else:
-        return image_subpix_shifted
+    if inplace and not keep_input_dtype:
+        raise ValueError("inplace=True doesn't make sense with keep_input_dtype=False")
+    if distance < -1 or distance > 1:
+        raise ValueError('subpixel offset distance must be between -1 and 1')
+    if abs(distance) < 1e-6:
+        return image if inplace else image.copy()
+    if edge_mode not in ['extend', 'wrap', 'reflect', 'constant']:
+        raise ValueError('edge_mode must be one of "extend", "wrap",'
+                         ' "reflect", or "constant"')
+    if fill_transparent:
+        raise NotImplementedError('fill_transparent not yet implemented')
+
+    if not inplace:
+        if keep_input_dtype:
+            image = image.copy()
+        else:
+            image = image.astype('float64')
+
+    abs_distance = abs(distance)
+    sign = 1 if distance > 0 else -1
+    axis_size = image.shape[axis]
+    slicer: List[Union[slice, int]] = [slice(None)] * image.ndim
+
+    # Handle last slice which attempts to pull data from out of bounds
+    final_index = 0 if sign > 0 else -1
+    slicer[axis] = final_index
+    final_slice = tuple(slicer)
+
+    if edge_mode == 'extend':
+        edge_data = image[final_slice].copy()
+    elif edge_mode == 'wrap':
+        slicer[axis] -= sign
+        edge_data = image[tuple(slicer)].copy()
+    elif edge_mode == 'reflect':
+        slicer[axis] += sign
+        edge_data = image[tuple(slicer)].copy()
+    elif edge_mode == 'constant':
+        if constant_edge_value is None:
+            raise ValueError('constant_edge_value must be provided when'
+                             ' edge_mode is "constant"')
+        edge_data = constant_edge_value
+
+    loop_range = range(axis_size - 1, 0, -1) if sign > 0 else range(0, axis_size - 1, 1)
+
+    for i in tqdm(loop_range, desc=progress_msg, disable=not bool(progress_msg)):
+        slicer[axis] = i
+        current_slice = tuple(slicer)
+        slicer[axis] = i - sign
+        adjacent_slice = tuple(slicer)
+
+        new_values = (
+            (1 - abs_distance) * image[current_slice]
+            + abs_distance * image[adjacent_slice]
+        )
+        if keep_input_dtype and np.issubdtype(image.dtype, np.integer):
+            new_values = iround(new_values, output_dtype=image.dtype)
+        image[current_slice] = new_values
+
+    image[final_slice] = (
+        (1 - abs_distance) * image[final_slice]
+        + abs_distance * edge_data
+    )
+
+    if not inplace:
+        return image
 
 
 def paste(image: np.ndarray,
           target: np.ndarray,
-          offset: Iterable[float]):
+          offset: Iterable[float],
+          subpixel_edge_mode: Literal['extend', 'wrap',
+                                      'reflect', 'constant'] = 'extend',
+          constant_edge_value: Optional[float] = None,
+          verbose: bool = False):
     """
     Paste an image onto another image at a given offset.
 
@@ -468,12 +524,20 @@ def paste(image: np.ndarray,
     except TypeError:
         offset = [offset] * len(image.shape)
     if len(offset) != image.ndim:
-        raise ValueError('The length of the offset must match the number of dimensions in the image.')
+        raise ValueError('The length of the offset must match the number of '
+                         'dimensions in the image.')
     offset_int = [int(x) for x in offset]
     offset_subpixel = [x - int(x) for x in offset]
+    if any(not eq(o, 0) for o in offset_subpixel):
+        image = image.copy()
     for i, offset in enumerate(offset_subpixel):
+        progress_msg = f'Performing subpixel offset along axis {i}' if verbose else None
         if not eq(offset, 0):
-            _offset_subpixel(image, offset, i, inplace=True)
+            _offset_subpixel(image, offset, i,
+                             edge_mode=subpixel_edge_mode,
+                             constant_edge_value=constant_edge_value,
+                             inplace=True,
+                             progress_msg=progress_msg)
 
     source_range = [slice(max(0, -o), min(s, t-o))
                     for o, s, t in zip(offset_int, image.shape, target.shape)]

{numpyimage-3.2.0 → numpyimage-3.3.0}/npimage/utils.py

@@ -60,30 +60,46 @@ def isint(n):
 
 def find_channel_axis(data,
                       possible_channel_axes=[-1, 0],
-                      possible_channel_lengths=[2, 3, 4]) -> Union[int, None]:
+                      possible_channel_lengths=[2, 3, 4],
+                      minimum_image_size=(32, 32)) -> Union[int, None]:
     """
     If the given numpy array has a shape suggesting that it has a
-    channel (color) axis (that is, any axis with length 2 (2-color),
+    channel (color) axis (that is, an axis with length 2 (2-color),
     3 (RGB), or 4 (RGBA)), return the index of that axis.
 
+    With the default parameters, the smallest array shapes that will be
+    recognized as having a channel axis are (2, 32, 32) and (32, 32, 2).
+    Note that shapes (32, 2) and (32, 16, 2) will NOT be recognized due
+    to the minimum_image_size parameter. If you have arrays that look
+    like this and you want to recognize them as having a channel axis,
+    you can adjust the minimum_image_size parameter accordingly.
+
     Parameters
     ----------
     data : numpy.ndarray
         The numpy array to check for a channel axis.
 
-    possible_channel_axes : int or list of int, default [0, -1]
-        If None, any axis having length 2, 3, or 4 will be considered
-        a channel axis.
+    possible_channel_axes : int or list of int, default [-1, 0]
+        If None, any axis having length in possible_channel_lengths will
+        be considered a channel axis.
         If an int, only that axis index will be checked.
-        If a list of ints, all axes with those indices will be checked.
-        The default value of [-1, 0] checks the last and first axes, which is
-        almost always where a channel axis will be found.
+        If a list of ints, all axes with those indices will be checked,
+        and the first one that satisfies the other criteria will be returned.
+        The default value of [-1, 0] checks the last and first axes (in that
+        order), which is almost always where a channel axis will be found.
 
     possible_channel_lengths : int or list of int, default [2, 3, 4]
         If an int, only that length will be considered a channel axis.
         If a list of ints, an axis with any of those lengths will be considered
         a channel axis.
 
+    minimum_image_size : tuple of int, default (32, 32)
+        In addition to having an axis with a length in possible_channel_lengths,
+        the data must also have other axes with at least these lengths in order
+        to be considered to have a channel axis. This prevents small arrays
+        with shapes like (3, 3, 3) or (128, 3) from being misinterpreted
+        as having a channel axis when they are probably not intended as such.
+
     Returns
     -------
     int or None
@@ -99,16 +115,46 @@ def find_channel_axis(data,
         axis, so be careful not to do a test like `if find_channel_axis(data):`
         because 0 will evaluate to False even though the data has a channel axis.
         Instead write `if find_channel_axis(data) is not None:`
+
+    Examples
+    --------
+    >>> npimage.find_channel_axis(np.empty((3, 1024, 1024)))
+    0
+    >>> npimage.find_channel_axis(np.empty((1024, 1024, 3)))
+    2
+    >>> npimage.find_channel_axis(np.empty((1024, 3, 1024)))
+    None  # Due to possible_channel_axes=[-1, 0] not being met
+    >>> npimage.find_channel_axis(np.empty((256, 128, 128)))
+    None  # Due to possible_channel_lengths=[2, 3, 4] not being met
+    >>> npimage.find_channel_axis(np.empty((1024, 4)))
+    None  # Due to minimum_image_size=(32, 32) not being met
+    >>> npimage.find_channel_axis(np.empty((30, 30, 4)))
+    None  # Due to minimum_image_size=(32, 32) not being met
+    >>> npimage.find_channel_axis(np.empty((30, 4)), minimum_image_size=0)
+    1
     """
     if isinstance(possible_channel_axes, int):
         possible_channel_axes = [possible_channel_axes]
     if possible_channel_axes is None:
         possible_channel_axes = range(data.ndim)
+
     if isinstance(possible_channel_lengths, int):
         possible_channel_lengths = [possible_channel_lengths]
+
+    if isinstance(minimum_image_size, int):
+        minimum_image_size = (minimum_image_size,)
+
     for axis in possible_channel_axes:
-        if data.shape[axis] in possible_channel_lengths:
-            return axis
+        if data.shape[axis] not in possible_channel_lengths:
+            continue
+        other_axis_lengths = [data.shape[i] for i in range(data.ndim) if i != axis]
+        if len(other_axis_lengths) < len(minimum_image_size):
+            continue
+        other_axis_lengths = sorted(other_axis_lengths, reverse=True)
+        other_axis_lengths = other_axis_lengths[:len(minimum_image_size)]
+        if any(i < j for i, j in zip(other_axis_lengths, minimum_image_size)):
+            continue
+        return axis % data.ndim
     return None
 
 

{numpyimage-3.2.0 → numpyimage-3.3.0}/npimage/vidio.py

@@ -844,9 +844,10 @@ def save_video(data, filename, time_axis=0, color_axis=None, overwrite=False,
         raise ImportError('Missing optional dependency for video processing,'
                           ' run `pip install av tqdm`')
 
-    filename = Path(filename).expanduser()
+    filename = str(filename)
     if filename.split('.')[-1].lower() not in supported_extensions:
         filename += '.mp4'
+    filename = Path(filename).expanduser()
     if filename.exists() and not overwrite:
         raise FileExistsError(f'File {filename} already exists. '
                               'Set overwrite=True to overwrite.')
@@ -879,7 +880,7 @@ def save_video(data, filename, time_axis=0, color_axis=None, overwrite=False,
         n_frames = data.shape[0]
         height, width = data.shape[1:]
 
-    extension = filename.split('.')[-1].lower()
+    extension = filename.suffix.lower().lstrip('.')
     if extension == 'mp4':
         pad = [[0, 0], [0, 0], [0, 0]]
         if height % 2 != 0:

{numpyimage-3.2.0 → numpyimage-3.3.0/numpyimage.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 3.2.0
+Version: 3.3.0
 Summary: Load, save, & manipulate image files as numpy arrays
 Author-email: Jasper Phelps <jasper.s.phelps@gmail.com>
 License: MIT License

{numpyimage-3.2.0 → numpyimage-3.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = 'setuptools.build_meta'
 
 [project]
 name = 'numpyimage'
-version = '3.2.0'
+version = '3.3.0'
 description = 'Load, save, & manipulate image files as numpy arrays'
 readme.file = 'README.md'
 readme.content-type = 'text/markdown'