gsvvcompressor 1.2.0__cp311-cp311-win_amd64.whl

gsvvcompressor/interframe/combine.py

@@ -0,0 +1,271 @@
+from dataclasses import dataclass
+from typing import List, Self
+
+from gaussian_splatting import GaussianModel
+
+from ..payload import Payload
+from .interface import (
+    InterframeCodecInterface,
+    InterframeCodecContext,
+    InterframeEncoderInitConfig,
+)
+
+
+@dataclass
+class CombinedPayload(Payload):
+    """
+    Combined payload containing multiple sub-codec payloads.
+    """
+    payloads: List[Payload]
+
+    def to(self, device) -> Self:
+        """
+        Move the Payload to the specified device.
+
+        Args:
+            device: The target device (e.g., 'cpu', 'cuda', torch.device).
+
+        Returns:
+            A new CombinedPayload instance with all sub-payloads on the target device.
+        """
+        return CombinedPayload(
+            payloads=[p.to(device) for p in self.payloads],
+        )
+
+
+@dataclass
+class CombinedInterframeEncoderInitConfig(InterframeEncoderInitConfig):
+    """
+    Combined encoder initialization configuration containing multiple sub-codec configs.
+    """
+    init_configs: List[InterframeEncoderInitConfig]
+
+
+@dataclass
+class CombinedInterframeCodecContext(InterframeCodecContext):
+    """
+    Combined context containing multiple sub-codec contexts.
+    """
+    contexts: List[InterframeCodecContext]
+
+
+class CombinedInterframeCodecInterface(InterframeCodecInterface):
+    """
+    A codec that combines multiple InterframeCodecInterface instances.
+
+    Each method calls the corresponding method on all sub-codecs and combines
+    their outputs.
+    """
+
+    def __init__(self, interfaces: List[InterframeCodecInterface]):
+        """
+        Initialize the combined codec with a list of sub-codecs.
+
+        Args:
+            interfaces: List of InterframeCodecInterface instances to combine.
+        """
+        if not interfaces:
+            raise ValueError("At least one interface must be provided")
+        self.interfaces = interfaces
+
+    def decode_interframe(
+        self, payload: CombinedPayload, prev_context: CombinedInterframeCodecContext
+    ) -> CombinedInterframeCodecContext:
+        """
+        Decode a delta payload to reconstruct the next frame's context.
+
+        Calls decode_interframe on all sub-codecs and combines their contexts.
+
+        Args:
+            payload: The delta payload containing individual payloads for each sub-codec.
+            prev_context: The context of the previous frame containing individual contexts for each sub-codec.
+
+        Returns:
+            A CombinedInterframeCodecContext containing all sub-codec contexts.
+        """
+        # Call decode_interframe on each sub-codec
+        contexts = []
+        for interface, payload, prev_context in zip(self.interfaces, payload.payloads, prev_context.contexts):
+            context = interface.decode_interframe(payload, prev_context)
+            contexts.append(context)
+        return CombinedInterframeCodecContext(contexts=contexts)
+
+    def encode_interframe(
+        self,
+        prev_context: CombinedInterframeCodecContext,
+        next_context: CombinedInterframeCodecContext,
+    ) -> CombinedPayload:
+        """
+        Encode the difference between two consecutive frames.
+
+        Calls encode_interframe on all sub-codecs and combines their payloads.
+
+        Args:
+            prev_context: The context of the previous frame containing individual contexts for each sub-codec.
+            next_context: The context of the next frame containing individual contexts for each sub-codec.
+
+        Returns:
+            A CombinedPayload containing all sub-codec payloads.
+        """
+        # Call encode_interframe on each sub-codec
+        payloads = []
+        for interface, prev_context, next_context in zip(self.interfaces, prev_context.contexts, next_context.contexts):
+            payload = interface.encode_interframe(prev_context, next_context)
+            payloads.append(payload)
+        return CombinedPayload(payloads=payloads)
+
+    def decode_keyframe(self, payload: CombinedPayload) -> CombinedInterframeCodecContext:
+        """
+        Decode a keyframe payload to create initial context.
+
+        Calls decode_keyframe on all sub-codecs and combines their contexts.
+
+        Args:
+            payload: The keyframe payload containing individual payloads for each sub-codec.
+
+        Returns:
+            A CombinedInterframeCodecContext containing all sub-codec contexts.
+        """
+        # Call decode_keyframe on each sub-codec
+        contexts = []
+        for interface, payload in zip(self.interfaces, payload.payloads):
+            context = interface.decode_keyframe(payload)
+            contexts.append(context)
+        return CombinedInterframeCodecContext(contexts=contexts)
+
+    def decode_keyframe_for_encode(
+        self, payload: CombinedPayload, context: CombinedInterframeCodecContext
+    ) -> CombinedInterframeCodecContext:
+        """
+        Decode a keyframe payload during encoding to avoid error accumulation.
+
+        Calls decode_keyframe_for_encode on all sub-codecs and combines their contexts.
+
+        Args:
+            payload: The keyframe payload containing individual payloads for each sub-codec.
+            context: The original context containing individual contexts for each sub-codec.
+
+        Returns:
+            A CombinedInterframeCodecContext containing all sub-codec reconstructed contexts.
+        """
+        # Call decode_keyframe_for_encode on each sub-codec
+        contexts = []
+        for interface, sub_payload, sub_context in zip(
+            self.interfaces, payload.payloads, context.contexts
+        ):
+            reconstructed = interface.decode_keyframe_for_encode(sub_payload, sub_context)
+            contexts.append(reconstructed)
+        return CombinedInterframeCodecContext(contexts=contexts)
+
+    def decode_interframe_for_encode(
+        self, payload: CombinedPayload, prev_context: CombinedInterframeCodecContext
+    ) -> CombinedInterframeCodecContext:
+        """
+        Decode an interframe payload during encoding to avoid error accumulation.
+
+        Calls decode_interframe_for_encode on all sub-codecs and combines their contexts.
+
+        Args:
+            payload: The interframe payload containing individual payloads for each sub-codec.
+            prev_context: The previous context containing individual contexts for each sub-codec.
+
+        Returns:
+            A CombinedInterframeCodecContext containing all sub-codec reconstructed contexts.
+        """
+        # Call decode_interframe_for_encode on each sub-codec
+        contexts = []
+        for interface, sub_payload, sub_prev_context in zip(
+            self.interfaces, payload.payloads, prev_context.contexts
+        ):
+            reconstructed = interface.decode_interframe_for_encode(sub_payload, sub_prev_context)
+            contexts.append(reconstructed)
+        return CombinedInterframeCodecContext(contexts=contexts)
+
+    def encode_keyframe(
+        self, context: CombinedInterframeCodecContext
+    ) -> CombinedPayload:
+        """
+        Encode the first frame as a keyframe.
+
+        Calls encode_keyframe on all sub-codecs and combines their payloads.
+
+        Args:
+            context: The context of the first frame containing individual contexts for each sub-codec.
+
+        Returns:
+            A CombinedPayload containing all sub-codec payloads.
+        """
+        # Call encode_keyframe on each sub-codec
+        payloads = []
+        for interface, context in zip(self.interfaces, context.contexts):
+            payload = interface.encode_keyframe(context)
+            payloads.append(payload)
+        return CombinedPayload(payloads=payloads)
+
+    def keyframe_to_context(
+        self, frame: GaussianModel, init_config: CombinedInterframeEncoderInitConfig
+    ) -> CombinedInterframeCodecContext:
+        """
+        Convert a keyframe to a Context.
+
+        Calls keyframe_to_context on all sub-codecs and combines their contexts.
+
+        Args:
+            frame: The GaussianModel frame to convert.
+            init_config: Encoder initialization configuration containing individual configs for each sub-codec.
+
+        Returns:
+            A CombinedInterframeCodecContext containing all sub-codec contexts.
+        """
+        # Call keyframe_to_context on each sub-codec
+        contexts = []
+        for interface, init_config in zip(self.interfaces, init_config.init_configs):
+            context = interface.keyframe_to_context(frame, init_config)
+            contexts.append(context)
+        return CombinedInterframeCodecContext(contexts=contexts)
+
+    def interframe_to_context(
+        self,
+        frame: GaussianModel,
+        prev_context: CombinedInterframeCodecContext,
+    ) -> CombinedInterframeCodecContext:
+        """
+        Convert a frame to a Context using the previous context as reference.
+
+        Calls interframe_to_context on all sub-codecs and combines their contexts.
+
+        Args:
+            frame: The GaussianModel frame to convert.
+            prev_context: The context from the previous frame containing individual contexts for each sub-codec.
+
+        Returns:
+            A CombinedInterframeCodecContext containing all sub-codec contexts.
+        """
+        # Call interframe_to_context on each sub-codec
+        contexts = []
+        for interface, prev_context in zip(self.interfaces, prev_context.contexts):
+            context = interface.interframe_to_context(frame, prev_context)
+            contexts.append(context)
+        return CombinedInterframeCodecContext(contexts=contexts)
+
+    def context_to_frame(
+        self, context: CombinedInterframeCodecContext, frame: GaussianModel
+    ) -> GaussianModel:
+        """
+        Convert a Context back to a frame.
+
+        Calls context_to_frame on all sub-codecs sequentially, applying each
+        context to the frame in order.
+
+        Args:
+            context: The Context to convert containing individual contexts for each sub-codec.
+            frame: An empty GaussianModel or one from previous pipeline steps.
+                This frame will be modified in-place by each sub-codec.
+
+        Returns:
+            The modified GaussianModel with the frame data.
+        """
+        # Apply each context sequentially to the frame
+        for interface, context in zip(self.interfaces, context.contexts):
+            frame = interface.context_to_frame(context, frame)
+        return frame

gsvvcompressor/interframe/decoder.py

@@ -0,0 +1,99 @@
+from typing import Iterator, Optional
+
+import torch
+
+from gaussian_splatting import GaussianModel
+
+from ..decoder import AbstractDecoder
+from ..deserializer import AbstractDeserializer
+from ..payload import Payload
+from .interface import InterframeCodecContext, InterframeCodecInterface
+
+
+class InterframeDecoder(AbstractDecoder):
+    """
+    Decoder that uses inter-frame decompression.
+
+    This decoder maintains an internal Context state and decodes frames
+    by applying deltas to the previous frame's context. The first frame
+    is decoded as a keyframe, and subsequent frames are decoded as deltas.
+    """
+
+    def __init__(
+        self,
+        deserializer: AbstractDeserializer,
+        interface: InterframeCodecInterface,
+        payload_device: str | torch.device | None = None,
+        device: str | torch.device | None = None,
+    ):
+        """
+        Initialize the inter-frame decoder.
+
+        Args:
+            deserializer: The deserializer to use for converting bytes to Payload.
+            interface: The InterframeCodecInterface instance that provides decoding methods.
+            payload_device: The target device for input Payloads before
+                unpacking (e.g., 'cpu', 'cuda'). If None, no device
+                transfer is performed.
+            device: The target device for output GaussianModel frames
+                (e.g., 'cpu', 'cuda'). If None, no device transfer is performed.
+        """
+        super().__init__(deserializer, payload_device, device)
+        self._interface = interface
+        self._prev_context: Optional[InterframeCodecContext] = None
+
+    def create_empty_frame(self) -> GaussianModel:
+        """
+        Create an empty GaussianModel for frame reconstruction.
+
+        This method is called before `context_to_frame` to provide a frame
+        that will be populated with data. Override this method if your
+        GaussianModel contains custom data or attributes that are not part of
+        the standard GaussianModel(), such as additional fields or custom
+        initialization logic.
+
+        Returns:
+            An empty GaussianModel instance.
+        """
+        return GaussianModel(sh_degree=3)
+
+    def unpack(self, payload: Payload) -> Iterator[GaussianModel]:
+        """
+        Unpack frame(s) from a Payload using inter-frame decoding.
+
+        The first payload is decoded as a keyframe. Subsequent payloads
+        are decoded as deltas from the previous frame.
+
+        Args:
+            payload: A Payload instance to unpack.
+
+        Yields:
+            Unpacked GaussianModel instances.
+        """
+        if self._prev_context is None:
+            # First frame: decode as keyframe
+            current_context = self._interface.decode_keyframe(payload)
+        else:
+            # Subsequent frames: decode as delta from previous
+            current_context = self._interface.decode_interframe(
+                payload, self._prev_context
+            )
+
+        # Update the previous context for next frame
+        self._prev_context = current_context
+
+        # Convert context back to frame
+        frame = self.create_empty_frame()
+        yield self._interface.context_to_frame(current_context, frame)
+
+    def flush_unpack(self) -> Iterator[GaussianModel]:
+        """
+        Flush any remaining buffered frames from the unpacking stage.
+
+        For inter-frame decoding, there are no buffered frames to flush.
+
+        Yields:
+            No frames (empty iterator).
+        """
+        return
+        yield  # Make this a generator

gsvvcompressor/interframe/encoder.py

@@ -0,0 +1,92 @@
+from typing import Iterator, Optional
+
+from gaussian_splatting import GaussianModel
+
+from ..encoder import AbstractEncoder
+from ..payload import Payload
+from ..serializer import AbstractSerializer
+from .interface import InterframeCodecContext, InterframeEncoderInitConfig, InterframeCodecInterface
+
+
+class InterframeEncoder(AbstractEncoder):
+    """
+    Encoder that uses inter-frame compression.
+
+    This encoder maintains an internal Context state and encodes frames
+    as differences from the previous frame. The first frame is encoded
+    as a keyframe, and subsequent frames are encoded as deltas.
+    """
+
+    def __init__(
+        self,
+        serializer: AbstractSerializer,
+        interface: InterframeCodecInterface,
+        init_config: InterframeEncoderInitConfig,
+        payload_device=None,
+    ):
+        """
+        Initialize the inter-frame encoder.
+
+        Args:
+            serializer: The serializer to use for converting Payload to bytes.
+            interface: The InterframeCodecInterface instance that provides encoding methods.
+            init_config: Configuration parameters for keyframe initialization.
+            payload_device: The target device for encoded Payloads before
+                serialization (e.g., 'cpu', 'cuda'). If None, no device
+                transfer is performed.
+        """
+        super().__init__(serializer, payload_device)
+        self._interface = interface
+        self._init_config = init_config
+        self._prev_context: Optional[InterframeCodecContext] = None
+
+    def pack(self, frame: GaussianModel) -> Iterator[Payload]:
+        """
+        Pack a single frame into Payload objects using inter-frame encoding.
+
+        The first frame is encoded as a keyframe. Subsequent frames are
+        encoded as deltas from the previous frame.
+
+        Args:
+            frame: A GaussianModel instance to pack.
+
+        Yields:
+            Packed Payload instances.
+        """
+        if self._prev_context is None:
+            # First frame: convert and encode as keyframe
+            current_context = self._interface.keyframe_to_context(frame, self._init_config)
+            payload = self._interface.encode_keyframe(current_context)
+            # Decode back to get reconstructed context (avoid error accumulation)
+            reconstructed_context = self._interface.decode_keyframe_for_encode(
+                payload, current_context
+            )
+        else:
+            # Subsequent frames: convert and encode as delta from previous
+            current_context = self._interface.interframe_to_context(
+                frame, self._prev_context
+            )
+            payload = self._interface.encode_interframe(
+                self._prev_context, current_context
+            )
+            # Decode back to get reconstructed context (avoid error accumulation)
+            reconstructed_context = self._interface.decode_interframe_for_encode(
+                payload, self._prev_context
+            )
+
+        # Use reconstructed context as previous for next frame
+        self._prev_context = reconstructed_context
+
+        yield payload
+
+    def flush_pack(self) -> Iterator[Payload]:
+        """
+        Flush any remaining buffered payloads from the packing stage.
+
+        For inter-frame encoding, there are no buffered payloads to flush.
+
+        Yields:
+            No payloads (empty iterator).
+        """
+        return
+        yield  # Make this a generator

gsvvcompressor/interframe/interface.py

@@ -0,0 +1,221 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from gaussian_splatting import GaussianModel
+
+from ..payload import Payload
+
+
+@dataclass
+class InterframeEncoderInitConfig:
+    """
+    Configuration for initializing the encoder when encoding the first frame (keyframe).
+
+    This dataclass is passed to `keyframe_to_context()` when the encoder processes
+    the first frame. It contains encoder-specific settings that determine how the
+    encoding context is initialized, such as quality settings, compression levels,
+    or algorithm parameters.
+
+    Subclasses should define specific fields for their encoding scheme.
+
+    Note:
+        This config is only used by the encoder during keyframe processing.
+        Configurations shared by both encoder and decoder should be stored
+        in InterframeCodecInterface.
+    """
+    pass
+
+
+@dataclass
+class InterframeCodecContext:
+    """
+    Context data for inter-frame encoding/decoding.
+
+    This dataclass holds the state information needed to encode/decode
+    frames relative to a reference frame. Both encoder and decoder
+    maintain their own InterframeCodecContext instances.
+
+    Subclasses should define specific fields for their encoding scheme.
+
+    Note:
+        This is for encoder/decoder runtime state (e.g., reference frame data,
+        accumulated statistics). Encoder initialization config should be stored
+        in InterframeEncoderInitConfig. Shared configurations should be stored
+        in InterframeCodecInterface.
+    """
+    pass
+
+
+class InterframeCodecInterface(ABC):
+    """
+    Abstract interface for inter-frame encoding/decoding algorithms.
+
+    This interface defines the methods required to implement inter-frame
+    compression, where frames are encoded as differences from previous frames.
+
+    Design Guidelines:
+        - InterframeCodecInterface: Store configurations shared by both encoder
+          and decoder (e.g., algorithm parameters that affect both encoding and
+          decoding, such as quantization tables or codebook sizes).
+        - InterframeCodecContext: Store encoder/decoder runtime state (e.g.,
+          reference frame data, accumulated statistics). Each side maintains
+          its own context instance.
+        - InterframeEncoderInitConfig: Store encoder initialization config that
+          is passed to `keyframe_to_context()` when encoding the first frame
+          (e.g., quality settings, compression levels).
+    """
+
+    @abstractmethod
+    def decode_interframe(self, payload: Payload, prev_context: InterframeCodecContext) -> InterframeCodecContext:
+        """
+        Decode a delta payload to reconstruct the next frame's context.
+
+        Args:
+            payload: The delta payload containing the difference data.
+            prev_context: The context of the previous frame.
+
+        Returns:
+            The reconstructed context for the current frame.
+        """
+        pass
+
+    @abstractmethod
+    def encode_interframe(self, prev_context: InterframeCodecContext, next_context: InterframeCodecContext) -> Payload:
+        """
+        Encode the difference between two consecutive frames.
+
+        Args:
+            prev_context: The context of the previous frame.
+            next_context: The context of the next frame.
+
+        Returns:
+            A payload containing the delta information.
+        """
+        pass
+
+    @abstractmethod
+    def decode_keyframe(self, payload: Payload) -> InterframeCodecContext:
+        """
+        Decode a keyframe payload to create initial context.
+
+        Args:
+            payload: The keyframe payload containing full frame data.
+
+        Returns:
+            The context for the first/key frame.
+        """
+        pass
+
+    @abstractmethod
+    def decode_keyframe_for_encode(self, payload: Payload, context: InterframeCodecContext) -> InterframeCodecContext:
+        """
+        Decode a keyframe payload during encoding to avoid error accumulation.
+
+        This method is used by the encoder after encoding a keyframe. It decodes
+        the payload back to get the reconstructed context that the decoder would
+        produce, which should be used as the reference for encoding subsequent
+        frames instead of the original context.
+
+        Unlike `decode_keyframe()`, this method may reuse data from the original
+        encoding context (passed as `context`) for efficiency, since certain
+        information may not need to be re-decoded during encoding.
+
+        Args:
+            payload: The keyframe payload that was just encoded.
+            context: The original context used for encoding this keyframe.
+
+        Returns:
+            The reconstructed context as the decoder would produce it.
+        """
+        pass
+
+    def decode_interframe_for_encode(
+        self, payload: Payload, prev_context: InterframeCodecContext
+    ) -> InterframeCodecContext:
+        """
+        Decode an interframe payload during encoding to avoid error accumulation.
+
+        This method is used by the encoder after encoding an interframe. It decodes
+        the payload back to get the reconstructed context that the decoder would
+        produce, which should be used as the reference for encoding subsequent
+        frames instead of the original context.
+
+        Unlike `decode_interframe()`, this method may reuse data from the previous
+        context for efficiency, since certain information (like codec parameters)
+        can be obtained from the context without re-decoding from the payload.
+
+        Args:
+            payload: The interframe payload that was just encoded.
+            prev_context: The previous frame's context (reconstructed version).
+
+        Returns:
+            The reconstructed context as the decoder would produce it.
+        """
+        return self.decode_interframe(payload, prev_context)
+
+    @abstractmethod
+    def encode_keyframe(self, context: InterframeCodecContext) -> Payload:
+        """
+        Encode the first frame as a keyframe.
+
+        Args:
+            context: The context of the first frame.
+
+        Returns:
+            A payload containing the full keyframe data.
+        """
+        pass
+
+    @abstractmethod
+    def keyframe_to_context(self, frame: GaussianModel, init_config: InterframeEncoderInitConfig) -> InterframeCodecContext:
+        """
+        Convert a keyframe to a Context.
+
+        This method is called by the encoder when processing the first frame.
+        The init_config provides encoder-specific settings for initializing
+        the encoding context.
+
+        Args:
+            frame: The GaussianModel frame to convert.
+            init_config: Encoder initialization configuration.
+
+        Returns:
+            The corresponding Context representation.
+        """
+        pass
+
+    @abstractmethod
+    def interframe_to_context(
+        self,
+        frame: GaussianModel,
+        prev_context: InterframeCodecContext,
+    ) -> InterframeCodecContext:
+        """
+        Convert a frame to a Context using the previous context as reference.
+
+        Args:
+            frame: The GaussianModel frame to convert.
+            prev_context: The context from the previous frame.
+
+        Returns:
+            The corresponding Context representation.
+        """
+        pass
+
+    @abstractmethod
+    def context_to_frame(self, context: InterframeCodecContext, frame: GaussianModel) -> GaussianModel:
+        """
+        Convert a Context back to a frame.
+
+        This method populates the provided GaussianModel with data from the
+        context and returns it.
+
+        Args:
+            context: The Context to convert.
+            frame: An empty GaussianModel or one from previous pipeline steps.
+                This frame will be modified in-place with the context data.
+
+        Returns:
+            The modified GaussianModel with the frame data.
+        """
+        pass