Skip to content

todmount/wicca

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

96 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

WICCA: Wavelet-based Image Compression and Classification Analysis

Python 3.12+ License Code style: black

Overview

WICCA is a research-driven framework for investigating how wavelet-based image compression and scaling affect the classification performance of pretrained models. WICCA leverages Discrete Wavelet Transform (DWT) to generate compressed icons — small representations of images extracted from wavelet decomposition. At the moment, Haar wavelet compression is implemented as the initial method, with extensions to other wavelets planned.

Project Goals

Global Goal

  • Systematically evaluate how different wavelet compression techniques influence classification across a variety of pretrained models.

Current Goals

  • Analyze how Haar wavelet compression affects classification performance.
  • Compare classification results between original high-resolution images and their compressed counterparts.

How It Works

  • Dataset preparation: Large-scale, high-resolution images (≥2K) are sourced.
  • Wavelet compression: Haar decomposition is applied to extract representative icons.
  • Model inference: Pre-trained CNN classifiers are used to evaluate both original and compressed images.
  • Prediction analysis: Performance is compared using top-1 accuracy match, top-5 class intersection, and prediction similarity.
  • Results storage: Outcomes are structured in Pandas DataFrames and exported as .csv.

Core Functionality

✅ Supports high-resolution image datasets.
✅ Supports multiple CNN architectures.
✅ Uses pre-trained models: no model training required.
✅ Enables structured analysis, comparing classification results between original images and their wavelet-compressed counterparts.
✅ Developed to use in Jupyter Notebook, but can be used as a CLI tool.
✅ Implemented in a way that it's manageable to add a new wavelet.

Installation

Requirements
  • Python 3.12+
  1. Clone the repository

    git clone https://github.com/your-username/WICCA.git
    cd WICCA
  2. Set up a virtual environment

    python3 -m venv .venv
    source .venv/bin/activate # On Windows: venv\Scripts\activate
  3. Install dependencies

    pip install -r requirements.txt

Usage

Please refer to the demonstration notebook to see all available functionality.

Basic usage is as follows:

Imports:
import os

import cv2
import pandas as pd
import matplotlib.pyplot as plt
import tensorflow.keras.applications as apps
from pathlib import Path

import wicca.visualization as viz
import wicca.result_manager as rmgr
from wicca.data_loader import load_image, load_models
from wicca.wavelet_coder import HaarCoder
from wicca.classifying_tools import ClassifierProcessor
from wicca.config.constants import SIM_CLASSES_PERC, SIM_BEST_CLASS, RESULTS_FOLDER
  1. Define the models' dictionary in the format as in the example and load it:

    models_dict = {
       # Mobile Networks (standard 224×224)
       'MobileNetV2': apps.mobilenet_v2.MobileNetV2,
       # NasNet family (custom shapes)
       'NASNetMobile': apps.nasnet.NASNetMobile,  # Uses 224×224
       'NASNetLarge': (apps.nasnet.NASNetLarge, {'shape': (331, 331)}),
    }
    classifiers = load_models(models_dict)
  2. Define the processor and call it:

    processor = ClassifierProcessor(
        data_folder='data/originals',  # Set directory containing images to process
        wavelet_coder=HaarCoder(),  # Set our wavelet
        transform_depth=range(1,6),  # Set the depth of transforming; accepts int | range | list
        top_classes=5,  # Set top classes for comparison
        interpolation=cv2.INTER_AREA,  # Set interpolation method
        results_folder='results',  # Set results folder
        log_info=True,  # Print input-related info; enabled by default
        batch_size=30 # Set size of image batch for classifier
    )
    processor.process_classifiers(classifiers, timeout=3600) # timeout for whole process, in seconds
    Output:
       **Image Processing Configuration**
       Note: For image statistics, a sample of 50 random images was taken.
       You may change the sample size [MAX_INFO_SAMPLE_SIZE] in the config.constants module.
       
       Data folder: data\originals
       Number of images: 130
       Mean image dimensions: 8284x6393 px
       Mean image resolution: 52.7 MP (52685873 pixels)
       Transform depth: (2, 3, 4, 5, 6)
       Interpolation: cv2.INTER_AREA
       Top classes: 5
       Results folder: C:\MyProjects\WICCA\results
    
       Processing depth 2:   100%|▮▮▮▮▮▮▮▮▮▮|[15:00]   
       Processing depth 3:   100%|▮▮▮▮▮▮▮▮▮▮|[17:00]   
       Processing depth 4:   100%|▮▮▮▮▮▮▮▮▮▮|[20:00]   
       Processing depth 5:   100%|▮▮▮▮▮▮▮▮▮▮|[23:00]   
       Processing depth 6:   100%|▮▮▮▮▮▮▮▮▮▮|[25:00]
    
       Total processing time: 1 hour 30 minutes

    Runtime depends heavily on dataset size, transform depth, and available hardware.

  3. See the results in table format:

    results['MobileNetV2'] # direct call to DataFrame will output results for all depth
    rmgr.load_summary_results(results_folder='results', depth = 5, classifier_name='EfficientNetB0') # load csv with specific depth
    Output:
    stat similar classes (count) similar classes (%) similar best class
    0 mean 4.24 84.92 83.84
    2 min 1.00 20.00 0.00
    3 max 5.00 100.00 100.00

    The output summarizes mean, min, and max similarity metrics across images

  4. You could visualize results using the built-in functionality:

    comparison = rmgr.compare_summaries(res_default, classifiers, 5, 'mean')
    names, similar_classes_pct = rmgr.extract_from_comparison(comparison, 'similar classes (%)')
    
    # similar classes
    viz.plot_metric_radar(
     names=names, 
     metric=similar_classes_pct,
     title='Best 5 Classes Similarity',
     min_value=75, max_value=95
    )
    Output: output_example.png
    comparison_data = rmgr.compare_summaries(res_default, classifiers, depth_range, "mean")
    viz.visualize_comparison(
        comparison_data=comparison_data,
        metric=SIM_CLASSES_PERC,
        title="Best 5 Classes Similarity Heatmap"
    )
    Output: output_heatmap.png

Results & Insights

  • Haar wavelet compression yields icons that preserve structural features, enabling effective classification.
  • While image size is significantly reduced, essential visual information remains intact.
  • Compression reduces computational cost but may slightly impact accuracy, depending on the classifier.
  • Classification accuracy shows model-dependent sensitivity to compression; architectures such as ResNet and NASNet maintain robustness.

Contributing

Though the project is on pause, contributions are welcome!
Feel free to open an issue or submit a pull request.

Contact

You could find relevant contact info on my GitHub profile.

About

This is a program for analysis of Wavelet Compressed Large-image Classification

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published