DOI: 10.5281/zenodo.18763683
title: Visual Acoustics Open Dataset: Cross-modal correspondence metrics with human perceptual validation

description: This repository contains a complete computational pipeline for the analysis of iris images, developed as part of the Argira Station research project (Visual Acoustics). The pipeline integrates:

- **Image preprocessing** (CLAHE enhancement, Gaussian blur)- **Automatic pupil/iris detection** using Hough circle transforms and adaptive refinement- **Radial and angular profile extraction** to capture intensity variations- **Angular FFT analysis** to identify dominant periodicities (crypts, furrows, pigment patterns)- **Golden ratio (φ) comparison** of the iris/pupil radius ratio- **Fractal dimension estimation** via box‑counting on edge‑detected structures- **Sonification** of the angular profile using additive synthesis (φ‑scaled frequencies)- **Validation** with synthetic iris images containing ground‑truth parameters

The work extends the Visual Acoustics open research platform ([DOI: 10.5281/zenodo.18734732](https://doi.org/10.5281/zenodo.18734732)) with applications in ophthalmology, biometrics, and generative art.

---

## 📁 Files included

| File | Description ||------|-------------|| `iris_analysis.py` | Main pipeline for real iris images: detection, profile extraction, FFT, fractal dimension, sonification, and figure generation. || `iris_synthetic_v2.py` | Synthetic iris generator with controlled ground‑truth parameters (pupil/iris radii, angular peaks). Used for validation and robustness testing. || `iris_analysis_real.png` | Summary figure of the analysis on a sample real iris. || `iris_synthetic.png` | Example of a synthetic iris image generated by `iris_synthetic_v2.py`. || `iris_validation.png` | Validation figure comparing detection vs ground‑truth under different noise levels. || `iris_sound.wav` | Audio sonification of the analysed iris (generated by the pipeline). || `README.md` | This file. |

Usage

1. Analysing a real iris image

Step 1: Prepare your image

Place a frontal iris image (e.g., my_iris.jpg) in the working directory. Good quality images with visible iris texture work best.

Step 2: Edit the script

Open iris_analysis.py and modify the IMG_PATH variable (line ~30) to point to your image:

python

IMG_PATH = '/path/to/your/iris.jpg'

## 🚀 Usage

### 1. Analysing a real iris image

#### Step 1: Prepare your image

Place a frontal iris image (e.g., `my_iris.jpg`) in the working directory. Good quality images with visible iris texture work best.

#### Step 2: Edit the script

Open `iris_analysis.py` and modify the `IMG_PATH` variable (line ~30) to point to your image:

```python

IMG_PATH = '/path/to/your/iris.jpg'

```

Optionally adjust parameters:

· max_dim (line 34): resize image for faster processing (default 900px)

· duration (line 420): length of sonification in seconds (default 8.0)

· n_angles (line 146): angular resolution (default 360)

Step 3: Run the analysis

```bash

python iris_analysis.py

```

Step 4: Outputs

The script generates:

· Terminal output: detection results, metrics, fractal dimensions, FFT peaks

· iris_analysis.png: summary figure with 7 panels (detection, edges, radial/angular profiles, FFT, sonification waveform, polar map)

· iris_sound.wav: 8‑second audio sonification

---

2. Generating and validating with synthetic irises

Run the synthetic pipeline

```bash

python iris_synthetic_v2.py

```

This script:

· Generates a synthetic iris with known parameters:

  · Pupil/iris radii (φ‑based ratio)

  · Embedded angular frequencies (e.g., peaks at k = 5, 8, 13)

  · Adjustable noise levels (σ = 2, 8, 20, 40)

· Runs the detection algorithm on each noisy version

· Compares detected vs ground‑truth values

· Produces iris_validation.png (8‑panel figure showing detection under noise)

 

Customising the synthetic iris

Inside iris_synthetic_v2.py, you can modify:

· size (default 600): image dimensions

· fib_peaks (default [5,8,13]): angular frequencies to embed

· noise_std (default 8.0): baseline noise level

· noise_levels (line 280): list of σ for robustness tests

 

---

3. Understanding the sonification

The sonification maps angular FFT peaks to audible frequencies using:

```

freq_hz = 220 * φ^(k/6)

```

where k is the angular frequency (cycles per revolution) and φ ≈ 1.618.

This creates a harmonic series where each partial is scaled by the golden ratio.

The amplitude of each partial is modulated by the angular profile intensity, and a slow envelope fades in/out to avoid clicks.

 

4. Using the interactive web interface

 

Open index.html in any modern browser to explore the sonification process in real time. The interface allows you to:

· Upload images and see their visual metrics extracted instantly.

· Listen to the generated sonification.

· Rate the result (1–5 stars) to contribute anonymous data to the public dataset.

· View the collected dataset and download it as JSON.

 

No image is ever uploaded to any server — all processing happens locally in your browser.

 

---

📊 Expected outputs (iris analysis)

 

For a real iris (example from iris_analysis_real.png)

Metric Value Interpretation

Pupil radius 255 px –

Iris radius 908 px –

Iris/pupil ratio 0.281 Compared to φ⁻¹ ≈ 0.618 (deviation 54%)

Pigment coverage 48.1% Sectorial amber/brown heterochromia

Fractal dimension (edges) 1.2705 Moderate complexity, organised tissue

Fractal dimension (pigment) 1.7790 Close to DLA dimension (~1.8), suggesting fractal aggregation

Angular FFT peaks k = 5, 8, 13, … Fibonacci‑related periodicities

 

For synthetic validation

The pipeline should recover embedded frequencies with high accuracy at low noise (σ ≤ 8), and maintain acceptable performance up to σ = 20.

---

📝 Citation

 

If you use this work, please cite:

Ranero García, J. (2026). Visual Acoustics Open Dataset: Cross-modal correspondence metrics with human perceptual validation (Version v4). Zenodo. https://doi.org/10.5281/zenodo.18763683

For the foundational work on phyllotaxis:

Ranero García, J. (2026). Computational Verification of Vogel's Model in Phyllotaxis Patterns. Zenodo. DOI: 10.5281/zenodo.18714818

---

🔗 Related projects

· K‑nacci Solar Layouts v7 – Optimisation of solar panel arrangements using phyllotaxis and discrepancy theory.

· Visual Acoustics (previous version) – Earlier release of the platform.

---

📜 License

This work is licensed under a Creative Commons Attribution 4.0 International License (CC BY 4.0).

You are free to share and adapt the material for any purpose, even commercially, as long as you give appropriate credit.

--

📬 Contact

Jose Ranero García – Independent Researcher

🌌 Argira Station

📡 YouTube Channel ☄️🔭📡

Last updated: February 2026