numpyimage 3.8.2__tar.gz → 3.9.0__tar.gz

{numpyimage-3.8.2 → numpyimage-3.9.0}/PKG-INFO

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

{numpyimage-3.8.2 → numpyimage-3.9.0}/npimage/imageio.py

@@ -52,13 +52,17 @@ def load(filename, dim_order='zyx', **kwargs) -> Union[np.ndarray, Tuple[np.ndar
     metadata = None
 
     if extension in ['jpg', 'jpeg', 'png']:
-        from PIL import Image
-        data = np.array(Image.open(filename))  # PIL.Image.open returns zyx order
+        from PIL import Image, ImageOps
+        # PIL.Image.open returns the raw stored pixels and does not apply the
+        # EXIF Orientation tag, so photos taken in a rotated orientation would
+        # load sideways or upside-down. ImageOps.exif_transpose applies the tag
+        # (and is a no-op when no Orientation tag is present).
+        data = np.array(ImageOps.exif_transpose(Image.open(filename)))
 
     if extension == 'heic':
         _ensure_heif_opener_registered()
-        from PIL import Image
-        data = np.array(Image.open(filename))  # PIL.Image.open returns zyx order
+        from PIL import Image, ImageOps
+        data = np.array(ImageOps.exif_transpose(Image.open(filename)))
 
     if extension in ['tif', 'tiff']:
         import tifffile

{numpyimage-3.8.2 → numpyimage-3.9.0}/npimage/vidio.py

@@ -18,14 +18,16 @@ Class list:
     because you don't ever have to have all the frames in memory at once.
 """
 
-from typing import Union, Tuple, Iterator, Literal
+from typing import Union, Tuple, Iterator, Literal, Optional
 from pathlib import Path
+from collections import OrderedDict
 import subprocess
 import shutil
 import sys
 import threading
 import json
 import math
+import re
 import bisect
 from fractions import Fraction
 
@@ -243,11 +245,64 @@ class VideoSeekError(RuntimeError):
     pass
 
 
+_cache_size_units = {
+    'b': 1,
+    'kb': 1024,
+    'mb': 1024 ** 2,
+    'gb': 1024 ** 3,
+}
+
+
+def _parse_cache_size(cache_size: Optional[Union[int, str]]
+                      ) -> Tuple[Optional[int], Optional[int]]:
+    """
+    Interpret the `cache_size` argument of `VideoStreamer` and return a
+    `(max_frames, max_bytes)` tuple in which exactly one element is set when
+    caching is enabled, or `(None, None)` when caching is disabled.
+
+    See the `VideoStreamer` initializer docstring for the accepted formats.
+    """
+    if cache_size is None:
+        return None, None
+    if isinstance(cache_size, bool):
+        raise TypeError(f'cache_size must be an int, str, or None, not a bool '
+                        f'(got {cache_size})')
+    if isinstance(cache_size, (int, np.integer)):
+        if cache_size < 0:
+            raise ValueError(f'cache_size must be non-negative, got {cache_size}')
+        if cache_size == 0:
+            return None, None
+        return int(cache_size), None
+    if isinstance(cache_size, str):
+        match = re.fullmatch(r'\s*([0-9]*\.?[0-9]+)\s*([a-zA-Z]*)\s*', cache_size)
+        if match is None:
+            raise ValueError(f'Could not interpret cache_size string "{cache_size}". '
+                             "Expected something like '64', '256MB', or '1.5GB'.")
+        number, unit = match.group(1), match.group(2).lower()
+        if unit == '':
+            # A bare number means a frame count, which must be a whole number.
+            value = float(number)
+            if not value.is_integer():
+                raise ValueError(f'A cache_size given as a number of frames must be '
+                                 f'a whole number, got "{cache_size}"')
+            return (int(value), None) if value > 0 else (None, None)
+        # Accept binary-prefix spellings like 'MiB' as aliases for 'MB'.
+        unit = unit.replace('ib', 'b')
+        if unit not in _cache_size_units:
+            raise ValueError(f'Unrecognized cache_size unit "{match.group(2)}". '
+                             f'Recognized units are B, KB, MB, and GB.')
+        num_bytes = int(float(number) * _cache_size_units[unit])
+        return (None, num_bytes) if num_bytes > 0 else (None, None)
+    raise TypeError(f'cache_size must be an int, str, or None, got '
+                    f'{type(cache_size).__name__}')
+
+
 class VideoStreamer:
     def __init__(self,
                  filename: str,
                  verbose: bool = False,
-                 cache_index: Literal['auto', True, False] = 'auto'):
+                 cache_index: Literal['auto', True, False] = 'auto',
+                 cache_size: Optional[Union[int, str]] = '256MB'):
         """
         Parameters
         ----------
@@ -263,6 +318,32 @@ class VideoStreamer:
             next to the video file for faster loading next time.
             If 'auto', the index is cached only if building it takes
             more than 0.5 seconds, which only happens for ~1+ GB videos.
+
+        cache_size : int, str, or None, default '256MB'
+            Sets the size of an in-memory cache of decoded frames. The cache
+            makes a three-way tradeoff: in exchange for holding up to
+            `cache_size` worth of decoded frames in memory, reading a frame
+            that is already cached is dramatically faster (~20x in benchmarks
+            on a 1080p video) than decoding it, while reading a not-yet-cached
+            frame is only marginally slower (~2%, the cost of copying the
+            decoded frame before returning it). This is a large net win
+            whenever you revisit frames, for example when scrubbing back and
+            forth through a video, which is why caching is on by default. The
+            least recently used frames are evicted once the cache is full.
+            (The ~20x and ~2% figures are approximate and vary with the video.)
+
+            - None or 0 disables caching.
+            - An int sets the maximum number of frames to cache, e.g.
+              `cache_size=64`.
+            - A string sets a maximum memory budget, e.g. `cache_size='256MB'`
+              or `cache_size='1.5GB'`. Recognized units are B, KB, MB, and GB
+              (interpreted as powers of 1024, so '1MB' means 1024*1024 bytes).
+              A bare numeric string like '64' is treated as a frame count.
+
+            Frames returned by indexing are always independent, writeable
+            arrays, exactly as when caching is disabled: the cache holds its own
+            private copy of each frame, so modifying a returned frame never
+            affects the cache or any other returned frame.
         """
         extension = Path(filename).suffix.lower().lstrip('.')
         if extension == 'gif':
@@ -287,6 +368,15 @@ class VideoStreamer:
         self._current_frame_number = None
         self._lock = threading.Lock()
 
+        # In-memory frame cache (see the cache_size docstring above). Exactly
+        # one of _cache_max_frames / _cache_max_bytes is set when caching is on.
+        self._cache_max_frames, self._cache_max_bytes = _parse_cache_size(cache_size)
+        if self._cache_max_frames is None and self._cache_max_bytes is None:
+            self._cache = None
+        else:
+            self._cache = OrderedDict()
+        self._cache_bytes = 0
+
         self.index_filename = self.filename.with_suffix(self.filename.suffix + '.index')
         self._build_index(cache_index=cache_index)
         self.t = _VideoStreamerTimeIndexer(self)
@@ -560,6 +650,12 @@ class VideoStreamer:
 
         with self._lock:
             frame_number = self._normalize_frame_number(frame_number)
+            if self._cache is not None and frame_number in self._cache:
+                # Cache hit: mark as most recently used and hand back an
+                # independent, writeable copy so callers can't corrupt the
+                # cached frame by modifying what they receive.
+                self._cache.move_to_end(frame_number)
+                return self._cache[frame_number].copy()
             if (self._current_frame_number is None
                     or frame_number <= self._current_frame_number
                     or frame_number > self._current_frame_number + 100):
@@ -598,8 +694,39 @@ class VideoStreamer:
 
             if self.rotation not in [None, '0', 0]:
                 image = np.rot90(image, k=-int(self.rotation) // 90)
+            if self._cache is not None:
+                self._cache_store(frame_number, image)
+                # Return a copy, keeping the cached frame as a private canonical
+                # copy that callers can never corrupt (see the hit path above).
+                return image.copy()
             return image
 
+    def _cache_store(self, frame_number: int, image: np.ndarray) -> None:
+        """
+        Insert a decoded frame into the cache as the most recently used entry,
+        then evict least recently used entries until the cache is within its
+        configured size limit.
+        """
+        self._cache[frame_number] = image
+        self._cache.move_to_end(frame_number)
+        if self._cache_max_bytes is not None:
+            self._cache_bytes += image.nbytes
+            while self._cache_bytes > self._cache_max_bytes and len(self._cache) > 1:
+                _, evicted = self._cache.popitem(last=False)
+                self._cache_bytes -= evicted.nbytes
+        else:
+            while len(self._cache) > self._cache_max_frames:
+                self._cache.popitem(last=False)
+
+    def clear_cache(self) -> None:
+        """
+        Empty the in-memory frame cache. Has no effect if caching is disabled.
+        """
+        with self._lock:
+            if self._cache is not None:
+                self._cache.clear()
+                self._cache_bytes = 0
+
     def _normalize_frame_number(self, frame_number: int) -> int:
         """
         Support negative indexing by converting negative frame numbers to
@@ -1116,7 +1243,8 @@ def save_video(data, filename, time_axis=0, color_axis=None, overwrite=False,
     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 must be 3D (greyscale) or 4D with one length 3 axis (RGB).
+        If None, data must be 3D (greyscale) or 4D with one length 3 axis (RGB)
+        or length 4 axis (RGBA, whose alpha channel will be dropped).
 
     overwrite : bool, default False
         Whether to overwrite the file if it already exists.
@@ -1158,9 +1286,10 @@ def save_video(data, filename, time_axis=0, color_axis=None, overwrite=False,
     if not isinstance(data, np.ndarray):
         data = np.array(data)
     if color_axis is None and data.ndim == 4:
-        color_axis = utils.find_channel_axis(data, possible_channel_lengths=3)
+        color_axis = utils.find_channel_axis(data, possible_channel_lengths=[3, 4])
         if color_axis is None:
-            raise ValueError('4D input data must have an RGB (length 3) axis.')
+            raise ValueError('4D input data must have an RGB (length 3) or '
+                             'RGBA (length 4) axis.')
     if color_axis is not None:
         if data.ndim != 4:
             raise ValueError('Input data must be 4D when color_axis is specified.')
@@ -1172,6 +1301,11 @@ def save_video(data, filename, time_axis=0, color_axis=None, overwrite=False,
             data = data.swapaxes(1, 2)
         n_frames = data.shape[0]
         height, width, channels = data.shape[1:]
+        if channels == 4:
+            # While some video codecs support an alpha channel, most don't,
+            # so we drop it and keep just the RGB channels
+            data = data[..., :3]
+            channels = 3
         if channels != 3:
             raise ValueError(f'Color video must have 3 channels (RGB) but had {channels}.')
     else:

{numpyimage-3.8.2 → numpyimage-3.9.0}/numpyimage.egg-info/PKG-INFO

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

{numpyimage-3.8.2 → numpyimage-3.9.0}/numpyimage.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ numpyimage.egg-info/dependency_links.txt
 numpyimage.egg-info/requires.txt
 numpyimage.egg-info/top_level.txt
 tests/test_heic.py
+tests/test_orientation.py
 tests/test_pbm.py
 tests/test_video_streamer.py
 tests/test_video_writers.py

{numpyimage-3.8.2 → numpyimage-3.9.0}/pyproject.toml

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

numpyimage-3.9.0/tests/test_orientation.py

@@ -0,0 +1,51 @@
+"""Tests that load() applies the EXIF orientation tag for photo formats."""
+
+import numpy as np
+import pytest
+from PIL import Image, ImageOps
+
+import npimage
+
+
+def _save_with_orientation(array, path, orientation):
+    """
+    Save `array` as an image at `path`, stamping the given EXIF Orientation
+    value (e.g. 6 = Rotate 90 CW) without rotating the stored pixels, so that
+    only a reader honoring the tag will display it upright.
+    """
+    image = Image.fromarray(array)
+    exif = image.getexif()
+    exif[0x0112] = orientation  # 0x0112 is the EXIF Orientation tag
+    image.save(str(path), exif=exif)
+
+
+@pytest.mark.parametrize('extension', ['jpg', 'png'])
+def test_load_applies_rotate_90(tmp_path, extension):
+    """
+    A photo whose pixels are stored landscape but tagged Rotate 90 CW loads
+    with its width and height swapped (i.e. the rotation is applied).
+    """
+    height, width = 20, 40
+    array = np.zeros((height, width, 3), dtype=np.uint8)
+    array[:, :width // 2] = [255, 0, 0]  # left half red, so rotation is visible
+    path = tmp_path / f'rotated.{extension}'
+    _save_with_orientation(array, path, orientation=6)  # Rotate 90 CW
+
+    loaded = npimage.load(str(path))
+    # Applying Rotate 90 CW swaps the axes, so a (height, width) image
+    # becomes (width, height).
+    assert loaded.shape[:2] == (width, height)
+    # And it matches PIL's orientation-applied result exactly.
+    truth = np.array(ImageOps.exif_transpose(Image.open(str(path))))
+    assert np.array_equal(loaded, truth)
+
+
+def test_load_without_orientation_is_unchanged(tmp_path):
+    """An image with no Orientation tag loads with its pixels untouched."""
+    array = np.random.randint(0, 256, (20, 40, 3), dtype=np.uint8)
+    path = tmp_path / 'plain.png'
+    Image.fromarray(array).save(str(path))
+
+    loaded = npimage.load(str(path))
+    assert loaded.shape == array.shape
+    assert np.array_equal(loaded, array)

{numpyimage-3.8.2 → numpyimage-3.9.0}/tests/test_video_streamer.py

@@ -10,6 +10,7 @@ import numpy as np
 import pytest
 
 import npimage
+from npimage.vidio import _parse_cache_size
 
 TESTS_DIR = Path(__file__).parent
 SPINNING_MP4 = TESTS_DIR / 'table-tennis-emoji-spinning.mp4'
@@ -320,3 +321,187 @@ def test_t_indexer_variable_framerate_uses_bisect(spinning_streamer):
     finally:
         vid._framerate = original_framerate
         vid.frames_pts = original_frames_pts
+
+
+# ----------------------------------------------------------------------------
+# Frame caching
+# ----------------------------------------------------------------------------
+
+def test_parse_cache_size_disabled():
+    """None and 0 (in either int or string form) disable caching."""
+    assert _parse_cache_size(None) == (None, None)
+    assert _parse_cache_size(0) == (None, None)
+    assert _parse_cache_size('0') == (None, None)
+    assert _parse_cache_size('0MB') == (None, None)
+
+
+def test_parse_cache_size_frame_counts():
+    """Bare ints and bare numeric strings are interpreted as frame counts."""
+    assert _parse_cache_size(64) == (64, None)
+    assert _parse_cache_size('64') == (64, None)
+
+
+def test_parse_cache_size_byte_budgets():
+    """Strings with units are interpreted as memory budgets (powers of 1024)."""
+    assert _parse_cache_size('1B') == (None, 1)
+    assert _parse_cache_size('1KB') == (None, 1024)
+    assert _parse_cache_size('256MB') == (None, 256 * 1024 ** 2)
+    assert _parse_cache_size('1.5GB') == (None, int(1.5 * 1024 ** 3))
+    # Binary-prefix spellings are accepted as aliases.
+    assert _parse_cache_size('1MiB') == (None, 1024 ** 2)
+    # Whitespace and case are tolerated.
+    assert _parse_cache_size('  2 gb ') == (None, 2 * 1024 ** 3)
+
+
+def test_parse_cache_size_invalid():
+    """Bad units, non-whole frame counts, bools, and negatives all raise."""
+    with pytest.raises(ValueError):
+        _parse_cache_size('abc')
+    with pytest.raises(ValueError):
+        _parse_cache_size('10TB')
+    with pytest.raises(ValueError):
+        _parse_cache_size('1.5')  # fractional frame count
+    with pytest.raises(ValueError):
+        _parse_cache_size(-5)
+    with pytest.raises(TypeError):
+        _parse_cache_size(True)
+
+
+def test_cache_returns_correct_frames():
+    """Cached frames are pixel-identical to uncached ones, even out of order."""
+    reference = npimage.VideoStreamer(str(SPINNING_MP4), cache_size=None)
+    cached = npimage.VideoStreamer(str(SPINNING_MP4), cache_size=4)
+    try:
+        for i in [0, 5, 2, 5, 0, 7, 3, 7, 1]:
+            assert np.array_equal(reference[i], cached[i]), f'mismatch at frame {i}'
+    finally:
+        reference.close()
+        cached.close()
+
+
+def test_cache_disabled_returns_writeable_frames():
+    """With caching off, returned frames are writeable (unchanged behavior)."""
+    vid = npimage.VideoStreamer(str(SPINNING_MP4), cache_size=None)
+    try:
+        assert vid._cache is None
+        assert vid[0].flags.writeable
+    finally:
+        vid.close()
+
+
+def test_cache_enabled_returns_writeable_independent_frames():
+    """
+    With caching on, returned frames are still writeable, and mutating a
+    returned frame must not corrupt the cached copy handed to later callers.
+
+    This exercises both the cache-miss return path (the first read of a frame)
+    and the cache-hit return path (subsequent reads): mutating the frame
+    returned from either must leave the cache untouched.
+    """
+    vid = npimage.VideoStreamer(str(SPINNING_MP4), cache_size=4)
+    try:
+        first = vid[0]                  # cache miss: this return is freshly decoded
+        assert first.flags.writeable
+        original = first.copy()
+        # Guard against a vacuous test: the frame must have content to clobber.
+        assert original.any()
+
+        first[:] = 0                    # mutate the miss-path frame in place
+        second = vid[0]                 # cache hit: must be the pristine frame
+        assert np.array_equal(second, original), (
+            'Mutating the frame returned on a cache miss corrupted the cache.'
+        )
+
+        second[:] = 0                   # now mutate the hit-path frame in place
+        third = vid[0]                  # another cache hit: still pristine
+        assert np.array_equal(third, original), (
+            'Mutating the frame returned on a cache hit corrupted the cache.'
+        )
+
+        # Every read handed back an independent array object.
+        assert first is not second
+        assert second is not third
+        assert first is not third
+    finally:
+        vid.close()
+
+
+def test_cache_lru_eviction_by_frame_count():
+    """The least recently used frames are evicted once the cache is full."""
+    vid = npimage.VideoStreamer(str(SPINNING_MP4), cache_size=4)
+    try:
+        for i in range(5):  # fill past capacity: 0 should be evicted
+            _ = vid[i]
+        assert list(vid._cache.keys()) == [1, 2, 3, 4]
+        # Touch frame 1 (most recently used), then add two more.
+        _ = vid[1]
+        _ = vid[5]
+        _ = vid[6]
+        # 2 and 3 (oldest untouched) evicted; 1 retained because it was reused.
+        assert 1 in vid._cache
+        assert 2 not in vid._cache
+        assert 3 not in vid._cache
+    finally:
+        vid.close()
+
+
+def test_cache_respects_byte_budget():
+    """A memory-budgeted cache never holds more bytes than allowed."""
+    reference = npimage.VideoStreamer(str(SPINNING_MP4), cache_size=None)
+    frame_bytes = reference[0].nbytes
+    # Budget for exactly two frames.
+    vid = npimage.VideoStreamer(str(SPINNING_MP4), cache_size=f'{2 * frame_bytes}B')
+    try:
+        for i in range(5):
+            _ = vid[i]
+        assert len(vid._cache) == 2
+        assert vid._cache_bytes <= 2 * frame_bytes
+    finally:
+        reference.close()
+        vid.close()
+
+
+def test_clear_cache():
+    """clear_cache empties the cache and resets the byte tally."""
+    vid = npimage.VideoStreamer(str(SPINNING_MP4), cache_size='64MB')
+    try:
+        for i in range(4):
+            _ = vid[i]
+        assert len(vid._cache) > 0
+        vid.clear_cache()
+        assert len(vid._cache) == 0
+        assert vid._cache_bytes == 0
+        # The streamer still works after clearing.
+        assert np.array_equal(vid[0], vid[0])
+    finally:
+        vid.close()
+
+
+def test_cache_hit_serves_without_redecoding():
+    """
+    The core promise of the cache: re-reading a cached frame returns it
+    straight from memory without decoding it again.
+
+    We verify this without mocking by watching `_current_frame_number`, which
+    tracks the decoder's position. Decoding a frame advances it to that frame,
+    whereas a cache hit returns before touching the stream and so leaves it
+    unchanged. We also confirm the cached frame is still pixel-correct.
+    """
+    reference = npimage.VideoStreamer(str(SPINNING_MP4), cache_size=None)
+    vid = npimage.VideoStreamer(str(SPINNING_MP4), cache_size=8)
+    try:
+        _ = vid[5]                              # cache miss: decodes frame 5
+        _ = vid[2]                              # cache miss: decodes frame 2
+        assert vid._current_frame_number == 2   # decoder is now parked at 2
+
+        frame5 = vid[5]                          # cache hit: must NOT decode
+        assert vid._current_frame_number == 2, (
+            'Re-reading a cached frame moved the decoder, so it was decoded '
+            'again instead of served from the cache.'
+        )
+        assert 5 in vid._cache
+        # The frame served from the cache is identical to a fresh decode.
+        assert np.array_equal(frame5, reference[5])
+    finally:
+        reference.close()
+        vid.close()