tx2_iff/
lib.rs

1//! # TX2-IFF: Involuted Fractal Format
2//!
3//! A next-generation image codec based on Physics-Prime Factorization (PPF),
4//! 360-prime quantization, and symplectic warping fields.
5//!
6//! ## Three-Layer Architecture
7//!
8//! ### Layer 1: Skeleton (Structural Geometry)
9//! - **Method**: Integer Wavelet Transform (CDF 5/3)
10//! - **Storage**: Low-frequency bands + high-magnitude high-frequency coefficients
11//! - **Quantization**: 360-prime pattern table
12//! - **Purpose**: Sharp edges, shapes, text
13//!
14//! ### Layer 2: Flesh (Deterministic Texture Synthesis)
15//! - **Method**: PPF-based deterministic noise generation
16//! - **Storage**: Region descriptors `{x, y, w, h, seed, chaos, scale}`
17//! - **Correction**: Sparse residual (real - synthesized)
18//! - **Purpose**: High-entropy texture (skin, fabric, nature)
19//!
20//! ### Layer 3: Warping Field (Symplectic Spatial Advection)
21//! - **Method**: 4-fold radial basis + vortex primitives
22//! - **Storage**: Basis coefficients + sparse vortex list
23//! - **Purpose**: Self-similar regions with geometric deformation
24//!
25//! ## Mathematical Foundations
26//!
27//! The codec is built on several mathematical frameworks:
28//!
29//! - **Physics-Prime Factorization (PPF)**: -1 as the unique "Sign Prime"
30//! - **360 Prime Pattern**: 96 residue classes modulo 360 for optimal coverage
31//! - **IOT/RIOT Geometry**: Involuted Oblate Toroid with fractal warping function
32//! - **Symplectic Mechanics**: 4-fold radial symmetry for universal stability
33//! - **Fixed-Point Integer Math**: 16.16 representation for deterministic computation
34//!
35//! ## Example Usage
36//!
37//! ```rust,no_run
38//! use tx2_iff::{Encoder, Decoder, EncoderConfig, DecoderConfig};
39//!
40//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
41//! // Encode an image
42//! let image = image::open("input.png")?;
43//! let config = EncoderConfig::default();
44//! let encoder = Encoder::new(config);
45//! let iff_data = encoder.encode(&image)?;
46//!
47//! // Decode the image
48//! let decoder_config = DecoderConfig::default();
49//! let decoder = Decoder::new(decoder_config);
50//! let decoded = decoder.decode(&iff_data)?;
51//! # Ok(())
52//! # }
53//! ```
54
55pub mod error;
56pub mod fixed;
57pub mod prime;
58pub mod wavelet;
59pub mod noise;
60pub mod texture;
61pub mod warp;
62pub mod format;
63pub mod compression;
64pub mod color;
65
66#[cfg(feature = "encoder")]
67pub mod encoder;
68
69#[cfg(feature = "decoder")]
70pub mod decoder;
71
72#[cfg(feature = "gpu")]
73pub mod gpu;
74
75// Re-exports
76pub use error::{IffError, Result};
77pub use fixed::Fixed;
78pub use format::{IffImage, Layer};
79pub use texture::Region;
80pub use warp::Vortex;
81
82#[cfg(feature = "encoder")]
83pub use encoder::{Encoder, EncoderConfig};
84
85#[cfg(feature = "decoder")]
86pub use decoder::{Decoder, DecoderConfig};
87
88/// Library version
89pub const VERSION: &str = env!("CARGO_PKG_VERSION");
90
91/// PPF-IFF magic number: "PPFI" in ASCII
92pub const MAGIC: u32 = 0x50504649;
93
94/// Maximum supported image dimension
95pub const MAX_DIMENSION: u32 = 65536;
96
97/// Fixed-point fractional bits (16.16 format)
98pub const FIXED_FRAC_BITS: u32 = 16;
99
100/// Number of 360-prime residue classes
101pub const PRIME_RESIDUE_CLASSES: usize = 96;
102
103/// CDF 5/3 wavelet decomposition levels
104pub const WAVELET_LEVELS: usize = 5;
105
106/// 4-fold radial symmetry constant
107pub const RADIAL_SYMMETRY_ORDER: usize = 4;
108
109#[cfg(test)]
110mod tests {
111    use super::*;
112
113    #[test]
114    fn test_magic_number() {
115        assert_eq!(MAGIC, 0x50504649);
116        let bytes = MAGIC.to_be_bytes();
117        assert_eq!(&bytes, b"PPFI");
118    }
119
120    #[test]
121    fn test_fixed_point_bits() {
122        assert_eq!(FIXED_FRAC_BITS, 16);
123    }
124
125    #[test]
126    fn test_prime_residue_count() {
127        // φ(360) = φ(2³) × φ(3²) × φ(5) = 4 × 6 × 4 = 96
128        assert_eq!(PRIME_RESIDUE_CLASSES, 96);
129    }
130
131    #[test]
132    fn test_radial_symmetry() {
133        // n_r = 4 for universal stability
134        assert_eq!(RADIAL_SYMMETRY_ORDER, 4);
135    }
136}
tx2_iff/lib.rs

tx2_iff/
lib.rs
