Metadata-Version: 2.4
Name: fourier-image-similarity
Version: 0.1.0
Summary: A small, reusable toolkit for Fourier-domain image similarity and reference selection.
Author: Joseph Smith
License-Expression: MIT
Project-URL: Homepage, https://github.com/Smithy305/fourier-image-similarity
Project-URL: Repository, https://github.com/Smithy305/fourier-image-similarity
Project-URL: Issues, https://github.com/Smithy305/fourier-image-similarity/issues
Keywords: fourier transform,fft,image similarity,computer vision,frequency domain
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: Pillow
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install fourier-image-similarity
```

For local development:

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

## CLI Usage

Use a fixed reference directory:

```bash
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:

```bash
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:

```bash
python demo.py --help
```

## Python Usage

```python
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:

```bibtex
@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/*`
