numpyimage 3.7.0__tar.gz → 3.8.0__tar.gz

{numpyimage-3.7.0 → numpyimage-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 3.7.0
+Version: 3.8.0
 Summary: Load, save, & manipulate image files as numpy arrays
 Author-email: Jasper Phelps <jasper.s.phelps@gmail.com>
 License: MIT License
@@ -42,21 +42,38 @@ Requires-Dist: pillow-heif
 Requires-Dist: tifffile
 Requires-Dist: pynrrd
 Requires-Dist: matplotlib
-Requires-Dist: opencv-python-headless
+Provides-Extra: vid
+Requires-Dist: av; extra == "vid"
+Provides-Extra: align
+Requires-Dist: opencv-python-headless; extra == "align"
 Provides-Extra: all
 Requires-Dist: av; extra == "all"
+Requires-Dist: opencv-python-headless; extra == "all"
+Provides-Extra: dev
+Requires-Dist: av; extra == "dev"
+Requires-Dist: opencv-python-headless; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: psutil; extra == "dev"
 Dynamic: license-file
 
-# npimage
+# npimage: Load, save & manipulate numpy arrays representing images & videos
+
+[![Tests](https://github.com/jasper-tms/npimage/actions/workflows/tests.yml/badge.svg)](https://github.com/jasper-tms/npimage/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/jasper-tms/npimage/branch/main/graph/badge.svg)](https://codecov.io/gh/jasper-tms/npimage)
+[![PyPI version](https://img.shields.io/pypi/v/numpyimage)](https://pypi.org/project/numpyimage/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/numpyimage)](https://pypi.org/project/numpyimage/)
+[![License](https://img.shields.io/github/license/jasper-tms/npimage)](https://github.com/jasper-tms/npimage/blob/main/LICENSE)
+
 Need to load pixel values from image files as numpy arrays, and hate having to remember whether you should use PIL, tifffile, matplotlib, or something else? Hate having to deal with the fact that those libraries all use different function names and syntaxes? Wish you could just provide a filename and get back a numpy array? This library's `imageio.py` does that, with `array = npimage.load(filename)`, `npimage.save(array, filename)`, and `npimage.show(array)` functions that let you easily handle a number of common image file formats without having to remember library-specific syntax. Additionally, `vidio.py` provides `array = npimage.load_video(filename)` and `npimage.save_video(array, filename)` for videos as well. (Another similar library to consider using is [imageio](https://pypi.org/project/imageio/).)
 
-Want to draw simple shapes like lines, triangles, and circles into 3D numpy arrays? Frustrated that the python libraries you can find online like `opencv` and `skimage.draw` work on 2D arrays but not 3D? I wrote some functions in `graphics.py` that do the trick in 3D. (If you know of another library that can do this, please let me know!)
+Want to draw simple shapes like lines, triangles, and circles into 3D numpy arrays? Frustrated that the python libraries you can find online like `opencv` and `skimage.draw` work on 2D arrays but not 3D/4D/+? I wrote some functions in `graphics.py` that do the trick.
 
 
 ### Documentation
 - `imageio.py`: load, save, or show images.
 - `vidio.py`: load or save videos.
-- `graphics.py`: draw points, lines, triangles, circles, or spheres into 2D or 3D numpy arrays representing image volumes.
+- `graphics.py`: draw points, lines, triangles, circles, or spheres into 2D/3D/+D numpy arrays representing image data.
 - `nrrd_utils.py`: compress or read metadata from `.nrrd` files.
 - `operations.py`: perform operations on images.
 
@@ -70,6 +87,9 @@ As is always the case in python, consider making a virtual environment (using yo
 **Option 1:** `pip install` from PyPI:
 
     pip install numpyimage
+    pip install 'numpyimage[vid]'  # If you also want to install the video loading/saving dependencies
+    pip install 'numpyimage[align]'  # If you also want to install the image alignment dependencies
+    pip install 'numpyimage[all]'  # If you want to install both video and alignment dependencies
 
 (Unfortunately the name `npimage` was already taken on PyPI, so `pip install npimage` will get you a different package.)
 
@@ -82,6 +102,6 @@ As is always the case in python, consider making a virtual environment (using yo
     cd ~/repos  # Or wherever on your computer you want to download this code to
     git clone https://github.com/jasper-tms/npimage.git
     cd npimage
-    pip install .
+    pip install '.[all]'
 
 **After installing,** you can import this package in python using `import npimage` (not `import numpyimage`!)

{numpyimage-3.7.0 → numpyimage-3.8.0}/README.md

@@ -1,13 +1,20 @@
-# npimage
+# npimage: Load, save & manipulate numpy arrays representing images & videos
+
+[![Tests](https://github.com/jasper-tms/npimage/actions/workflows/tests.yml/badge.svg)](https://github.com/jasper-tms/npimage/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/jasper-tms/npimage/branch/main/graph/badge.svg)](https://codecov.io/gh/jasper-tms/npimage)
+[![PyPI version](https://img.shields.io/pypi/v/numpyimage)](https://pypi.org/project/numpyimage/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/numpyimage)](https://pypi.org/project/numpyimage/)
+[![License](https://img.shields.io/github/license/jasper-tms/npimage)](https://github.com/jasper-tms/npimage/blob/main/LICENSE)
+
 Need to load pixel values from image files as numpy arrays, and hate having to remember whether you should use PIL, tifffile, matplotlib, or something else? Hate having to deal with the fact that those libraries all use different function names and syntaxes? Wish you could just provide a filename and get back a numpy array? This library's `imageio.py` does that, with `array = npimage.load(filename)`, `npimage.save(array, filename)`, and `npimage.show(array)` functions that let you easily handle a number of common image file formats without having to remember library-specific syntax. Additionally, `vidio.py` provides `array = npimage.load_video(filename)` and `npimage.save_video(array, filename)` for videos as well. (Another similar library to consider using is [imageio](https://pypi.org/project/imageio/).)
 
-Want to draw simple shapes like lines, triangles, and circles into 3D numpy arrays? Frustrated that the python libraries you can find online like `opencv` and `skimage.draw` work on 2D arrays but not 3D? I wrote some functions in `graphics.py` that do the trick in 3D. (If you know of another library that can do this, please let me know!)
+Want to draw simple shapes like lines, triangles, and circles into 3D numpy arrays? Frustrated that the python libraries you can find online like `opencv` and `skimage.draw` work on 2D arrays but not 3D/4D/+? I wrote some functions in `graphics.py` that do the trick.
 
 
 ### Documentation
 - `imageio.py`: load, save, or show images.
 - `vidio.py`: load or save videos.
-- `graphics.py`: draw points, lines, triangles, circles, or spheres into 2D or 3D numpy arrays representing image volumes.
+- `graphics.py`: draw points, lines, triangles, circles, or spheres into 2D/3D/+D numpy arrays representing image data.
 - `nrrd_utils.py`: compress or read metadata from `.nrrd` files.
 - `operations.py`: perform operations on images.
 
@@ -21,6 +28,9 @@ As is always the case in python, consider making a virtual environment (using yo
 **Option 1:** `pip install` from PyPI:
 
     pip install numpyimage
+    pip install 'numpyimage[vid]'  # If you also want to install the video loading/saving dependencies
+    pip install 'numpyimage[align]'  # If you also want to install the image alignment dependencies
+    pip install 'numpyimage[all]'  # If you want to install both video and alignment dependencies
 
 (Unfortunately the name `npimage` was already taken on PyPI, so `pip install npimage` will get you a different package.)
 
@@ -33,6 +43,6 @@ As is always the case in python, consider making a virtual environment (using yo
     cd ~/repos  # Or wherever on your computer you want to download this code to
     git clone https://github.com/jasper-tms/npimage.git
     cd npimage
-    pip install .
+    pip install '.[all]'
 
 **After installing,** you can import this package in python using `import npimage` (not `import numpyimage`!)

{numpyimage-3.7.0 → numpyimage-3.8.0}/npimage/align.py

@@ -2,18 +2,15 @@
 """
 Functions for aligning images.
 """
-from typing import Optional, Tuple, Literal
+from typing import Optional, Tuple
 
 import numpy as np
-import cv2 as cv
 
 
 def find_landmark(image: np.ndarray,
                   landmark: np.ndarray,
                   search_bbox: Optional[Tuple[Tuple[int, int], Tuple[int, int]]] = None,
-                  metric: Literal[cv.TM_SQDIFF, cv.TM_SQDIFF_NORMED,
-                                  cv.TM_CCORR, cv.TM_CCORR_NORMED,
-                                  cv.TM_CCOEFF, cv.TM_CCOEFF_NORMED] = cv.TM_CCOEFF_NORMED,
+                  metric: Optional[int] = None,
                   subpixel_accuracy: bool = True
                   ) -> Tuple[Tuple[int, int], float]:
     """
@@ -45,7 +42,8 @@ def find_landmark(image: np.ndarray,
     metric : cv.TemplateMatchModes, optional
         The metric to use to compare the landmark to the image. Options are
         cv.TM_SQDIFF, cv.TM_SQDIFF_NORMED, cv.TM_CCORR, cv.TM_CCORR_NORMED,
-        cv.TM_CCOEFF, cv.TM_CCOEFF_NORMED. Default is cv.TM_CCOEFF_NORMED.
+        cv.TM_CCOEFF, cv.TM_CCOEFF_NORMED.
+        If left as None, defaults to cv.TM_CCOEFF_NORMED.
 
     Returns
     -------
@@ -57,6 +55,17 @@ def find_landmark(image: np.ndarray,
             The score of the match, from 0 to 1. A score of 1 indicates
             a perfect match.
     """
+    try:
+        import cv2 as cv
+    except ImportError as e:
+        raise ImportError(
+            'find_landmark requires opencv. Install it with '
+            '`pip install numpyimage[align]` or `pip install opencv-python-headless`.'
+        ) from e
+
+    if metric is None:
+        metric = cv.TM_CCOEFF_NORMED
+
     if search_bbox is not None:
         if all(isinstance(el, slice) for el in search_bbox):
             img_to_search = image[search_bbox[0], search_bbox[1]]

{numpyimage-3.7.0 → numpyimage-3.8.0}/npimage/graphics.py

@@ -399,10 +399,14 @@ def imset(image, coords, value,
     Parameters
     ----------
     image : numpy.ndarray
-        The image to set pixel value(s) in.
+        The N-dimensional image to set pixel value(s) in.
 
     coords : numpy.ndarray or array-like
-        The coordinate locations to set values of.
+        The coordinate locations to set values of. Must be a 2D array
+        of shape (C, M) where C is however many coordinates you want to
+        set, and M must equal N (number of dimensions in `image`) if
+        `add_missing_dims` is None, or M can be less than N if
+        `add_missing_dims` is 'start' or 'end'.
 
     value : int, float, or array-like
         The value to set the pixel(s) at the given coordinates to.
@@ -443,20 +447,26 @@ def imset(image, coords, value,
         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.
-
+        If `coords` has fewer columns (M) than `image` has dimensions (N),
+        this parameter determines whether to add columns of slice(None) to
+        the 'start' or 'end' of the coordinate list (or to raise an error
+        when set to None).
         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')
+        channels of an image to a particular value. See `Examples` below
+
+    Examples
+    --------
+    Using `add_missing_dims` to set RGB pixels in a color image. Let's say:
+    - 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)
+    coords = coords[~np.isnan(coords).any(axis=1)]
 
     if out_of_bounds == 'wrap':
         allow_negative_wrapping = True

{numpyimage-3.7.0 → numpyimage-3.8.0}/npimage/imageio.py

@@ -452,6 +452,32 @@ def _ensure_heif_opener_registered() -> None:
     """Register the HEIF opener if not already registered."""
     global _heif_opener_registered
     if not _heif_opener_registered:
+        _check_pyav_not_loaded_before_heif()
         from pillow_heif import register_heif_opener
         register_heif_opener()
         _heif_opener_registered = True
+
+
+def _check_pyav_not_loaded_before_heif() -> None:
+    """Raise a clear error if PyAV has been imported before HEIF.
+
+    On macOS, loading PyAV's bundled native libraries before libheif causes a
+    segfault inside pillow_heif when it first initializes. Loading libheif
+    first (or not loading PyAV at all) avoids the crash. Once libheif is
+    loaded, further HEIF operations and PyAV use coexist fine in the same
+    process.
+    """
+    import sys
+    if sys.platform != 'darwin' or 'av' not in sys.modules:
+        return
+    raise RuntimeError(
+        'Cannot open a HEIC file: PyAV (`av`) has already been imported in '
+        'this process, which on macOS causes pillow_heif to segfault when it '
+        'first loads libheif.\n\n'
+        'Workarounds:\n'
+        '  1. Open/save your HEIC files before any code path that imports '
+        '`av` runs (e.g. before using npimage.VideoStreamer, AVVideoWriter, '
+        'or any other code that uses PyAV).\n'
+        '  2. Do HEIC I/O in a separate Python process from your video I/O.\n'
+        '  3. Use a different image format (PNG, JPEG, TIFF).'
+    )

{numpyimage-3.7.0 → numpyimage-3.8.0}/npimage/vidio.py

@@ -11,7 +11,8 @@ Function list:
 
 Class list:
 - VideoStreamer: Provides fast random access to frames in a video file
-    via VideoStreamer[frame_number].
+    via VideoStreamer[frame_number], or by time in seconds via
+    VideoStreamer.t[time_in_seconds].
 - VideoWriter: Allows writing frames one-by-one to a video file via
     VideoWriter.write(image). This can be advantageous compared to save_video
     because you don't ever have to have all the frames in memory at once.
@@ -22,6 +23,8 @@ from pathlib import Path
 import subprocess
 import threading
 import json
+import math
+import bisect
 from fractions import Fraction
 
 import numpy as np
@@ -247,9 +250,10 @@ class VideoStreamer:
 
         self.index_filename = self.filename.with_suffix(self.filename.suffix + '.index')
         self._build_index(cache_index=cache_index)
+        self.t = _VideoStreamerTimeIndexer(self)
 
     def _build_index(self, cache_index='auto'):
-        if self.index_filename.exists():
+        if cache_index and self.index_filename.exists():
             return self._load_index()
         if self.verbose:
             print('Building frame timestamp index for fast random frame access...')
@@ -301,9 +305,8 @@ class VideoStreamer:
         if len(frames_pts) == 0:
             raise RuntimeError('No timestamps found in frame metadata')
 
-        self.frames_pts = frames_pts
         self.n_frames = len(frames_pts)
-        self.pts0 = self.frames_pts[0]
+        self.pts0 = frames_pts[0]
         self.rotation = _get_rotation_from_metadata(self.filename)
         index = {}
 
@@ -319,10 +322,14 @@ class VideoStreamer:
             else:
                 index['framerate'] = {'numerator': self._framerate.numerator,
                                       'denominator': self._framerate.denominator}
+            self.frames_pts = range(self.pts0,
+                                    self.pts0 + self.pts_delta * self.n_frames,
+                                    self.pts_delta)
         else:
             # The video is variable framerate
             self._framerate = 'variable'
             index['framerate'] = 'variable'
+            self.frames_pts = frames_pts
 
         index['n_frames'] = self.n_frames
         index['rotation'] = self.rotation
@@ -368,6 +375,9 @@ class VideoStreamer:
                 raise ValueError('pts_delta does not appear to be an integer. This is'
                                  ' unexpected and may indicate a malformed index.')
             self.pts_delta = self.pts_delta.numerator
+            self.frames_pts = range(self.pts0,
+                                    self.pts0 + self.pts_delta * self.n_frames,
+                                    self.pts_delta)
 
     @property
     def framerate(self) -> Union[float, Literal['variable']]:
@@ -378,9 +388,11 @@ class VideoStreamer:
     @property
     def fps(self) -> float:
         """
-        Note that fps always returns a float even if the framerate is 'variable'.
-        (If framerate is 'variable', fps returns exactly what its name, "frames per second",
-        implies: the number of frame intervals divided by the video duration in seconds.)
+        Frames per second, returned as a float even when the framerate is
+        'variable'. For variable-framerate videos this is the average rate,
+        equal to `n_frames / duration`, equivalently the number of frame
+        intervals divided by the time span between the first and last frames'
+        timestamps.
         """
         if self.framerate == 'variable':
             return float((self.n_frames - 1) / self.time_base
@@ -396,7 +408,21 @@ class VideoStreamer:
 
     @property
     def duration(self) -> float:
-        return float((self.frames_pts[-1] - self.frames_pts[0]) * self.time_base)
+        """
+        Total playback duration of the video in seconds, equal to
+        `n_frames / fps`.
+
+        Each frame is treated as occupying one inter-frame interval on
+        screen, so the duration extends from the first frame's timestamp to
+        one mean inter-frame interval past the last frame's timestamp. For
+        constant-framerate videos this is exactly `n_frames * timestep`.
+        For variable-framerate videos the last frame's display interval is
+        assumed to equal the mean inter-frame interval, which may differ
+        slightly from ffprobe's reported duration (ffprobe trusts the
+        encoder-written last-frame duration metadata, which is encoder-
+        dependent).
+        """
+        return float(self.n_frames / self.fps)
 
     def frame_number_to_pts(self, frame_number: int) -> int:
         if hasattr(frame_number, '__iter__'):
@@ -612,6 +638,76 @@ class VideoStreamer:
         self.close()
 
 
+class _VideoStreamerTimeIndexer:
+    """
+    Helper exposing time-based indexing on a VideoStreamer via
+    ``streamer.t[time_in_seconds]``.
+
+    Returns a 3-tuple ``(image, timestamp, frame_index)`` for the frame
+    that is "on screen" at the requested time:
+      - ``image`` (np.ndarray): the frame's pixel data
+      - ``timestamp`` (float): the frame's actual timestamp in seconds
+      - ``frame_index`` (int): the frame's integer index in the video
+
+    Each frame N is treated as occupying the half-open interval
+    ``[frame_N_timestamp, frame_{N+1}_timestamp)``, and the last frame
+    occupies one mean inter-frame interval past its timestamp. The lookup
+    is therefore "largest frame timestamp less than or equal to the
+    requested time", with a half-tick eps tolerance so that a request for
+    the exact timestamp of frame N reliably returns frame N even when
+    floating-point arithmetic has nudged the value slightly below.
+
+    Valid times span ``[first_frame_timestamp, end_of_playback)``, where
+    ``end_of_playback = first_frame_timestamp + duration``.
+
+    Negative times wrap around relative to ``end_of_playback``, mirroring
+    how negative integer indices wrap on ``VideoStreamer``: a time of
+    ``-x`` resolves to ``end_of_playback - x``. Times more negative than
+    ``-duration`` raise ``IndexError``.
+    """
+    def __init__(self, streamer: 'VideoStreamer'):
+        self._streamer = streamer
+
+    def __getitem__(self, time) -> Tuple[np.ndarray, float, int]:
+        if not np.issubdtype(type(time), np.number):
+            raise TypeError(f'Time index must be a number, got {type(time).__name__}')
+        s = self._streamer
+        time = float(time)
+        first_frame_time = s.frame_number_to_time(0)
+        end_of_playback = first_frame_time + s.duration
+        if time < 0:
+            if time < -s.duration:
+                raise IndexError(f'Negative time {time:g} s is more than one'
+                                 f' video duration ({s.duration:g} s) before'
+                                 f' the end of the video.')
+            time = time + end_of_playback
+        if time >= end_of_playback:
+            raise IndexError(f'No frame at time {time:g} s (playback'
+                             f' ends at {end_of_playback:g} s).')
+        if time < first_frame_time:
+            raise IndexError(f'Time {time:g} s is before the first frame'
+                             f' (timestamp {first_frame_time:g} s).')
+        # Convert the requested time to a fractional PTS, then add half a
+        # time_base tick. The eps shift means a request for the exact
+        # timestamp of frame N returns frame N (rather than frame N-1) even
+        # if float arithmetic has nudged the converted value below the
+        # stored integer PTS.
+        target_pts = time / float(s.time_base) + 0.5
+        if s._framerate == 'variable':
+            # Largest index i with s.frames_pts[i] <= target_pts.
+            frame_number = bisect.bisect_right(s.frames_pts, target_pts) - 1
+        else:
+            offset = target_pts - s.pts0
+            frame_number = math.floor(offset / s.pts_delta)
+        # The bound checks above guarantee frame_number lands in
+        # [0, n_frames - 1] under exact arithmetic. Clamp defensively for
+        # the float-roundoff edge at exactly time == end_of_playback - eps.
+        frame_number = max(0, min(frame_number, s.n_frames - 1))
+        image = s._get_frame(frame_number)
+        timestamp = s.frame_number_to_time(frame_number)
+        return (image, timestamp, frame_number)
+
+
 class AVVideoWriter:
     """
     Create a video writer object for saving frames to a video file.
@@ -655,6 +751,9 @@ class AVVideoWriter:
             raise FileExistsError(f'File {filename} already exists. '
                                   'Set overwrite=True to overwrite.')
         self.filename = filename
+        if not np.issubdtype(type(framerate), np.number):
+            raise TypeError('framerate must be a number but got'
+                            f' type {type(framerate)} instead')
         self._framerate = utils.limit_fraction(framerate)
         self.crf = crf
         self.compression_speed = compression_speed
@@ -770,6 +869,9 @@ class FFmpegVideoWriter:
             raise FileExistsError(f'File {filename} already exists. '
                                   'Set overwrite=True to overwrite.')
         self.filename = filename
+        if not np.issubdtype(type(framerate), np.number):
+            raise TypeError('framerate must be a number but got'
+                            f' type {type(framerate)} instead')
         self._framerate = utils.limit_fraction(framerate)
         self.crf = crf
         self.compression_speed = compression_speed

{numpyimage-3.7.0 → numpyimage-3.8.0}/numpyimage.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 3.7.0
+Version: 3.8.0
 Summary: Load, save, & manipulate image files as numpy arrays
 Author-email: Jasper Phelps <jasper.s.phelps@gmail.com>
 License: MIT License
@@ -42,21 +42,38 @@ Requires-Dist: pillow-heif
 Requires-Dist: tifffile
 Requires-Dist: pynrrd
 Requires-Dist: matplotlib
-Requires-Dist: opencv-python-headless
+Provides-Extra: vid
+Requires-Dist: av; extra == "vid"
+Provides-Extra: align
+Requires-Dist: opencv-python-headless; extra == "align"
 Provides-Extra: all
 Requires-Dist: av; extra == "all"
+Requires-Dist: opencv-python-headless; extra == "all"
+Provides-Extra: dev
+Requires-Dist: av; extra == "dev"
+Requires-Dist: opencv-python-headless; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: psutil; extra == "dev"
 Dynamic: license-file
 
-# npimage
+# npimage: Load, save & manipulate numpy arrays representing images & videos
+
+[![Tests](https://github.com/jasper-tms/npimage/actions/workflows/tests.yml/badge.svg)](https://github.com/jasper-tms/npimage/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/jasper-tms/npimage/branch/main/graph/badge.svg)](https://codecov.io/gh/jasper-tms/npimage)
+[![PyPI version](https://img.shields.io/pypi/v/numpyimage)](https://pypi.org/project/numpyimage/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/numpyimage)](https://pypi.org/project/numpyimage/)
+[![License](https://img.shields.io/github/license/jasper-tms/npimage)](https://github.com/jasper-tms/npimage/blob/main/LICENSE)
+
 Need to load pixel values from image files as numpy arrays, and hate having to remember whether you should use PIL, tifffile, matplotlib, or something else? Hate having to deal with the fact that those libraries all use different function names and syntaxes? Wish you could just provide a filename and get back a numpy array? This library's `imageio.py` does that, with `array = npimage.load(filename)`, `npimage.save(array, filename)`, and `npimage.show(array)` functions that let you easily handle a number of common image file formats without having to remember library-specific syntax. Additionally, `vidio.py` provides `array = npimage.load_video(filename)` and `npimage.save_video(array, filename)` for videos as well. (Another similar library to consider using is [imageio](https://pypi.org/project/imageio/).)
 
-Want to draw simple shapes like lines, triangles, and circles into 3D numpy arrays? Frustrated that the python libraries you can find online like `opencv` and `skimage.draw` work on 2D arrays but not 3D? I wrote some functions in `graphics.py` that do the trick in 3D. (If you know of another library that can do this, please let me know!)
+Want to draw simple shapes like lines, triangles, and circles into 3D numpy arrays? Frustrated that the python libraries you can find online like `opencv` and `skimage.draw` work on 2D arrays but not 3D/4D/+? I wrote some functions in `graphics.py` that do the trick.
 
 
 ### Documentation
 - `imageio.py`: load, save, or show images.
 - `vidio.py`: load or save videos.
-- `graphics.py`: draw points, lines, triangles, circles, or spheres into 2D or 3D numpy arrays representing image volumes.
+- `graphics.py`: draw points, lines, triangles, circles, or spheres into 2D/3D/+D numpy arrays representing image data.
 - `nrrd_utils.py`: compress or read metadata from `.nrrd` files.
 - `operations.py`: perform operations on images.
 
@@ -70,6 +87,9 @@ As is always the case in python, consider making a virtual environment (using yo
 **Option 1:** `pip install` from PyPI:
 
     pip install numpyimage
+    pip install 'numpyimage[vid]'  # If you also want to install the video loading/saving dependencies
+    pip install 'numpyimage[align]'  # If you also want to install the image alignment dependencies
+    pip install 'numpyimage[all]'  # If you want to install both video and alignment dependencies
 
 (Unfortunately the name `npimage` was already taken on PyPI, so `pip install npimage` will get you a different package.)
 
@@ -82,6 +102,6 @@ As is always the case in python, consider making a virtual environment (using yo
     cd ~/repos  # Or wherever on your computer you want to download this code to
     git clone https://github.com/jasper-tms/npimage.git
     cd npimage
-    pip install .
+    pip install '.[all]'
 
 **After installing,** you can import this package in python using `import npimage` (not `import numpyimage`!)

numpyimage-3.8.0/numpyimage.egg-info/requires.txt

@@ -0,0 +1,24 @@
+numpy
+tqdm
+pillow
+pillow-heif
+tifffile
+pynrrd
+matplotlib
+
+[align]
+opencv-python-headless
+
+[all]
+av
+opencv-python-headless
+
+[dev]
+av
+opencv-python-headless
+pytest
+pytest-cov
+psutil
+
+[vid]
+av

{numpyimage-3.7.0 → numpyimage-3.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = 'setuptools.build_meta'
 
 [project]
 name = 'numpyimage'
-version = '3.7.0'
+version = '3.8.0'
 description = 'Load, save, & manipulate image files as numpy arrays'
 readme.file = 'README.md'
 readme.content-type = 'text/markdown'
@@ -28,12 +28,31 @@ dependencies = [
     'tifffile',
     'pynrrd',
     'matplotlib',
-    'opencv-python-headless',
 ]
 
 [project.optional-dependencies]
+vid = [
+    'av',
+]
+align = [
+    'opencv-python-headless',
+]
 all = [
-    'av'
+    'av',
+    'opencv-python-headless',
+]
+dev = [
+    'av',
+    'opencv-python-headless',
+    'pytest',
+    'pytest-cov',
+    'psutil',
+]
+
+[tool.pytest.ini_options]
+testpaths = ['tests']
+markers = [
+    'slow: marks tests that shell out to ffmpeg or write real video files (deselect with -m "not slow")',
 ]
 
 [tool.setuptools.packages.find]

numpyimage-3.8.0/tests/test_heic.py

@@ -0,0 +1,58 @@
+"""Tests for HEIC read/write support."""
+
+import subprocess
+import sys
+import textwrap
+
+import numpy as np
+import pytest
+
+import npimage
+
+
+def test_heic_extension_registered():
+    """HEIC is in the set of supported file extensions."""
+    assert 'heic' in npimage.imageio.supported_extensions
+
+
+def test_heic_load_save_roundtrip(tmp_path):
+    """A uint8 RGB image roundtripped through HEIC keeps its shape and dtype."""
+    data = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
+    path = tmp_path / 'test_image.heic'
+
+    npimage.save(data, str(path))
+    assert path.exists()
+
+    loaded = npimage.load(str(path))
+    assert loaded.shape == data.shape
+    assert loaded.dtype == np.uint8
+
+
+@pytest.mark.skipif(sys.platform != 'darwin', reason='guard only fires on macOS')
+def test_heic_guards_against_pyav_already_imported(tmp_path):
+    """
+    On macOS, importing PyAV before libheif causes a segfault inside
+    pillow_heif. npimage guards against this by raising a RuntimeError with a
+    clear message instead of letting the segfault happen.
+    """
+    script = textwrap.dedent(f"""
+        import av  # noqa: F401
+        import numpy as np
+        import npimage
+        data = np.zeros((10, 10, 3), dtype=np.uint8)
+        try:
+            npimage.save(data, r'{tmp_path / "x.heic"}')
+        except RuntimeError as e:
+            print('GUARD_FIRED:', e)
+            raise SystemExit(0)
+        raise SystemExit('guard did not fire')
+    """)
+    result = subprocess.run(
+        [sys.executable, '-c', script], capture_output=True, text=True
+    )
+    assert result.returncode == 0, (
+        f'subprocess exited {result.returncode}. stdout={result.stdout!r} '
+        f'stderr={result.stderr!r}'
+    )
+    assert 'GUARD_FIRED:' in result.stdout
+    assert 'PyAV' in result.stdout