numpyimage 2.6.0__tar.gz → 2.6.1__tar.gz

{numpyimage-2.6.0 → numpyimage-2.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 2.6.0
+Version: 2.6.1
 Summary: Load, save, & manipulate image files as numpy arrays
 Author-email: Jasper Phelps <jasper.s.phelps@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -701,18 +701,19 @@ Requires-Dist: av; extra == "all"
 Dynamic: license-file
 
 # npimage
-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 `core.py` does that, with `array = load(filename)`, `save(array, filename)`, and `show(array)` functions that let you easily handle a number of common image file formats without having to remember library-specific syntax. (Another choice of library to consider for accomplishing similar goals is [imageio](https://pypi.org/project/imageio/), which also supports loading videos through the FFmpeg wrapper library [pyav](https://pypi.org/project/av/).)
+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!)
 
 
 ### Documentation
-- `core.py`: load, save, or show images.
+- `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.
 - `nrrd_utils.py`: compress or read metadata from `.nrrd` files.
 - `operations.py`: perform operations on images.
 
-For now, check each function's docstring for more. A jupyter notebook demonstrating this package's functions will come later.
+Check each function's docstring for more details.
 
 
 ### Installation

{numpyimage-2.6.0 → numpyimage-2.6.1}/README.md

@@ -1,16 +1,17 @@
 # npimage
-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 `core.py` does that, with `array = load(filename)`, `save(array, filename)`, and `show(array)` functions that let you easily handle a number of common image file formats without having to remember library-specific syntax. (Another choice of library to consider for accomplishing similar goals is [imageio](https://pypi.org/project/imageio/), which also supports loading videos through the FFmpeg wrapper library [pyav](https://pypi.org/project/av/).)
+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!)
 
 
 ### Documentation
-- `core.py`: load, save, or show images.
+- `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.
 - `nrrd_utils.py`: compress or read metadata from `.nrrd` files.
 - `operations.py`: perform operations on images.
 
-For now, check each function's docstring for more. A jupyter notebook demonstrating this package's functions will come later.
+Check each function's docstring for more details.
 
 
 ### Installation

{numpyimage-2.6.0 → numpyimage-2.6.1}/npimage/__init__.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python3
 
-from .core import *
+from .imageio import *
+from .vidio import *
+
 from .operations import *
 from .align import *
 from .graphics import *

{numpyimage-2.6.0 → numpyimage-2.6.1}/npimage/graphics.py

@@ -686,7 +686,7 @@ def floodfill(image, seed, fill_value, fill_diagonally=False,
 
         if debug_frequency is not None and iteration % debug_frequency == 0:
             print(f'Writing iteration{iteration}.nrrd')
-            from .core import save
+            from .imageio import save
             save(image, f'iteration{iteration}.nrrd')
 
         #recurseifneighbors

numpyimage-2.6.0/npimage/core.py → numpyimage-2.6.1/npimage/imageio.py

@@ -5,11 +5,10 @@ Functions for reading, writing, and showing images.
 Function list:
 - load(filename) -> numpy.ndarray
 - save(data, filename) -> Saves a numpy array as an nD image file
-- save_video(data, filename) -> Saves a 3D numpy array as a video
 - show(np_array) -> Displays a numpy array of pixel values as an image
 """
 
-from typing import Literal, Union, Tuple, Iterator
+from typing import Literal, Union, Tuple
 import os
 import glob
 from builtins import open as builtin_open
@@ -361,286 +360,6 @@ write = save  # Function name alias
 to_file = save  # Function name alias
 
 
-def load_video(filename,
-               return_framerate=False,
-               progress_bar=True) -> Union[np.ndarray, Tuple[np.ndarray, float]]:
-    """
-    Load all images in a video file as a numpy array.
-
-    Parameters
-    ----------
-    filename : str
-        Path to the video file
-    return_framerate : bool, default False
-        If True, return the frame rate of the video
-    progress_bar : bool, default True
-        If True, display a progress bar
-
-    Returns
-    -------
-    data : numpy.ndarray
-        The video frames as a numpy array, shape (num_frames, height, width, colors)
-    """
-    try:
-        import av
-        from tqdm import tqdm
-    except ImportError:
-        raise ImportError('Missing optional dependency for video processing,'
-                          ' run `pip install av tqdm`')
-
-    container = av.open(filename)
-    stream = container.streams.video[0]
-    num_frames = stream.frames
-    if not num_frames or num_frames == 0:
-        # If we don't know the number of frames, we can't preallocate, so
-        # it's hard to do better than the following approach which temporarily
-        # uses double the amount of RAM compared to the preallocated approach.
-        data = np.array(list(lazy_load_video(filename)))
-        if return_framerate:
-            return data, float(stream.average_rate)
-        else:
-            return data
-    else:
-        # Load first image to get shape and dtype
-        frame_iter = container.decode(stream)
-        first_frame = next(frame_iter)
-        first_img = first_frame.to_ndarray(format='rgb24')
-        # Preallocate memory for the entire array
-        data = np.empty((num_frames, *first_img.shape), dtype=first_img.dtype)
-        # Then fill it up frame by frame
-        data[0] = first_img
-        for i, frame in tqdm(enumerate(frame_iter), total=num_frames,
-                             desc='Loading video', disable=not progress_bar):
-            if i == 0:
-                continue
-            img = frame.to_ndarray(format='rgb24')
-            data[i] = img
-        if return_framerate:
-            return data, float(stream.average_rate)
-        else:
-            return data
-
-
-def lazy_load_video(filename) -> Iterator[np.ndarray]:
-    """
-    Lazily load video frames as numpy arrays using PyAV.
-
-    Parameters
-    ----------
-    filename : str
-        Path to the video file.
-
-    Yields
-    ------
-    frame : np.ndarray
-        Video frame as a numpy array, shape (height, width, colors).
-    """
-    try:
-        import av
-    except ImportError:
-        raise ImportError('Missing optional dependency for video processing,'
-                          ' run `pip install av tqdm`')
-    container = av.open(filename)
-    stream = container.streams.video[0]
-    for frame in container.decode(stream):
-        img = frame.to_ndarray(format='rgb24')
-        yield img
-
-
-codec_aliases = {
-    "libx264": "libx264",
-    "avc1": "libx264",
-    "h264": "libx264",
-    "H.264": "libx264",
-    "libx265": "libx265",
-    "hevc": "libx265",
-    "hvc1": "libx265",
-    "hev1": "libx265",
-    "h265": "libx265",
-    "H.265": "libx265",
-}
-
-
-class VideoWriter:
-    """
-    Create a video writer object for saving frames to a video file.
-
-    Parameters
-    ----------
-    filename : str
-        The filename to save the video to.
-    framerate : int, default 30
-        The frame rate of the video.
-    crf : int, default 23
-        Constant Rate Factor for encoding quality (lower is better quality).
-    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.
-    """
-    def __init__(self, filename, framerate=30, crf=23, compression_speed='medium',
-                 codec: Literal['libx264', 'libx265'] = 'libx264',
-                 overwrite=False):
-        try:
-            import av
-        except ImportError:
-            raise ImportError('Missing optional dependency for video processing,'
-                              ' run `pip install av tqdm`')
-        self.av = av
-        filename = os.path.expanduser(str(filename))
-        if os.path.exists(filename) and not overwrite:
-            raise FileExistsError(f'File {filename} already exists. '
-                                  'Set overwrite=True to overwrite.')
-        self.filename = filename
-        self.framerate = framerate
-        self.crf = crf
-        self.compression_speed = compression_speed
-        self.codec = codec_aliases[codec.lower()]
-        self.container = av.open(filename, mode='w')
-        self.stream = self.container.add_stream(self.codec, rate=framerate)
-        self.stream.pix_fmt = 'yuv420p'
-        self.stream.options = {'crf': str(crf), 'preset': compression_speed}
-        self._closed = False
-        self.stream.width = 0
-        self.stream.height = 0
-
-    def write(self, frame):
-        if not isinstance(frame, self.av.VideoFrame):
-            if frame.ndim == 3 and frame.shape[-1] == 3:
-                frame = self.av.VideoFrame.from_ndarray(frame, format='rgb24')
-            elif frame.ndim == 2:
-                frame = self.av.VideoFrame.from_ndarray(frame, format='gray')
-            else:
-                raise ValueError(f'Frame must be (H, W) or (H, W, 3) but was {frame.shape}')
-        if self.stream.width == 0:
-            self.stream.width = frame.width
-        if self.stream.height == 0:
-            self.stream.height = frame.height
-        for packet in self.stream.encode(frame):
-            self.container.mux(packet)
-
-    def __enter__(self):
-        return self
-
-    def __exit__(self, exc_type, exc_val, exc_tb):
-        # Flush stream
-        for packet in self.stream.encode():
-            self.container.mux(packet)
-        self.container.close()
-        self._closed = True
-
-
-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:
-    """
-    Save a 3D numpy array of greyscale values OR a 4D numpy array of RGB values as a video
-
-    Follows the PyAV cookbook section on generating video from numpy arrays:
-    https://pyav.basswood-io.com/docs/develop/cookbook/numpy.html#generating-video
-
-    Parameters
-    ----------
-    data : numpy.ndarray or list of filenames
-        A 3D (grayscale) or 4D (RGB) numpy array of pixel values.
-
-    filename : str
-        The filename to save the video to.
-
-    time_axis : int, default 0
-        The axis of the data array that will be played as time in the video.
-
-    color_axis : int or None, default None
-        If not None, specifies the axis of the color channels (e.g., -1 for last axis,
-        1 for second axis).
-        If None, data must be 3D (greyscale) or 4D with one length 3 axis (RGB).
-
-    overwrite : bool, default False
-        Whether to overwrite the file if it already exists.
-
-    dim_order : 'yx' (default) or 'xy'
-        The order of the spatial dimensions in the input data.
-
-    framerate : int, default 30
-        The frame rate of the video.
-
-    crf : int, default 23
-        Constant Rate Factor that specifies amount of lossiness allowed in compression.
-        Lower values produce better quality, larger videos. crf=17 has no human-visible
-        compression artifacts. File size approximately doubles/halves each time you
-        add/subtract 6 from crf, so crf=17 produces files about twice as large as
-        the default crf=23.
-
-    compression_speed : str, default 'medium'
-        Compression speed preset: 'ultrafast', 'superfast', 'veryfast',
-        'faster', 'fast', 'medium', 'slow', 'slower', 'veryslow'.
-
-    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.
-    """
-    try:
-        from tqdm import tqdm
-    except ImportError:
-        raise ImportError('Missing optional dependency for video processing,'
-                          ' run `pip install av tqdm`')
-
-    filename = os.path.expanduser(str(filename))
-    if filename.split('.')[-1].lower() not in ['mp4', 'mkv', 'avi', 'mov']:
-        filename += '.mp4'
-    if os.path.exists(filename) and not overwrite:
-        raise FileExistsError(f'File {filename} already exists. '
-                              'Set overwrite=True to overwrite.')
-
-    if color_axis is None and data.ndim == 4:
-        color_axis = find_channel_axis(data, possible_channel_lengths=3)
-        if color_axis is None:
-            raise ValueError('4D input data must have an RGB (length 3) axis.')
-    if color_axis is not None:
-        if data.ndim != 4:
-            raise ValueError('Input data must be 4D when color_axis is specified.')
-        # Move time axis to 0, color axis to -1
-        data = np.moveaxis(data, time_axis, 0)
-        if color_axis != -1:
-            data = np.moveaxis(data, color_axis, -1)
-        if 'xy' in dim_order:
-            data = data.swapaxes(1, 2)
-        n_frames = data.shape[0]
-        height, width, channels = data.shape[1:]
-        if channels != 3:
-            raise ValueError(f'Color video must have 3 channels (RGB) but had {channels}.')
-    else:
-        if data.ndim != 3:
-            raise ValueError('Input data must be 3D when color_axis is not specified.')
-        data = np.moveaxis(data, time_axis, 0)
-        if 'xy' in dim_order:
-            data = data.swapaxes(1, 2)
-        n_frames = data.shape[0]
-        height, width = data.shape[1:]
-
-    extension = filename.split('.')[-1].lower()
-    if extension == 'mp4':
-        pad = [[0, 0], [0, 0], [0, 0]]
-        if height % 2 != 0:
-            pad[1][1] = 1
-        if width % 2 != 0:
-            pad[2][1] = 1
-        if pad != [[0, 0], [0, 0], [0, 0]]:
-            data = np.pad(data, pad, mode='edge')
-
-    with VideoWriter(filename, framerate=framerate, crf=crf,
-                     compression_speed=compression_speed, codec=codec,
-                     overwrite=overwrite) as writer:
-        for frame_i in tqdm(range(n_frames), total=n_frames,
-                            desc='Saving video', disable=not progress_bar):
-            writer.write(data[frame_i])
-
-
 def show(data,
          dim_order='yx',
          data_type: Literal['image', 'segmentation'] = 'image',

numpyimage-2.6.1/npimage/vidio.py

@@ -0,0 +1,489 @@
+#!/usr/bin/env python3
+"""
+Functions for reading, writing, and showing images.
+
+Function list:
+- load_video(filename) -> np.ndarray
+- lazy_load_video(filename) -> Iterator[np.ndarray]
+- save_video(data, filename) -> Saves a 3D numpy array as a video
+
+"""
+
+from typing import Union, Tuple, Iterator, Literal
+from pathlib import Path
+import os
+import subprocess
+import threading
+import json
+
+import numpy as np
+
+from .imageio import find_channel_axis
+
+codec_aliases = {
+    "libx264": "libx264",
+    "avc1": "libx264",
+    "h264": "libx264",
+    "H.264": "libx264",
+    "libx265": "libx265",
+    "hevc": "libx265",
+    "hvc1": "libx265",
+    "hev1": "libx265",
+    "h265": "libx265",
+    "H.265": "libx265",
+}
+
+
+def load_video(filename,
+               return_framerate=False,
+               progress_bar=True) -> Union[np.ndarray, Tuple[np.ndarray, float]]:
+    """
+    Load all images in a video file as a numpy array.
+
+    Parameters
+    ----------
+    filename : str
+        Path to the video file
+    return_framerate : bool, default False
+        If True, return the frame rate of the video
+    progress_bar : bool, default True
+        If True, display a progress bar
+
+    Returns
+    -------
+    data : numpy.ndarray
+        The video frames as a numpy array, shape (num_frames, height, width, colors)
+    """
+    try:
+        import av
+        from tqdm import tqdm
+    except ImportError:
+        raise ImportError('Missing optional dependency for video processing,'
+                          ' run `pip install av tqdm`')
+
+    container = av.open(filename)
+    stream = container.streams.video[0]
+    num_frames = stream.frames
+    if not num_frames or num_frames == 0:
+        # If we don't know the number of frames, we can't preallocate, so
+        # it's hard to do better than the following approach which temporarily
+        # uses double the amount of RAM compared to the preallocated approach.
+        data = np.array(list(lazy_load_video(filename)))
+        if return_framerate:
+            return data, float(stream.average_rate)
+        else:
+            return data
+    else:
+        # Load first image to get shape and dtype
+        frame_iter = container.decode(stream)
+        first_frame = next(frame_iter)
+        first_img = first_frame.to_ndarray(format='rgb24')
+        # Preallocate memory for the entire array
+        data = np.empty((num_frames, *first_img.shape), dtype=first_img.dtype)
+        # Then fill it up frame by frame
+        data[0] = first_img
+        for i, frame in tqdm(enumerate(frame_iter), total=num_frames,
+                             desc='Loading video', disable=not progress_bar):
+            if i == 0:
+                continue
+            img = frame.to_ndarray(format='rgb24')
+            data[i] = img
+        if return_framerate:
+            return data, float(stream.average_rate)
+        else:
+            return data
+
+
+def lazy_load_video(filename) -> Iterator[np.ndarray]:
+    """
+    Lazily load video frames as numpy arrays using PyAV.
+
+    This iterator yields images in the order they appear in the video.
+    If you want reasonably fast random access to arbitrary frames in
+    a video, use the VideoStreamer class instead.
+
+    Parameters
+    ----------
+    filename : str
+        Path to the video file.
+
+    Yields
+    ------
+    frame : np.ndarray
+        Video frame as a numpy array, shape (height, width, colors).
+    """
+    try:
+        import av
+    except ImportError:
+        raise ImportError('Missing optional dependency for video processing,'
+                          ' run `pip install av tqdm`')
+    container = av.open(filename)
+    stream = container.streams.video[0]
+    for frame in container.decode(stream):
+        img = frame.to_ndarray(format='rgb24')
+        yield img
+
+
+class VideoStreamer:
+    def __init__(self, filename):
+        try:
+            import av
+        except ImportError:
+            raise ImportError('Missing optional dependency for video processing,'
+                              ' run `pip install av tqdm`')
+        self.filename = Path(filename)
+        if not self.filename.exists():
+            raise FileNotFoundError(f"File {filename} not found")
+        self.index_filename = Path(str(filename).replace('.mp4', '_index.json'))
+        self._load_index()
+
+        self.container = av.open(str(self.filename))
+        self.stream = self.container.streams.video[0]
+        self.time_base = self.stream.time_base
+        self._shape = None
+        self._first_frame = None
+        self._current_frame_number = None
+        self._lock = threading.Lock()
+
+    def _build_index(self):
+        print("Building index for fast random frame access...")
+        cmd = [
+            'ffprobe',
+            '-select_streams', 'v:0',
+            '-show_frames',
+            '-show_entries', 'frame=pkt_pos,pkt_pts_time,coded_picture_number',
+            '-of', 'json',
+            self.filename
+        ]
+        result = subprocess.run(cmd, stdout=subprocess.PIPE,
+                                stderr=subprocess.PIPE, text=True)
+        if result.returncode != 0:
+            raise RuntimeError(f"ffprobe failed: {result.stderr}")
+        frames = json.loads(result.stdout).get('frames', [])
+        time_index = [float(frame['pkt_pts_time']) for frame in frames]
+        if len(time_index) == 0:
+            raise RuntimeError("No frames found in video")
+        self.n_frames = len(time_index)
+        self.t0 = time_index[0]
+        index = {
+            'n_frames': self.n_frames,
+            't0': self.t0,
+        }
+
+        # Determine whether the video is constant or variable framerate
+        time_deltas = np.diff(time_index) if len(time_index) > 1 else None
+        if time_deltas is not None and np.allclose(time_deltas, time_deltas[0], atol=1e-6):
+            self.timestep = float(time_deltas[0])  # The video is constant framerate
+            index['timestep'] = self.timestep
+        else:
+            index.update({
+                'timestep': 'variable',  # The video is variable framerate
+                'time_index': time_index,
+            })
+        with open(self.index_filename, 'w') as f:
+            json.dump(index, f)
+        print(f"Saved index to {self.index_filename} so this slow step is not needed again.")
+
+    def _load_index(self):
+        if not self.index_filename.exists():
+            self._build_index()
+        else:
+            with open(self.index_filename, 'r') as f:
+                index = json.load(f)
+        self.n_frames = index['n_frames']
+        self.t0 = index['t0']
+
+        if not isinstance(index['timestep'], (str, float, int)):
+            raise ValueError('Malformed index: timestep is not a string or number')
+
+        if index['timestep'] == 'variable':
+            self.timestep = 'variable'
+            self.time_index = index['time_index']
+        else:
+            self.timestep = float(index['timestep'])
+            if self.timestep <= 0:
+                raise ValueError('Malformed index: timestep is not positive')
+
+    def frame_to_time(self, frame_number):
+        if self.timestep == 'variable':
+            return self.time_index[frame_number]
+        else:
+            return self.timestep * frame_number + self.t0
+
+    def __getitem__(self, key):
+        if isinstance(key, tuple):
+            frame_idx = key[0]
+            frame = self._get_frame(frame_idx)
+            if len(key) == 1:
+                return frame
+            else:
+                return frame[key[1:]]
+        else:
+            return self._get_frame(key)
+
+    def _get_frame(self, frame_number):
+        """
+        Provides access to random frames as fast as is reasonable when getting
+        frames from compressed video in python.
+        """
+        
+        def decode_until(frame_number) -> np.ndarray:
+            """
+            Decode forward from the current frame in the stream until we get
+            to the requested frame number.
+            """
+            target_time = self.frame_to_time(frame_number)
+            for frame in self.container.decode(self.stream):
+                frame_time = float(frame.pts * self.time_base)
+                if abs(frame_time - target_time) < 1e-6:
+                    frame = frame.to_ndarray(format='rgb24')
+                    self._current_frame_number = frame_number
+                    return frame
+                if frame_time > target_time:
+                    raise RuntimeError(f"Frame with time {target_time} not found after"
+                                       f" seeking – current frame time: {frame_time}")
+            raise RuntimeError(f"Frame with time {target_time} not found after"
+                               f" seeking – current frame time: {frame_time}")
+
+        if isinstance(frame_number, slice):  # Support slicing
+            start, stop, step = frame_number.indices(self.n_frames)
+            return np.array([self._get_frame(i) for i in range(start, stop, step)])
+        with self._lock:
+            if frame_number < 0 or frame_number >= self.n_frames:
+                raise IndexError(f"Frame {frame_number} out of range: [0, {self.n_frames})")
+
+            if (self._current_frame_number is None
+                    or frame_number <= self._current_frame_number
+                    or frame_number > self._current_frame_number + 100):
+                target_time = self.frame_to_time(frame_number)
+                seek_time = int(target_time / float(self.time_base))
+                # The following actually seeks to the closest keyframe before
+                # seek_time, because it's not possible to seek directly to
+                # non-keyframes due to video files being compressed.
+                self.container.seek(seek_time, any_frame=False,
+                                    backward=True, stream=self.stream)
+            # Now we decode frames forward until we get to the requested frame
+            return decode_until(frame_number)
+
+    @property
+    def first_frame(self):
+        if self._first_frame is None:
+            self._first_frame = self[0]
+        return self._first_frame
+
+    @property
+    def shape(self):
+        # (num_frames, height, width, channels)
+        if self._shape is None:
+            self._shape = (self.n_frames,) + self.first_frame.shape
+        return self._shape
+
+    @property
+    def ndim(self):
+        return len(self.shape)
+
+    @property
+    def dtype(self):
+        return self.first_frame.dtype
+
+    def __len__(self):
+        return self.n_frames
+
+    def close(self):
+        self.container.close()
+
+    def __del__(self):
+        try:
+            self.close()
+        except Exception:
+            pass
+
+
+class VideoWriter:
+    """
+    Create a video writer object for saving frames to a video file.
+
+    Example usage:
+    >>> with VideoWriter('output.mp4', framerate=30) as writer:
+    >>>     for i in range(n_frames):
+    >>>         frame = do_something_to_build_an_image(i)
+    >>>         writer.write(frame)
+
+    This allows you to write a bunch of frames to a video file without
+    ever needing to store all the frames in memory at once. If you have all
+    your frames in memory already, you could use save_video(data, filename)
+
+    Parameters
+    ----------
+    filename : str
+        The filename to save the video to.
+    framerate : int, default 30
+        The frame rate of the video.
+    crf : int, default 23
+        Constant Rate Factor for encoding quality (lower is better quality).
+    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.
+    """
+    def __init__(self, filename, framerate=30, crf=23, compression_speed='medium',
+                 codec: Literal['libx264', 'libx265'] = 'libx264',
+                 overwrite=False):
+        try:
+            import av
+        except ImportError:
+            raise ImportError('Missing optional dependency for video processing,'
+                              ' run `pip install av tqdm`')
+        self.av = av
+        filename = os.path.expanduser(str(filename))
+        if os.path.exists(filename) and not overwrite:
+            raise FileExistsError(f'File {filename} already exists. '
+                                  'Set overwrite=True to overwrite.')
+        self.filename = filename
+        self.framerate = framerate
+        self.crf = crf
+        self.compression_speed = compression_speed
+        self.codec = codec_aliases[codec.lower()]
+        self.container = av.open(filename, mode='w')
+        self.stream = self.container.add_stream(self.codec, rate=framerate)
+        self.stream.pix_fmt = 'yuv420p'
+        self.stream.options = {'crf': str(crf), 'preset': compression_speed}
+        self._closed = False
+        self.stream.width = 0
+        self.stream.height = 0
+
+    def write(self, frame):
+        if not isinstance(frame, self.av.VideoFrame):
+            if frame.ndim == 3 and frame.shape[-1] == 3:
+                frame = self.av.VideoFrame.from_ndarray(frame, format='rgb24')
+            elif frame.ndim == 2:
+                frame = self.av.VideoFrame.from_ndarray(frame, format='gray')
+            else:
+                raise ValueError(f'Frame must be (H, W) or (H, W, 3) but was {frame.shape}')
+        if self.stream.width == 0:
+            self.stream.width = frame.width
+        if self.stream.height == 0:
+            self.stream.height = frame.height
+        for packet in self.stream.encode(frame):
+            self.container.mux(packet)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        # Flush stream
+        for packet in self.stream.encode():
+            self.container.mux(packet)
+        self.container.close()
+        self._closed = True
+
+
+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:
+    """
+    Save a 3D numpy array of greyscale values OR a 4D numpy array of RGB values as a video
+
+    Follows the PyAV cookbook section on generating video from numpy arrays:
+    https://pyav.basswood-io.com/docs/develop/cookbook/numpy.html#generating-video
+
+    Parameters
+    ----------
+    data : numpy.ndarray or list of filenames
+        A 3D (grayscale) or 4D (RGB) numpy array of pixel values.
+
+    filename : str
+        The filename to save the video to.
+
+    time_axis : int, default 0
+        The axis of the data array that will be played as time in the video.
+
+    color_axis : int or None, default None
+        If not None, specifies the axis of the color channels (e.g., -1 for last axis,
+        1 for second axis).
+        If None, data must be 3D (greyscale) or 4D with one length 3 axis (RGB).
+
+    overwrite : bool, default False
+        Whether to overwrite the file if it already exists.
+
+    dim_order : 'yx' (default) or 'xy'
+        The order of the spatial dimensions in the input data.
+
+    framerate : int, default 30
+        The frame rate of the video.
+
+    crf : int, default 23
+        Constant Rate Factor that specifies amount of lossiness allowed in compression.
+        Lower values produce better quality, larger videos. crf=17 has no human-visible
+        compression artifacts. File size approximately doubles/halves each time you
+        add/subtract 6 from crf, so crf=17 produces files about twice as large as
+        the default crf=23.
+
+    compression_speed : str, default 'medium'
+        Compression speed preset: 'ultrafast', 'superfast', 'veryfast',
+        'faster', 'fast', 'medium', 'slow', 'slower', 'veryslow'.
+
+    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.
+    """
+    try:
+        from tqdm import tqdm
+    except ImportError:
+        raise ImportError('Missing optional dependency for video processing,'
+                          ' run `pip install av tqdm`')
+
+    filename = os.path.expanduser(str(filename))
+    if filename.split('.')[-1].lower() not in ['mp4', 'mkv', 'avi', 'mov']:
+        filename += '.mp4'
+    if os.path.exists(filename) and not overwrite:
+        raise FileExistsError(f'File {filename} already exists. '
+                              'Set overwrite=True to overwrite.')
+
+    if color_axis is None and data.ndim == 4:
+        color_axis = find_channel_axis(data, possible_channel_lengths=3)
+        if color_axis is None:
+            raise ValueError('4D input data must have an RGB (length 3) axis.')
+    if color_axis is not None:
+        if data.ndim != 4:
+            raise ValueError('Input data must be 4D when color_axis is specified.')
+        # Move time axis to 0, color axis to -1
+        data = np.moveaxis(data, time_axis, 0)
+        if color_axis != -1:
+            data = np.moveaxis(data, color_axis, -1)
+        if 'xy' in dim_order:
+            data = data.swapaxes(1, 2)
+        n_frames = data.shape[0]
+        height, width, channels = data.shape[1:]
+        if channels != 3:
+            raise ValueError(f'Color video must have 3 channels (RGB) but had {channels}.')
+    else:
+        if data.ndim != 3:
+            raise ValueError('Input data must be 3D when color_axis is not specified.')
+        data = np.moveaxis(data, time_axis, 0)
+        if 'xy' in dim_order:
+            data = data.swapaxes(1, 2)
+        n_frames = data.shape[0]
+        height, width = data.shape[1:]
+
+    extension = filename.split('.')[-1].lower()
+    if extension == 'mp4':
+        pad = [[0, 0], [0, 0], [0, 0]]
+        if height % 2 != 0:
+            pad[1][1] = 1
+        if width % 2 != 0:
+            pad[2][1] = 1
+        if pad != [[0, 0], [0, 0], [0, 0]]:
+            data = np.pad(data, pad, mode='edge')
+
+    with VideoWriter(filename, framerate=framerate, crf=crf,
+                     compression_speed=compression_speed, codec=codec,
+                     overwrite=overwrite) as writer:
+        for frame_i in tqdm(range(n_frames), total=n_frames,
+                            desc='Saving video', disable=not progress_bar):
+            writer.write(data[frame_i])

{numpyimage-2.6.0 → numpyimage-2.6.1}/numpyimage.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 2.6.0
+Version: 2.6.1
 Summary: Load, save, & manipulate image files as numpy arrays
 Author-email: Jasper Phelps <jasper.s.phelps@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -701,18 +701,19 @@ Requires-Dist: av; extra == "all"
 Dynamic: license-file
 
 # npimage
-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 `core.py` does that, with `array = load(filename)`, `save(array, filename)`, and `show(array)` functions that let you easily handle a number of common image file formats without having to remember library-specific syntax. (Another choice of library to consider for accomplishing similar goals is [imageio](https://pypi.org/project/imageio/), which also supports loading videos through the FFmpeg wrapper library [pyav](https://pypi.org/project/av/).)
+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!)
 
 
 ### Documentation
-- `core.py`: load, save, or show images.
+- `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.
 - `nrrd_utils.py`: compress or read metadata from `.nrrd` files.
 - `operations.py`: perform operations on images.
 
-For now, check each function's docstring for more. A jupyter notebook demonstrating this package's functions will come later.
+Check each function's docstring for more details.
 
 
 ### Installation

{numpyimage-2.6.0 → numpyimage-2.6.1}/numpyimage.egg-info/SOURCES.txt

@@ -3,11 +3,12 @@ README.md
 pyproject.toml
 npimage/__init__.py
 npimage/align.py
-npimage/core.py
 npimage/graphics.py
+npimage/imageio.py
 npimage/nrrd_utils.py
 npimage/operations.py
 npimage/utils.py
+npimage/vidio.py
 numpyimage.egg-info/PKG-INFO
 numpyimage.egg-info/SOURCES.txt
 numpyimage.egg-info/dependency_links.txt

{numpyimage-2.6.0 → numpyimage-2.6.1}/pyproject.toml

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