src/domain/interfaces/services/vgtlnet_preprocessor.py

"""
domain/interfaces/services/vgtlnet_preprocessor.py
──────────────────────────────────────────────────
Abstract interface for VGTL-Net signal preprocessing.
"""

from __future__ import annotations

from abc import ABC, abstractmethod
import numpy as np
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    import torch

class VGTLNetSignalPreprocessor(ABC):
    """
    Contract for preprocessing signals for VGTL-Net.

    Responsible for:
        1. Calculating Visibility Graphs (NVG) for PPG, ECG, and dPPG signals.
        2. Creating a 224x224x3 RGB image (R=PPG, G=ECG, B=dPPG).
        3. Converting images to PyTorch tensors and normalizing with mean=0.5, std=0.5.
    """

    @abstractmethod
    def preprocess_signals(
        self,
        ppg_segments: np.ndarray,
        ecg_segments: np.ndarray,
    ) -> torch.Tensor:
        """
        Convert matched batches of PPG and ECG signal windows (each window of size 224 @ 125 Hz)
        into a PyTorch tensor batch of shape (N, 3, 224, 224) representing
        the sparse visibility graph adjacency matrices.

        Args:
            ppg_segments: 2-D array of shape (N_windows, 224).
            ecg_segments: 2-D array of shape (N_windows, 224).

        Returns:
            PyTorch float32 Tensor of shape (N_windows, 3, 224, 224) normalized to [-1, 1].

        Raises:
            PreprocessingError: If preprocessing or graph building fails.
        """
        ...