PySDKit 0.4.36__tar.gz → 0.4.37__tar.gz

{pysdkit-0.4.36 → pysdkit-0.4.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PySDKit
-Version: 0.4.36
+Version: 0.4.37
 Summary: A Python library for signal decomposition algorithms with a unified interface.
 Author: josefinez, Deeksha Manjunath, Yuan Feng, JacktheFowler
 Author-email: Whenxuan Wang <wwhenxuan@gmail.com>, RuiZhe Wang <3133986068@qq.com>, WenTong Zhao <23049200290@stu.xidian.edu.cn>
@@ -155,8 +155,8 @@ plot_IMFs_amplitude_spectra(IMFs, smooth="exp")   # use exp smooth
 | [`TVF_EMD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_emd/tvf_emd.py) (Time Varying Filter Based EMD) | [[paper]](https://www.sciencedirect.com/science/article/pii/S0165168417301135) |   [[code]](https://github.com/stfbnc/pytvfemd/tree/master)   |   ✔️   |
 | [`EFD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_emd/efd.py) (Empirical Fourier Decomposition) | [[paper]](https://www.sciencedirect.com/science/article/abs/pii/S0888327021005355) | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/97747-empirical-fourier-decomposition-efd) |   ✔️   |
 | [`FAEMD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd.py) (Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✔️   |
-| [`FAEMD2D`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd2d.py) (Two-Dimensional Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✖️   |
-| [`FAEMD3D`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd3d.py) (Three-Dimensional Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✖️   |
+| [`FAEMD2D`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd2d.py) (Two-Dimensional Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✔️   |
+| [`FAEMD3D`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd3d.py) (Three-Dimensional Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✔️   |
 | [`HVD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_hvd/hvd.py) (Hilbert Vibration Decomposition) | [[paper]](https://www.sciencedirect.com/science/article/pii/S0022460X06001556) | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/178804-hilbert-vibration-decomposition?s_tid=FX_rc1_behav) |   ✔️   |
 | [`ITD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_itd/itd.py) (Intrinsic Time-Scale Decomposition) | [[paper]](https://royalsocietypublishing.org/doi/10.1098/rspa.2006.1761) | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/69380-intrinsic-time-scale-decomposition-itd) |   ✔️   |
 | [`ALIF`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_alif/alif.py) (Adaptive Local Iterative Filtering) |          [[paper]](https://arxiv.org/abs/1411.6051)          |           [[code]](https://github.com/Cicone/ALIF)           |   ✔️   |

{pysdkit-0.4.36 → pysdkit-0.4.37}/PySDKit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PySDKit
-Version: 0.4.36
+Version: 0.4.37
 Summary: A Python library for signal decomposition algorithms with a unified interface.
 Author: josefinez, Deeksha Manjunath, Yuan Feng, JacktheFowler
 Author-email: Whenxuan Wang <wwhenxuan@gmail.com>, RuiZhe Wang <3133986068@qq.com>, WenTong Zhao <23049200290@stu.xidian.edu.cn>
@@ -155,8 +155,8 @@ plot_IMFs_amplitude_spectra(IMFs, smooth="exp")   # use exp smooth
 | [`TVF_EMD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_emd/tvf_emd.py) (Time Varying Filter Based EMD) | [[paper]](https://www.sciencedirect.com/science/article/pii/S0165168417301135) |   [[code]](https://github.com/stfbnc/pytvfemd/tree/master)   |   ✔️   |
 | [`EFD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_emd/efd.py) (Empirical Fourier Decomposition) | [[paper]](https://www.sciencedirect.com/science/article/abs/pii/S0888327021005355) | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/97747-empirical-fourier-decomposition-efd) |   ✔️   |
 | [`FAEMD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd.py) (Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✔️   |
-| [`FAEMD2D`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd2d.py) (Two-Dimensional Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✖️   |
-| [`FAEMD3D`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd3d.py) (Three-Dimensional Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✖️   |
+| [`FAEMD2D`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd2d.py) (Two-Dimensional Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✔️   |
+| [`FAEMD3D`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd3d.py) (Three-Dimensional Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✔️   |
 | [`HVD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_hvd/hvd.py) (Hilbert Vibration Decomposition) | [[paper]](https://www.sciencedirect.com/science/article/pii/S0022460X06001556) | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/178804-hilbert-vibration-decomposition?s_tid=FX_rc1_behav) |   ✔️   |
 | [`ITD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_itd/itd.py) (Intrinsic Time-Scale Decomposition) | [[paper]](https://royalsocietypublishing.org/doi/10.1098/rspa.2006.1761) | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/69380-intrinsic-time-scale-decomposition-itd) |   ✔️   |
 | [`ALIF`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_alif/alif.py) (Adaptive Local Iterative Filtering) |          [[paper]](https://arxiv.org/abs/1411.6051)          |           [[code]](https://github.com/Cicone/ALIF)           |   ✔️   |

{pysdkit-0.4.36 → pysdkit-0.4.37}/PySDKit.egg-info/SOURCES.txt

@@ -112,7 +112,9 @@ pysdkit/tests/run_all.py
 pysdkit/tests/test_alif.py
 pysdkit/tests/test_apmd.py
 pysdkit/tests/test_avncmd.py
+pysdkit/tests/test_bmemd.py
 pysdkit/tests/test_ceemdan.py
+pysdkit/tests/test_eemd.py
 pysdkit/tests/test_emd.py
 pysdkit/tests/test_ewt.py
 pysdkit/tests/test_ewt2d.py

{pysdkit-0.4.36 → pysdkit-0.4.37}/README.md

@@ -101,8 +101,8 @@ plot_IMFs_amplitude_spectra(IMFs, smooth="exp")   # use exp smooth
 | [`TVF_EMD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_emd/tvf_emd.py) (Time Varying Filter Based EMD) | [[paper]](https://www.sciencedirect.com/science/article/pii/S0165168417301135) |   [[code]](https://github.com/stfbnc/pytvfemd/tree/master)   |   ✔️   |
 | [`EFD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_emd/efd.py) (Empirical Fourier Decomposition) | [[paper]](https://www.sciencedirect.com/science/article/abs/pii/S0888327021005355) | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/97747-empirical-fourier-decomposition-efd) |   ✔️   |
 | [`FAEMD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd.py) (Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✔️   |
-| [`FAEMD2D`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd2d.py) (Two-Dimensional Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✖️   |
-| [`FAEMD3D`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd3d.py) (Three-Dimensional Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✖️   |
+| [`FAEMD2D`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd2d.py) (Two-Dimensional Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✔️   |
+| [`FAEMD3D`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_faemd/faemd3d.py) (Three-Dimensional Fast and Adaptive EMD) |   [[paper]](https://ieeexplore.ieee.org/document/8447300)    | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/71270-fast-and-adaptive-multivariate-and-multidimensional-emd) |   ✔️   |
 | [`HVD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_hvd/hvd.py) (Hilbert Vibration Decomposition) | [[paper]](https://www.sciencedirect.com/science/article/pii/S0022460X06001556) | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/178804-hilbert-vibration-decomposition?s_tid=FX_rc1_behav) |   ✔️   |
 | [`ITD`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_itd/itd.py) (Intrinsic Time-Scale Decomposition) | [[paper]](https://royalsocietypublishing.org/doi/10.1098/rspa.2006.1761) | [[code]](https://www.mathworks.com/matlabcentral/fileexchange/69380-intrinsic-time-scale-decomposition-itd) |   ✔️   |
 | [`ALIF`](https://github.com/wwhenxuan/PySDKit/blob/main/pysdkit/_alif/alif.py) (Adaptive Local Iterative Filtering) |          [[paper]](https://arxiv.org/abs/1411.6051)          |           [[code]](https://github.com/Cicone/ALIF)           |   ✔️   |

{pysdkit-0.4.36 → pysdkit-0.4.37}/pysdkit/__init__.py

@@ -2,7 +2,7 @@
 A Python library for signal decomposition algorithms.
 """
 
-__version__ = "0.4.36"
+__version__ = "0.4.37"
 
 # Empirical Mode Decomposition
 from ._emd import EMD
@@ -34,6 +34,9 @@ from ._faemd import FAEMD, FAEMD2D, FAEMD3D
 # Empirical Mode Decomposition 2D for images
 from ._emd2d import EMD2D
 
+# Bidimensional Multivariate Empirical Mode Decomposition
+from ._emd2d import BMEMD
+
 # Hilbert Vibration Decomposition
 from ._hvd import HVD
 
@@ -163,6 +166,7 @@ Fast and Adaptive Empirical Mode Decomposition  |    FAEMD
 Bidimensional FAEMD                             |    FAEMD2D
 Tridimensional FAEMD                            |    FAEMD3D
 Empirical Mode Decomposition 2D for images      |    EMD2D
+Bidimensional Multivariate EMD                  |    BMEMD
 Hilbert Vibration Decomposition                 |    HVD
 Intrinsic Time-Scale Decomposition              |    ITD
 Local Mean Decomposition                        |    LMD
@@ -211,6 +215,7 @@ __all__ = [
     "FAEMD2D",
     "FAEMD3D",
     "EMD2D",
+    "BMEMD",
     "HVD",
     "ITD",
     "LMD",

{pysdkit-0.4.36 → pysdkit-0.4.37}/pysdkit/_emd/semd.py

@@ -37,7 +37,9 @@ def concatenate_signals(matrix_x: np.ndarray, num_interval: int) -> np.ndarray:
     """
     matrix_x = np.asarray(matrix_x, dtype=float)
     if matrix_x.ndim != 2:
-        raise ValueError("matrix_x must be a 2-D array of shape (n_samples, n_channels)")
+        raise ValueError(
+            "matrix_x must be a 2-D array of shape (n_samples, n_channels)"
+        )
 
     n_length, n_signal = matrix_x.shape
     if n_signal < 1:
@@ -276,7 +278,11 @@ class SEMD(object):
         if max_imfs is None:
             max_imfs = self.max_imfs
         # Only forward a hard cap when it is positive; otherwise let the backend decide
-        emd_kwargs = {} if (max_imfs is None or int(max_imfs) < 0) else {"max_imfs": int(max_imfs)}
+        emd_kwargs = (
+            {}
+            if (max_imfs is None or int(max_imfs) < 0)
+            else {"max_imfs": int(max_imfs)}
+        )
 
         if x.ndim == 1:
             imfs = self.emd.fit_transform(x, **emd_kwargs)

{pysdkit-0.4.36 → pysdkit-0.4.37}/pysdkit/_emd2d/__init__.py

@@ -6,3 +6,5 @@ Created on 2025/02/03 18:36:49
 """
 
 from .emd2d import EMD2D
+
+from .bmemd import BMEMD, local_var_img, fuse_images

pysdkit-0.4.37/pysdkit/_emd2d/bmemd.py

@@ -0,0 +1,413 @@
+# -*- coding: utf-8 -*-
+"""
+Created on 2025/02/05 13:18:18
+@author: Whenxuan Wang
+@email: wwhenxuan@gmail.com
+
+Bidimensional Multivariate Empirical Mode Decomposition (BMEMD)
+
+Xia, Y., Zhang, B., Pei, W., and Mandic, D. P. (2019).
+Bidimensional Multivariate Empirical Mode Decomposition with Applications
+in Multi-Scale Image Fusion. IEEE Access, 7:114261–114270.
+
+MATLAB reference:
+https://github.com/z-bingo/Bidimensional-Multivariate-Empirical-Mode-Decomposition
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Sequence, Tuple, Union
+
+import numpy as np
+from scipy.interpolate import CloughTocher2DInterpolator, NearestNDInterpolator
+from scipy.ndimage import maximum_filter, minimum_filter, uniform_filter
+
+from pysdkit._emd.memd import hamm, nth_prime
+
+
+class BMEMD(object):
+    """
+    Bidimensional Multivariate Empirical Mode Decomposition (BMEMD)
+
+    Projects a multi-channel image onto direction vectors on the
+    ``(n-1)``-sphere, finds 2-D extrema of each projected surface, builds
+    multivariate envelopes by Delaunay-based surface interpolation, and
+    sifts until a MEMD-style stop criterion is met.  All channels share the
+    same BIMF count, which enables multi-scale image fusion.
+    """
+
+    def __init__(
+        self,
+        n_dir: int = 8,
+        max_imfs: int = 4,
+        stop_crit: str = "stop",
+        stop_vec: Optional[Sequence[float]] = None,
+        stop_cnt: int = 2,
+        max_iter: int = 1000,
+        max_sift: int = 50,
+    ) -> None:
+        """
+        :param n_dir: Number of projection directions (``>= 6``; MATLAB default 8)
+        :param max_imfs: Maximum number of oscillatory BIMFs before the residue
+        :param stop_crit: ``"stop"`` (sd / sd2 / tol) or ``"fix_h"``
+        :param stop_vec: ``[sd, sd2, tol]`` when ``stop_crit="stop"``;
+            default ``[0.01, 0.1, 0.01]`` (MATLAB BMEMD default)
+        :param stop_cnt: Fixed sifting count when ``stop_crit="fix_h"``
+        :param max_iter: Hard cap on outer BIMF extraction iterations
+        :param max_sift: Hard cap on inner sifting iterations per BIMF
+        """
+        if not isinstance(n_dir, (int, np.integer)) or n_dir < 6:
+            raise ValueError("n_dir must be an integer >= 6")
+        if not isinstance(max_imfs, (int, np.integer)) or max_imfs < 1:
+            raise ValueError("max_imfs must be a positive integer")
+        if stop_crit not in ("stop", "fix_h"):
+            raise ValueError("stop_crit must be 'stop' or 'fix_h'")
+
+        self.n_dir = int(n_dir)
+        self.max_imfs = int(max_imfs)
+        self.stop_crit = stop_crit
+        if stop_vec is None:
+            stop_vec = (0.01, 0.1, 0.01)
+        if len(stop_vec) != 3:
+            raise ValueError("stop_vec must contain three elements [sd, sd2, tol]")
+        self.sd, self.sd2, self.tol = map(float, stop_vec)
+        self.stop_cnt = int(stop_cnt)
+        self.max_iter = int(max_iter)
+        self.max_sift = int(max_sift)
+
+        self.imfs: Optional[np.ndarray] = None
+        self.residue: Optional[np.ndarray] = None
+
+    def __str__(self) -> str:
+        return "Bidimensional Multivariate Empirical Mode Decomposition (BMEMD)"
+
+    def __call__(
+        self, images: np.ndarray, max_imfs: Optional[int] = None
+    ) -> np.ndarray:
+        return self.fit_transform(images, max_imfs=max_imfs)
+
+    # ------------------------------------------------------------------ #
+    # Public API
+    # ------------------------------------------------------------------ #
+    def fit_transform(
+        self, images: np.ndarray, max_imfs: Optional[int] = None
+    ) -> np.ndarray:
+        """
+        Decompose a multi-channel image stack.
+
+        :param images: Array of shape ``(n_channels, H, W)`` with
+            ``2 <= n_channels <= 16``
+        :param max_imfs: Optional override for the number of oscillatory BIMFs
+        :return: ``(K, n_channels, H, W)`` where the last slice is the residue
+        """
+        x = self._check_input(images)
+        n_ch, height, width = x.shape
+        max_imfs = self.max_imfs if max_imfs is None else int(max_imfs)
+
+        directions = self._direction_vectors(n_ch)
+        residue = x.astype(float, copy=True)
+        modes: List[np.ndarray] = []
+
+        for _ in range(max_imfs):
+            if self._stop_emd(residue, directions):
+                break
+
+            mode = residue.copy()
+            sift_i = 0
+            n_h = 0  # consecutive OK counts for fix_h
+
+            while sift_i < self.max_sift:
+                sift_i += 1
+                try:
+                    env_mean, nem, amp = self._envelope_mean(mode, directions)
+                except Exception:
+                    env_mean = np.zeros_like(mode)
+                    break
+
+                if self.stop_crit == "stop":
+                    if self._stop_sifting(env_mean, amp, nem):
+                        break
+                else:  # fix_h
+                    # MEMD-style: count successive siftings with enough extrema
+                    if nem > 9:
+                        n_h += 1
+                    else:
+                        n_h = 0
+                    if n_h >= self.stop_cnt:
+                        break
+
+                mode = mode - env_mean
+
+            modes.append(mode)
+            residue = residue - mode
+            if sift_i >= self.max_sift:
+                break
+
+        modes.append(residue)
+        imfs = np.stack(modes, axis=0)
+        self.imfs = imfs[:-1]
+        self.residue = residue
+        return imfs
+
+    def fuse(
+        self,
+        images: np.ndarray,
+        imfs: Optional[np.ndarray] = None,
+        var_window: int = 5,
+    ) -> np.ndarray:
+        """
+        Multi-scale image fusion via local-variance weights (Xia et al.).
+
+        For each oscillatory BIMF, channel weights are proportional to the
+        local squared deviation from a moving mean (MATLAB ``local_var_img``).
+        The residue is fused by intensity proportions.
+
+        :param images: ``(n_channels, H, W)`` input stack (used if ``imfs`` is None)
+        :param imfs: Optional precomputed BIMFs ``(K, n_channels, H, W)``
+        :param var_window: Odd window size for local variance (default 5)
+        :return: Fused grayscale image ``(H, W)``
+        """
+        if imfs is None:
+            imfs = self.fit_transform(images)
+        imfs = np.asarray(imfs, dtype=float)
+        if imfs.ndim != 4:
+            raise ValueError("imfs must have shape (K, n_channels, H, W)")
+
+        k_modes, n_ch, height, width = imfs.shape
+        fused = np.zeros((height, width), dtype=float)
+
+        for q in range(k_modes):
+            bimf = imfs[q]  # (C, H, W)
+            if q < k_modes - 1:
+                var = local_var_img(bimf, var_window)  # (C, H, W)
+                denom = np.sum(var, axis=0, keepdims=True) + 1e-12
+                weights = var / denom
+            else:
+                denom = np.sum(bimf, axis=0, keepdims=True)
+                # Avoid division by zero on flat residue
+                denom = np.where(np.abs(denom) < 1e-12, 1.0, denom)
+                weights = bimf / denom
+            fused = fused + np.sum(bimf * weights, axis=0)
+
+        return fused
+
+    # ------------------------------------------------------------------ #
+    # Internals
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _check_input(images: np.ndarray) -> np.ndarray:
+        x = np.asarray(images, dtype=float)
+        if x.ndim != 3:
+            raise ValueError("BMEMD expects a 3-D array of shape (n_channels, H, W)")
+        n_ch, height, width = x.shape
+        if n_ch < 2 or n_ch > 16:
+            raise ValueError("n_channels must satisfy 2 <= n_channels <= 16")
+        if height < 3 or width < 3:
+            raise ValueError("Each spatial dimension must be >= 3")
+        return x
+
+    def _direction_vectors(self, n_dim: int) -> np.ndarray:
+        """
+        Unit directions of shape ``(n_dir, n_dim)``.
+
+        Matches MATLAB ``get_dir`` / Hammersley construction in ``bmemd.m``.
+        """
+        ndir = self.n_dir
+        dirs = np.zeros((ndir, n_dim), dtype=float)
+
+        if n_dim == 2:
+            # Uniform samples on the circle (MATLAB 1-based index)
+            for it in range(1, ndir + 1):
+                dirs[it - 1, 0] = np.cos(2.0 * np.pi * it / ndir)
+                dirs[it - 1, 1] = np.sin(2.0 * np.pi * it / ndir)
+            return dirs
+
+        # Hammersley low-discrepancy sequence
+        if n_dim == 3:
+            base = [-ndir, 2]
+            seq = np.zeros((2, ndir))
+            for it in range(2):
+                seq[it, :] = np.asarray(hamm(ndir, base[it])).ravel()
+            for it in range(ndir):
+                tt = float(np.clip(2.0 * seq[0, it] - 1.0, -1.0, 1.0))
+                phirad = float(seq[1, it] * 2.0 * np.pi)
+                st = np.sqrt(max(1.0 - tt * tt, 0.0))
+                dirs[it, 0] = st * np.cos(phirad)
+                dirs[it, 1] = st * np.sin(phirad)
+                dirs[it, 2] = tt
+            return dirs
+
+        # n_dim > 3 (same construction as MEMD / MATLAB bmemd.m)
+        primes = nth_prime(n_dim - 1)
+        base = [-ndir] + list(primes[: n_dim - 1])
+        seq = np.zeros((n_dim, ndir))
+        for it in range(n_dim):
+            seq[it, :] = np.asarray(hamm(ndir, base[it])).ravel()
+
+        for it in range(ndir):
+            b = 2.0 * seq[:, it] - 1.0
+            # atan2(sqrt(flipud(cumsum(b(end:-1:2).^2))), b(1:end-1))
+            tht = np.arctan2(
+                np.sqrt(np.flipud(np.cumsum(b[:0:-1] ** 2))), b[: n_dim - 1]
+            )
+            dir_t = np.cumprod(np.concatenate(([1.0], np.sin(tht))))
+            dir_t = np.asarray(dir_t[:n_dim], dtype=float)
+            dir_t[: n_dim - 1] = np.cos(tht) * dir_t[: n_dim - 1]
+            dirs[it] = dir_t
+        return dirs
+
+    @staticmethod
+    def _project(images: np.ndarray, direction: np.ndarray) -> np.ndarray:
+        """Pixel-wise projection ``Σ_c I_c * u_c`` → shape ``(H, W)``."""
+        return np.tensordot(direction, images, axes=(0, 0))
+
+    @staticmethod
+    def _regional_extrema(surface: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """Boolean maps of regional maxima / minima (MATLAB ``imregional*``)."""
+        maxima = maximum_filter(surface, size=3) == surface
+        minima = minimum_filter(surface, size=3) == surface
+        return maxima, minima
+
+    def _stop_emd(self, residue: np.ndarray, directions: np.ndarray) -> bool:
+        """Stop if any projection has fewer than 3 maxima or minima."""
+        for d in directions:
+            y = self._project(residue, d)
+            maxima, minima = self._regional_extrema(y)
+            if maxima.sum() < 3 or minima.sum() < 3:
+                return True
+        return False
+
+    def _envelope_mean(
+        self, mode: np.ndarray, directions: np.ndarray
+    ) -> Tuple[np.ndarray, int, np.ndarray]:
+        """
+        Average multivariate envelopes over all projection directions.
+
+        :return: ``(env_mean, nem_last, amp)`` where ``amp`` is the summed
+            envelope amplitude map used by the stop criterion.
+        """
+        n_ch, height, width = mode.shape
+        env_mean = np.zeros_like(mode)
+        amp = np.zeros((height, width), dtype=float)
+        nem = 0
+
+        yy_grid, xx_grid = np.mgrid[0:height, 0:width]
+
+        for d in directions:
+            y = self._project(mode, d)
+            maxima, minima = self._regional_extrema(y)
+            nem = int(maxima.sum() + minima.sum())
+
+            max_r, max_c = np.nonzero(maxima)
+            min_r, min_c = np.nonzero(minima)
+            if max_r.size < 3 or min_r.size < 3:
+                raise RuntimeError("Insufficient extrema for envelope fitting")
+
+            env_max = np.zeros_like(mode)
+            env_min = np.zeros_like(mode)
+            for c in range(n_ch):
+                env_max[c] = _surface_from_points(
+                    max_c, max_r, mode[c, max_r, max_c], xx_grid, yy_grid
+                )
+                env_min[c] = _surface_from_points(
+                    min_c, min_r, mode[c, min_r, min_c], xx_grid, yy_grid
+                )
+
+            amp = amp + np.sqrt(np.sum((env_max - env_min) ** 2, axis=0))
+            env_mean = env_mean + 0.5 * (env_max + env_min)
+
+        env_mean = env_mean / float(len(directions))
+        return env_mean, nem, amp
+
+    def _stop_sifting(self, env_mean: np.ndarray, amp: np.ndarray, nem: int) -> bool:
+        """Return True if sifting should stop (MATLAB ``stop_sifting``)."""
+        sx = np.sqrt(np.sum(env_mean**2, axis=0))
+        if np.any(amp):
+            sx = sx / (amp + 1e-12)
+        continue_sift = (
+            (np.mean(sx > self.sd) > self.tol) or np.any(sx > self.sd2)
+        ) and (nem > 9)
+        return not continue_sift
+
+
+def _surface_from_points(
+    x: np.ndarray,
+    y: np.ndarray,
+    z: np.ndarray,
+    xx_grid: np.ndarray,
+    yy_grid: np.ndarray,
+) -> np.ndarray:
+    """
+    Interpolate scattered extrema onto the full image grid.
+
+    Uses Clough–Tocher (Delaunay-based) interpolation as recommended in the
+    BMEMD paper, with nearest-neighbour fill for exterior / degenerate regions.
+    """
+    points = np.column_stack([x.astype(float), y.astype(float)])
+    values = z.astype(float)
+
+    # Deduplicate coincident extrema (keep mean value)
+    _, unique_idx = np.unique(points, axis=0, return_index=True)
+    points = points[unique_idx]
+    values = values[unique_idx]
+
+    if points.shape[0] < 3:
+        return np.full(xx_grid.shape, float(np.mean(values)))
+
+    try:
+        interp = CloughTocher2DInterpolator(points, values, fill_value=np.nan)
+        surface = interp(xx_grid, yy_grid)
+    except Exception:
+        surface = np.full(xx_grid.shape, np.nan, dtype=float)
+
+    if np.any(~np.isfinite(surface)):
+        nearest = NearestNDInterpolator(points, values)
+        nan_mask = ~np.isfinite(surface)
+        surface[nan_mask] = nearest(xx_grid[nan_mask], yy_grid[nan_mask])
+
+    return surface
+
+
+def local_var_img(images: np.ndarray, window: int = 5) -> np.ndarray:
+    """
+    Local squared deviation from a moving mean (MATLAB ``local_var_img``).
+
+    :param images: ``(H, W)`` or ``(C, H, W)``
+    :param window: Odd filter size
+    :return: Same shape as ``images``
+    """
+    x = np.asarray(images, dtype=float)
+    w = int(window)
+    if w < 1:
+        raise ValueError("window must be a positive integer")
+
+    if x.ndim == 2:
+        mean = uniform_filter(x, size=w, mode="nearest")
+        return (x - mean) ** 2
+
+    if x.ndim == 3:
+        out = np.empty_like(x)
+        for i in range(x.shape[0]):
+            mean = uniform_filter(x[i], size=w, mode="nearest")
+            out[i] = (x[i] - mean) ** 2
+        return out
+
+    raise ValueError("images must be 2-D or 3-D")
+
+
+def fuse_images(
+    images: np.ndarray,
+    n_dir: int = 8,
+    max_imfs: int = 4,
+    var_window: int = 5,
+    **bmemd_kwargs,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Convenience wrapper: BMEMD decomposition + variance-weighted fusion.
+
+    :return: ``(fused_image, imfs)``
+    """
+    bmemd = BMEMD(n_dir=n_dir, max_imfs=max_imfs, **bmemd_kwargs)
+    imfs = bmemd.fit_transform(images)
+    fused = bmemd.fuse(images, imfs=imfs, var_window=var_window)
+    return fused, imfs

{pysdkit-0.4.36 → pysdkit-0.4.37}/pysdkit/_faemd/faemd.py

@@ -163,9 +163,7 @@ class FAEMD(object):
 
     def get_imfs_and_residue(self) -> Tuple[np.ndarray, np.ndarray]:
         if self.imfs is None or self.residue is None:
-            raise ValueError(
-                "No IMF found. Please run `fit_transform` method first."
-            )
+            raise ValueError("No IMF found. Please run `fit_transform` method first.")
         return self.imfs, self.residue
 
 
@@ -178,9 +176,7 @@ def check_inputs(signal: np.ndarray) -> Tuple[np.ndarray, Tuple]:
     elif signal.ndim == 2:
         pass
     else:
-        raise ValueError(
-            "signal must have shape [seq_len] or [n_channels, seq_len]"
-        )
+        raise ValueError("signal must have shape [seq_len] or [n_channels, seq_len]")
     return signal.T, inputs_shape
 
 

{pysdkit-0.4.36 → pysdkit-0.4.37}/pysdkit/_faemd/faemd2d.py

@@ -60,9 +60,7 @@ class FAEMD2D(object):
         self.residue: Optional[np.ndarray] = None
 
     def __str__(self) -> str:
-        return (
-            "Bidimensional Fast and Adaptive Empirical Mode Decomposition (FAEMD2D)"
-        )
+        return "Bidimensional Fast and Adaptive Empirical Mode Decomposition (FAEMD2D)"
 
     def __call__(
         self, signal: np.ndarray, max_imfs: Optional[int] = None
@@ -81,9 +79,7 @@ class FAEMD2D(object):
             return x[np.newaxis, ...], True
         if x.ndim == 3:
             return x, False
-        raise ValueError(
-            "FAEMD2D expects shape (H, W) or (n_channels, H, W)"
-        )
+        raise ValueError("FAEMD2D expects shape (H, W) or (n_channels, H, W)")
 
     def fit_transform(
         self,

{pysdkit-0.4.36 → pysdkit-0.4.37}/pysdkit/_faemd/faemd3d.py

@@ -58,9 +58,7 @@ class FAEMD3D(object):
         self.residue: Optional[np.ndarray] = None
 
     def __str__(self) -> str:
-        return (
-            "Tridimensional Fast and Adaptive Empirical Mode Decomposition (FAEMD3D)"
-        )
+        return "Tridimensional Fast and Adaptive Empirical Mode Decomposition (FAEMD3D)"
 
     def __call__(
         self, signal: np.ndarray, max_imfs: Optional[int] = None
@@ -79,9 +77,7 @@ class FAEMD3D(object):
             if min(x.shape[1:]) < 3:
                 raise ValueError("Each spatial dimension must be >= 3")
             return x, False
-        raise ValueError(
-            "FAEMD3D expects shape (X, Y, Z) or (n_channels, X, Y, Z)"
-        )
+        raise ValueError("FAEMD3D expects shape (X, Y, Z) or (n_channels, X, Y, Z)")
 
     def fit_transform(
         self,

{pysdkit-0.4.36 → pysdkit-0.4.37}/pysdkit/_faemd/filter.py

@@ -81,9 +81,7 @@ def filter_size1D(
     return _seven_windows_from_spacings(edge_max, edge_min, window_type)
 
 
-def ord_filt1(
-    signal: np.ndarray, order: str, window_size: int
-) -> np.ndarray:
+def ord_filt1(signal: np.ndarray, order: str, window_size: int) -> np.ndarray:
     """1-D rank-order filter with symmetric (reflected) padding."""
     signal = np.asarray(signal, dtype=float)
     shape = signal.shape
@@ -139,12 +137,8 @@ def identify_max_min_2d(signal: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
     signal = np.asarray(signal, dtype=float)
     mask = np.ones((3, 3), dtype=bool)
     mask[1, 1] = False
-    neigh_max = ndimage.maximum_filter(
-        signal, footprint=mask, mode="nearest"
-    )
-    neigh_min = ndimage.minimum_filter(
-        signal, footprint=mask, mode="nearest"
-    )
+    neigh_max = ndimage.maximum_filter(signal, footprint=mask, mode="nearest")
+    neigh_min = ndimage.minimum_filter(signal, footprint=mask, mode="nearest")
     maxima = signal >= neigh_max
     minima = signal <= neigh_min
     return maxima, minima
@@ -281,9 +275,7 @@ def filter_size_3d(
     return _seven_windows_from_spacings(max_nearest, min_nearest, window_type)
 
 
-def ord_filt3_separable(
-    signal: np.ndarray, order: str, window_size: int
-) -> np.ndarray:
+def ord_filt3_separable(signal: np.ndarray, order: str, window_size: int) -> np.ndarray:
     """Separable 3-D OSF: apply 1-D rank filter along each axis."""
     w = int(window_size)
     if w < 3: