numpyimage 3.5.2__tar.gz → 3.6.0__tar.gz

{numpyimage-3.5.2/numpyimage.egg-info → numpyimage-3.6.0}/PKG-INFO

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

{numpyimage-3.5.2 → numpyimage-3.6.0}/npimage/graphics.py

@@ -637,13 +637,20 @@ def get_voxels_within_distance(distance, center=None, ndims=None,
     """
     Generates a list of voxel coordinates within a given distance of a given
     center point.
-        center, tuple   : Voxel coordinate to be used as the center.
-                            Defaults to the origin.
-        distance, float : How far away from the center point to include.
-        metric, string    : How to calculate distance. Options are:
-                              euclidian (default)
-                              manhattan (sum of coordinates)
-                              chebyshev (max of coordinates)
+
+    Parameters
+    ----------
+    center : tuple
+        Voxel coordinate to be used as the center. Defaults to the origin.
+
+    distance : float
+        How far away from the center point to include.
+
+    metric : string, default 'euclidian'
+        How to calculate distance. Options are:
+        - euclidian (default)
+        - manhattan (sum of coordinates)
+        - chebyshev (max of coordinates)
     """
     assert metric in ['euclidian', 'manhattan', 'chebyshev']
 

{numpyimage-3.5.2 → numpyimage-3.6.0}/npimage/vidio.py

@@ -40,9 +40,22 @@ codec_aliases = {
     'hev1': 'libx265',
     'h265': 'libx265',
     'H.265': 'libx265',
+    'libvpx': 'libvpx',
+    'vp8': 'libvpx',
+    'libvpx-vp9': 'libvpx-vp9',
+    'vp9': 'libvpx-vp9',
 }
 
-supported_extensions = ['mp4', 'mkv', 'avi', 'mov', 'webm']
+# Default codec for each container format
+extension_default_codecs = {
+    'mp4': 'libx264',
+    'mkv': 'libx264',
+    'avi': 'libx264',
+    'mov': 'libx264',
+    'webm': 'libvpx-vp9',
+}
+
+supported_extensions = ['mp4', 'mkv', 'avi', 'mov', 'webm', 'gif']
 
 
 def _import_av():
@@ -79,6 +92,30 @@ def load_video(filename,
         framerate : float
             The frame rate of the video in frames per second
     """
+    extension = Path(filename).suffix.lower().lstrip('.')
+    if extension == 'gif':
+        from PIL import Image
+        frames = []
+        durations = []
+        with Image.open(filename) as img:
+            while True:
+                frames.append(np.array(img.convert('RGB')))
+                durations.append(img.info.get('duration', None))
+                try:
+                    img.seek(img.tell() + 1)
+                except EOFError:
+                    break
+        data = np.array(frames)
+        if return_framerate:
+            if None in durations:
+                raise ValueError('Cannot return framerate for GIF because one or'
+                                 ' more frames are missing duration metadata')
+            if len(durations) == 0:
+                return data, None
+            framerate = 1000 / np.mean(durations)
+            return data, float(framerate)
+        return data
+
     av = _import_av()
     with av.open(filename) as container:
         stream = container.streams.video[0]
@@ -120,7 +157,7 @@ def load_video(filename,
 
 def lazy_load_video(filename) -> Iterator[np.ndarray]:
     """
-    Lazily load video frames as numpy arrays using PyAV.
+    Lazily load video frames as numpy arrays using PyAV (or using PIL for gifs)
 
     This iterator yields images in the order they appear in the video.
     If you want reasonably fast random access to arbitrary frames in
@@ -136,6 +173,19 @@ def lazy_load_video(filename) -> Iterator[np.ndarray]:
     frame : np.ndarray
         Video frame as a numpy array, shape (height, width, colors).
     """
+    extension = Path(filename).suffix.lower().lstrip('.')
+    if extension == 'gif':
+        from PIL import Image
+        with Image.open(filename) as img:
+            while True:
+                img_array = np.array(img.convert('RGB'))
+                yield img_array
+                try:
+                    img.seek(img.tell() + 1)
+                except EOFError:
+                    break
+        return
+
     av = _import_av()
     rotation = _get_rotation_from_metadata(filename)
     with av.open(Path(filename).expanduser()) as container:
@@ -172,6 +222,10 @@ class VideoStreamer:
             If 'auto', the index is cached only if building it takes
             more than 0.5 seconds, which only happens for ~1+ GB videos.
         """
+        extension = Path(filename).suffix.lower().lstrip('.')
+        if extension == 'gif':
+            raise NotImplementedError('Streaming from gifs not yet implemented. '
+                                      'Use load_video() or lazy_load_video() instead.')
         self.av = _import_av()
         self.verbose = verbose
         self.filename = Path(filename).expanduser()
@@ -210,10 +264,11 @@ class VideoStreamer:
 
             with self.av.open(str(self.filename)) as container:
                 stream = container.streams.video[0]
+                start_pts = stream.start_time if stream.start_time is not None else 0
                 # Access as packets to only read metadata (fast), not pixel data (slow)
                 for packet in tqdm(container.demux(stream), total=stream.frames,
                                    desc='Indexing frames', disable=not self.verbose):
-                    if packet.pts is not None:
+                    if packet.pts is not None and packet.pts >= start_pts:
                         frames_pts.append(packet.pts)
 
             # demux gave us packets in the order they appeared in the file
@@ -256,7 +311,7 @@ class VideoStreamer:
         pts_deltas = np.diff(frames_pts) if len(frames_pts) > 1 else None
         if pts_deltas is not None and (pts_deltas == pts_deltas[0]).all():
             # The video is constant framerate
-            self.pts_delta = pts_deltas[0]
+            self.pts_delta = int(pts_deltas[0])
             self._framerate = 1 / (self.pts_delta * self.time_base)
             if self._framerate.denominator == 1:
                 self._framerate = self._framerate.numerator
@@ -572,15 +627,20 @@ class AVVideoWriter:
     compression_speed : str, default 'medium'
         Compression speed preset: 'ultrafast', 'superfast', 'veryfast',
         'faster', 'fast', 'medium', 'slow', 'slower', 'veryslow'.
-    codec : Literal['libx264', 'libx265'], default 'libx264'
-        The video codec to use for encoding. Can be any of a number of aliases for
-        these two codecs, including avc1/h264 vs hevc/hvc1/hev1/h265.
+    codec : str or None, default None
+        The video codec to use for encoding. If None, automatically chosen based
+        on the file extension (e.g. libx264 for .mp4, libvpx-vp9 for .webm).
+        Accepts aliases like h264, h265, vp8, vp9, etc.
     """
     def __init__(self, filename, framerate=30, crf=23, compression_speed='medium',
-                 codec: Literal['libx264', 'libx265'] = 'libx264',
+                 codec: Literal['libx264', 'libx265', 'libvpx', 'libvpx-vp9', None] = None,
                  overwrite=False):
         self.av = _import_av()
         filename = Path(filename).expanduser()
+        extension = filename.suffix.lower().lstrip('.')
+        if extension == 'gif':
+            raise NotImplementedError('Saving to GIF format not yet implemented. '
+                                      'Use save_video() instead.')
         if filename.exists() and not overwrite:
             raise FileExistsError(f'File {filename} already exists. '
                                   'Set overwrite=True to overwrite.')
@@ -588,11 +648,20 @@ class AVVideoWriter:
         self._framerate = utils.limit_fraction(framerate)
         self.crf = crf
         self.compression_speed = compression_speed
-        self.codec = codec_aliases[codec.lower()]
+
+        if codec is None:
+            ext = filename.suffix.lower().lstrip('.')
+            self.codec = extension_default_codecs.get(ext, 'libx264')
+        else:
+            self.codec = codec_aliases[codec.lower()]
+
         self.container = self.av.open(filename, mode='w')
         self.stream = self.container.add_stream(self.codec, rate=self._framerate)
         self.stream.pix_fmt = 'yuv420p'
-        self.stream.options = {'crf': str(crf), 'preset': compression_speed}
+        if self.codec in ('libvpx', 'libvpx-vp9'):
+            self.stream.options = {'crf': str(crf), 'b:v': '0'}
+        else:
+            self.stream.options = {'crf': str(crf), 'preset': compression_speed}
         self._closed = False
         self.stream.width = 0
         self.stream.height = 0
@@ -676,14 +745,15 @@ class FFmpegVideoWriter:
     compression_speed : str, default 'medium'
         Compression speed preset: 'ultrafast', 'superfast', 'veryfast',
         'faster', 'fast', 'medium', 'slow', 'slower', 'veryslow'.
-    codec : Literal['libx264', 'libx265'], default 'libx264'
-        The video codec to use for encoding. Can be any of a number of aliases for
-        these two codecs, including avc1/h264 vs hevc/hvc1/hev1/h265.
+    codec : str or None, default None
+        The video codec to use for encoding. If None, automatically chosen based
+        on the file extension (e.g. libx264 for .mp4, libvpx-vp9 for .webm).
+        Accepts aliases like h264, h265, vp8, vp9, etc.
     overwrite : bool, default False
         Whether to overwrite the file if it already exists.
     """
     def __init__(self, filename, framerate=30, crf=23, compression_speed='medium',
-                 codec: Literal['libx264', 'libx265'] = 'libx264',
+                 codec: Literal['libx264', 'libx265', 'libvpx', 'libvpx-vp9', None] = None,
                  overwrite=False):
         filename = Path(filename).expanduser()
         if filename.exists() and not overwrite:
@@ -693,7 +763,12 @@ class FFmpegVideoWriter:
         self._framerate = utils.limit_fraction(framerate)
         self.crf = crf
         self.compression_speed = compression_speed
-        self.codec = codec_aliases[codec.lower()]
+
+        if codec is None:
+            ext = filename.suffix.lower().lstrip('.')
+            self.codec = extension_default_codecs.get(ext, 'libx264')
+        else:
+            self.codec = codec_aliases[codec.lower()]
 
         # Initialize process state
         self._process = None
@@ -725,9 +800,13 @@ class FFmpegVideoWriter:
             '-c:v', self.codec,
             '-pix_fmt', 'yuv420p',  # Output pixel format
             '-crf', str(self.crf),
-            '-preset', self.compression_speed,
-            self.filename
         ]
+        if self.codec in ('libvpx', 'libvpx-vp9'):
+            # VP8/VP9 need -b:v 0 for constant quality (CRF) mode
+            command += ['-b:v', '0']
+        else:
+            command += ['-preset', self.compression_speed]
+        command.append(str(self.filename))
 
         # Start FFmpeg process
         self._process = subprocess.Popen(
@@ -823,7 +902,9 @@ VideoWriter = FFmpegVideoWriter
 
 def save_video(data, filename, time_axis=0, color_axis=None, overwrite=False,
                dim_order='yx', framerate=30, crf=23, compression_speed='medium',
-               progress_bar=True, codec: Literal['libx264', 'libx265'] = 'libx264') -> None:
+               progress_bar=True, codec: Literal['libx264', 'libx265', 'libvpx',
+                                                 'libvpx-vp9', None] = None
+               ) -> None:
     """
     Save a 3D numpy array of greyscale values OR a 4D numpy array of RGB values as a video
 
@@ -869,9 +950,10 @@ def save_video(data, filename, time_axis=0, color_axis=None, overwrite=False,
     progress_bar : bool, default True
         If True, display a progress bar.
 
-    codec : Literal['libx264', 'libx265'], default 'libx264'
-        The video codec to use for encoding. Can be any of a number of aliases for
-        these two codecs, including avc1/h264 vs hevc/hvc1/hev1/h265.
+    codec : str or None, default None
+        The video codec to use for encoding. If None, automatically chosen based
+        on the file extension (e.g. libx264 for .mp4, libvpx-vp9 for .webm).
+        Accepts aliases like h264, h265, vp8, vp9, etc.
     """
 
     filename = str(filename)
@@ -920,6 +1002,36 @@ def save_video(data, filename, time_axis=0, color_axis=None, overwrite=False,
         if pad != [[0, 0], [0, 0], [0, 0]]:
             data = np.pad(data, pad, mode='edge')
 
+    if extension == 'gif':
+        from PIL import Image
+        pil_images = [Image.fromarray(frame) for frame in data]
+
+        # GIF frame delays must be multiples of 10ms, so GIF doesn't
+        # natively suppport framerates like 30 fps which require an
+        # inter-frame delay of 33.33 ms. To support arbitrary
+        # framerates, we copy the solution used in ffmpeg which is to
+        # use variable inter-frame intervals: 30 ms some frames and 40 ms
+        # others to achieve an average interval of 33.33 ms (for the
+        # example of 30 fps). Implementation of alternating delays:
+        ideal_delay_cs = 100 / framerate
+        lo = int(ideal_delay_cs)
+        hi = lo + 1
+        durations_ms = []
+        accumulated = 0.0
+        for _ in range(len(pil_images)):
+            accumulated += ideal_delay_cs
+            if accumulated >= hi:
+                durations_ms.append(hi * 10)
+                accumulated -= hi
+            else:
+                durations_ms.append(lo * 10)
+                accumulated -= lo
+
+        pil_images[0].save(filename, format='GIF', save_all=True,
+                           append_images=pil_images[1:],
+                           duration=durations_ms, loop=0)
+        return
+
     with VideoWriter(filename, framerate=framerate, crf=crf,
                      compression_speed=compression_speed, codec=codec,
                      overwrite=overwrite) as writer:

{numpyimage-3.5.2 → numpyimage-3.6.0/numpyimage.egg-info}/PKG-INFO

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

{numpyimage-3.5.2 → numpyimage-3.6.0}/numpyimage.egg-info/SOURCES.txt

@@ -16,4 +16,5 @@ numpyimage.egg-info/requires.txt
 numpyimage.egg-info/top_level.txt
 tests/test_heic.py
 tests/test_pbm.py
+tests/test_video_streamer.py
 tests/test_video_writers.py

{numpyimage-3.5.2 → numpyimage-3.6.0}/pyproject.toml

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

numpyimage-3.6.0/tests/test_video_streamer.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+Tests for VideoStreamer, particularly handling of HEVC videos with
+negative-PTS priming packets (common in iPhone recordings).
+"""
+
+import os
+import subprocess
+import tempfile
+
+import numpy as np
+
+import npimage
+
+
+def test_negative_pts_priming_packet():
+    """
+    Test that 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.
+    """
+    with tempfile.TemporaryDirectory() as tmpdir:
+        video_path = os.path.join(tmpdir, 'test_negative_pts.mp4')
+
+        # Create a small HEVC video with a negative-PTS priming packet.
+        # The -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',
+            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
+        import av
+        with av.open(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(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 '
+            f'decoded frames ({len(frame_pts)}). The test setup may need '
+            f'updating if ffmpeg behavior has changed.'
+        )
+        assert pkt_pts[0] < 0, (
+            f'First packet PTS should be negative, got {pkt_pts[0]}'
+        )
+
+        # Now test that VideoStreamer handles this correctly
+        vid = npimage.VideoStreamer(video_path)
+
+        # The number of frames should match decoded frames, not packets
+        assert vid.n_frames == len(frame_pts), (
+            f'Expected {len(frame_pts)} frames, got {vid.n_frames}'
+        )
+
+        # Accessing frame 0 should work without raising VideoSeekError
+        frame = vid[0]
+        assert isinstance(frame, np.ndarray)
+        assert frame.shape == (240, 320, 3)
+
+        # Accessing the last frame should also work
+        last_frame = vid[vid.n_frames - 1]
+        assert isinstance(last_frame, np.ndarray)
+
+        print(f'PASSED: Loaded {vid.n_frames} frames from video with '
+              f'negative-PTS priming packet')
+
+
+def main():
+    test_negative_pts_priming_packet()
+    print('\nAll VideoStreamer tests passed.')
+
+
+if __name__ == '__main__':
+    main()