Compression & Serialization

CompressedImage

Sparse representation of an image in the frequency domain.

Fields

• indices::Vector{Int}: Linear indices of non-zero coefficients
• values_real::Vector{Float64}: Real parts of coefficient values
• values_imag::Vector{Float64}: Imaginary parts of coefficient values
• original_size::Tuple{Int,Int}: Original image dimensions (height, width)
• basis_hash::String: Hash of the basis used for compression (for verification)

Note

The compressed representation stores only the non-zero coefficients after truncation, achieving compression by discarding small coefficients.

CompressedImageJSON

Internal struct for JSON serialization of CompressedImage.

Base.show(io::IO, compressed::CompressedImage)

Pretty print the CompressedImage.

_reconstruct_frequency_domain(compressed::CompressedImage, size::Tuple{Int,Int})

Reconstruct full frequency domain matrix from sparse representation.

_select_top_coefficients(freq_domain::AbstractMatrix, k::Int)

Select top k coefficients by magnitude. Matches the magnitude-only topk_truncate used during training — no frequency weighting.

compress(basis::AbstractSparseBasis, image::AbstractMatrix; ratio::Float64=0.9)

Compress an image using the given sparse basis.

Arguments

• basis::AbstractSparseBasis: The trained basis to use for compression
• image::AbstractMatrix: Input image (must match basis dimensions)
• ratio::Float64 = 0.9: Compression ratio (0.9 means keep only 10% of coefficients)

Returns

• CompressedImage: Sparse representation of the image

Example

basis = load_basis("trained_basis.json")
image = load_grayscale_image("photo.png")
compressed = compress(basis, image; ratio=0.95)  # Keep top 5%
save_compressed("photo.cimg", compressed)

compress_with_k(basis::AbstractSparseBasis, image::AbstractMatrix; k::Int)

Compress an image keeping exactly k coefficients.

Arguments

• basis::AbstractSparseBasis: The trained basis to use
• image::AbstractMatrix: Input image
• k::Int: Exact number of coefficients to keep

Returns

• CompressedImage: Sparse representation

compression_stats(compressed::CompressedImage) -> NamedTuple

Get statistics about the compression.

Returns

A named tuple with:

• original_size: Original image dimensions
• total_coefficients: Total number of coefficients
• kept_coefficients: Number of non-zero coefficients kept
• compression_ratio: Ratio of discarded coefficients
• storage_reduction: Approximate storage reduction factor

load_compressed(path::String) -> CompressedImage

Load a compressed image from a JSON file.

Arguments

• path::String: Path to the compressed image file

Returns

• CompressedImage: The loaded compressed image

recover(basis::AbstractSparseBasis, compressed::CompressedImage; verify_hash::Bool=true)

Recover an image from its compressed representation.

Arguments

• basis::AbstractSparseBasis: The basis used for compression
• compressed::CompressedImage: The compressed image data
• verify_hash::Bool = true: Whether to verify basis hash matches

Returns

• Matrix{Float64}: Reconstructed image (real-valued)

Example

basis = load_basis("trained_basis.json")
compressed = load_compressed("photo.cimg")
recovered = recover(basis, compressed)

save_compressed(path::String, compressed::CompressedImage)

Save a compressed image to a JSON file.

Arguments

• path::String: File path to save to
• compressed::CompressedImage: The compressed image to save

Returns

• String: The path where the file was saved

BasisJSON

Internal struct for JSON serialization of QFTBasis.

EntangledBasisJSON

Internal struct for JSON serialization of EntangledQFTBasis.

MERABasisJSON

Internal struct for JSON serialization of MERABasis.

TEBDBasisJSON

Internal struct for JSON serialization of TEBDBasis.

_basis_to_json(basis::EntangledQFTBasis)

Convert an EntangledQFTBasis to JSON-serializable format.

_basis_to_json(basis::MERABasis)

Convert a MERABasis to JSON-serializable format.

_basis_to_json(basis::QFTBasis)

Convert a QFTBasis to JSON-serializable format.

_basis_to_json(basis::TEBDBasis)

Convert a TEBDBasis to JSON-serializable format.

_json_to_basis(json_data::BasisJSON)

Convert JSON data back to a QFTBasis object.

_json_to_entangled_basis(json_data::EntangledBasisJSON)

Convert JSON data back to an EntangledQFTBasis object.

_json_to_mera_basis(json_data::MERABasisJSON)

Convert JSON data back to a MERABasis object.

_json_to_tebd_basis(json_data::TEBDBasisJSON)

Convert JSON data back to a TEBDBasis object.

basis_to_dict(basis::EntangledQFTBasis) -> Dict

Convert an EntangledQFTBasis to a dictionary for custom serialization.

Returns

• Dict: Dictionary representation of the basis

basis_to_dict(basis::MERABasis) -> Dict

Convert a MERABasis to a dictionary for custom serialization.

Returns

• Dict: Dictionary representation of the basis

basis_to_dict(basis::AbstractSparseBasis) -> Dict

Convert a basis to a dictionary for custom serialization.

Returns

• Dict: Dictionary representation of the basis

basis_to_dict(basis::TEBDBasis) -> Dict

Convert a TEBDBasis to a dictionary for custom serialization.

Returns

• Dict: Dictionary representation of the basis

dict_to_basis(d::Dict) -> AbstractSparseBasis

Convert a dictionary back to a basis.

Arguments

• d::Dict: Dictionary with basis data

Returns

• AbstractSparseBasis: The reconstructed basis

load_basis(path::String) -> AbstractSparseBasis

Load a sparse basis from a JSON file.

Arguments

• path::String: Path to the JSON file

Returns

• AbstractSparseBasis: The loaded basis (concrete type depends on file contents)

Example

basis = load_basis("trained_basis.json")
freq = forward_transform(basis, image)

save_basis(path::String, basis::AbstractSparseBasis)

Save a sparse basis to a JSON file.

Arguments

• path::String: File path to save to (should end in .json)
• basis::AbstractSparseBasis: The basis to save

Example

basis = train_basis(QFTBasis, images; m=6, n=6)
save_basis("trained_basis.json", basis)