numpyimage 2.2.0__tar.gz → 2.4.0__tar.gz

{numpyimage-2.2.0 → numpyimage-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 2.2.0
+Version: 2.4.0
 Summary: Load, save, & manipulate image files as numpy arrays
 Author-email: Jasper Phelps <jasper.s.phelps@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -690,6 +690,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
 Requires-Dist: pillow
+Requires-Dist: pillow-heif
 Requires-Dist: tifffile
 Requires-Dist: pynrrd
 Requires-Dist: matplotlib

{numpyimage-2.2.0 → numpyimage-2.4.0}/npimage/core.py

@@ -20,9 +20,21 @@ from . import operations, utils
 
 supported_extensions = [
     'tif', 'tiff', 'jpg', 'jpeg', 'png', 'pbm',
-    'nrrd', 'zarr', 'raw', 'vol', 'ng'
+    'nrrd', 'zarr', 'raw', 'vol', 'ng', 'heic'
 ]
 
+# Flag to track if HEIF opener has been registered
+_heif_opener_registered = False
+
+
+def _ensure_heif_opener_registered():
+    """Register the HEIF opener if not already registered."""
+    global _heif_opener_registered
+    if not _heif_opener_registered:
+        from pillow_heif import register_heif_opener
+        register_heif_opener()
+        _heif_opener_registered = True
+
 
 def load(filename, dim_order='zyx', **kwargs):
     """
@@ -33,7 +45,7 @@ def load(filename, dim_order='zyx', **kwargs):
      images, or yxc for multi-channel (RGB/RGBA) 2D images.
     Set dim_order='xy' if you want to reverse the order of the axes.
     """
-    filename = str(filename)
+    filename = os.path.expanduser(str(filename))
     while filename.endswith('/'):
         filename = filename[:-1]
     if 'format' in kwargs:
@@ -45,7 +57,7 @@ def load(filename, dim_order='zyx', **kwargs):
                          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.')
+        raise ValueError(f'File format of "{filename}" not supported/recognized.')
 
     data = None
     metadata = None
@@ -54,6 +66,11 @@ def load(filename, dim_order='zyx', **kwargs):
         from PIL import Image
         data = np.array(Image.open(filename)) #PIL.Image.open returns zyx order
 
+    if extension == 'heic':
+        _ensure_heif_opener_registered()
+        from PIL import Image
+        data = np.array(Image.open(filename)) #PIL.Image.open returns zyx order
+
     if extension in ['tif', 'tiff']:
         import tifffile
         data = tifffile.imread(filename) #tifffile.imread returns zyx order
@@ -161,7 +178,7 @@ def save(data,
     Currently `pixel_size`, `units`, and `compress` are only recognized
     when saving to .nrrd and .ng files, and ignored otherwise.
     """
-    filename = str(filename)
+    filename = os.path.expanduser(str(filename))
     filename = filename.rstrip('/')
     if os.path.exists(filename) and not overwrite:
         raise FileExistsError(f'File {filename} already exists. '
@@ -195,6 +212,11 @@ def save(data,
         from PIL import Image  # pip install pillow
         Image.fromarray(data).save(filename)
 
+    if extension == 'heic':
+        _ensure_heif_opener_registered()
+        from PIL import Image
+        Image.fromarray(data).save(filename)
+
     if extension == 'pbm':
         from .filetypes import pbm
         pbm.save(data, filename, comments=metadata)
@@ -352,10 +374,10 @@ write = save  # Function name alias
 to_file = save  # Function name alias
 
 
-def save_video(data, filename, time_axis=0, overwrite=False, dim_order='yx',
-               framerate=30, crf=23, compression_speed='medium'):
+def save_video(data, filename, time_axis=0, color_axis=None, overwrite=False,
+               dim_order='yx', framerate=30, crf=23, compression_speed='medium'):
     """
-    Save a 3D numpy array as a video, with a specified axis as the time axis.
+    Save a 3D numpy array of greyscale values OR a 4D numpy array of RGB values as a video
 
     Follows the PyAV cookbook section on generating video from numpy arrays:
     https://pyav.basswood-io.com/docs/develop/cookbook/numpy.html#generating-video
@@ -363,7 +385,7 @@ def save_video(data, filename, time_axis=0, overwrite=False, dim_order='yx',
     Parameters
     ----------
     data : numpy.ndarray or list of filenames
-        A 3D numpy array of pixel values.
+        A 3D (grayscale) or 4D (RGB) numpy array of pixel values.
 
     filename : str
         The filename to save the video to.
@@ -371,24 +393,44 @@ def save_video(data, filename, time_axis=0, overwrite=False, dim_order='yx',
     time_axis : int, default 0
         The axis of the data array that will be played as time in the video.
 
+    color_axis : int or None, default None
+        If not None, specifies the axis of the color channels (e.g., -1 for last axis, 1 for second axis).
+        If None, data is assumed to be grayscale.
+
     overwrite : bool, default False
         Whether to overwrite the file if it already exists.
 
     dim_order : 'yx' (default) or 'xy'
         The order of the spatial dimensions in the input data.
     """
-    if not data.ndim == 3:
-        raise ValueError('Input data must be a 3D numpy array.')
     try:
         import av
     except ImportError:
-        raise ImportError('To save videos, you must have PyAV installed. '
-                          'You can install it with "pip install av".')
-    data = np.moveaxis(data, time_axis, 0)
-    if 'xy' in dim_order:
-        data = data.swapaxes(1, 2)
-    n_frames = data.shape[0]
+        raise ImportError('To save videos, you must have PyAV installed. You can install it with "pip install av".')
+
+    if color_axis is not None:
+        if data.ndim != 4:
+            raise ValueError('Input data must be a 4D numpy array for color video.')
+        # Move time axis to 0, color axis to -1
+        data = np.moveaxis(data, time_axis, 0)
+        if color_axis != -1:
+            data = np.moveaxis(data, color_axis, -1)
+        if 'xy' in dim_order:
+            data = data.swapaxes(1, 2)
+        n_frames = data.shape[0]
+        height, width, channels = data.shape[1:]
+        if channels != 3:
+            raise ValueError('Color video must have 3 channels (RGB).')
+    else:
+        if data.ndim != 3:
+            raise ValueError('Input data must be a 3D numpy array for grayscale video.')
+        data = np.moveaxis(data, time_axis, 0)
+        if 'xy' in dim_order:
+            data = data.swapaxes(1, 2)
+        n_frames = data.shape[0]
+        height, width = data.shape[1:]
 
+    filename = os.path.expanduser(str(filename))
     if filename.split('.')[-1].lower() not in ['mp4', 'mkv', 'avi', 'mov']:
         filename += '.mp4'
     if os.path.exists(filename) and not overwrite:
@@ -397,9 +439,9 @@ def save_video(data, filename, time_axis=0, overwrite=False, dim_order='yx',
     extension = filename.split('.')[-1].lower()
     if extension == 'mp4':
         pad = [[0, 0], [0, 0], [0, 0]]
-        if data.shape[1] % 2 != 0:
+        if height % 2 != 0:
             pad[1][1] = 1
-        if data.shape[2] % 2 != 0:
+        if width % 2 != 0:
             pad[2][1] = 1
         if pad != [[0, 0], [0, 0], [0, 0]]:
             data = np.pad(data, pad, mode='edge')
@@ -412,7 +454,10 @@ def save_video(data, filename, time_axis=0, overwrite=False, dim_order='yx',
     stream.width = data.shape[2]
 
     for frame_i in range(n_frames):
-        frame = av.VideoFrame.from_ndarray(data[frame_i], format='gray')
+        if color_axis is not None:
+            frame = av.VideoFrame.from_ndarray(data[frame_i], format='rgb24')
+        else:
+            frame = av.VideoFrame.from_ndarray(data[frame_i], format='gray')
         for packet in stream.encode(frame):
             container.mux(packet)
 
@@ -535,3 +580,88 @@ def find_channel_axis(data, expected_channel_axis=[0, -1]):
         if data.shape[axis] in [2, 3, 4]:
             return axis
     return None
+
+
+def load_video(filename, force_rgb=False, progress_bar=True):
+    """
+    Load all images in a video file as a numpy array.
+
+    Parameters
+    ----------
+    filename : str
+        Path to the video file
+    force_rgb : bool, default False
+        If True, always return frames as RGB arrays (shape=(H, W, 3))
+        If False, return frames in their native format (e.g., grayscale if possible)
+    progress_bar : bool, default True
+        If True, display a progress bar
+
+    Returns
+    -------
+    data : numpy.ndarray
+        The video frames as a numpy array, shape (num_frames, height, width[, channels])
+    """
+    try:
+        import av
+    except ImportError:
+        raise ImportError('To use load_video, install PyAV: pip install av')
+    from tqdm import tqdm
+    container = av.open(filename)
+    stream = container.streams.video[0]
+    num_frames = stream.frames
+    if not num_frames or num_frames == 0:
+        # If we don't know the number of frames, we can't preallocate, so
+        # it's hard to do better than the following approach (which temporarily
+        # uses double the amount of RAM than the preallocated approach uses).
+        return np.array(list(lazy_load_video(filename, force_rgb=force_rgb)))
+    else:
+        # Load first image to get shape and dtype
+        frame_iter = container.decode(stream)
+        first_frame = next(frame_iter)
+        if force_rgb:
+            first_img = first_frame.to_ndarray(format='rgb24')
+        else:
+            first_img = first_frame.to_ndarray()
+        # Preallocate memory for the entire array
+        data = np.empty((num_frames, *first_img.shape), dtype=first_img.dtype)
+        # Then fill it up frame by frame
+        data[0] = first_img
+        for i, frame in tqdm(enumerate(frame_iter, start=1), total=num_frames,
+                             desc='Loading video', disable=not progress_bar):
+            if force_rgb:
+                img = frame.to_ndarray(format='rgb24')
+            else:
+                img = frame.to_ndarray()
+            data[i] = img
+        return data
+
+
+def lazy_load_video(filename, force_rgb=False):
+    """
+    Lazily load video frames as numpy arrays using PyAV.
+
+    Parameters
+    ----------
+    filename : str
+        Path to the video file.
+    force_rgb : bool, default False
+        If True, always return frames as RGB arrays (shape=(H, W, 3)).
+        If False, return frames in their native format (e.g., grayscale if possible).
+
+    Yields
+    ------
+    frame : np.ndarray
+        Video frame as a numpy array, shape (height, width[, colors]).
+    """
+    try:
+        import av
+    except ImportError:
+        raise ImportError('To use lazy_load_video, install PyAV: pip install av')
+    container = av.open(filename)
+    stream = container.streams.video[0]
+    for frame in container.decode(stream):
+        if force_rgb:
+            img = frame.to_ndarray(format='rgb24')
+        else:
+            img = frame.to_ndarray()
+        yield img

{numpyimage-2.2.0 → numpyimage-2.4.0}/npimage/operations.py

@@ -19,12 +19,14 @@ import numpy as np
 from .utils import iround, eq, isint
 
 
-def squeeze_dtype(image: np.ndarray):
+def squeeze_dtype(image: np.ndarray, minimum_bits=1):
     """
     Cast a numpy array to the smallest possible dtype without losing information.
     """
     if not isinstance(image, np.ndarray):
         raise TypeError('image must be a numpy array')
+    if minimum_bits > 64:
+        raise ValueError('minimum_bits must be <= 64')
 
     im_has_fractions = not np.all(image == np.floor(image))
     if im_has_fractions:
@@ -35,17 +37,17 @@ def squeeze_dtype(image: np.ndarray):
         return image
     elif image.min() < 0:
         candidates = [np.int8, np.int16, np.int32, np.int64]
-    elif image.max() <= 1:
+    elif image.max() <= 1 and minimum_bits <= 1:
         return image.astype(bool, copy=False)
     else:
         candidates = [np.uint8, np.uint16, np.uint32, np.uint64]
 
     image_max = image.max()
-    if image_max <= 1:
+    if image_max <= 1 and minimum_bits <= 1:
         return image.astype(bool, copy=False)
     for dtype in candidates:
         info = np.iinfo(dtype)
-        if image_max <= info.max:
+        if image_max <= info.max and info.bits >= minimum_bits:
             return image.astype(dtype, copy=False)
     raise ValueError('Image has values larger than the maximum representable value')
 
@@ -70,7 +72,8 @@ def to_16bit(image: np.ndarray, **kwargs) -> np.ndarray:
 
 def cast(image: np.ndarray,
          output_dtype: Union[str, np.dtype],
-         maximize_contrast=True,
+         maximize_contrast: bool = False,
+         round_before_cast_to_int: bool = True,
          bottom_percentile=0.05,
          top_percentile=99.95,
          bottom_value=None,
@@ -132,11 +135,15 @@ def cast(image: np.ndarray,
         raise TypeError(f'Unsupported dtype: {output_dtype}')
 
     if not maximize_contrast:
+        if (round_before_cast_to_int
+                and np.issubdtype(output_dtype, np.integer)
+                and not np.issubdtype(image.dtype, np.integer)):
+            image = image.round()
         return np.clip(
             image,
             info.min,
             info.max
-        ).astype(output_dtype)
+        ).astype(output_dtype, copy=False)
 
     if bottom_value is None or top_value is None:
         percentiles = np.percentile(image, [bottom_percentile, top_percentile])

{numpyimage-2.2.0 → numpyimage-2.4.0}/numpyimage.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 2.2.0
+Version: 2.4.0
 Summary: Load, save, & manipulate image files as numpy arrays
 Author-email: Jasper Phelps <jasper.s.phelps@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -690,6 +690,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
 Requires-Dist: pillow
+Requires-Dist: pillow-heif
 Requires-Dist: tifffile
 Requires-Dist: pynrrd
 Requires-Dist: matplotlib

{numpyimage-2.2.0 → numpyimage-2.4.0}/numpyimage.egg-info/SOURCES.txt

@@ -3,17 +3,15 @@ README.md
 pyproject.toml
 npimage/__init__.py
 npimage/align.py
-npimage/align_scratch.py
 npimage/core.py
 npimage/graphics.py
 npimage/nrrd_utils.py
 npimage/operations.py
 npimage/utils.py
-npimage/filetypes/__init__.py
-npimage/filetypes/pbm.py
 numpyimage.egg-info/PKG-INFO
 numpyimage.egg-info/SOURCES.txt
 numpyimage.egg-info/dependency_links.txt
 numpyimage.egg-info/requires.txt
 numpyimage.egg-info/top_level.txt
+tests/test_heic.py
 tests/test_pbm.py

{numpyimage-2.2.0 → numpyimage-2.4.0}/numpyimage.egg-info/requires.txt

@@ -1,5 +1,6 @@
 numpy
 pillow
+pillow-heif
 tifffile
 pynrrd
 matplotlib

{numpyimage-2.2.0 → numpyimage-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = 'setuptools.build_meta'
 
 [project]
 name = 'numpyimage'
-version = '2.2.0'
+version = '2.4.0'
 description = 'Load, save, & manipulate image files as numpy arrays'
 readme.file = 'README.md'
 readme.content-type = 'text/markdown'
@@ -23,6 +23,7 @@ urls = {Repository = 'https://github.com/jasper-tms/npimage'}
 dependencies = [
     'numpy',
     'pillow',
+    'pillow-heif',
     'tifffile',
     'pynrrd',
     'matplotlib',

numpyimage-2.4.0/tests/test_heic.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+
+import os
+import tempfile
+import numpy as np
+import npimage
+
+
+def test_heic_load_save():
+    """Test loading and saving HEIC images."""
+    # Create a simple test image
+    test_data = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
+    
+    with tempfile.TemporaryDirectory() as tmpdir:
+        # Test saving as HEIC
+        heic_filename = os.path.join(tmpdir, "test_image.heic")
+        
+        try:
+            # Save the test data as HEIC
+            npimage.save(test_data, heic_filename)
+            
+            # Verify the file was created
+            assert os.path.exists(heic_filename), "HEIC file was not created"
+            
+            # Load the HEIC file back
+            loaded_data = npimage.load(heic_filename)
+            
+            # Check that the loaded data has the same shape
+            assert loaded_data.shape == test_data.shape, f"Shape mismatch: expected {test_data.shape}, got {loaded_data.shape}"
+            
+            # Check that the data type is correct
+            assert loaded_data.dtype == np.uint8, f"Data type mismatch: expected uint8, got {loaded_data.dtype}"
+            
+            print("Test passed: HEIC load/save functionality works correctly.")
+            
+        except Exception as e:
+            print(f"Test failed with error: {e}")
+            raise
+
+
+def test_heic_extension_support():
+    """Test that HEIC extension is properly recognized."""
+    # Test that HEIC is in the supported extensions
+    assert 'heic' in npimage.core.supported_extensions, "HEIC extension not in supported extensions"
+    
+    # Test that the extension is properly parsed
+    filename = "test_image.heic"
+    extension = filename.split('.')[-1].lower()
+    assert extension == 'heic', f"Extension parsing failed: expected 'heic', got '{extension}'"
+    
+    print("Test passed: HEIC extension is properly supported.")
+
+
+if __name__ == '__main__':
+    try:
+        test_heic_extension_support()
+        test_heic_load_save()
+        print("All HEIC tests passed!")
+    except Exception as e:
+        print(f"HEIC tests failed: {e}")
+        raise

numpyimage-2.2.0/npimage/align_scratch.py

@@ -1,50 +0,0 @@
-
-
-
-def align(im1, im2, num_divisions=4):
-    """
-    Return a translated version of im1 that is aligned with im2.
-
-    To align the images, this function divides im1 into a grid of
-    num_divisions x num_divisions regions. For each region, we find the
-    region in im2 that is most similar to it. After removing outliers
-    for which the similarity score is too low, we calculate the average
-    translation between the two images. We then shift im1 by this
-    average translation.
-    """
-    # The code below is entirely GitHub copilot generated and needs to
-    # be looked at, finished, tested, etc
-
-    # Divide the image into a grid of num_divisions x num_divisions regions
-    height, width = im1.shape
-    region_height = height // num_divisions
-    region_width = width // num_divisions
-
-    # Initialize lists to store the translations for each region
-    translations = []
-
-    # For each region in im1, find the most similar region in im2
-    for i in range(num_divisions):
-        for j in range(num_divisions):
-            # Define the region in im1
-            top_left = (i * region_height, j * region_width)
-            bottom_right = ((i + 1) * region_height, (j + 1) * region_width)
-            region1 = im1[top_left[0]:bottom_right[0], top_left[1]:bottom_right[1]]
-
-            # Define the search region in im2
-            search_bbox = (slice(max(0, top_left[0] - region_height),
-                                 min(height, bottom_right[0] + region_height)),
-                           slice(max(0, top_left[1] - region_width),
-                                 min(width, bottom_right[1] + region_width)))
-
-            # Find the most similar region in im2
-            top_left2, score = find_landmark(im2, region1, search_bbox=search_bbox)
-
-            # Add the translation to the list of translations
-            translations.append((top_left[0] - top_left2[0], top_left[1] - top_left2[1]))
-
-    # Remove outliers from the list of translations
-    translations = np.array(translations)
-    mean_translations = np.mean(translations)
-    # Shift im1 by the average translation
-    aligned_im1 = np.roll(im1, mean_translations, axis=(0, 1))

numpyimage-2.2.0/npimage/filetypes/__init__.py

@@ -1 +0,0 @@
-__all__ = ['pbm']

numpyimage-2.2.0/npimage/filetypes/pbm.py

@@ -1,103 +0,0 @@
-#!/usr/bin/env python3
-"""
-Read and write PBM files, whose format is specified at
-http://netpbm.sourceforge.net/doc/pbm.html
-"""
-
-import numpy as np
-
-
-def load(filename):
-    """
-    Load pixel data from a PBM file and return it as a numpy array.
-    The returned array has dimensions ordered y then x, as is
-    standard in Python. This means data.shape is ordered (height, width)
-    """
-    with open(filename, 'rb') as f:
-        assert f.readline() == b'P4\n', 'This is not a PBM file'
-        line = f.readline()
-        while line.startswith(b'#'):  # Print and skip comments
-            print(line.decode().strip('\n'))
-            line = f.readline()
-        line = line.decode().strip().split()
-        w = int(line[0])
-        h = int(line[1])
-
-        # Calculate the number of bytes per row (padded to the next byte boundary)
-        row_bytes = (w + 7) // 8
-        data = np.frombuffer(f.read(row_bytes * h), dtype=np.uint8)
-
-        # Unpack bits and reshape, then slice to remove padding bits
-        data = np.unpackbits(data).reshape((h, row_bytes * 8))[:, :w]
-
-    return data.astype(bool)
-
-
-def save(data, filename, comments=None):
-    """
-    Write a numpy array to file in PBM format
-    """
-    if not isinstance(data, np.ndarray):
-        raise TypeError('data must be a np.ndarray but was {}'.format(type(data)))
-    if not isinstance(filename, str):
-        raise TypeError('filename must be a str but was {}'.format(type(filename)))
-    if comments is not None and not isinstance(comments, str):
-        raise TypeError('comments must be a str but was {}'.format(type(comments)))
-    with open(filename, 'wb') as f:
-        # Header
-        f.write(b'P4\n')
-
-        # Comments
-        if comments is not None:
-            # Insist on each line starting with a '# '
-            comments = '# ' + comments.replace('\n', '\n# ')
-            # Remove any double '# ', if we created any
-            comments = comments.replace('# # ', '# ')
-            while any([comments.endswith(c) for c in ['#', ' ', '\n']]):
-                comments = comments[:-1]
-            print(comments)
-            f.write(comments.encode())
-            f.write(b'\n')
-
-        # Size
-        f.write(str(data.shape[1]).encode())
-        f.write(b' ')
-        f.write(str(data.shape[0]).encode())
-        f.write(b'\n')
-
-        # Data
-        # Pad each row to the next byte boundary
-        row_bytes = (data.shape[1] + 7) // 8
-        padded_data = np.zeros((data.shape[0], row_bytes * 8), dtype=bool)
-        padded_data[:, :data.shape[1]] = data
-        f.write(np.packbits(padded_data).tobytes())
-
-
-def predict_file_size(data: np.ndarray) -> int:
-    """
-    Predict the file size of a PBM file given the image data.
-
-    Parameters
-    ----------
-    data : np.ndarray
-        The image data as a numpy array.
-
-    Returns
-    -------
-    int
-        The predicted file size in bytes.
-    """
-    if not isinstance(data, np.ndarray):
-        raise TypeError('data must be a np.ndarray but was {}'.format(type(data)))
-
-    # Header: 'P4\n' (3 bytes)
-    header_size = 3
-
-    # Dimensions: '<width> <height>\n'
-    dimensions_size = len(f"{data.shape[1]} {data.shape[0]}\n")
-
-    # Data: Each row is padded to the next byte boundary
-    row_bytes = (data.shape[1] + 7) // 8
-    data_size = row_bytes * data.shape[0]
-
-    return header_size + dimensions_size + data_size