numpyimage 3.7.1__tar.gz → 3.8.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 3.7.1
+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
@@ -57,22 +57,23 @@ 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.
 
@@ -86,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.)
 
@@ -98,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.1 → numpyimage-3.8.0}/README.md

@@ -1,19 +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.
 
@@ -27,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.)
 
@@ -39,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.1 → 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.1 → 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,6 +250,7 @@ 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 cache_index and self.index_filename.exists():
@@ -384,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
@@ -402,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__'):
@@ -618,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.
@@ -661,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
@@ -776,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.1 → numpyimage-3.8.0}/numpyimage.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 3.7.1
+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
@@ -57,22 +57,23 @@ 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.
 
@@ -86,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.)
 
@@ -98,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.1 → numpyimage-3.8.0}/pyproject.toml

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

numpyimage-3.8.0/tests/test_video_streamer.py

@@ -0,0 +1,322 @@
+"""
+Tests for VideoStreamer, particularly handling of HEVC videos with
+negative-PTS priming packets (common in iPhone recordings).
+"""
+
+import subprocess
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+import npimage
+
+TESTS_DIR = Path(__file__).parent
+SPINNING_MP4 = TESTS_DIR / 'table-tennis-emoji-spinning.mp4'
+
+
+@pytest.fixture
+def spinning_streamer():
+    """A VideoStreamer over the bundled 8-frame, 4 fps test video."""
+    vid = npimage.VideoStreamer(str(SPINNING_MP4))
+    yield vid
+    vid.close()
+
+
+@pytest.mark.slow
+def test_negative_pts_priming_packet(tmp_path):
+    """
+    VideoStreamer correctly handles HEVC videos where the first packet has a
+    negative PTS (a "priming" packet used for B-frame prediction that doesn't
+    produce a decoded frame).
+
+    This is common in iPhone HEVC recordings. The bug was that the index was
+    built from demuxed packets, which included the priming packet's negative
+    PTS. When trying to access frame 0, it would seek to that negative PTS,
+    which no decoded frame ever has, causing a VideoSeekError.
+    """
+    import av
+
+    video_path = tmp_path / 'test_negative_pts.mp4'
+
+    # Create a small HEVC video with a negative-PTS priming packet.
+    # -output_ts_offset shifts timestamps so the first keyframe packet gets a
+    # negative PTS, mimicking iPhone HEVC behavior.
+    result = subprocess.run([
+        'ffmpeg', '-y',
+        '-f', 'lavfi', '-i', 'color=c=red:size=320x240:rate=30:d=1',
+        '-c:v', 'libx265', '-preset', 'ultrafast',
+        '-bf', '2', '-x265-params', 'bframes=2',
+        '-tag:v', 'hvc1',
+        '-output_ts_offset', '-0.033',
+        str(video_path),
+    ], capture_output=True, text=True)
+    assert result.returncode == 0, f'ffmpeg failed: {result.stderr}'
+
+    # Verify the test video actually has the problematic structure: more
+    # packets than decoded frames due to the priming packet.
+    with av.open(str(video_path)) as container:
+        stream = container.streams.video[0]
+        pkt_pts = sorted(
+            p.pts for p in container.demux(stream) if p.pts is not None
+        )
+    with av.open(str(video_path)) as container:
+        stream = container.streams.video[0]
+        frame_pts = [f.pts for f in container.decode(stream)]
+
+    assert len(pkt_pts) > len(frame_pts), (
+        f'Test video should have more packets ({len(pkt_pts)}) than decoded '
+        f'frames ({len(frame_pts)}). The test setup may need updating if '
+        f'ffmpeg behavior has changed.'
+    )
+    assert pkt_pts[0] < 0, f'First packet PTS should be negative, got {pkt_pts[0]}'
+
+    vid = npimage.VideoStreamer(str(video_path))
+
+    assert vid.n_frames == len(frame_pts)
+
+    frame = vid[0]
+    assert isinstance(frame, np.ndarray)
+    assert frame.shape == (240, 320, 3)
+
+    last_frame = vid[vid.n_frames - 1]
+    assert isinstance(last_frame, np.ndarray)
+
+
+def test_duration_matches_n_frames_over_fps():
+    """
+    `duration` follows the View-B convention: each frame occupies one
+    inter-frame interval on screen, so total duration is
+    ``n_frames / fps`` (equivalent to ``n_frames * timestep`` for CFR).
+
+    The bundled test video has 8 frames at 4 fps. View A would give
+    7 * 0.25 = 1.75 s; View B gives 8 * 0.25 = 2.00 s, matching the
+    duration ffprobe reports for the same file.
+    """
+    vid = npimage.VideoStreamer(str(SPINNING_MP4))
+    try:
+        assert vid.n_frames == 8
+        assert vid.fps == 4.0
+        assert vid.duration == pytest.approx(2.0)
+        # Self-consistency: duration, fps, and n_frames form a closed triple.
+        assert vid.duration == pytest.approx(vid.n_frames / vid.fps)
+        # For CFR specifically, duration should also equal n_frames * timestep.
+        assert vid.duration == pytest.approx(vid.n_frames * vid.timestep)
+    finally:
+        vid.close()
+
+
+def test_duration_matches_ffprobe_on_cfr():
+    """
+    For constant-framerate videos, our `duration` should agree with
+    ffprobe to within a small tolerance.
+    """
+    result = subprocess.run([
+        'ffprobe', '-v', 'error',
+        '-show_entries', 'format=duration',
+        '-of', 'default=noprint_wrappers=1:nokey=1',
+        str(SPINNING_MP4),
+    ], capture_output=True, text=True)
+    assert result.returncode == 0, f'ffprobe failed: {result.stderr}'
+    ffprobe_duration = float(result.stdout.strip())
+
+    vid = npimage.VideoStreamer(str(SPINNING_MP4))
+    try:
+        assert vid.duration == pytest.approx(ffprobe_duration, abs=1e-6)
+    finally:
+        vid.close()
+
+
+def test_t_indexer_exact_timestamp_returns_that_frame(spinning_streamer):
+    """vid.t[exact_frame_time] returns that frame, not the next one."""
+    vid = spinning_streamer
+    for i in range(vid.n_frames):
+        _, _, idx = vid.t[vid.frame_number_to_time(i)]
+        assert idx == i
+
+
+def test_t_indexer_returns_3tuple(spinning_streamer):
+    """The return value is a plain (image, timestamp, frame_index) tuple."""
+    vid = spinning_streamer
+    result = vid.t[0.5]
+    assert type(result) is tuple
+    assert len(result) == 3
+    image, timestamp, idx = result
+    assert isinstance(image, np.ndarray)
+    assert image.shape == vid.shape[1:]
+    assert isinstance(timestamp, float)
+    assert isinstance(idx, int)
+
+
+def test_t_indexer_supports_tuple_unpacking(spinning_streamer):
+    """Callers can unpack the result positionally as (image, time, index)."""
+    vid = spinning_streamer
+    image, timestamp, idx = vid.t[0.75]
+    assert isinstance(image, np.ndarray)
+    assert timestamp == pytest.approx(0.75)
+    assert idx == 3
+
+
+def test_t_indexer_eps_below_timestamp_still_returns_that_frame(spinning_streamer):
+    """A request slightly under a frame's timestamp still returns that frame.
+
+    This is the float-eps-tolerance behavior: small negative drift from the
+    exact timestamp must not cause the indexer to fall back to the previous
+    frame. (We only test that direction; small drift above the timestamp is
+    correctly resolved to the next frame, see the next test.)
+    """
+    vid = spinning_streamer
+    t5 = vid.frame_number_to_time(5)
+    assert vid.t[t5 - 1e-12][2] == 5
+    assert vid.t[t5 - 1e-9][2] == 5
+
+
+def test_t_indexer_just_above_timestamp_stays_on_that_frame(spinning_streamer):
+    """A request just inside a frame's display interval returns that frame.
+
+    Under View B each frame is on screen during ``[pts_N, pts_{N+1})``, so
+    a time 1 ms after frame 5's timestamp is still inside frame 5's
+    display interval (which spans 250 ms on this 4 fps video).
+    """
+    vid = spinning_streamer
+    t5 = vid.frame_number_to_time(5)
+    assert vid.t[t5 + 1e-3][2] == 5
+
+
+def test_t_indexer_between_frames_returns_earlier_frame(spinning_streamer):
+    """A time strictly between two frames returns the earlier (still-displayed) one."""
+    vid = spinning_streamer
+    midpoint = (vid.frame_number_to_time(2) + vid.frame_number_to_time(3)) / 2
+    assert vid.t[midpoint][2] == 2
+
+
+def test_t_indexer_just_before_next_frame_still_returns_current(spinning_streamer):
+    """A time meaningfully shy of frame N+1's timestamp still returns frame N.
+
+    This is the "scrub to the deep tail of frame N's display interval"
+    case — under View B the next frame hasn't appeared yet. The delta
+    must be larger than half a time_base tick or the eps tolerance will
+    snap the request up to frame N+1.
+    """
+    vid = spinning_streamer
+    t6 = vid.frame_number_to_time(6)
+    # 1 ms before frame 6 starts (well above half-tick eps) -> still frame 5
+    assert vid.t[t6 - 1e-3][2] == 5
+
+
+def test_t_indexer_zero_returns_first_frame(spinning_streamer):
+    """Time 0.0 resolves to frame 0."""
+    assert spinning_streamer.t[0.0][2] == 0
+
+
+def test_t_indexer_negative_time_wraps_relative_to_end(spinning_streamer):
+    """Negative times wrap, mirroring the integer indexer's negative semantics.
+
+    ``vid.t[-x]`` resolves to ``end_of_playback - x``. On the 8-frame,
+    4 fps test video (frames at 0.00, 0.25, ..., 1.75; duration 2.00 s)
+    a request for -0.25 s lands at absolute time 1.75 — frame 7's
+    timestamp, the start of its display interval, so frame 7. -1.0 s
+    lands at 1.0 = frame 4. -duration lands at 0.0 = frame 0.
+    """
+    vid = spinning_streamer
+    assert vid.t[-0.25][2] == 7
+    assert vid.t[-1.0][2] == 4
+    assert vid.t[-vid.duration][2] == 0
+
+
+def test_t_indexer_negative_time_eps_tolerance(spinning_streamer):
+    """The eps shift also applies after negative-time wrap.
+
+    A wrapped time that equals an exact frame timestamp should resolve to
+    that frame, not the previous one, due to float drift. -0.25 s wraps
+    to exactly 1.75 s = frame 7's timestamp.
+    """
+    vid = spinning_streamer
+    assert vid.t[-0.25][2] == 7
+    assert vid.t[-0.25 - 1e-12][2] == 7
+
+
+def test_t_indexer_too_negative_raises(spinning_streamer):
+    """Negative times more negative than -duration raise IndexError."""
+    vid = spinning_streamer
+    with pytest.raises(IndexError):
+        vid.t[-vid.duration - 1e-3]
+    with pytest.raises(IndexError):
+        vid.t[-100.0]
+
+
+def test_t_indexer_past_last_frame_timestamp_still_returns_last_frame(spinning_streamer):
+    """Times within the last frame's display interval still return it.
+
+    Under View B the last frame is on screen during
+    ``[last_frame_timestamp, end_of_playback)``, so a request 1 ms past
+    the last frame's timestamp (well inside the 250 ms last interval) is
+    still the last frame, not an error.
+    """
+    vid = spinning_streamer
+    last = vid.frame_number_to_time(vid.n_frames - 1)
+    assert vid.t[last + 1e-3][2] == vid.n_frames - 1
+    # Just shy of end_of_playback should also still be the last frame.
+    assert vid.t[vid.duration - 1e-6][2] == vid.n_frames - 1
+
+
+def test_t_indexer_past_end_of_playback_raises(spinning_streamer):
+    """Times at or past end_of_playback raise IndexError."""
+    vid = spinning_streamer
+    with pytest.raises(IndexError):
+        vid.t[vid.duration]
+    with pytest.raises(IndexError):
+        vid.t[vid.duration + 1e-3]
+    with pytest.raises(IndexError):
+        vid.t[vid.duration + 100.0]
+
+
+def test_t_indexer_image_matches_frame_lookup(spinning_streamer):
+    """The image returned by t[time] is identical to streamer[returned_index]."""
+    vid = spinning_streamer
+    image, _, idx = vid.t[0.6]
+    assert np.array_equal(image, vid[idx])
+
+
+def test_t_indexer_rejects_non_numeric(spinning_streamer):
+    """Non-numeric keys raise TypeError rather than failing deeper in."""
+    vid = spinning_streamer
+    with pytest.raises(TypeError):
+        vid.t['0.5']
+    with pytest.raises(TypeError):
+        vid.t[None]
+
+
+def test_t_indexer_variable_framerate_uses_bisect(spinning_streamer):
+    """The variable-framerate code path correctly resolves between frames.
+
+    The bundled test video is constant-framerate, so we coerce the streamer
+    into the variable-framerate branch by swapping in a list of PTS values
+    and flipping `_framerate`. This exercises the ``bisect_right`` path in
+    ``_VideoStreamerTimeIndexer.__getitem__`` against the same View B
+    semantics.
+    """
+    vid = spinning_streamer
+    original_framerate = vid._framerate
+    original_frames_pts = vid.frames_pts
+    try:
+        vid._framerate = 'variable'
+        # Materialize the range as a list so bisect operates on real ints.
+        vid.frames_pts = list(original_frames_pts)
+
+        # Exact timestamp -> that frame.
+        t4 = vid.frame_number_to_time(4)
+        assert vid.t[t4][2] == 4
+        # Just below -> still that frame (eps tolerance).
+        assert vid.t[t4 - 1e-9][2] == 4
+        # Between two frames -> the earlier one (still on screen).
+        midpoint = (vid.frame_number_to_time(1) + vid.frame_number_to_time(2)) / 2
+        assert vid.t[midpoint][2] == 1
+        # Just inside the last frame's display interval -> last frame.
+        assert vid.t[vid.duration - 1e-6][2] == vid.n_frames - 1
+        # At or past end_of_playback -> IndexError.
+        with pytest.raises(IndexError):
+            vid.t[vid.duration]
+    finally:
+        vid._framerate = original_framerate
+        vid.frames_pts = original_frames_pts

numpyimage-3.7.1/tests/test_video_streamer.py

@@ -1,71 +0,0 @@
-"""
-Tests for VideoStreamer, particularly handling of HEVC videos with
-negative-PTS priming packets (common in iPhone recordings).
-"""
-
-import subprocess
-
-import numpy as np
-import pytest
-
-import npimage
-
-
-@pytest.mark.slow
-def test_negative_pts_priming_packet(tmp_path):
-    """
-    VideoStreamer correctly handles HEVC videos where the first packet has a
-    negative PTS (a "priming" packet used for B-frame prediction that doesn't
-    produce a decoded frame).
-
-    This is common in iPhone HEVC recordings. The bug was that the index was
-    built from demuxed packets, which included the priming packet's negative
-    PTS. When trying to access frame 0, it would seek to that negative PTS,
-    which no decoded frame ever has, causing a VideoSeekError.
-    """
-    import av
-
-    video_path = tmp_path / 'test_negative_pts.mp4'
-
-    # Create a small HEVC video with a negative-PTS priming packet.
-    # -output_ts_offset shifts timestamps so the first keyframe packet gets a
-    # negative PTS, mimicking iPhone HEVC behavior.
-    result = subprocess.run([
-        'ffmpeg', '-y',
-        '-f', 'lavfi', '-i', 'color=c=red:size=320x240:rate=30:d=1',
-        '-c:v', 'libx265', '-preset', 'ultrafast',
-        '-bf', '2', '-x265-params', 'bframes=2',
-        '-tag:v', 'hvc1',
-        '-output_ts_offset', '-0.033',
-        str(video_path),
-    ], capture_output=True, text=True)
-    assert result.returncode == 0, f'ffmpeg failed: {result.stderr}'
-
-    # Verify the test video actually has the problematic structure: more
-    # packets than decoded frames due to the priming packet.
-    with av.open(str(video_path)) as container:
-        stream = container.streams.video[0]
-        pkt_pts = sorted(
-            p.pts for p in container.demux(stream) if p.pts is not None
-        )
-    with av.open(str(video_path)) as container:
-        stream = container.streams.video[0]
-        frame_pts = [f.pts for f in container.decode(stream)]
-
-    assert len(pkt_pts) > len(frame_pts), (
-        f'Test video should have more packets ({len(pkt_pts)}) than decoded '
-        f'frames ({len(frame_pts)}). The test setup may need updating if '
-        f'ffmpeg behavior has changed.'
-    )
-    assert pkt_pts[0] < 0, f'First packet PTS should be negative, got {pkt_pts[0]}'
-
-    vid = npimage.VideoStreamer(str(video_path))
-
-    assert vid.n_frames == len(frame_pts)
-
-    frame = vid[0]
-    assert isinstance(frame, np.ndarray)
-    assert frame.shape == (240, 320, 3)
-
-    last_frame = vid[vid.n_frames - 1]
-    assert isinstance(last_frame, np.ndarray)