gsvvcompressor 1.2.0__cp311-cp311-win_amd64.whl

gsvvcompressor/__init__.py

@@ -0,0 +1,13 @@
+from .decoder import AbstractDecoder
+from .deserializer import AbstractDeserializer
+from .encoder import AbstractEncoder
+from .payload import Payload
+from .serializer import AbstractSerializer
+
+__all__ = [
+    "Payload",
+    "AbstractEncoder",
+    "AbstractDecoder",
+    "AbstractSerializer",
+    "AbstractDeserializer",
+]

gsvvcompressor/__main__.py

@@ -0,0 +1,243 @@
+"""
+Command-line interface for gsvvcompressor.
+
+This module provides encode and decode subcommands for each registered
+encoder/decoder combination.
+
+Usage:
+    python -m gsvvcompressor encode <codec_name> [options]
+    python -m gsvvcompressor decode <codec_name> [options]
+
+Example:
+    python -m gsvvcompressor encode vqxyzzstd \
+        input.first_frame_path=data/frame_0000.ply \
+        input.subsequent_format="data/frame_{:04d}.ply" \
+        output.path=compressed.bin
+
+    python -m gsvvcompressor decode vqxyzzstd \
+        input.path=compressed.bin \
+        output.first_frame_path=decoded/frame_0000.ply \
+        output.subsequent_format="decoded/frame_{:04d}.ply"
+
+Hydra options:
+    --help              Show configuration schema
+    --cfg job           Show resolved configuration
+    --info config       Show config search path
+"""
+
+import logging
+import sys
+from dataclasses import field, make_dataclass
+from typing import Iterable, Iterator, List, Type, TypeVar
+
+import hydra
+from hydra.core.config_store import ConfigStore
+from hydra.core.global_hydra import GlobalHydra
+from omegaconf import DictConfig
+
+from .combinations import ENCODERS, DECODERS
+from .io import (
+    FrameReaderConfig,
+    FrameWriterConfig,
+    BytesReaderConfig,
+    BytesWriterConfig,
+    build_frame_reader,
+    build_frame_writer,
+    build_bytes_reader,
+    build_bytes_writer,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Progress Logging Utilities
+# =============================================================================
+
+def iter_with_progress(iterable: Iterator, desc: str) -> Iterator:
+    """Wrap an iterable to log progress for each item."""
+    for i, item in enumerate(iterable):
+        logger.info(f"{desc} {i}")
+        yield item
+    logger.info(f"{desc} finished")
+
+
+def format_size(size: int) -> str:
+    """Format byte size to human-readable string (KB, MB, GB, etc.)."""
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if abs(size) < 1024:
+            return f"{size:.2f} {unit}"
+        size /= 1024
+    return f"{size:.2f} PB"
+
+
+def iter_with_size_logging(iterable: Iterator[bytes], desc: str) -> Iterator[bytes]:
+    """Wrap a bytes iterable to log the size of each item."""
+    total_size = 0
+    for i, item in enumerate(iterable):
+        size = len(item)
+        total_size += size
+        logger.info(f"{desc} {i}: {format_size(size)} (total: {format_size(total_size)})")
+        yield item
+    logger.info(f"{desc} finished, total size: {format_size(total_size)}")
+
+
+# =============================================================================
+# Dynamic Config Generation
+# =============================================================================
+
+def make_encode_config(codec_config_cls: Type) -> Type:
+    """Dynamically create an encode config dataclass for a given codec."""
+    return make_dataclass(
+        f"Encode{codec_config_cls.__name__}",
+        [
+            ("input", FrameReaderConfig, field(default_factory=FrameReaderConfig)),
+            ("output", BytesWriterConfig, field(default_factory=BytesWriterConfig)),
+            ("codec", codec_config_cls, field(default_factory=codec_config_cls)),
+        ],
+    )
+
+
+def make_decode_config(codec_config_cls: Type) -> Type:
+    """Dynamically create a decode config dataclass for a given codec."""
+    return make_dataclass(
+        f"Decode{codec_config_cls.__name__}",
+        [
+            ("input", BytesReaderConfig, field(default_factory=BytesReaderConfig)),
+            ("output", FrameWriterConfig, field(default_factory=FrameWriterConfig)),
+            ("codec", codec_config_cls, field(default_factory=codec_config_cls)),
+        ],
+    )
+
+
+# =============================================================================
+# Encode/Decode Functions
+# =============================================================================
+
+def do_encode(cfg: DictConfig, codec_name: str) -> None:
+    """Execute the encoding process with resolved config."""
+    encoder_entry = ENCODERS[codec_name]
+
+    # Build components from config
+    frame_reader = build_frame_reader(cfg.input)
+    bytes_writer = build_bytes_writer(cfg.output)
+
+    # Build encoder from codec config
+    encoder = encoder_entry.factory(cfg.codec)
+
+    logger.info(f"Encoding with {codec_name}...")
+    logger.info(f"  Input: {cfg.input.first_frame_path}")
+    logger.info(f"  Output: {cfg.output.path}")
+
+    # Read frames and encode
+    frame_stream = iter_with_progress(frame_reader.read(), "Reading frame")
+    encoded_stream = iter_with_progress(encoder.encode_stream(frame_stream), "Encoded chunk")
+
+    # Write encoded bytes with size logging
+    bytes_writer.write(iter_with_size_logging(encoded_stream, "Writing chunk"))
+
+    logger.info("Encoding complete!")
+
+
+def do_decode(cfg: DictConfig, codec_name: str) -> None:
+    """Execute the decoding process with resolved config."""
+    decoder_entry = DECODERS[codec_name]
+
+    # Build components from config
+    bytes_reader = build_bytes_reader(cfg.input)
+    frame_writer = build_frame_writer(cfg.output)
+
+    # Build decoder from codec config
+    decoder = decoder_entry.factory(cfg.codec)
+
+    logger.info(f"Decoding with {codec_name}...")
+    logger.info(f"  Input: {cfg.input.path}")
+    logger.info(f"  Output: {cfg.output.first_frame_path}")
+
+    # Read bytes and decode
+    bytes_stream = iter_with_size_logging(bytes_reader.read(), "Reading chunk")
+    decoded_stream = iter_with_progress(decoder.decode_stream(bytes_stream), "Decoded frame")
+
+    # Write decoded frames
+    frame_writer.write(iter_with_progress(decoded_stream, "Writing frame"))
+
+    logger.info("Decoding complete!")
+
+
+def run_encode(codec_name: str, hydra_args: List[str]) -> None:
+    """Run encoding with Hydra configuration."""
+    encoder_entry = ENCODERS[codec_name]
+    config_cls = make_encode_config(encoder_entry.config_class)
+
+    # Clear and register config
+    GlobalHydra.instance().clear()
+    cs = ConfigStore.instance()
+    cs.store(name="config", node=config_cls)
+
+    @hydra.main(version_base=None, config_path=None, config_name="config")
+    def _main(cfg: DictConfig) -> None:
+        do_encode(cfg, codec_name)
+
+    sys.argv = [sys.argv[0]] + hydra_args
+    _main()
+
+
+def run_decode(codec_name: str, hydra_args: List[str]) -> None:
+    """Run decoding with Hydra configuration."""
+    decoder_entry = DECODERS[codec_name]
+    config_cls = make_decode_config(decoder_entry.config_class)
+
+    # Clear and register config
+    GlobalHydra.instance().clear()
+    cs = ConfigStore.instance()
+    cs.store(name="config", node=config_cls)
+
+    @hydra.main(version_base=None, config_path=None, config_name="config")
+    def _main(cfg: DictConfig) -> None:
+        do_decode(cfg, codec_name)
+
+    sys.argv = [sys.argv[0]] + hydra_args
+    _main()
+
+
+# =============================================================================
+# Main Entry Point
+# =============================================================================
+
+def main() -> None:
+    """Main entry point for the CLI."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+
+    if len(sys.argv) < 2 or sys.argv[1] in ("--help", "-h", "help"):
+        print("Usage: python -m gsvvcompressor <encode|decode> <codec> [options]")
+        print(f"  Encoders: {list(ENCODERS.keys())}")
+        print(f"  Decoders: {list(DECODERS.keys())}")
+        print("Use --help after codec name for configuration options.")
+        sys.exit(0 if len(sys.argv) >= 2 else 1)
+
+    command = sys.argv[1]
+    if command not in ("encode", "decode"):
+        sys.exit(f"Error: Unknown command '{command}'. Use 'encode' or 'decode'.")
+
+    if len(sys.argv) < 3:
+        sys.exit(f"Error: Please specify a codec for {command}. Available: {list(ENCODERS.keys() if command == 'encode' else DECODERS.keys())}")
+
+    codec_name = sys.argv[2]
+    registry = ENCODERS if command == "encode" else DECODERS
+    if codec_name not in registry:
+        sys.exit(f"Error: Unknown {command}r '{codec_name}'. Available: {list(registry.keys())}")
+
+    # Remaining args go to Hydra (--help, --cfg, overrides, etc.)
+    hydra_args = sys.argv[3:]
+
+    if command == "encode":
+        run_encode(codec_name, hydra_args)
+    else:
+        run_decode(codec_name, hydra_args)
+
+
+if __name__ == "__main__":
+    main()

gsvvcompressor/combinations/__init__.py

@@ -0,0 +1,84 @@
+"""
+Combination modules for composing multiple codec components.
+"""
+
+from .registry import (
+    ENCODERS,
+    DECODERS,
+    register_encoder,
+    register_decoder,
+    EncoderEntry,
+    DecoderEntry,
+)
+
+# Import to trigger registration
+from . import vq_xyz_zstd
+from . import vq_xyz_1mask_zstd
+from . import vq_xyz_draco
+from . import vq_xyz_draco_2pass
+
+from .vq_xyz_zstd import (
+    VQXYZZstdEncoderConfig,
+    VQXYZZstdDecoderConfig,
+    VQXYZZstdEncoder,
+    VQXYZZstdDecoder,
+    build_vqxyzzstd_encoder,
+    build_vqxyzzstd_decoder,
+)
+from .vq_xyz_1mask_zstd import (
+    VQXYZ1MaskZstdEncoder,
+    VQXYZ1MaskZstdDecoder,
+    build_vqxyz1maskzstd_encoder,
+    build_vqxyz1maskzstd_decoder,
+)
+from .vq_xyz_draco import (
+    VQXYZDracoEncoderConfig,
+    VQXYZDracoDecoderConfig,
+    VQXYZDracoEncoder,
+    VQXYZDracoDecoder,
+    build_vqxyzdraco_encoder,
+    build_vqxyzdraco_decoder,
+)
+from .vq_xyz_draco_2pass import (
+    VQXYZDraco2PassEncoderConfig,
+    VQXYZDraco2PassDecoderConfig,
+    VQXYZDraco2PassEncoder,
+    VQXYZDraco2PassDecoder,
+    build_vqxyzdraco2pass_encoder,
+    build_vqxyzdraco2pass_decoder,
+)
+
+__all__ = [
+    "ENCODERS",
+    "DECODERS",
+    "register_encoder",
+    "register_decoder",
+    "EncoderEntry",
+    "DecoderEntry",
+    # VQ + XYZ + Zstd
+    "VQXYZZstdEncoderConfig",
+    "VQXYZZstdDecoderConfig",
+    "VQXYZZstdEncoder",
+    "VQXYZZstdDecoder",
+    "build_vqxyzzstd_encoder",
+    "build_vqxyzzstd_decoder",
+    # VQ (single merged mask) + XYZ + Zstd
+    "VQXYZ1MaskZstdEncoder",
+    "VQXYZ1MaskZstdDecoder",
+    "build_vqxyz1maskzstd_encoder",
+    "build_vqxyz1maskzstd_decoder",
+    # VQ + XYZ + Draco
+    "VQXYZDracoEncoderConfig",
+    "VQXYZDracoDecoderConfig",
+    "VQXYZDracoEncoder",
+    "VQXYZDracoDecoder",
+    "build_vqxyzdraco_encoder",
+    "build_vqxyzdraco_decoder",
+    # VQ + XYZ + Two-Pass Draco
+    "VQXYZDraco2PassEncoderConfig",
+    "VQXYZDraco2PassDecoderConfig",
+    "VQXYZDraco2PassEncoder",
+    "VQXYZDraco2PassDecoder",
+    "build_vqxyzdraco2pass_encoder",
+    "build_vqxyzdraco2pass_decoder",
+]

gsvvcompressor/combinations/registry.py

@@ -0,0 +1,52 @@
+"""
+Global registry for encoder and decoder combinations.
+"""
+
+from dataclasses import dataclass
+from typing import Callable, Dict, Type
+
+from ..encoder import AbstractEncoder
+from ..decoder import AbstractDecoder
+
+
+@dataclass
+class EncoderEntry:
+    """Entry in the encoder registry."""
+    name: str
+    factory: Callable[..., AbstractEncoder]
+    config_class: Type
+    description: str = ""
+
+
+@dataclass
+class DecoderEntry:
+    """Entry in the decoder registry."""
+    name: str
+    factory: Callable[..., AbstractDecoder]
+    config_class: Type
+    description: str = ""
+
+
+# Global registries
+ENCODERS: Dict[str, EncoderEntry] = {}
+DECODERS: Dict[str, DecoderEntry] = {}
+
+
+def register_encoder(
+    name: str,
+    factory: Callable[..., AbstractEncoder],
+    config_class: Type,
+    description: str = "",
+) -> None:
+    """Register an encoder."""
+    ENCODERS[name] = EncoderEntry(name, factory, config_class, description)
+
+
+def register_decoder(
+    name: str,
+    factory: Callable[..., AbstractDecoder],
+    config_class: Type,
+    description: str = "",
+) -> None:
+    """Register a decoder."""
+    DECODERS[name] = DecoderEntry(name, factory, config_class, description)

gsvvcompressor/combinations/vq_xyz_1mask.py

@@ -0,0 +1,89 @@
+"""
+VQ + XYZ quantization combined codec interface with merged mask.
+
+This module provides the combined VQ + XYZ codec interface that uses a single
+merged mask for interframe encoding.
+"""
+
+from ..interframe.combine import (
+    CombinedInterframeCodecInterface,
+    CombinedInterframeCodecContext,
+    CombinedPayload,
+)
+from ..vq.interface import VQInterframeCodecContext
+from ..vq.singlemask import VQMergeMaskInterframeCodecInterface, VQMergeMaskInterframePayload
+from ..xyz.interface import (
+    XYZQuantInterframeCodecInterface,
+    XYZQuantInterframeCodecContext,
+    XYZQuantInterframePayload,
+)
+
+
+class VQXYZQuantMergeMaskInterframeCodecInterface(CombinedInterframeCodecInterface):
+    """
+    Combined VQ + XYZ codec with single merged mask for interframe encoding.
+
+    This interface extends CombinedInterframeCodecInterface but uses a single merged mask
+    (OR of XYZ mask and all VQ attribute masks) for interframe payloads. Both XYZ and VQ
+    payloads use the same mask, improving compression efficiency.
+
+    Assumes interfaces order: [xyz_interface, vq_interface]
+    """
+
+    def __init__(self):
+        """
+        Initialize the combined codec with XYZ and VQ interfaces.
+        """
+        xyz_interface = XYZQuantInterframeCodecInterface()
+        vq_interface = VQMergeMaskInterframeCodecInterface()
+        super().__init__([xyz_interface, vq_interface])
+        self.xyz_interface = xyz_interface
+        self.vq_interface = vq_interface
+
+    def encode_interframe(
+        self,
+        prev_context: CombinedInterframeCodecContext,
+        next_context: CombinedInterframeCodecContext,
+    ) -> CombinedPayload:
+        """
+        Encode the difference between two consecutive frames.
+
+        Calls super to get individual payloads, then merges masks (OR) and
+        re-extracts data using the merged mask.
+
+        Args:
+            prev_context: The context of the previous frame.
+            next_context: The context of the next frame.
+
+        Returns:
+            A CombinedPayload with XYZ and VQ payloads using the same merged mask.
+        """
+        # Get original payloads from parent
+        original_payload: CombinedPayload = super().encode_interframe(prev_context, next_context)
+        xyz_original: XYZQuantInterframePayload = original_payload.payloads[0]
+        vq_original: VQMergeMaskInterframePayload = original_payload.payloads[1]
+
+        # Merge masks: XYZ mask OR VQ mask
+        merged_mask = xyz_original.xyz_mask | vq_original.ids_mask
+
+        # Get next context data
+        xyz_next_context: XYZQuantInterframeCodecContext = next_context.contexts[0]
+        vq_next_context: VQInterframeCodecContext = next_context.contexts[1]
+
+        # Create XYZ payload with merged mask
+        xyz_payload = XYZQuantInterframePayload(
+            xyz_mask=merged_mask,
+            quantized_xyz=xyz_next_context.quantized_xyz[merged_mask],
+        )
+
+        # Create VQ payload with merged mask
+        changed_ids_dict = {}
+        for key, next_ids in vq_next_context.ids_dict.items():
+            changed_ids_dict[key] = next_ids[merged_mask]
+
+        vq_payload = VQMergeMaskInterframePayload(
+            ids_mask=merged_mask,
+            ids_dict=changed_ids_dict,
+        )
+
+        return CombinedPayload(payloads=[xyz_payload, vq_payload])

gsvvcompressor/combinations/vq_xyz_1mask_zstd.py

@@ -0,0 +1,103 @@
+"""
+VQ + XYZ quantization with single merged mask + Zstd compression encoder/decoder combination.
+
+This module provides a combined codec where VQ and XYZ share a single merged mask
+for interframe encoding, improving compression efficiency.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from ..compress.zstd import ZstdSerializer, ZstdDeserializer
+from ..interframe.combine import CombinedInterframeEncoderInitConfig
+from ..interframe.encoder import InterframeEncoder
+from ..interframe.decoder import InterframeDecoder
+from ..vq.interface import VQInterframeCodecConfig
+from ..xyz.interface import XYZQuantInterframeCodecConfig
+from .registry import register_encoder, register_decoder
+from .vq_xyz_1mask import VQXYZQuantMergeMaskInterframeCodecInterface
+
+
+def VQXYZ1MaskZstdEncoder(
+    vq_config: VQInterframeCodecConfig,
+    xyz_config: XYZQuantInterframeCodecConfig,
+    zstd_level: int = 7,
+    payload_device: Optional[str] = None,
+) -> InterframeEncoder:
+    """Create an encoder combining VQ + XYZ quantization with merged mask + Zstd compression."""
+    combined_interface = VQXYZQuantMergeMaskInterframeCodecInterface()
+    combined_config = CombinedInterframeEncoderInitConfig(
+        init_configs=[xyz_config, vq_config]
+    )
+    serializer = ZstdSerializer(level=zstd_level)
+    return InterframeEncoder(
+        serializer=serializer,
+        interface=combined_interface,
+        init_config=combined_config,
+        payload_device=payload_device,
+    )
+
+
+def VQXYZ1MaskZstdDecoder(
+    payload_device: Optional[str] = None,
+    device: Optional[str] = None,
+) -> InterframeDecoder:
+    """Create a decoder for VQ + XYZ quantization with merged mask + Zstd compressed data."""
+    combined_interface = VQXYZQuantMergeMaskInterframeCodecInterface()
+    deserializer = ZstdDeserializer()
+    return InterframeDecoder(
+        deserializer=deserializer,
+        interface=combined_interface,
+        payload_device=payload_device,
+        device=device,
+    )
+
+
+@dataclass
+class VQXYZ1MaskZstdEncoderConfig:
+    """Configuration for VQ + XYZ (merged mask) + Zstd encoder."""
+    vq: VQInterframeCodecConfig = field(default_factory=VQInterframeCodecConfig)
+    xyz: XYZQuantInterframeCodecConfig = field(default_factory=XYZQuantInterframeCodecConfig)
+    zstd_level: int = 7
+    payload_device: Optional[str] = None
+
+
+@dataclass
+class VQXYZ1MaskZstdDecoderConfig:
+    """Configuration for VQ + XYZ (merged mask) + Zstd decoder."""
+    payload_device: Optional[str] = None
+    device: Optional[str] = None
+
+
+def build_vqxyz1maskzstd_encoder(config: VQXYZ1MaskZstdEncoderConfig) -> InterframeEncoder:
+    """Build encoder from configuration."""
+    return VQXYZ1MaskZstdEncoder(
+        vq_config=config.vq,
+        xyz_config=config.xyz,
+        zstd_level=config.zstd_level,
+        payload_device=config.payload_device,
+    )
+
+
+def build_vqxyz1maskzstd_decoder(config: VQXYZ1MaskZstdDecoderConfig) -> InterframeDecoder:
+    """Build decoder from configuration."""
+    return VQXYZ1MaskZstdDecoder(
+        payload_device=config.payload_device,
+        device=config.device,
+    )
+
+
+# Register
+register_encoder(
+    "vqxyz1maskzstd",
+    build_vqxyz1maskzstd_encoder,
+    VQXYZ1MaskZstdEncoderConfig,
+    "VQ + XYZ quantization (merged mask) + Zstd compression",
+)
+
+register_decoder(
+    "vqxyz1maskzstd",
+    build_vqxyz1maskzstd_decoder,
+    VQXYZ1MaskZstdDecoderConfig,
+    "VQ + XYZ quantization (merged mask) + Zstd decompression",
+)