hqitc 0.1.1

Hybrid Quantum-Inspired Transform Codec - A novel image compression algorithm combining quantum-inspired encoding, attention mechanisms, and adaptive DCT transforms

HQITC - Hybrid Quantum-Inspired Transform Codec

A novel image compression algorithm that combines quantum-inspired encoding, attention mechanisms, and adaptive DCT transforms to achieve high-quality image compression with intelligent coefficient selection.

Features

Core Capabilities

• Quantum-Inspired Encoding: Novel quantum state simulation for enhanced patch representation
• Multi-Head Attention: Intelligent patch importance ranking based on content analysis
• Adaptive DCT Transform: Quality-driven coefficient selection and quantization
• Multi-Scale Processing: Hierarchical attention across different patch scales (4x4, 8x8, 16x16)
• Color Image Support: RGB to YUV conversion with channel-specific compression ratios
• Perceptual Optimization: Human visual system-aware quality metrics

Advanced Features

• Entropy-based bit rate estimation
• Adaptive quantization based on patch importance
• Multi-scale attention fusion for complex textures
• Channel-specific quality control for color images
• Comprehensive test suite with 65+ passing tests

Installation

Prerequisites

• Python 3.9 or higher
• NumPy 1.21.0+
• SciPy 1.7.0+

Install from Source

pip install hqitc

Development Installation

git clone https://github.com/your-username/hqitc.git
cd hqitc
pip install -e ".[dev]"

Quick Start

Basic Usage

import numpy as np
from hqitc import HQITCCompressor

# Create compressor instance
compressor = HQITCCompressor(
    patch_size=8,           # Patch size (4, 8, or 16)
    quality_factor=0.7,     # Compression quality (0.0-1.0)
    use_quantum=False,      # Enable quantum encoding
    use_multiscale=True,    # Enable multi-scale attention
    color_mode='auto'       # Color processing mode
)

# Load your image (grayscale or RGB)
image = np.random.rand(128, 128) * 255  # Example grayscale image
# image = np.random.rand(128, 128, 3) * 255  # Example RGB image

# Compress the image
compressed = compressor.compress(image, quality_factor=0.7, verbose=True)

# Decompress the image
reconstructed = compressor.decompress(compressed, verbose=True)

# Calculate quality metrics
mse = np.mean((image - reconstructed) ** 2)
psnr = 10 * np.log10((255.0 ** 2) / (mse + 1e-12))
print(f"PSNR: {psnr:.2f} dB")
print(f"Compression Ratio: {compressed['compression_ratio']:.2f}:1")

Color Image Processing

# Color image compression with channel-specific settings
color_compressor = HQITCCompressor(
    color_mode='auto',      # Automatically detect color images
    use_multiscale=True,    # Better for complex color textures
    multiscale_sizes=[4, 8, 16]
)

# Compress RGB image
rgb_image = np.random.rand(256, 256, 3) * 255
compressed = color_compressor.compress(rgb_image, quality_factor=0.8)

# The compressor automatically:
# - Converts RGB to YUV color space
# - Applies different compression ratios to Y/U/V channels
# - Preserves perceptual quality with reduced chrominance data

reconstructed = color_compressor.decompress(compressed)

Multi-Scale Attention

# Enhanced compression for images with multiple texture scales
multiscale_compressor = HQITCCompressor(
    use_multiscale=True,
    multiscale_sizes=[4, 8, 16],  # Process at multiple scales
    patch_size=8                   # Base patch size
)

# The multi-scale approach:
# - Extracts patches at different scales (4x4, 8x8, 16x16)
# - Applies hierarchical attention across scales
# - Fuses information for optimal coefficient selection
# - Particularly effective for natural images with varied textures

compressed = multiscale_compressor.compress(image, quality_factor=0.75)

Algorithm Overview

Core Components

1. Patch Extraction: Images are divided into overlapping patches
2. Quantum-Inspired Encoding (optional): Patches undergo quantum state simulation
3. Attention Mechanism: Multi-head attention computes patch importance scores
4. DCT Transform: Patches are transformed to frequency domain
5. Adaptive Selection: Coefficients are selected based on importance and quality settings
6. Quantization: Selected coefficients are quantized with adaptive step sizes
7. Entropy Estimation: Bit rate estimation for compression ratio calculation

Multi-Scale Processing Flow

Input Image
     ↓
Multi-Scale Patch Extraction (4x4, 8x8, 16x16)
     ↓
Hierarchical Attention (cross-scale context)
     ↓
Scale Fusion (weighted combination)
     ↓
Adaptive Coefficient Selection
     ↓
Quantization & Encoding

Color Processing Pipeline

RGB Image
     ↓
RGB → YUV Conversion
     ↓
Channel-Specific Compression:
  - Y channel: Higher quality (full resolution)
  - U channel: Reduced quality (human vision optimized)
  - V channel: Reduced quality (human vision optimized)
     ↓
YUV → RGB Reconstruction

Performance Metrics

Typical performance on natural images:

Configuration	PSNR Range	Compression Ratio	Use Case
Basic (8x8)	22-35 dB	10-25:1	General purpose
Multi-scale	25-40 dB	8-20:1	Complex textures
Color + Multi-scale	20-45 dB	5-15:1	High-quality color
High Quality (q=0.9)	35-168 dB	3-8:1	Near-lossless

API Reference

HQITCCompressor

Main compression class with configurable parameters.

Constructor Parameters

HQITCCompressor(
    patch_size: int = 8,              # Patch dimensions (4, 8, 16)
    quantum_dim: int = 32,            # Quantum encoding dimension
    num_heads: int = 8,               # Attention heads
    embed_dim: int = 64,              # Embedding dimension
    use_quantum: bool = False,        # Enable quantum encoding
    use_multiscale: bool = False,     # Enable multi-scale processing
    multiscale_sizes: List[int] = None, # Scale sizes for multi-scale
    color_mode: str = 'auto',         # 'auto', 'color', 'grayscale'
    seed: int = 42                    # Random seed for reproducibility
)

Methods

compress(image, quality_factor=0.5, keep_ratio=0.3, verbose=True)

Compresses an input image.

Parameters:

• image: Input image array (2D grayscale or 3D RGB)
• quality_factor: Compression quality (0.0-1.0, higher = better quality)
• keep_ratio: Base coefficient retention ratio (0.0-1.0)
• verbose: Enable compression progress output

Returns: Compressed data dictionary with compression statistics

decompress(compressed_data, verbose=True)

Reconstructs image from compressed data.

Parameters:

• compressed_data: Dictionary returned by compress()
• verbose: Enable decompression progress output

Returns: Reconstructed image array

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Code Style

This project uses:

• Black for code formatting
• isort for import sorting
• flake8 for linting
• mypy for type checking

Run formatting and linting:

black src/ tests/
isort src/ tests/
flake8 src/ tests/
mypy src/

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use this work in your research, please consider citing:

@software{hqitc2025,
  title={HQITC: Hybrid Quantum-Inspired Transform Codec},
  author={Khushiyant},
  year={2025},
  url={https://github.com/your-username/hqitc},
  note={A novel image compression algorithm combining quantum-inspired encoding and attention mechanisms}
}