prpy 0.2.30__tar.gz → 0.3.2__tar.gz

{prpy-0.2.30/prpy.egg-info → prpy-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prpy
-Version: 0.2.30
+Version: 0.3.2
 Summary: Collection of Python utils for signal, image, and video processing
 Author-email: Philipp Rouast <philipp@rouast.com>
 License: MIT License
@@ -51,7 +51,7 @@ It contains subpackages for working with `numpy`, `ffmpeg`, `tensorflow`, and `t
 
 ## Installation
 
-General prerequisites are `python>=3.8` and `ffmpeg` installed and accessible via the `$PATH` environment variable.
+General prerequisites are `python>=3.9` and `ffmpeg` installed and accessible via the `$PATH` environment variable.
 
 - Please note: If using `numpy` or `tensorflow` options, we only support Python `<3.12` because of the dependencies. 
 

{prpy-0.2.30 → prpy-0.3.2}/README.md

@@ -9,7 +9,7 @@ It contains subpackages for working with `numpy`, `ffmpeg`, `tensorflow`, and `t
 
 ## Installation
 
-General prerequisites are `python>=3.8` and `ffmpeg` installed and accessible via the `$PATH` environment variable.
+General prerequisites are `python>=3.9` and `ffmpeg` installed and accessible via the `$PATH` environment variable.
 
 - Please note: If using `numpy` or `tensorflow` options, we only support Python `<3.12` because of the dependencies. 
 

prpy-0.3.2/prpy/numpy/__init__.py

@@ -0,0 +1,29 @@
+# Copyright (c) 2025 Philipp Rouast
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from .core import *
+from .face import *
+from .filters import *
+from .freq import *
+from .image import *
+from .interp import *
+from .metric import *
+from .stride_tricks import *
+from .utils import *

prpy-0.3.2/prpy/numpy/core.py

@@ -0,0 +1,91 @@
+# Copyright (c) 2025 Philipp Rouast
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import numpy as np
+from typing import Union
+
+def div0(
+    a: Union[np.ndarray, float, int],
+    b: Union[np.ndarray, float, int],
+    fill: Union[float, int] = np.nan
+  ) -> np.ndarray:
+  """
+  Divide after accounting for zeros in divisor, e.g.:
+  
+  - div0( [-1, 0, 1], 0, fill=np.nan) -> [nan nan nan]
+  - div0( 1, 0, fill=np.inf ) -> inf
+  
+  Source: https://stackoverflow.com/a/35696047/3595278
+  
+  Args:
+    a: Dividend
+    b: Divisor
+    fill: Use this value to fill where b == 0.
+  Returns:
+    c: safe a/b
+  """
+  assert isinstance(fill, (int, float))
+  with np.errstate(divide='ignore', invalid='ignore'):
+    c = np.true_divide(a, b)
+  if np.isscalar(c):
+    return c if np.isfinite(c) else fill
+  else:
+    c[~np.isfinite(c)] = fill
+    return c
+  
+def standardize(
+    x: np.ndarray,
+    axis: Union[int, None] = -1
+  ) -> np.ndarray:
+  """
+  Perform standardization
+  
+  - Note: Returns zero if std == 0
+  
+  Args:
+    x: The input data
+    axis: Axis over which to standardize
+  Returns:
+    x: The standardized data
+  """
+  assert axis is None or isinstance(axis, int) or (isinstance(axis, tuple) and all(isinstance(i, int) for i in axis))
+  x = np.array(x)
+  x -= np.mean(x, axis=axis, keepdims=x.ndim>0)
+  std = np.std(x, axis=axis, keepdims=x.ndim>0)
+  x = div0(x, std, fill=0)
+  return x
+
+def normalize(
+    x: np.ndarray,
+    axis: Union[int, tuple, None] = -1
+  ) -> np.ndarray:
+  """
+  Perform normalization
+
+  Args:
+    x: The input data
+    axis: Axis or axes over which to normalize
+  Returns:
+    x: The normalized data
+  """
+  assert axis is None or isinstance(axis, int) or (isinstance(axis, tuple) and all(isinstance(i, int) for i in axis))
+  x = np.array(x)
+  x -= np.mean(x, axis=axis, keepdims=x.ndim>0)
+  return x

prpy-0.3.2/prpy/numpy/detect.py

@@ -0,0 +1,267 @@
+# Copyright (c) 2025 Philipp Rouast
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from dataclasses import dataclass
+import logging
+import numpy as np
+from scipy import signal
+from typing import Callable, Tuple, Optional, List, Union
+
+from prpy.numpy.freq import estimate_freq_periodogram
+from prpy.numpy.interp import interpolate_data_outliers
+from prpy.numpy.rolling import rolling_calc
+
+@dataclass
+class PeakDetectDebug:
+  t: np.ndarray
+  vals_raw: np.ndarray
+  vals_trans: np.ndarray
+  freqs: np.ndarray
+  det_idxs: np.ndarray
+  det_idxs_raw: Optional[np.ndarray]
+  det_t_diff: np.ndarray
+  det_t_diff_imp: np.ndarray
+  min_dist_t: float
+  min_width_t: Optional[float]
+  period_rel_tol: Tuple[float, float]
+
+def detect_valid_peaks(
+    vals: np.ndarray,
+    *,
+    f_s: Optional[float] = None,
+    height: float = 0.,
+    prominence: Optional[Tuple[float, float]] = None,
+    period_rel_tol: Tuple[float, float] = (0.4, 0.8),
+    window_size: int,
+    overlap: Optional[int] = None,
+    min_det_for_valid_seq: int = 1,
+    t: Optional[np.ndarray] = None,
+    width: Optional[Union[float, Tuple[float, float]]] = None,
+    fft_fn: Optional[Callable[[np.ndarray], np.ndarray]] = None,
+    f_range: Optional[Tuple[float, float]] = None,
+    f_res: Optional[float] = None,
+    vals_fn: Optional[Callable[[np.ndarray], np.ndarray]] = None,
+    interp_vals_outliers_z: Optional[float] = None,
+    interp_freqs_outliers_z: Optional[float] = None,
+    refine: Optional[str] = None,
+    refine_dist: float = 0.1,
+    return_debug: bool = False,
+  ) -> tuple:
+  """
+  Detect sequences of valid peaks in a periodical signal (e.g., ECG)
+  
+  Args:
+    vals: The signal values to search for peaks (n,)
+    f_s: Sampling frequency in Hz. Required if `t` not given.
+    height: Required height of peaks
+    prominence: Required (min, max) prominence of peaks
+    period_rel_tol: (shorter, longer)
+      - Allowed *relative* deviation of each peak-to-peak interval from the reference interval:
+        valid if  (1-shorter)·T_ref  <  T  <  (1+longer)·T_ref
+    window_size: The size of the reference frequency calculation window in number of data points
+    overlap: The overlap of consecutive reference frequency calculation windows in number of data points
+    min_det_for_valid_seq: Minimum consecutive valid detections to keep a sequence.
+    t: The timestamps of the signal values (n,). If omitted, derived from `f_s`.
+    width: Required width of peaks in seconds (either scalar as minimum or tuple for (min, max))
+    fft_fn: Optional callable to be applied to vals before fft
+    f_range: The frequency range to be considered (may be None)
+    f_res: The frequency resolution (may be None)
+    vals_fn: Optional transform applied before peak detection
+    interp_vals_outliers_z, interp_freqs_outliers_z: Z-score thresholds for outlier interpolation.
+    refine: Secondary peak-refinement strategy (None, 'raw_peak', 'raw_foot')
+    refine_dist: Max admissible shift (seconds) during refinement.
+    return_debug: If True, also return a `PeakDetectDebug` object.
+  Returns:
+    Tuple of
+     - valid_det_idxs_list: List of lists of indices representing sequences of valid peaks
+     - valid: Boolean array indicating which parts of the signal had valid peak detections (n,)
+     - debug: PeakDetectDebug
+  """
+  # Basic checks
+  if t is None and f_s is None: raise ValueError("Provide either `t` or `f_s`.")
+  assert isinstance(vals, np.ndarray)
+  size = vals.shape[0]
+  if t is None:
+    t = np.arange(size) / f_s
+  else:
+    assert t.shape[0] == size, "`t` must match `vals` length"
+    if f_s is None:
+      f_s = size / (t[-1] - t[0])
+  vals_raw = vals.copy()
+  period_rel_tol_shorter, period_rel_tol_longer = period_rel_tol
+  # Sliding reference freq
+  window_size = min(window_size, size - 1)
+  if overlap is None: overlap = window_size // 2
+  freqs = rolling_calc(
+    x=vals,
+    calc_fn=lambda x: estimate_freq_periodogram(
+      x=x,
+      f_s=f_s,
+      f_range=f_range,
+      f_res=f_res,
+      axis=1
+    ), 
+    min_window_size=window_size,
+    max_window_size=window_size,
+    overlap=overlap,
+    transform_fn=fft_fn,
+    fill_method='start'
+  )
+  # Preprocess
+  if interp_vals_outliers_z is not None:
+    vals = interpolate_data_outliers(vals, z_score=interp_vals_outliers_z)
+  if vals_fn is not None:
+    vals = vals_fn(vals)
+  if interp_freqs_outliers_z is not None:
+    freqs = interpolate_data_outliers(freqs, z_score=interp_freqs_outliers_z)
+  # Peak detection
+  if width is not None:
+    width_s = width
+    width = width * f_s if isinstance(width, float) else tuple(w * f_s if w is not None else None for w in width)
+  else:
+    width_s = None  
+  min_dist_samples = max(1/np.quantile(freqs, 0.9) * f_s * (1 - period_rel_tol_shorter), 0)
+  raw_det_idxs, _ = signal.find_peaks(
+    vals,
+    height=height,
+    distance=min_dist_samples,
+    width=width,
+    prominence=prominence
+  )
+  if raw_det_idxs.size == 0:
+    logging.warning("No peaks found - maybe tweak `vals_fn` or thresholds.")
+    return ([], np.zeros(size)) if not return_debug else ([], np.zeros(size), None)
+  if raw_det_idxs.size == 1:
+    logging.warning("Only a single peak - periodicity checks will pass trivially.")
+    valid = np.ones(size)
+    return ([raw_det_idxs.tolist()], valid) if not return_debug \
+        else ([raw_det_idxs.tolist()], valid, None)
+  # Optional refinement
+  det_idxs = raw_det_idxs
+  if refine is not None:
+    window_samples = int(refine_dist * f_s)
+    if refine == 'raw_peak':
+      det_idxs = _refine_raw_peak(vals=vals_raw,
+                                  det_idxs=raw_det_idxs,
+                                  window_samples=window_samples)
+    elif refine == 'raw_foot':
+      det_idxs = _refine_raw_foot(vals=vals_raw,
+                                  det_idxs=raw_det_idxs,
+                                  window_samples=window_samples)
+    else:
+      raise ValueError(f"Unknown refine mode '{refine}'.")
+  # Validity test
+  det_t_diff = np.diff(t[det_idxs])
+  det_t_diff = np.concatenate([[det_t_diff[0]], det_t_diff])
+  det_t_diff_imp = 1/freqs[det_idxs]
+  # Detections are valid if diffs are close enough to implied diffs
+  det_valid = np.logical_and(det_t_diff < det_t_diff_imp * (1 + period_rel_tol_longer),
+                             det_t_diff > det_t_diff_imp * (1 - period_rel_tol_shorter))
+  # Determine sequences of consecutive valid detections
+  det_valid_seq_start_idx = np.where(np.logical_and(np.concatenate([[True], np.diff(det_valid)]), det_valid))[0]
+  det_valid_seq_end_idx = np.where(np.logical_and(np.concatenate([np.diff(det_valid), [True]]), det_valid))[0]
+  valid_det_idxs_list = [det_idxs[start:end+1].tolist() for start, end in zip(det_valid_seq_start_idx, det_valid_seq_end_idx) if end-start >= min_det_for_valid_seq]
+  # Determine valid column
+  valid_idxs_list = [list(range(det_idxs[start], det_idxs[end])) for start, end in zip(det_valid_seq_start_idx, det_valid_seq_end_idx)]
+  valid_idxs = [item for sublist in valid_idxs_list for item in sublist]
+  valid = np.zeros(size)
+  valid[valid_idxs] = 1
+  if not return_debug:
+    return valid_det_idxs_list, valid
+  debug = PeakDetectDebug(
+    t=t,
+    vals_raw=vals_raw,
+    vals_trans=vals,
+    freqs=freqs,
+    det_idxs=det_idxs,
+    det_idxs_raw=raw_det_idxs,
+    det_t_diff=det_t_diff,
+    det_t_diff_imp=det_t_diff_imp,
+    min_dist_t=min_dist_samples / f_s,
+    min_width_t=width_s[0] if isinstance(width_s, tuple) else width_s,
+    period_rel_tol=period_rel_tol,
+  )
+  return valid_det_idxs_list, valid, debug
+
+def _refine_raw_peak(
+    vals: np.ndarray,
+    det_idxs: np.ndarray,
+    window_samples: int
+  ) -> list:
+  """
+  Refine peak detections by searching for maximum within local window.
+
+  Args:
+    vals: Signal values (n,)
+    det_idxs: Detected peak indices
+    window_samples: Number of samples defining the local search window around each detection
+  Returns:
+    Lost of lists of refined peak indices
+  """
+  half_w = window_samples // 2
+  offsets = np.arange(-half_w, half_w)
+  
+  # build a (N, window) index matrix around each detection
+  idx_matrix = det_idxs[:, None] + offsets[None, :]
+  idx_clipped = np.clip(idx_matrix, 0, vals.shape[0] - 1)
+  
+  # extract and mask out‑of‑bounds
+  mask = (idx_matrix < 0) | (idx_matrix >= vals.shape[0])
+  windows = vals[idx_clipped]
+  windows = np.where(mask, -np.inf, windows)
+  
+  # find local max per row
+  local_off = np.argmax(windows, axis=1)
+  refined = idx_clipped[np.arange(det_idxs.size), local_off]
+  
+  return refined
+
+def _refine_raw_foot(
+    vals: np.ndarray,
+    det_idxs: np.ndarray,
+    window_samples: int
+  ) -> list:
+  """
+  Refine peak detections by searching for minimum within local window.
+
+  Args:
+    vals: Signal values (n,)
+    det_idxs: Detected peak indices
+    window_samples: Number of samples defining the local search window around each detection
+  Returns:
+    Lost of lists of refined foot indices
+  """  
+  half_w = window_samples // 2
+  offsets = np.arange(-half_w, half_w)
+  
+  # build a (N, window) index matrix around each detection
+  idx_matrix = det_idxs[:, None] + offsets[None, :]
+  idx_clipped = np.clip(idx_matrix, 0, vals.shape[0] - 1)
+  
+  # extract and mask out‑of‑bounds
+  mask = (idx_matrix < 0) | (idx_matrix >= vals.shape[0])
+  windows = vals[idx_clipped]
+  windows = np.where(mask, -np.inf, windows)
+  
+  # find local max per row
+  local_off = np.argmin(windows, axis=1)
+  refined = idx_clipped[np.arange(det_idxs.size), local_off]
+
+  return refined

{prpy-0.2.30 → prpy-0.3.2}/prpy/numpy/face.py

@@ -23,7 +23,8 @@ from prpy.numpy.image import crop_slice_resize
 from typing import Union
 
 def _force_even_dims(roi: tuple) -> tuple:
-  """Force even dimensions
+  """
+  Force even dimensions
   
   Args:
     roi: The region of interest with potentially uneven dimensions
@@ -46,7 +47,8 @@ def _get_roi_from_det(
     clip_dims: Union[tuple, None] = None,
     force_even_dims: bool = False
   ) -> tuple:
-  """Convert face detection to roi by relative add/reduce.
+  """
+  Convert face detection to roi by relative add/reduce.
 
   Args:
     det: The face detection [0, H/W] in format (x0, y0, x1, y1).
@@ -83,8 +85,10 @@ def get_face_roi_from_det(
     det: tuple,
     force_even_dims: bool = False
   ) -> tuple:
-  """Convert face detection into face roi.
-  Reduces width to 60% and height to 80%. 
+  """
+  Convert face detection into face roi. 
+  
+  - Reduces width to 60% and height to 80%. 
   
   Args:
     det: The face detection [0, H/W] in form (x0, y0, x1, y1)
@@ -99,8 +103,10 @@ def get_forehead_roi_from_det(
     det: tuple,
     force_even_dims: bool = False
   ) -> tuple:
-  """Convert face detection into forehead roi.
-  Reduces det to forehead as 35% to 65% of width, and 15% to 25% of height. 
+  """
+  Convert face detection into forehead roi.
+  
+  - Reduces det to forehead as 35% to 65% of width, and 15% to 25% of height. 
   
   Args:
     det: The face detection [0, H/W] in form (x0, y0, x1, y1)
@@ -118,7 +124,8 @@ def get_upper_body_roi_from_det(
     v: int = 1,
     force_even_dims: bool = False
   ) -> tuple:
-  """Convert face detection into upper body roi and clip to frame constraints.
+  """
+  Convert face detection into upper body roi and clip to frame constraints.
 
   Args:
     det: The face detection [0, H/W] in form (x0, y0, x1, y1)
@@ -186,7 +193,8 @@ def get_meta_roi_from_det(
     clip_dims: tuple,
     force_even_dims: bool = False
   ) -> tuple:
-  """Convert face detection into meta roi and clip to frame constraints.
+  """
+  Convert face detection into meta roi and clip to frame constraints.
 
   Args:
     det: The face detection [0, H/W] in form (x0, y0, x1, y1)
@@ -205,7 +213,8 @@ def get_roi_from_det(
     clip_dims: Union[tuple, None] = None,
     force_even_dims: bool = False
   ) -> tuple:
-  """Convert face detection into specified roi.
+  """
+  Convert face detection into specified roi.
 
   Args:
     det: The face detection [0, H/W] in form (x0, y0, x1, y1)
@@ -253,8 +262,10 @@ def crop_resize_from_det(
     scale_algorithm: str,
     force_even_dims: bool = False
   ) -> np.ndarray:
-  """Crop and resize a video according to a single face detection.
-  Resize to specified size with specified method.
+  """
+  Crop and resize a video according to a single face detection.
+  
+  - Resize to specified size with specified method.
 
   Args:
     video: The video. Shape (n_frames, h, w, c)