numpyimage 2.6.1__tar.gz → 2.6.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 2.6.1
+Version: 2.6.3
 Summary: Load, save, & manipulate image files as numpy arrays
 Author-email: Jasper Phelps <jasper.s.phelps@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE

{numpyimage-2.6.1 → numpyimage-2.6.3}/npimage/imageio.py

@@ -15,7 +15,7 @@ from builtins import open as builtin_open
 
 import numpy as np
 
-from . import operations, utils
+from . import vidio, operations, utils
 
 supported_extensions = [
     'tif', 'tiff', 'jpg', 'jpeg', 'png', 'pbm',
@@ -43,7 +43,9 @@ def load(filename, dim_order='zyx', **kwargs) -> Union[np.ndarray, Tuple[np.ndar
         raise ValueError('Could not determine file format from filename'
                          f' "{filename}". Please specify the file type via'
                          ' the `format` argument, e.g. format="tif"')
-    if extension not in supported_extensions:
+    if extension in vidio.supported_extensions:
+        return vidio.VideoStreamer(filename)
+    elif extension not in supported_extensions:
         raise ValueError(f'File format of "{filename}" not supported/recognized.')
 
     data = None
@@ -178,7 +180,7 @@ def save(data,
               '.nrrd. Whether or not compression occurs now will depend on '
               'the format you are saving to.')
 
-    channel_axis = find_channel_axis(data)
+    channel_axis = utils.find_channel_axis(data)
     if 'xy' in dim_order:
         data = data.T
         if hasattr(pixel_size, '__iter__') and not isinstance(pixel_size, str):
@@ -392,7 +394,7 @@ def show(data,
     if data_type == 'segmentation':
         data = utils.assign_random_colors(data, seed=kwargs.get('seed', None))
 
-    if (not data.ndim == 2) and not (data.ndim == 3 and find_channel_axis(data) is not None):
+    if (not data.ndim == 2) and not (data.ndim == 3 and utils.find_channel_axis(data) is not None):
         m = ('Data must have shape (y, x) for grayscale, '
              '(y, x, 3) for RGB, or (y, x, 4) for RGBA but had '
              f'shape {data.shape}')
@@ -403,9 +405,9 @@ def show(data,
     if 'xy' in dim_order:
         data = data.T
     if channel_axis == 'guess':
-        channel_axis = find_channel_axis(data)
+        channel_axis = utils.find_channel_axis(data)
     if utils.isint(channel_axis) and channel_axis != -1:
-        data = np.moveaxis(data, find_channel_axis(data), -1)
+        data = np.moveaxis(data, utils.find_channel_axis(data), -1)
 
     if convert_to_8bit and data.dtype != np.uint8:
         data = operations.to_8bit(data)
@@ -430,60 +432,6 @@ def show(data,
 imshow = show  # Function name alias
 
 
-def find_channel_axis(data,
-                      possible_channel_axes=[-1, 0],
-                      possible_channel_lengths=[2, 3, 4]) -> Union[int, None]:
-    """
-    If the given numpy array has a shape suggesting that it has a
-    channel (color) axis (that is, any axis with length 2 (2-color),
-    3 (RGB), or 4 (RGBA)), return the index of that axis.
-
-    Parameters
-    ----------
-    data : numpy.ndarray
-        The numpy array to check for a channel axis.
-
-    possible_channel_axes : int or list of int, default [0, -1]
-        If None, any axis having length 2, 3, or 4 will be considered
-        a channel axis.
-        If an int, only that axis index will be checked.
-        If a list of ints, all axes with those indices will be checked.
-        The default value of [-1, 0] checks the last and first axes, which is
-        almost always where a channel axis will be found.
-
-    possible_channel_lengths : int or list of int, default [2, 3, 4]
-        If an int, only that length will be considered a channel axis.
-        If a list of ints, an axis with any of those lengths will be considered
-        a channel axis.
-
-    Returns
-    -------
-    int or None
-        The index of the channel axis, or None if no channel axis was found.
-
-        If possible_channel_axes is given, the returned value will be one of
-        the possible_channel_axes values, or None if no channel axis was found.
-
-        If possible_channel_axes is None, the returned value will be between
-        0 and data.ndim - 1, inclusive, or None if no channel axis was found.
-
-        Note that returning 0 means the channel axis was found and is the first
-        axis, so be careful not to do a test like `if find_channel_axis(data):`
-        because 0 will evaluate to False even though the data has a channel axis.
-        Instead write `if find_channel_axis(data) is not None:`
-    """
-    if isinstance(possible_channel_axes, int):
-        possible_channel_axes = [possible_channel_axes]
-    if possible_channel_axes is None:
-        possible_channel_axes = range(data.ndim)
-    if isinstance(possible_channel_lengths, int):
-        possible_channel_lengths = [possible_channel_lengths]
-    for axis in possible_channel_axes:
-        if data.shape[axis] in possible_channel_lengths:
-            return axis
-    return None
-
-
 # Flag to track if HEIF opener has been registered
 _heif_opener_registered = False
 def _ensure_heif_opener_registered() -> None:

{numpyimage-2.6.1 → numpyimage-2.6.3}/npimage/utils.py

@@ -11,6 +11,7 @@ Function list:
 - transpose_metadata (reverse the order of all per-axis metadata values)
 """
 
+from typing import Union
 from collections import OrderedDict
 
 import numpy as np
@@ -56,6 +57,60 @@ def isint(n):
         return isinstance(n, int) or np.issubdtype(type(n), np.integer)
 
 
+def find_channel_axis(data,
+                      possible_channel_axes=[-1, 0],
+                      possible_channel_lengths=[2, 3, 4]) -> Union[int, None]:
+    """
+    If the given numpy array has a shape suggesting that it has a
+    channel (color) axis (that is, any axis with length 2 (2-color),
+    3 (RGB), or 4 (RGBA)), return the index of that axis.
+
+    Parameters
+    ----------
+    data : numpy.ndarray
+        The numpy array to check for a channel axis.
+
+    possible_channel_axes : int or list of int, default [0, -1]
+        If None, any axis having length 2, 3, or 4 will be considered
+        a channel axis.
+        If an int, only that axis index will be checked.
+        If a list of ints, all axes with those indices will be checked.
+        The default value of [-1, 0] checks the last and first axes, which is
+        almost always where a channel axis will be found.
+
+    possible_channel_lengths : int or list of int, default [2, 3, 4]
+        If an int, only that length will be considered a channel axis.
+        If a list of ints, an axis with any of those lengths will be considered
+        a channel axis.
+
+    Returns
+    -------
+    int or None
+        The index of the channel axis, or None if no channel axis was found.
+
+        If possible_channel_axes is given, the returned value will be one of
+        the possible_channel_axes values, or None if no channel axis was found.
+
+        If possible_channel_axes is None, the returned value will be between
+        0 and data.ndim - 1, inclusive, or None if no channel axis was found.
+
+        Note that returning 0 means the channel axis was found and is the first
+        axis, so be careful not to do a test like `if find_channel_axis(data):`
+        because 0 will evaluate to False even though the data has a channel axis.
+        Instead write `if find_channel_axis(data) is not None:`
+    """
+    if isinstance(possible_channel_axes, int):
+        possible_channel_axes = [possible_channel_axes]
+    if possible_channel_axes is None:
+        possible_channel_axes = range(data.ndim)
+    if isinstance(possible_channel_lengths, int):
+        possible_channel_lengths = [possible_channel_lengths]
+    for axis in possible_channel_axes:
+        if data.shape[axis] in possible_channel_lengths:
+            return axis
+    return None
+
+
 def transpose_metadata(metadata: dict or OrderedDict,
                        inplace: bool = True) -> dict or OrderedDict or None:
     """

{numpyimage-2.6.1 → numpyimage-2.6.3}/npimage/vidio.py

@@ -1,12 +1,19 @@
 #!/usr/bin/env python3
 """
-Functions for reading, writing, and showing images.
+Functions for reading and writing videos.
 
 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
 
+Class list:
+- VideoStreamer: Provides fast random access to frames in a video file
+  via VideoStreamer[frame_number]
+- VideoWriter: Allows writing frames one-by-one to a video file via
+  VideoWriter.write(image). This can be advantageous compared to save_video
+  when you don't want to ever have to have all the frames in memory at once.
+
 """
 
 from typing import Union, Tuple, Iterator, Literal
@@ -18,7 +25,7 @@ import json
 
 import numpy as np
 
-from .imageio import find_channel_axis
+from . import utils
 
 codec_aliases = {
     "libx264": "libx264",
@@ -33,6 +40,8 @@ codec_aliases = {
     "H.265": "libx265",
 }
 
+supported_extensions = ['mp4', 'mkv', 'avi', 'mov']
+
 
 def load_video(filename,
                return_framerate=False,
@@ -51,8 +60,13 @@ def load_video(filename,
 
     Returns
     -------
-    data : numpy.ndarray
-        The video frames as a numpy array, shape (num_frames, height, width, colors)
+    If return_framerate is False:
+        data : numpy.ndarray
+            The video frames as a numpy array, shape (num_frames, height, width, colors)
+    If return_framerate is True:
+        (data, framerate) : tuple, where data is as above and:
+        framerate : float
+            The frame rate of the video in frames per second
     """
     try:
         import av
@@ -82,12 +96,17 @@ def load_video(filename,
         data = np.empty((num_frames, *first_img.shape), dtype=first_img.dtype)
         # Then fill it up frame by frame
         data[0] = first_img
+        container.seek(0, stream=stream)
         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')
+            if i == 0 and not np.array_equal(img, first_img):
+                raise RuntimeError('PyAV seek failed. Please report how this happened'
+                                   ' at github.com/jasper-tms/npimage/issues')
             data[i] = img
+        if (data[-1] == 0).all():
+            print('WARNING: Last frame of video is all zeros, this may'
+                  ' indicate an error in video loading unless you expected this.')
         if return_framerate:
             return data, float(stream.average_rate)
         else:
@@ -134,7 +153,7 @@ class VideoStreamer:
         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.index_filename = self.filename.parent / (self.filename.stem + '_index.json')
         self._load_index()
 
         self.container = av.open(str(self.filename))
@@ -142,6 +161,10 @@ class VideoStreamer:
         self.time_base = self.stream.time_base
         self._shape = None
         self._first_frame = None
+        self._width = None
+        self._height = None
+        self._ndim = None
+        self._dtype = None
         self._current_frame_number = None
         self._lock = threading.Lock()
 
@@ -163,11 +186,14 @@ class VideoStreamer:
         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]
+        self.rotation = _detect_rotation(self.filename)
         index = {
             'n_frames': self.n_frames,
             't0': self.t0,
+            'rotation': self.rotation,
         }
 
         # Determine whether the video is constant or variable framerate
@@ -187,11 +213,12 @@ class VideoStreamer:
     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)
+
+        with open(self.index_filename, 'r') as f:
+            index = json.load(f)
         self.n_frames = index['n_frames']
         self.t0 = index['t0']
+        self.rotation = index.get('rotation', None)
 
         if not isinstance(index['timestep'], (str, float, int)):
             raise ValueError('Malformed index: timestep is not a string or number')
@@ -226,7 +253,7 @@ class VideoStreamer:
         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
@@ -249,8 +276,15 @@ class VideoStreamer:
             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})")
+            # Support negative indexing
+            if frame_number < 0 and frame_number + self.n_frames >= 0:
+                frame_number += self.n_frames
+            elif frame_number >= self.n_frames:
+                raise IndexError(f"Frame {frame_number} out of range:"
+                                 f" [0, {self.n_frames-1}]")
+            elif frame_number < 0:
+                raise IndexError(f"Negative frame {frame_number} out of"
+                                 f" range: [-{self.n_frames}, -1]")
 
             if (self._current_frame_number is None
                     or frame_number <= self._current_frame_number
@@ -263,7 +297,17 @@ class VideoStreamer:
                 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)
+            return _rotate(decode_until(frame_number), self.rotation)
+
+    @property
+    def average_timestep(self):
+        """
+        Returns the average time step between frames.
+        """
+        if self.timestep == 'variable':
+            return (self.time_index[-1] - self.time_index[0]) / (self.n_frames - 1)
+        else:
+            return self.timestep
 
     @property
     def first_frame(self):
@@ -278,13 +322,29 @@ class VideoStreamer:
             self._shape = (self.n_frames,) + self.first_frame.shape
         return self._shape
 
+    @property
+    def width(self):
+        if self._width is None:
+            self._width = self.first_frame.shape[1]
+        return self._width
+
+    @property
+    def height(self):
+        if self._height is None:
+            self._height = self.first_frame.shape[0]
+        return self._height
+
     @property
     def ndim(self):
-        return len(self.shape)
+        if self._ndim is None:
+            self._ndim = len(self.shape)
+        return self._ndim
 
     @property
     def dtype(self):
-        return self.first_frame.dtype
+        if self._dtype is None:
+            self._dtype = self.first_frame.dtype
+        return self._dtype
 
     def __len__(self):
         return self.n_frames
@@ -317,7 +377,7 @@ class VideoWriter:
     ----------
     filename : str
         The filename to save the video to.
-    framerate : int, default 30
+    framerate : int or float, default 30
         The frame rate of the video.
     crf : int, default 23
         Constant Rate Factor for encoding quality (lower is better quality).
@@ -337,17 +397,27 @@ class VideoWriter:
             raise ImportError('Missing optional dependency for video processing,'
                               ' run `pip install av tqdm`')
         self.av = av
+        from fractions import Fraction
         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.framerate = str(framerate)  # str instead of float to avoid precision issues
+        while Fraction(self.framerate).denominator >= 2**32 or Fraction(self.framerate).numerator >= 2**32:
+            # If framerate has too many decimals to be expressed as a
+            # ratio of 32-bit ints, which is required by ffmpeg, crop
+            # off one decimal point of precision until it is expressable
+            self.framerate = self.framerate[:-1]
+            if self.framerate[-1] == '.':
+                self.framerate = self.framerate[:-1]
+            if len(self.framerate) == 0:
+                raise RuntimeError('Error occurred handling framerate argument')
         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 = self.container.add_stream(self.codec, rate=Fraction(self.framerate))
         self.stream.pix_fmt = 'yuv420p'
         self.stream.options = {'crf': str(crf), 'preset': compression_speed}
         self._closed = False
@@ -358,10 +428,14 @@ class VideoWriter:
         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 == 3 and frame.shape[-1] == 4:
+                # While some video codecs support an alpha channel, most don't,
+                # so for now we're just going to ignore the alpha channel
+                frame = self.av.VideoFrame.from_ndarray(frame[..., :3], 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}')
+                raise ValueError(f'Frame must be (H, W) (H, W, 3) or (H, W, 4) but was {frame.shape}')
         if self.stream.width == 0:
             self.stream.width = frame.width
         if self.stream.height == 0:
@@ -439,14 +513,14 @@ def save_video(data, filename, time_axis=0, color_axis=None, overwrite=False,
                           ' run `pip install av tqdm`')
 
     filename = os.path.expanduser(str(filename))
-    if filename.split('.')[-1].lower() not in ['mp4', 'mkv', 'avi', 'mov']:
+    if filename.split('.')[-1].lower() not in supported_extensions:
         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)
+        color_axis = utils.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:
@@ -487,3 +561,70 @@ def save_video(data, filename, time_axis=0, color_axis=None, overwrite=False,
         for frame_i in tqdm(range(n_frames), total=n_frames,
                             desc='Saving video', disable=not progress_bar):
             writer.write(data[frame_i])
+
+
+def _detect_rotation(filename):
+    """
+    Detect rotation metadata from the video file using ffprobe.
+    Returns the rotation angle as a string (e.g., '90', '180', '270'), or None if not present.
+    """
+    import subprocess
+    import json
+    cmd = [
+        'ffprobe',
+        '-v', 'quiet',
+        '-select_streams', 'v:0',
+        '-show_entries', 'stream_tags=rotate',
+        '-of', 'json',
+        str(filename)
+    ]
+    result = subprocess.run(cmd, stdout=subprocess.PIPE,
+                            stderr=subprocess.PIPE, text=True)
+    if result.returncode != 0:
+        return None
+    try:
+        data = json.loads(result.stdout)
+        streams = data.get('streams', [])
+        if streams and 'tags' in streams[0]:
+            rotate_tag = streams[0]['tags'].get('rotate')
+            if rotate_tag:
+                return rotate_tag
+    except (json.JSONDecodeError, KeyError, ValueError):
+        pass
+    return None
+
+
+def _rotate(data: np.ndarray, rotation: Union[str, int, None] = 0) -> np.ndarray:
+    """
+    Apply clockwise rotation to a numpy array
+
+    Parameters
+    ----------
+    data : np.ndarray
+        The numpy array to rotate.
+    rotation : str, int, or None, default 0
+        The rotation angle in degrees, as a string or integer.
+        Valid values are 0, 90, 180, 270, or 360.
+        If None, 0, or 360, no rotation is applied.
+
+    TODO find an actual video file with rotation_tag of 90 or 270 and check that
+    the rotation is applied in the right direction. If it's opposite the correct
+    direction, remove axes=(1, 0) from the np.rot90 calls in this function.
+    """
+    if rotation is None:
+        return data
+    try:
+        rotation = int(rotation)
+    except (ValueError, TypeError):
+        raise ValueError(f"Invalid rotation value: {rotation}")
+
+    if rotation in [0, 360]:
+        return data
+    if rotation == 90:
+        return np.rot90(data, k=1, axes=(1, 0))
+    elif rotation == 180:
+        return np.rot90(data, k=2, axes=(1, 0))
+    elif rotation == 270:
+        return np.rot90(data, k=3, axes=(1, 0))
+    else:
+        raise ValueError(f"Invalid rotation value: {rotation}")

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: numpyimage
-Version: 2.6.1
+Version: 2.6.3
 Summary: Load, save, & manipulate image files as numpy arrays
 Author-email: Jasper Phelps <jasper.s.phelps@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE

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

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