fourier-image-similarity 0.1.0

A small, reusable toolkit for Fourier-domain image similarity and reference selection.

Fourier Image Similarity

fourier-image-similarity is a small Python toolkit for comparing images in the frequency domain. It is written as a reusable Fourier-feature pipeline rather than for any single application domain.

The package provides:

• grayscale image loading and resizing
• 2D FFT magnitude and phase extraction
• Fourier peak detection
• local peak statistics such as prominence and entropy
• representative reference-image selection
• similarity scoring against a reference set

It intentionally excludes segmentation, spatial descriptors, dimensionality reduction, and downstream classifiers.

Installation

pip install fourier-image-similarity

For local development:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

CLI Usage

Use a fixed reference directory:

fourier-image-similarity \
  --query-dir /path/to/query_images \
  --reference-dir /path/to/reference_images \
  --num-references 10

Select references automatically from a larger pool:

fourier-image-similarity \
  --query-dir /path/to/query_images \
  --reference-candidate-dir /path/to/reference_pool \
  --num-references 10

The repository also includes a local wrapper:

python demo.py --help

Python Usage

from fourier_image_similarity.pipeline import run_similarity_analysis

rows, references = run_similarity_analysis(
    query_dir="/path/to/query_images",
    reference_dir="/path/to/reference_images",
    num_references=10,
)

for row in rows[:5]:
    print(row["file"], row["similarity_score"])

How It Works

Each image is converted into a compact frequency-domain description built from:

• FFT magnitude
• FFT phase
• prominent Fourier peaks
• local peak prominence
• local peak entropy
• local phase entropy

The final similarity score aggregates:

• peak match ratio
• peak mismatch ratio
• average nearest-peak distance
• mean prominence difference
• mean peak-entropy difference
• mean phase-entropy difference

Scores are normalized to [0, 1], where larger values indicate stronger agreement with the reference set.

Reference Selection

When more references are available than requested, the toolkit selects the most representative images using a frequency-only heuristic based on peak-pattern centrality.

Repository Layout

• src/fourier_image_similarity/io.py: image discovery and preprocessing
• src/fourier_image_similarity/fourier.py: FFT magnitude and phase extraction
• src/fourier_image_similarity/peaks.py: peak detection
• src/fourier_image_similarity/features.py: local peak statistics
• src/fourier_image_similarity/reference.py: reference selection
• src/fourier_image_similarity/scoring.py: similarity scoring
• src/fourier_image_similarity/pipeline.py: high-level workflow
• src/fourier_image_similarity/cli.py: command-line entry point

Citation

If this package is useful in research, please cite the paper that motivated the extracted Fourier-domain workflow:

@article{SMITH2026100643,
  title = {Mobile phone image-based framework for anti-copy pattern detection and classification},
  journal = {Array},
  volume = {29},
  pages = {100643},
  year = {2026},
  issn = {2590-0056},
  doi = {https://doi.org/10.1016/j.array.2025.100643},
  author = {Joseph Smith and Zheming Zuo and Jonathan Stonehouse and Boguslaw Obara}
}

PyPI Readiness

This repository is already close to PyPI-ready:

• it uses a src/ layout
• it has a pyproject.toml
• it exposes a console entry point

The remaining publication work is mostly packaging polish:

• choose the final repository URL and replace the placeholders in pyproject.toml
• confirm the license you want to publish under
• build with python -m build
• upload with twine upload dist/*