tx2-iff 0.1.0

PPF-IFF (Involuted Fractal Format) - Image codec using Physics-Prime Factorization, 360-prime quantization, and symplectic warping
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

//! # TX2-IFF: Involuted Fractal Format
//!
//! A next-generation image codec based on Physics-Prime Factorization (PPF),
//! 360-prime quantization, and symplectic warping fields.
//!
//! ## Three-Layer Architecture
//!
//! ### Layer 1: Skeleton (Structural Geometry)
//! - **Method**: Integer Wavelet Transform (CDF 5/3)
//! - **Storage**: Low-frequency bands + high-magnitude high-frequency coefficients
//! - **Quantization**: 360-prime pattern table
//! - **Purpose**: Sharp edges, shapes, text
//!
//! ### Layer 2: Flesh (Deterministic Texture Synthesis)
//! - **Method**: PPF-based deterministic noise generation
//! - **Storage**: Region descriptors `{x, y, w, h, seed, chaos, scale}`
//! - **Correction**: Sparse residual (real - synthesized)
//! - **Purpose**: High-entropy texture (skin, fabric, nature)
//!
//! ### Layer 3: Warping Field (Symplectic Spatial Advection)
//! - **Method**: 4-fold radial basis + vortex primitives
//! - **Storage**: Basis coefficients + sparse vortex list
//! - **Purpose**: Self-similar regions with geometric deformation
//!
//! ## Mathematical Foundations
//!
//! The codec is built on several mathematical frameworks:
//!
//! - **Physics-Prime Factorization (PPF)**: -1 as the unique "Sign Prime"
//! - **360 Prime Pattern**: 96 residue classes modulo 360 for optimal coverage
//! - **IOT/RIOT Geometry**: Involuted Oblate Toroid with fractal warping function
//! - **Symplectic Mechanics**: 4-fold radial symmetry for universal stability
//! - **Fixed-Point Integer Math**: 16.16 representation for deterministic computation
//!
//! ## Example Usage
//!
//! ```rust,no_run
//! use tx2_iff::{Encoder, Decoder, EncoderConfig, DecoderConfig};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Encode an image
//! let image = image::open("input.png")?;
//! let config = EncoderConfig::default();
//! let encoder = Encoder::new(config);
//! let iff_data = encoder.encode(&image)?;
//!
//! // Decode the image
//! let decoder_config = DecoderConfig::default();
//! let decoder = Decoder::new(decoder_config);
//! let decoded = decoder.decode(&iff_data)?;
//! # Ok(())
//! # }
//! ```

pub mod error;
pub mod fixed;
pub mod prime;
pub mod wavelet;
pub mod noise;
pub mod texture;
pub mod warp;
pub mod format;
pub mod compression;
pub mod color;

#[cfg(feature = "encoder")]
pub mod encoder;

#[cfg(feature = "decoder")]
pub mod decoder;

#[cfg(feature = "gpu")]
pub mod gpu;

// Re-exports
pub use error::{IffError, Result};
pub use fixed::Fixed;
pub use format::{IffImage, Layer};
pub use texture::Region;
pub use warp::Vortex;

#[cfg(feature = "encoder")]
pub use encoder::{Encoder, EncoderConfig};

#[cfg(feature = "decoder")]
pub use decoder::{Decoder, DecoderConfig};

/// Library version
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// PPF-IFF magic number: "PPFI" in ASCII
pub const MAGIC: u32 = 0x50504649;

/// Maximum supported image dimension
pub const MAX_DIMENSION: u32 = 65536;

/// Fixed-point fractional bits (16.16 format)
pub const FIXED_FRAC_BITS: u32 = 16;

/// Number of 360-prime residue classes
pub const PRIME_RESIDUE_CLASSES: usize = 96;

/// CDF 5/3 wavelet decomposition levels
pub const WAVELET_LEVELS: usize = 5;

/// 4-fold radial symmetry constant
pub const RADIAL_SYMMETRY_ORDER: usize = 4;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_magic_number() {
        assert_eq!(MAGIC, 0x50504649);
        let bytes = MAGIC.to_be_bytes();
        assert_eq!(&bytes, b"PPFI");
    }

    #[test]
    fn test_fixed_point_bits() {
        assert_eq!(FIXED_FRAC_BITS, 16);
    }

    #[test]
    fn test_prime_residue_count() {
        // φ(360) = φ(2³) × φ(3²) × φ(5) = 4 × 6 × 4 = 96
        assert_eq!(PRIME_RESIDUE_CLASSES, 96);
    }

    #[test]
    fn test_radial_symmetry() {
        // n_r = 4 for universal stability
        assert_eq!(RADIAL_SYMMETRY_ORDER, 4);
    }
}