StyleScope

Explainable visual-dataset auditing for artists, game developers, and ML researchers.

StyleScope turns a folder of images into an interactive audit. It uses multimodal embeddings to find near duplicates, detect visual outliers, discover clusters, map the dataset, search with natural language, and measure drift from user-selected style references.

Why this exists

Creative teams increasingly work with hundreds or thousands of concept images, textures, screenshots, references, and generated assets. Manual review is slow, duplicated files are easy to miss, and a few off-style images can quietly contaminate a training set or production library.

StyleScope makes those problems visible without requiring labeled classes.

Features

• Exact duplicates using SHA-256 hashes.
• Near duplicates using normalized SigLIP2 embeddings and cosine similarity.
• Visual outliers using Isolation Forest or Local Outlier Factor.
• Automatic clusters using HDBSCAN, with a K-Means fallback.
• Interactive dataset map using UMAP and Plotly.
• Natural-language image search through the shared SigLIP2 image-text space.
• Style anchors that rank assets by deviation from intended visual references.
• Portable reports in JSON and HTML.
• Embedding cache keyed by model and image hash.
• Safe ZIP extraction and automated tests.

Demo workflow

1. Upload a folder of images or a ZIP archive.
2. Run the audit with the recommended SigLIP2 backend.
3. Inspect duplicate pairs and top anomalies.
4. Explore clusters in the interactive map.
5. Search for assets with a phrase such as dark hand-painted fantasy environment.
6. Upload a few approved images as style anchors and inspect the largest deviations.
7. Export a reproducible JSON or shareable HTML report.

Installation

Python 3.10+ is required.

git clone https://github.com/AnastasiA-Asm/StyleScope.git
cd StyleScope
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
pip install -e ".[dev]"

FAISS is optional. To add it, run pip install -e ".[faiss]". Without FAISS, StyleScope uses a NumPy exact-neighbor fallback, which is fine for small datasets.

Run the web app

python app.py

Open the local URL printed by Gradio. The first SigLIP2 analysis downloads the model weights. Later runs reuse the Hugging Face and StyleScope caches.

For an instant UI smoke test with no model download, select Fast demo (color only). It is intentionally non-semantic and is not the main ML method.

Command line

stylescope ./my-images --output ./audit-report

Useful options:

stylescope ./my-images \
  --threshold 0.94 \
  --contamination 0.08 \
  --anomaly-method isolation_forest \
  --min-cluster-size 5

Architecture

images / ZIP
    │
    ├── validation + metadata + SHA-256
    │
    ├── SigLIP2 image embeddings ── embedding cache
    │              │
    │              ├── cosine / FAISS ── near duplicates
    │              ├── Isolation Forest / LOF ── anomaly scores
    │              ├── HDBSCAN ── visual clusters
    │              └── UMAP ── 2D interactive map
    │
    ├── SigLIP2 text embeddings ── natural-language search
    ├── style-anchor centroid ── style deviation ranking
    └── JSON + HTML reports

Repository structure

StyleScope/
├── app.py
├── src/stylescope/
│   ├── analysis.py
│   ├── embeddings.py
│   ├── image_io.py
│   ├── models.py
│   ├── pipeline.py
│   ├── report.py
│   └── visualization.py
├── benchmark/
├── tests/
├── .github/workflows/ci.yml
├── requirements.txt
├── pyproject.toml
└── LICENSE

Evaluation

The repository includes a deterministic synthetic benchmark generator. It creates a visually coherent set, obvious outliers, recompressed/brightness-adjusted near duplicates, and an exact duplicate.

python benchmark/generate_synthetic.py
python benchmark/run_benchmark.py benchmark/data

Do not publish invented metrics. Run the benchmark on SigLIP2 and record the actual results in a release or experiment table. A stronger follow-up benchmark should use licensed real game-art or texture datasets and human judgments.

Suggested experiment matrix:

Embedding	Neighbor method	Anomaly method	Duplicate precision	Duplicate recall	Outlier P@10	Runtime
Color histogram	NumPy	Isolation Forest	TBD	TBD	TBD	TBD
SigLIP2	NumPy	Isolation Forest	TBD	TBD	TBD	TBD
SigLIP2	FAISS	LOF	TBD	TBD	TBD	TBD

Important interpretation notes

• The style consistency score is a transparent product heuristic, not a validated scientific metric.
• UMAP coordinates are for exploration; distances in 2D do not perfectly preserve the original embedding space.
• An anomaly is not automatically a bad asset. It is an item worth reviewing.
• Similarity thresholds depend on the dataset and should be calibrated with labeled examples.
• Model embeddings may reflect biases in pretraining data.

Roadmap

• Thumbnail previews directly inside the dataset map.
• Per-cluster automatic text labels.
• CLIP versus SigLIP2 model comparison.
• Perceptual-hash baseline and duplicate explanation views.
• Human review queue with approve/reject feedback.
• Persistent projects and incremental indexing.
• Hugging Face Spaces deployment.
• Dataset cards and model cards for reproducible audits.

Resume description

StyleScope — Open-Source Visual Dataset Auditor: Developed a multimodal ML tool for detecting near-duplicate images, visual anomalies, style drift, and dataset clusters using SigLIP2 embeddings, FAISS, UMAP, and unsupervised anomaly detection. Built an interactive Gradio interface, reproducible benchmark, exportable reports, automated tests, and CI.

License

MIT. See LICENSE.