numpyimage 3.1.2__tar.gz → 3.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 3.1.2
+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.1.2 → numpyimage-3.3.0}/npimage/graphics.py

@@ -1,50 +1,24 @@
 #!/usr/bin/env python3
 """
-This package contains functions for drawing basic geometric shapes, like
-lines and triangles, into 3D numpy arrays (and the code almost works for nD
-arrays). opencv has drawline and drawtriangle functions, but those only
-operate on 2D image arrays. scipy.ndimage provides many other helpful,
-related functions for working with nD image arrays.
-
-Subpixel indexing conventions:
-
-'corner' convention (default): An operation that tries to get or set a pixel
-located at (x, y, z) will actually get or set the pixel with index (floor(x),
-floor(y), floor(z)). Therefore the pixel at location (x, y, z) represents the
-cube of physical locations (a, b, c) such that a is in [x, x+1), b is in [y,
-y+1), and c is [z, z+1). This is called the 'corner' convention because
-integer locations like (5, 2, 10) point to the corner of a voxel.
-
-'center' convention: An operation that tries to get or set a pixel located at
-(x, y, z) will actually get or set the pixel with index (round(x), round(y),
-round(z)). Therefore the pixel at location (x, y, z) represents the cube of
-physical locations (a, b, c) such that a is in [x-0.5, x+0.5), b is in
-[y-0.5, y+0.5), and c is in [z-0.5, z+0.5). This is called the 'center'
-convention because integer locations like (5, 2, 10) point to the middle of a
-voxel. This convention can be selected by passing convention='center' to any
-of the functions in this package (once I finish implementing it).
-
-Functions in this package use non-integer data types to preserve accuracy,
-only flooring or rounding (depending on the convention) during get-pixel or
-set-pixel operations.
-
-
-LIST OF MAJOR TODOS
-
-Implement 'center' convention logic for all functions.
-
-Make the image argument optional for drawpoint, drawline, and drawtriangle,
-in which case they should create an image just large enough to hold the drawn
-object and then return that image
-
-Make get_voxels_within_distance be able to take a multidimensional distance
-argument, in which case it should return all the voxels within an ellipse
-having its radii along each axis specified by the elements of distance. This
-is an extension of the current functionality, since currently a sphere is
-returned with radius in all dimensions equal to the int/float distance.
+Fnctions for drawing basic geometric shapes, like lines and triangles,
+into 3D numpy arrays (and the code almost works for nD arrays for any n).
+Related tools:
+- opencv has drawline and drawtriangle functions, but those only
+  operate on 2D image arrays.
+- scipy.ndimage provides many other helpful, related functions for
+  working with nD image arrays.
+
+
+TODOS:
+- Implement 'center' convention logic for all functions.
+- Make get_voxels_within_distance be able to take a multidimensional distance
+  argument, in which case it should return all the voxels within an ellipse
+  having its radii along each axis specified by the elements of distance. This
+  is an extension of the current functionality, since currently a sphere is
+  returned with radius in all dimensions equal to the int/float distance.
 """
 
-
+from typing import Literal
 import math
 import itertools
 
@@ -56,32 +30,39 @@ from .utils import eq, ifloor, iceil, iround, is_out_of_bounds, remove_out_of_bo
 
 # --- Primitive shapes - points, lines, triangles, circles, spheres --- #
 #TODO out_of_bounds='raise' isn't actually raising a lot of the time. Fix it.
-def drawpoint(image, coord, value, thickness=1,
-              convention='corner', out_of_bounds='ignore'):
+def drawpoint(image, coord, value, thickness=1, **imset_kwargs):
     """
-    TODO docstring
+    Change an image's value at a point or collection of points.
+
+    See npimage.graphics.imset's docstring for info on additional keyword arguments:
+    - convention: Literal['corner', 'center'] = 'corner'
+    - out_of_bounds: Literal['ignore', 'wrap', 'raise'] = 'ignore'
+    - add_missing_dims: Literal[None, 'start', 'end'] = None
     """
     coords = thicken(coord, thickness)
-    imset(image, coords, value,
-          convention=convention, out_of_bounds=out_of_bounds)
+    imset(image, coords, value, **imset_kwargs)
 
 
-# TODO switch to kwargs
 def drawline(image, pt1, pt2, value, thickness=1,
-             convention='corner', out_of_bounds='ignore'):
+             convention='corner', **imset_kwargs):
     """
+    Change an image's values along a line from pt1 to pt2.
+
     DDA algorithm described in
     https://www.tutorialspoint.com/computer_graphics/line_generation_algorithm.htm
     with some additional logic that allows for non-integer point coordinates.
+
+    See npimage.graphics.imset's docstring for info on additional keyword arguments:
+    - convention: Literal['corner', 'center'] = 'corner'
+    - out_of_bounds: Literal['ignore', 'wrap', 'raise'] = 'ignore'
+    - add_missing_dims: Literal[None, 'start', 'end'] = None
     """
     pt1, pt2, long_axis = _preprocess_polygon_vertices(pt1, pt2)
-    #print(f'after preprocessing, pt1 is {pt1}, pt2 is {pt2}, and long_axis is {long_axis}')
+    imset_kwargs['convention'] = convention
 
     # Deal with the start and end points as special - always draw them
-    drawpoint(image, pt1, value, thickness=thickness,
-              convention=convention, out_of_bounds=out_of_bounds)
-    drawpoint(image, pt2, value, thickness=thickness,
-              convention=convention, out_of_bounds=out_of_bounds)
+    drawpoint(image, pt1, value, thickness=thickness, **imset_kwargs)
+    drawpoint(image, pt2, value, thickness=thickness, **imset_kwargs)
 
     vec_1to2 = pt2 - pt1
     if eq(vec_1to2[long_axis], 0):
@@ -95,7 +76,6 @@ def drawline(image, pt1, pt2, value, thickness=1,
         pt2_adjustment = iceil(pt2[long_axis] - 0.5) - 0.5 - pt2[long_axis]
         pt1 += vec_1to2 * pt1_adjustment / vec_1to2[long_axis]
         pt2 += vec_1to2 * pt2_adjustment / vec_1to2[long_axis]
-        #print(f'Adjusted endpoints:\npt1={pt1}\npt2={pt2}')
     elif convention == 'center':
         #TODO Test this block more rigorously for corner case performance
         # Will be marking a pixel every time the line connecting pt1 and
@@ -105,7 +85,6 @@ def drawline(image, pt1, pt2, value, thickness=1,
         pt2_adjustment = iceil(pt2[long_axis] - 1) - pt2[long_axis]
         pt1 += vec_1to2 * pt1_adjustment / vec_1to2[long_axis]
         pt2 += vec_1to2 * pt2_adjustment / vec_1to2[long_axis]
-        #print(f'Adjusted endpoints:\npt1={pt1}\npt2={pt2}')
 
     if pt1[long_axis] > pt2[long_axis]:
         return  # Line is so short that no more points need to be marked
@@ -116,8 +95,7 @@ def drawline(image, pt1, pt2, value, thickness=1,
     n_steps = iround(n_steps)
 
     if n_steps == 0:  # pt1 == pt2, so only one point to mark
-        drawpoint(image, pt1, value, thickness=thickness,
-                  convention=convention, out_of_bounds=out_of_bounds)
+        drawpoint(image, pt1, value, thickness=thickness, **imset_kwargs)
         return
 
     pts = np.outer(np.arange(n_steps+1) / n_steps, vec_1to2) + pt1
@@ -125,22 +103,29 @@ def drawline(image, pt1, pt2, value, thickness=1,
     # slightly (20%) faster than calling drawpoint - despite drawpoint
     # literally just calling thicken and then imset itself. ???
     pts = thicken(pts, thickness)
-    imset(image, pts, value,
-          convention=convention, out_of_bounds=out_of_bounds)
+    imset(image, pts, value, **imset_kwargs)
 
 
-# TODO switch to kwargs
 def drawtriangle(image, pt1, pt2, pt3, value, thickness=1,
-                 watertight=True,
-                 fill_value=None, convention='corner', out_of_bounds='ignore'):
+                 watertight=True, fill_value=None, **imset_kwargs):
+    """
+    Draw a triangle into an image.
+
+    If `fill_value` is None, only the three edges of the triangle will be
+    drawn. If `fill_value` is a number, the inside of the triangle will be
+    drawn with that value. Note that `fill_value` for the inside of the
+    triangle can be the same as or different from `value` for the edge lines.
+
+    See npimage.graphics.imset's docstring for info on additional keyword arguments:
+    - convention: Literal['corner', 'center'] = 'corner'
+    - out_of_bounds: Literal['ignore', 'wrap', 'raise'] = 'ignore'
+    - add_missing_dims: Literal[None, 'start', 'end'] = None
+    """
 
     if fill_value is None:
-        drawline(image, pt1, pt2, value, thickness=thickness,
-                 convention=convention, out_of_bounds=out_of_bounds)
-        drawline(image, pt2, pt3, value, thickness=thickness,
-                 convention=convention, out_of_bounds=out_of_bounds)
-        drawline(image, pt3, pt1, value, thickness=thickness,
-                 convention=convention, out_of_bounds=out_of_bounds)
+        drawline(image, pt1, pt2, value, thickness=thickness, **imset_kwargs)
+        drawline(image, pt2, pt3, value, thickness=thickness, **imset_kwargs)
+        drawline(image, pt3, pt1, value, thickness=thickness, **imset_kwargs)
         return
 
     pt1, pt2, pt3, long_axis = _preprocess_polygon_vertices(pt1, pt2, pt3)
@@ -166,7 +151,7 @@ def drawtriangle(image, pt1, pt2, pt3, value, thickness=1,
 
     try:
         iter(thickness)
-    except:
+    except TypeError:
         thickness = np.full(len(image.shape), thickness)
 
     def draw_perpendicular_from_triangle_base(basept):
@@ -195,8 +180,7 @@ def drawtriangle(image, pt1, pt2, pt3, value, thickness=1,
             else:
                 thickness[long_axis - 2] += 1
 
-        drawline(image, basept, endpt, fill_value, thickness=thickness,
-                 convention=convention, out_of_bounds=out_of_bounds)
+        drawline(image, basept, endpt, fill_value, thickness=thickness, **imset_kwargs)
 
     if n_steps == 0:
         draw_perpendicular_from_triangle_base(pt1_adjusted)
@@ -205,26 +189,27 @@ def drawtriangle(image, pt1, pt2, pt3, value, thickness=1,
         startpt = pt1_adjusted + (i / n_steps) * vec_1to3_adj
         draw_perpendicular_from_triangle_base(startpt)
 
-    drawline(image, pt1, pt2, value, thickness=thickness,
-             convention=convention, out_of_bounds=out_of_bounds)
-    drawline(image, pt2, pt3, value, thickness=thickness,
-             convention=convention, out_of_bounds=out_of_bounds)
-    drawline(image, pt3, pt1, value, thickness=thickness,
-             convention=convention, out_of_bounds=out_of_bounds)
+    drawline(image, pt1, pt2, value, thickness=thickness, **imset_kwargs)
+    drawline(image, pt2, pt3, value, thickness=thickness, **imset_kwargs)
+    drawline(image, pt3, pt1, value, thickness=thickness, **imset_kwargs)
 
 
 def drawcircle(image, center, perpendicular, radius, value,
-               fill=False, spacing=1, **kwargs):
+               fill=False, spacing=1, **imset_kwargs):
     """
-    Draw a circle
-    See drawpoint for all kwargs.
+    Draw a circle into an image.
+
+    See npimage.graphics.imset's docstring for info on additional keyword arguments:
+    - convention: Literal['corner', 'center'] = 'corner'
+    - out_of_bounds: Literal['ignore', 'wrap', 'raise'] = 'ignore'
+    - add_missing_dims: Literal[None, 'start', 'end'] = None
     """
     ndims = 3  # TODO code up logic for determining this from the input
     return_image = False
     if image is None and center is None:
         image = np.zeros((2*iceil(radius) + 1,)*ndims, dtype=np.uint8)
         center = (radius, radius, radius)
-        kwargs['convention'] = 'center'
+        imset_kwargs['convention'] = 'center'
         return_image = True
 
     norm = lambda v: np.sqrt(sum(v**2))
@@ -241,7 +226,6 @@ def drawcircle(image, center, perpendicular, radius, value,
     v0 = v0 / norm(v0)
     v1 = v1 / norm(v1)
 
-    half_circumfrence = math.pi*radius
     num_pts = iceil(math.pi*radius/spacing) + 1
     angles = np.linspace(0, math.pi, num_pts)
     half1 = (np.outer(np.cos(angles), v0)
@@ -249,42 +233,45 @@ def drawcircle(image, center, perpendicular, radius, value,
     half2 = (np.outer(np.cos(angles), v0)
              - np.outer(np.sin(angles), v1)) * radius + center
     if fill:
-        #import npimage # for testing
         for pt1, pt2 in zip(half1, half2):
-            drawline(image, pt1, pt2, value, **kwargs)
-            #print(f'Just drew {pt1}->{pt2}')  # for testing
-            #npimage.imshow(image[0], mode='mpl')  # for testing
+            drawline(image, pt1, pt2, value, **imset_kwargs)
     else:
-        draw = lambda pts: imset(image, pts, value, **kwargs)
-        draw(half1)
-        draw(half2)
+        imset(image, half1, value, **imset_kwargs)
+        imset(image, half2, value, **imset_kwargs)
 
     if return_image:
         return image
 
 
-def drawsphere(*args, **kwargs):
-    drawneighborhood(*args, **kwargs)
-
-
-# TODO switch to kwargs
-def drawneighborhood(image=None, distance=None, ndims=None, value=1,
-                     center=None, voxel_size=None, metric='euclidian',
-                     out_of_bounds='ignore'):
+def drawsphere(image=None, distance=None, ndims=None, value=1,
+               center=None, voxel_size=None, metric='euclidian',
+               **imset_kwargs):
     """
     Draw a value into all pixels within a certain distance of a location.
-    This is almost the same thing as drawpoint, but drawpoint's thickness and
-    drawneighborhood's distance work differently.
+
+    drawsphere is a more general version of drawpoint. These are equivalent:
+    >>> im = np.full((240, 240), 255, dtype=np.uint8)
+    >>> npimage.drawsphere(im, distance=24, value=0, center=(120, 120), metric='chebyshev')
+    >>> npimage.drawpoint(im, (120, 120), 128, thickness=49)
+
+    which both draw boxes. But drawsphere with `metric='euclidian'` actually
+    draws spheres.
+
     If you want an image made for you with size just large enough to fit the
-    requested neighborhood, omit the image argument.
+    requested sphere, leave `image=None`.
+
+    See npimage.graphics.imset's docstring for info on additional keyword arguments:
+    - convention: Literal['corner', 'center'] = 'corner'
+    - out_of_bounds: Literal['ignore', 'wrap', 'raise'] = 'ignore'
+    - add_missing_dims: Literal[None, 'start', 'end'] = None
     """
     if ndims is None:
         try:
             ndims = len(distance)
-        except:
+        except TypeError:
             try:
                 ndims = len(image.shape)
-            except:
+            except TypeError:
                 if voxel_size is not None:
                     ndims = len(voxel_size)
                 elif center is not None:
@@ -292,7 +279,7 @@ def drawneighborhood(image=None, distance=None, ndims=None, value=1,
                 else:
                     raise Exception('Specify the dimensionality you want by'
                                     "passing 'ndims='")
-            
+
     if distance is None and image is None:
         raise Exception('Must specify distance or image.')
 
@@ -334,17 +321,17 @@ def drawneighborhood(image=None, distance=None, ndims=None, value=1,
         else:
             image = np.zeros(ifloor(center + distance + 1))
 
-    #print(f'center={center}')
-    #print(f'distance={distance}')
-    #print(f'image.shape={image.shape}')
-
+    if imset_kwargs.get('add_missing_dims', None) is not None:
+        ndims = None
     voxels = get_voxels_within_distance(distance, center=center, ndims=ndims,
                                         voxel_size=voxel_size, metric=metric)
-    imset(image, voxels, value, out_of_bounds=out_of_bounds)
+    imset(image, voxels, value, **imset_kwargs)
 
     if return_image:
         return image
 
+drawneighborhood = drawsphere  # Function name alias
+
 
 # --- Low-level wrappers for getting and setting values from arrays --- #
 def imget(image, coords, convention='corner',
@@ -369,7 +356,8 @@ def imget(image, coords, convention='corner',
     elif out_of_bounds != 'raise':
         raise ValueError("out_of_bounds must be 'ignore', 'raise', or"
                          f"'wrap' but was {out_of_bounds}.")
-    coords = remove_out_of_bounds(coords, image.shape, allow_negative_wrapping, convention)
+    coords = remove_out_of_bounds(coords, image.shape,
+                                  allow_negative_wrapping, convention)
     if n_original > coords.shape[0]:
         n_out_of_bounds = n_original - coords.shape[0]
         if out_of_bounds == 'raise':
@@ -387,15 +375,72 @@ def imget(image, coords, convention='corner',
         return image[tuple(iround(coords).T)]
 
 
-def imset(image, coords, value, convention='corner', out_of_bounds='ignore'):
+def imset(image, coords, value,
+          convention: Literal['corner', 'center'] = 'corner',
+          out_of_bounds: Literal['ignore', 'wrap', 'raise'] = 'ignore',
+          add_missing_dims: Literal[None, 'start', 'end'] = None):
     """
     Given a numpy array, set a particular coordinate or set of coordinates to
     have a given value.
-    By default, coordinates with negative indices are ignored, i.e. this
-    function won't wrap negative indexes around to access the end of the array,
-    despite numpy arrays normally wrapping negative indices. Refusing to wrap
-    makes more sense in most graphics applications.
-        out_of_bounds, string   : 'ignore' (default), 'wrap', or 'raise'
+
+    Parameters
+    ----------
+    image : numpy.ndarray
+        The image to set pixel value(s) in.
+
+    coords : numpy.ndarray or array-like
+        The coordinate locations to set values of.
+
+    value : int, float, or array-like
+        The value to set the pixel(s) at the given coordinates to.
+
+    convention : {'corner', 'center'}, default 'corner'
+        Whether to truncate ('corner') or round ('center') fractional
+        values in the `coords` argument.
+
+        'corner' (default):
+        In this mode, coordinate (5, 2) and coordinate (4.99, 2) refer
+        to different pixels because pixel borders are at integer values.
+        Implementation: Coordinates (a, b, c) are converted to integer
+        pixel indices via (floor(a), floor(b), floor(c)).
+        Therefore the pixel at integer index (x, y, z) will be addressed
+        by (a, b, c) when a is in [x, x+1), b is in [y, y+1), and c is
+        [z, z+1). This is called the 'corner' convention because integer
+        coordinates like (5, 2, 10) point to the upper-left corner of a
+        pixel. In this case, any tiny decrease from an integer value will
+        end up pointing to a different pixel in the image.
+
+        'center':
+        In this mode, coordinate (5, 2) and coordinate (4.99, 2) refer
+        to the same pixel because pixel borders are at half-integer
+        values, so (4.51, 2) and (4.49, 2) refer to different pixels.
+        Implementation: Coordinates (a, b, c) will be converted to integer
+        pixel indices via (round(a), round(b), round(c)). Therefore the
+        pixel at integer index (x, y, z) will be addressed by (a, b, c)
+        when a is in [x-0.5, x+0.5), b is in [y-0.5, y+0.5), and c is
+        [z-0.5, z+0.5). This is called the 'center' convention because
+        integer coordinates like (5, 2, 10) point to the center of a
+        pixel, so increasing or decreasing any of the coordinate values by
+        up to 0.5 will still point to the same pixel in the image.
+
+    out_of_bounds : {'ignore', 'wrap', 'raise'}, default 'ignore'
+        By default, coordinates with negative indices are ignored, i.e. this
+        function won't wrap negative indexes around to access the end of the
+        array, despite numpy arrays normally wrapping negative indices.
+        Refusing to wrap makes more sense in most graphics applications.
+
+    add_missing_dims : {None, 'start', 'end'}, default None
+        If the `coords` argument has fewer dimensions than the `image`
+        argument, this parameter determines how to handle that mismatch.
+
+        This is useful when you want to set all the rows, columns, or
+        channels of an image to a particular value. For example:
+        - You have a (360, 640, 3) RGB pixel array `image`
+        - You have 100 pixels specified in a (100, 2) array `coords`
+        - You want to make those pixels cyan, i.e. set the values along
+          the last axis to (0, 255, 255)
+        then since the color axis is the last axis, you can call:
+        >>> imset(image, coords, (0, 255, 255), add_missing_dims='end')
     """
     if not isinstance(coords, np.ndarray):
         coords = np.array(coords)
@@ -404,7 +449,15 @@ def imset(image, coords, value, convention='corner', out_of_bounds='ignore'):
         allow_negative_wrapping = True
     else:
         allow_negative_wrapping = False
-    is_oob = is_out_of_bounds(coords, image.shape, allow_negative_wrapping, convention)
+
+    bounds = image.shape
+    if add_missing_dims == 'start':
+        while len(bounds) > coords.shape[1]:
+            bounds = bounds[1:]
+    elif add_missing_dims == 'end':
+        while len(bounds) > coords.shape[1]:
+            bounds = bounds[:-1]
+    is_oob = is_out_of_bounds(coords, bounds, allow_negative_wrapping, convention)
     if is_oob.any():
         if out_of_bounds in ['ignore', 'wrap']:
             coords = coords[~is_oob]
@@ -416,9 +469,18 @@ def imset(image, coords, value, convention='corner', out_of_bounds='ignore'):
                              f"'wrap' but was {out_of_bounds}.")
 
     if convention == 'corner':
-        image[tuple(ifloor(coords).T)] = value
+        slicer = tuple(ifloor(coords).T)
     else:  # convention == 'center'
-        image[tuple(iround(coords).T)] = value
+        slicer = tuple(iround(coords).T)
+
+    if add_missing_dims == 'start':
+        while len(slicer) < image.ndim:
+            slicer = (slice(None),) + slicer
+    elif add_missing_dims == 'end':
+        while len(slicer) < image.ndim:
+            slicer = slicer + (slice(None),)
+
+    image[slicer] = value
 
 
 # --- Drawing shapes composed of many primitives, --- #
@@ -491,18 +553,8 @@ def _preprocess_polygon_vertices(*pts):
 
     pts = list(pts)  # Make mutable
     for i, pt in enumerate(pts):
-    # This block tried to guess whether the user wants center or corner
-    # convention, but now that the functions in this module explicitly include
-    # convention as an argument, it's no longer needed
-    #    if all(isint(pt)):
-    #        pts[i] = np.array(pts[i]) + 0.5
-    #        print(f'Adjusted {i+1}{suffixes.get(i+1, "th")} point to {pts[i]}'\
-    #               ' so it represents the middle of its pixel')
-    #    else:
         pts[i] = np.array(pts[i]).astype(np.float64)
 
-    #    assert pts[i].shape == (n_dims,)
-
     longest_axis = None
     longest_axis_len = -1
     for pt1_idx in range(len(pts)):
@@ -544,7 +596,7 @@ def thicken(pts, thickness=1, no_duplicates=True):
 
     try:
         iter(thickness)
-    except:
+    except TypeError:
         thickness = [thickness] * pts.shape[1]
 
     # TODO make an option for doing spherical thickening using
@@ -634,14 +686,16 @@ def floodfill(image, seed, fill_value, fill_diagonally=False,
     This implementation is very slow and needs improvement
     """
     seed_value = image[seed]
-    if verbose: print(f'seed_value={seed_value}')
+    if verbose:
+        print(f'seed_value={seed_value}')
     if fill_diagonally:
         neighbors = get_voxels_within_distance(1, ndims=len(image.shape),
                                                metric='chebyshev')
     else:
         neighbors = get_voxels_within_distance(1, ndims=len(image.shape))
 
-    if verbose: print(f'neighbors={neighbors}')
+    if verbose:
+        print(f'neighbors={neighbors}')
     neighbors = neighbors[~(neighbors == 0).all(axis=1)]
     fill_mask = np.zeros(image.shape, dtype=bool)
 
@@ -652,12 +706,10 @@ def floodfill(image, seed, fill_value, fill_diagonally=False,
     #TODO learn cython????
 
     def fill(wavefront, iteration):
-        if verbose: print(f'iteration={iteration}, len(wavefront)={len(wavefront)}')
-        #print(wavefront)
-        #fill wavefront
+        if verbose:
+            print(f'iteration={iteration}, len(wavefront)={len(wavefront)}')
         imset(fill_mask, wavefront, True)
         imset(image, wavefront, fill_value)
-        #print(f'image:\n{image}')
 
         #add valid neighbors
         new_wavefront = []
@@ -706,7 +758,6 @@ def to_physical_coordinates(voxel_coordinates, voxel_size, offset=0):
     (in units of microns per voxel) and offset (indicating the physical
     coordinates of the origin voxel, in microns)
     """
-    #TODO test this.
     return voxel_coordinates * voxel_size + offset
 
 
@@ -719,7 +770,4 @@ def to_voxel_coordinates(physical_coordinates, voxel_size, offset=0):
     accuracy, and downstream functions will need to convert to int if these are
     to be used to index an array.
     """
-    #print(f'physical_coordinates={physical_coordinates}')
-    #print(f'offset={offset}')
-    #print(f'voxel_size={voxel_size}')
     return (physical_coordinates - offset) / voxel_size

{numpyimage-3.1.2 → 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.1.2 → 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.1.2 → 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.1.2 → numpyimage-3.3.0}/npimage/vidio.py

@@ -19,7 +19,6 @@ Class list:
 
 from typing import Union, Tuple, Iterator, Literal
 from pathlib import Path
-import os
 import subprocess
 import threading
 import json
@@ -138,13 +137,17 @@ def lazy_load_video(filename) -> Iterator[np.ndarray]:
     except ImportError:
         raise ImportError('Missing optional dependency for video processing,'
                           ' run `pip install av tqdm`')
-    with av.open(filename) as container:
+    with av.open(Path(filename).expanduser()) as container:
         stream = container.streams.video[0]
         for frame in container.decode(stream):
             img = frame.to_ndarray(format='rgb24')
             yield img
 
 
+class VideoSeekError(RuntimeError):
+    pass
+
+
 class VideoStreamer:
     def __init__(self, filename, verbose: bool = False):
         try:
@@ -154,7 +157,7 @@ class VideoStreamer:
             raise ImportError('Missing optional dependency for video processing,'
                               ' run `pip install av tqdm`')
         self.verbose = verbose
-        self.filename = Path(filename)
+        self.filename = Path(filename).expanduser()
         if not self.filename.exists():
             raise FileNotFoundError(f'File {filename} not found')
 
@@ -378,11 +381,14 @@ class VideoStreamer:
                     return frame
                 if frame.pts > target_pts:
                     self._current_frame_number = self.pts_to_frame_number(frame.pts)
-                    raise RuntimeError(f'Frame with PTS {target_pts} not found after'
-                                       f' seeking – current frame PTS: {frame.pts}')
-            raise RuntimeError('Hit end of video before finding frame {frame_number} (PTS '
-                               f'{target_pts}). Last seen frame was {self._current_frame_number}'
-                               f' (PTS {self.frame_number_to_pts(self._current_frame_number)}')
+                    raise VideoSeekError(f'Frame with PTS {target_pts} not found after'
+                                         f' seeking – current frame PTS: {frame.pts}')
+                if type(self.verbose) is int and self.verbose:  # Set verbose=1 to use
+                    print(f'Passing frame {self.pts_to_frame_number(frame.pts)} (PTS {frame.pts})'
+                          f' while decoding to frame {frame_number} (PTS {target_pts})')
+            raise VideoSeekError('Hit end of video before finding frame {frame_number} (PTS '
+                                 f'{target_pts}). Last seen frame was {self._current_frame_number}'
+                                 f' (PTS {self.frame_number_to_pts(self._current_frame_number)}')
 
         if isinstance(frame_number, slice):  # Support slicing
             start, stop, step = frame_number.indices(self.n_frames)
@@ -392,17 +398,39 @@ class VideoStreamer:
             if (self._current_frame_number is None
                     or frame_number <= self._current_frame_number
                     or frame_number > self._current_frame_number + 100):
-                target_pts = self.frame_number_to_pts(frame_number)
+                # We seek to a few frames before the requested frame because
+                # seeking has the undesirable behavior of sometimes landing
+                # at a keyframe just after the requested frame, if a keyframe
+                # exists one or two frames after the requested frame.
+                seek_to_frame = max(0, frame_number - 3)
+                seek_to_pts = self.frame_number_to_pts(seek_to_frame)
                 if self.verbose:
-                    print(f'Seeking to frame {frame_number} (PTS {target_pts})')
-                # The following actually seeks to the closest keyframe before
+                    print(f'Frame {frame_number} requested: Seeking to'
+                          f' frame {seek_to_frame} (PTS {seek_to_pts})')
+                # The seek call actually seeks to the closest keyframe before
                 # target_pts, because it's not possible to seek directly to
                 # non-keyframes due to video files being compressed.
-                self.container.seek(target_pts, any_frame=False,
+                self.container.seek(seek_to_pts, any_frame=False,
                                     backward=True, stream=self.stream)
                 self._frame_iterator = self.container.decode(self.stream)
-            # Now we decode frames forward until we get to the requested frame
-            image = decode_until(frame_number)
+            try:
+                # Now we decode frames forward until we get to the requested frame
+                image = decode_until(frame_number)
+            except VideoSeekError as e:
+                # If we fail on the first attempt, try seeking back
+                # 30 frames (instead of 3) then decoding forward again.
+                seek_to_frame = max(0, frame_number - 30)
+                seek_to_pts = self.frame_number_to_pts(seek_to_frame)
+                if self.verbose:
+                    print(f'[WARNING] {e}')
+                    print(f'[RETRY] Frame {frame_number} requested: Seeking'
+                          f' to frame {seek_to_frame} (PTS {seek_to_pts})')
+                self.container.seek(seek_to_pts, stream=self.stream)
+                self._frame_iterator = self.container.decode(self.stream)
+                # If this one fails too, we let its exception raise.
+                # I haven't seen this ever fail, but who knows.
+                image = decode_until(frame_number)
+
             if self.rotation not in [None, '0', 0]:
                 image = np.rot90(image, k=-int(self.rotation) // 90)
             return image
@@ -517,8 +545,8 @@ class AVVideoWriter:
             raise ImportError('Missing optional dependency for video processing,'
                               ' run `pip install av tqdm`')
         self.av = av
-        filename = os.path.expanduser(str(filename))
-        if os.path.exists(filename) and not overwrite:
+        filename = Path(filename).expanduser()
+        if filename.exists() and not overwrite:
             raise FileExistsError(f'File {filename} already exists. '
                                   'Set overwrite=True to overwrite.')
         self.filename = filename
@@ -622,8 +650,8 @@ class FFmpegVideoWriter:
     def __init__(self, filename, framerate=30, crf=23, compression_speed='medium',
                  codec: Literal['libx264', 'libx265'] = 'libx264',
                  overwrite=False):
-        filename = os.path.expanduser(str(filename))
-        if os.path.exists(filename) and not overwrite:
+        filename = Path(filename).expanduser()
+        if filename.exists() and not overwrite:
             raise FileExistsError(f'File {filename} already exists. '
                                   'Set overwrite=True to overwrite.')
         self.filename = filename
@@ -632,11 +660,6 @@ class FFmpegVideoWriter:
         self.compression_speed = compression_speed
         self.codec = codec_aliases[codec.lower()]
 
-        # Check for existing file
-        if os.path.exists(self.filename) and not overwrite:
-            raise FileExistsError(f'File {self.filename} already exists. '
-                                  'Set overwrite=True to overwrite.')
-
         # Initialize process state
         self._process = None
         self._stdin = None
@@ -821,10 +844,11 @@ 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 = os.path.expanduser(str(filename))
+    filename = str(filename)
     if filename.split('.')[-1].lower() not in supported_extensions:
         filename += '.mp4'
-    if os.path.exists(filename) and not overwrite:
+    filename = Path(filename).expanduser()
+    if filename.exists() and not overwrite:
         raise FileExistsError(f'File {filename} already exists. '
                               'Set overwrite=True to overwrite.')
 
@@ -856,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.1.2 → numpyimage-3.3.0/numpyimage.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 3.1.2
+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.1.2 → numpyimage-3.3.0}/pyproject.toml

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