heatmatch 1.0.0__tar.gz

heatmatch-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xingyu Long
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

heatmatch-1.0.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: heatmatch
+Version: 1.0.0
+Summary: Orientation-aware visualization and comparison of very dense saccade patterns (scanpath comparison for long free viewing)
+Author: Xingyu Long
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xysLong/HeatMatch
+Project-URL: Paper, https://doi.org/10.1145/3803539
+Project-URL: Data, https://osf.io/f2xhj/
+Keywords: eye-tracking,saccades,scanpath,scanpath-comparison,gaze,heatmap,visualization,orientation-field,empirical-aesthetics,art-perception
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: Pillow
+Dynamic: license-file
+
+# HeatMatch
+
+**Visualize and compare very dense saccade patterns from long free-viewing eye-tracking data.**
+
+HeatMatch turns hundreds or thousands of saccades into continuous *orientation fields*: at every location it estimates saccade density, mean orientation, and how consistently the saccades agree in orientation. From these fields it draws orientation-coded heatmaps that show *where* gaze moves and *in which direction*. It also computes a similarity score for comparing saccade patterns across participants, stimuli, or conditions, without AOIs, scanpath alignment, or manual segmentation.
+
+It was developed for 60-second viewing of paintings (empirical aesthetics, art history) and works for any static stimulus. Python implementation accompanying the paper:
+
+<table border="0" cellspacing="0" cellpadding="0"><tr>
+<td width="72%" valign="top">
+
+<blockquote>
+Xingyu Long, Jozsef Arato, Sophia Kury, Anna Miscena, and Raphael Rosenberg. 2026.<br/>
+<strong>HeatMatch: Orientation-Aware Visualization and Comparison of Very Dense Saccade Patterns.</strong><br/>
+<em>Proceedings of the ACM on Computer Graphics and Interactive Techniques</em> (PACMCGIT), 9(2), Article 18.<br/>
+<a href="https://doi.org/10.1145/3803539">https://doi.org/10.1145/3803539</a>
+</blockquote>
+
+</td>
+<td width="28%" align="center" valign="middle">
+<img src="https://raw.githubusercontent.com/xysLong/HeatMatch/main/assets/logos.png" width="200" alt="CReA Lab and Vienna Cognitive Science Hub"/>
+</td>
+</tr></table>
+
+---
+
+## Overview
+
+1. **OOI-coded heatmaps** — orientation fields visualized with researcher-defined color anchors and confidence-weighted opacity.
+2. **HeatMatch similarity** — comparison based on saccade density and orientation.
+
+![HeatMatch heatmap example](https://raw.githubusercontent.com/xysLong/HeatMatch/main/assets/example_heatmaps.jpg)
+<sub>Per-participant (columns 1–5) and aggregated (column 6) heatmaps for three paintings. Hue = mean saccade orientation relative to OOI; opacity = local confidence. Stimulus images: public domain via [Wikimedia Commons](https://commons.wikimedia.org) — see paper for details.</sub>
+
+See the [paper](https://doi.org/10.1145/3803539) for methodology.
+
+### When to use it
+
+- **Long, dense viewing.** Scanpath comparison methods such as MultiMatch or ScanMatch align scanpaths sequence by sequence. With hundreds of saccades per trial and strongly diverging paths, they become slow and hard to interpret. HeatMatch aggregates instead of aligning, so it scales to arbitrarily dense data.
+- **Orientation matters.** Fixation heatmaps and density-based metrics ignore saccade direction. HeatMatch keeps orientation, so you can ask whether gaze follows horizontal, vertical, diagonal, or symmetric structure in an image, e.g. composition lines in a painting.
+- **Group, stimulus, and individual comparisons.** In the paper, the similarity score recovers the abstract vs. still-life distinction and differences in within-painting agreement. It also reveals stable individual "saccadic signatures" that hold across paintings.
+
+It is **not** a replacement for sequence-based methods. HeatMatch is permutation-invariant (it ignores saccade order) and treats orientations as unsigned (left-to-right = right-to-left). Use it alongside MultiMatch, ScanMatch, or RQA when order or direction matters.
+
+---
+
+## Installation
+
+```bash
+pip install heatmatch
+```
+
+Dependencies: `numpy`, `matplotlib`, `Pillow`. For development, clone the repository and run `pip install -e .`.
+
+---
+
+## Quick Start
+
+```python
+import matplotlib.pyplot as plt
+from heatmatch import make_reference_grid, make_orientation_field, Heatmap, compute_similarity
+
+W, H = 2880, 2160
+onset  = ...  # (J, 2) saccade start coordinates
+offset = ...  # (J, 2) saccade end coordinates
+
+pts, xx, yy = make_reference_grid(W, H, grid_resolution=200)
+field = make_orientation_field(pts, onset, offset, sigma=50.0, grid_shape=yy.shape)
+
+fig, ax = plt.subplots()
+Heatmap(field, W, H).draw(ax, ooi=0.0)  # ooi=0 → horizontal, ooi=90 → vertical
+plt.show()
+
+# Compare two patterns (fields built on the same grid, e.g. two participants)
+result = compute_similarity(field_a, field_b)
+s = (result.s_loc + result.s_dir) / 2  # composite HeatMatch score S in [0, 1]
+print(result.s_loc, result.s_dir, s)
+```
+
+A full worked example is in [`demo.ipynb`](https://github.com/xysLong/HeatMatch/blob/main/demo.ipynb). The dataset is not included — download `data_anonymized.csv` from **[osf.io/f2xhj](https://osf.io/f2xhj/)** and place it in `tests/`.
+
+---
+
+## API
+
+### `heatmatch.fields`
+
+| | |
+|---|---|
+| `make_reference_grid(w, h, grid_resolution)` | Returns `(pts, xx, yy)`; int → square grid, `(ny, nx)` tuple → rectangular |
+| `make_orientation_field(pts, onset, offset, sigma, grid_shape, ...)` | Returns `OrientationField` with `omega_mean`, `R`, `rho` |
+
+### `heatmatch.heatmapping`
+
+| | |
+|---|---|
+| `Heatmap(field, w, h, image=None)` | Caches colormap, opacity, and (optionally) grayscale background image |
+| `Heatmap.draw(ax, ooi, opacity_density_weight, base_opacity, cmap, ...)` | Renders onto `ax` |
+
+OOI in degrees: 0 = east, 90 = north, 180 = west, 270 = south. Unsigned, so `ooi` and `ooi ± 180` are equivalent.
+
+### `heatmatch.matching`
+
+| | |
+|---|---|
+| `compute_similarity(field_a, field_b, density_coherence_tradeoff)` | Returns `SimilarityResult(s_loc, s_dir)` |
+
+---
+
+## Key Parameters
+
+| Parameter | Default | Notes |
+|---|---|---|
+| `sigma` | `50.0` | Gaussian bandwidth in px. Paper evaluates {50, 100, 150}. |
+| `grid_resolution` | `200` | Int or `(ny, nx)`. Paper uses 200. |
+| `ooi` | `0.0` | Orientation of Interest in degrees. |
+| `opacity_density_weight` | `1.0` | Density vs. coherence for opacity. Recommended 0.5–1.0. |
+| `base_opacity` | `0.85` | Global opacity ceiling; useful with a background image. |
+| `density_coherence_tradeoff` | `0.5` | Density vs. coherence for *S*_dir. At 1.0, angular information is discarded. |
+
+---
+
+## Citation
+
+```bibtex
+@article{long2026heatmatch,
+  author    = {Long, Xingyu and Arato, Jozsef and Kury, Sophia and Miscena, Anna and Rosenberg, Raphael},
+  title     = {HeatMatch: Orientation-Aware Visualization and Comparison of Very Dense Saccade Patterns},
+  journal   = {Proc. ACM Comput. Graph. Interact. Tech.},
+  year      = {2026},
+  volume    = {9},
+  number    = {2},
+  articleno = {18},
+  doi       = {10.1145/3803539},
+}
+```

heatmatch-1.0.0/README.md

@@ -0,0 +1,136 @@
+# HeatMatch
+
+**Visualize and compare very dense saccade patterns from long free-viewing eye-tracking data.**
+
+HeatMatch turns hundreds or thousands of saccades into continuous *orientation fields*: at every location it estimates saccade density, mean orientation, and how consistently the saccades agree in orientation. From these fields it draws orientation-coded heatmaps that show *where* gaze moves and *in which direction*. It also computes a similarity score for comparing saccade patterns across participants, stimuli, or conditions, without AOIs, scanpath alignment, or manual segmentation.
+
+It was developed for 60-second viewing of paintings (empirical aesthetics, art history) and works for any static stimulus. Python implementation accompanying the paper:
+
+<table border="0" cellspacing="0" cellpadding="0"><tr>
+<td width="72%" valign="top">
+
+<blockquote>
+Xingyu Long, Jozsef Arato, Sophia Kury, Anna Miscena, and Raphael Rosenberg. 2026.<br/>
+<strong>HeatMatch: Orientation-Aware Visualization and Comparison of Very Dense Saccade Patterns.</strong><br/>
+<em>Proceedings of the ACM on Computer Graphics and Interactive Techniques</em> (PACMCGIT), 9(2), Article 18.<br/>
+<a href="https://doi.org/10.1145/3803539">https://doi.org/10.1145/3803539</a>
+</blockquote>
+
+</td>
+<td width="28%" align="center" valign="middle">
+<img src="https://raw.githubusercontent.com/xysLong/HeatMatch/main/assets/logos.png" width="200" alt="CReA Lab and Vienna Cognitive Science Hub"/>
+</td>
+</tr></table>
+
+---
+
+## Overview
+
+1. **OOI-coded heatmaps** — orientation fields visualized with researcher-defined color anchors and confidence-weighted opacity.
+2. **HeatMatch similarity** — comparison based on saccade density and orientation.
+
+![HeatMatch heatmap example](https://raw.githubusercontent.com/xysLong/HeatMatch/main/assets/example_heatmaps.jpg)
+<sub>Per-participant (columns 1–5) and aggregated (column 6) heatmaps for three paintings. Hue = mean saccade orientation relative to OOI; opacity = local confidence. Stimulus images: public domain via [Wikimedia Commons](https://commons.wikimedia.org) — see paper for details.</sub>
+
+See the [paper](https://doi.org/10.1145/3803539) for methodology.
+
+### When to use it
+
+- **Long, dense viewing.** Scanpath comparison methods such as MultiMatch or ScanMatch align scanpaths sequence by sequence. With hundreds of saccades per trial and strongly diverging paths, they become slow and hard to interpret. HeatMatch aggregates instead of aligning, so it scales to arbitrarily dense data.
+- **Orientation matters.** Fixation heatmaps and density-based metrics ignore saccade direction. HeatMatch keeps orientation, so you can ask whether gaze follows horizontal, vertical, diagonal, or symmetric structure in an image, e.g. composition lines in a painting.
+- **Group, stimulus, and individual comparisons.** In the paper, the similarity score recovers the abstract vs. still-life distinction and differences in within-painting agreement. It also reveals stable individual "saccadic signatures" that hold across paintings.
+
+It is **not** a replacement for sequence-based methods. HeatMatch is permutation-invariant (it ignores saccade order) and treats orientations as unsigned (left-to-right = right-to-left). Use it alongside MultiMatch, ScanMatch, or RQA when order or direction matters.
+
+---
+
+## Installation
+
+```bash
+pip install heatmatch
+```
+
+Dependencies: `numpy`, `matplotlib`, `Pillow`. For development, clone the repository and run `pip install -e .`.
+
+---
+
+## Quick Start
+
+```python
+import matplotlib.pyplot as plt
+from heatmatch import make_reference_grid, make_orientation_field, Heatmap, compute_similarity
+
+W, H = 2880, 2160
+onset  = ...  # (J, 2) saccade start coordinates
+offset = ...  # (J, 2) saccade end coordinates
+
+pts, xx, yy = make_reference_grid(W, H, grid_resolution=200)
+field = make_orientation_field(pts, onset, offset, sigma=50.0, grid_shape=yy.shape)
+
+fig, ax = plt.subplots()
+Heatmap(field, W, H).draw(ax, ooi=0.0)  # ooi=0 → horizontal, ooi=90 → vertical
+plt.show()
+
+# Compare two patterns (fields built on the same grid, e.g. two participants)
+result = compute_similarity(field_a, field_b)
+s = (result.s_loc + result.s_dir) / 2  # composite HeatMatch score S in [0, 1]
+print(result.s_loc, result.s_dir, s)
+```
+
+A full worked example is in [`demo.ipynb`](https://github.com/xysLong/HeatMatch/blob/main/demo.ipynb). The dataset is not included — download `data_anonymized.csv` from **[osf.io/f2xhj](https://osf.io/f2xhj/)** and place it in `tests/`.
+
+---
+
+## API
+
+### `heatmatch.fields`
+
+| | |
+|---|---|
+| `make_reference_grid(w, h, grid_resolution)` | Returns `(pts, xx, yy)`; int → square grid, `(ny, nx)` tuple → rectangular |
+| `make_orientation_field(pts, onset, offset, sigma, grid_shape, ...)` | Returns `OrientationField` with `omega_mean`, `R`, `rho` |
+
+### `heatmatch.heatmapping`
+
+| | |
+|---|---|
+| `Heatmap(field, w, h, image=None)` | Caches colormap, opacity, and (optionally) grayscale background image |
+| `Heatmap.draw(ax, ooi, opacity_density_weight, base_opacity, cmap, ...)` | Renders onto `ax` |
+
+OOI in degrees: 0 = east, 90 = north, 180 = west, 270 = south. Unsigned, so `ooi` and `ooi ± 180` are equivalent.
+
+### `heatmatch.matching`
+
+| | |
+|---|---|
+| `compute_similarity(field_a, field_b, density_coherence_tradeoff)` | Returns `SimilarityResult(s_loc, s_dir)` |
+
+---
+
+## Key Parameters
+
+| Parameter | Default | Notes |
+|---|---|---|
+| `sigma` | `50.0` | Gaussian bandwidth in px. Paper evaluates {50, 100, 150}. |
+| `grid_resolution` | `200` | Int or `(ny, nx)`. Paper uses 200. |
+| `ooi` | `0.0` | Orientation of Interest in degrees. |
+| `opacity_density_weight` | `1.0` | Density vs. coherence for opacity. Recommended 0.5–1.0. |
+| `base_opacity` | `0.85` | Global opacity ceiling; useful with a background image. |
+| `density_coherence_tradeoff` | `0.5` | Density vs. coherence for *S*_dir. At 1.0, angular information is discarded. |
+
+---
+
+## Citation
+
+```bibtex
+@article{long2026heatmatch,
+  author    = {Long, Xingyu and Arato, Jozsef and Kury, Sophia and Miscena, Anna and Rosenberg, Raphael},
+  title     = {HeatMatch: Orientation-Aware Visualization and Comparison of Very Dense Saccade Patterns},
+  journal   = {Proc. ACM Comput. Graph. Interact. Tech.},
+  year      = {2026},
+  volume    = {9},
+  number    = {2},
+  articleno = {18},
+  doi       = {10.1145/3803539},
+}
+```

heatmatch-1.0.0/heatmatch/__init__.py

@@ -0,0 +1,3 @@
+from heatmatch.fields import make_reference_grid, make_orientation_field, OrientationField
+from heatmatch.heatmapping import Heatmap
+from heatmatch.matching import compute_similarity, SimilarityResult

heatmatch-1.0.0/heatmatch/fields.py

@@ -0,0 +1,197 @@
+import numpy as np
+from dataclasses import dataclass
+
+"""
+Field Computation
+
+Computes orientation fields over a reference grid from saccade data.
+
+- Orientation — unsigned saccade orientation ω_j ∈ [0, π).
+- Point-Saccade Distance — minimal Euclidean distance from a reference point p_i
+  to a saccade segment s_j.
+- Gaussian Kernel — kernel K(p_i, s_j) and kernel mass m_i.
+- Mean Orientation and Coherence — weighted mean orientation ω̄_i and mean
+  resultant length R_i via double-angle embedding.
+- Density — normalized kernel mass ρ_i.
+
+Public API : make_reference_grid, make_orientation_field, OrientationField
+Internal   : _compute_orientations, _point_to_segment_distances, _gaussian_kernel
+"""
+
+
+@dataclass
+class OrientationField:
+    """
+    Precomputed orientation field over a reference grid.
+
+    Holds the three per-point statistics returned by make_orientation_field
+    together with the grid shape so that callers need not carry it separately.
+
+    Attributes
+    ----------
+    omega_mean : (P,) array in [0, π), NaN where m_i = 0
+    R          : (P,) array in [0, 1] — mean resultant length (coherence)
+    rho        : (P,) array in [0, 1] — normalized kernel mass (density), sums to 1
+    grid_shape : (ny, nx) tuple — reshape arrays with .reshape(grid_shape)
+    """
+    omega_mean: np.ndarray
+    R:          np.ndarray
+    rho:        np.ndarray
+    grid_shape: tuple
+
+
+def _compute_orientations(onset, offset):
+    """
+    Unsigned saccade orientations ω_j ∈ [0, π).
+
+    ω_j = atan2(y_{j1} − y_{j0}; x_{j1} − x_{j0})  mod  π
+
+    Orientations are unsigned: ω and ω+π are treated as equivalent, so that
+    back-and-forth saccades along the same axis reinforce rather than cancel.
+
+    Used internally by make_orientation_field; not part of the public API.
+    """
+    d = offset - onset
+    return np.mod(np.arctan2(d[:, 1], d[:, 0]), np.pi)
+
+
+def _point_to_segment_distances(points, onset, offset):
+    """
+    Minimal Euclidean distance d(p_i, s_j) from each reference point p_i to each
+    saccade segment s_j = [s_{j0}, s_{j1}].
+
+    Used internally by make_orientation_field; not part of the public API.
+    """
+    p  = points[:, None, :]   # (P, 1, 2)
+    a  = onset[None,  :, :]   # (1, J, 2)
+    b  = offset[None, :, :]   # (1, J, 2)
+
+    ab      = b - a                                                       # (1, J, 2)
+    ap      = p - a                                                       # (P, J, 2)
+    ab_len2 = np.sum(ab * ab, axis=-1, keepdims=True)                     # (1, J, 1)
+    ab_len2 = np.where(ab_len2 == 0.0, 1.0, ab_len2)                     # guard zero-length
+
+    t = np.clip(np.sum(ap * ab, axis=-1, keepdims=True) / ab_len2, 0.0, 1.0)  # (P, J, 1)
+    closest = a + t * ab                                                  # (P, J, 2)
+    return np.linalg.norm(p - closest, axis=-1)                           # (P, J)
+
+
+def _gaussian_kernel(d, sigma):
+    """
+    Gaussian kernel K(p_i, s_j) = exp(−½ (d / σ)²).
+
+    Used internally by make_orientation_field; not part of the public API.
+    """
+    return np.exp(-0.5 * (d / sigma) ** 2)
+
+
+
+def make_reference_grid(w, h, grid_resolution=200):
+    """
+    Uniform reference grid of positions {p_i} ⊂ [1..W] × [1..H].
+
+    Parameters
+    ----------
+    w, h             : stimulus width and height in pixels
+    grid_resolution  : int or (ny, nx) tuple
+                       Number of grid points along each axis. A single integer
+                       produces a square grid; a tuple sets rows and columns
+                       independently. Follows numpy's (rows, cols) = (ny, nx)
+                       convention, matching the shape of the returned YY array.
+                       Default: 200 (i.e. 200×200 = 40 000 points).
+
+    Returns
+    -------
+    pts : (ny*nx, 2) array — flattened (x, y) positions, input to make_orientation_field
+    XX  : (ny, nx) meshgrid of x-coordinates (use for reshaping field outputs)
+    YY  : (ny, nx) meshgrid of y-coordinates (use for reshaping field outputs)
+    """
+    if isinstance(grid_resolution, int):
+        ny = nx = grid_resolution
+    else:
+        ny, nx = grid_resolution
+    xs = np.linspace(1, w, nx, dtype=np.float64)
+    ys = np.linspace(1, h, ny, dtype=np.float64)
+    xx, yy = np.meshgrid(xs, ys)
+    pts = np.column_stack([xx.ravel(), yy.ravel()])
+    return pts, xx, yy
+
+
+def make_orientation_field(points, onset, offset, sigma=50.0,
+                           grid_shape=None,
+                           points_per_chunk=4096, segs_per_chunk=512):
+    """
+    Compute the orientation field (ω̄, R, ρ) over all reference points.
+
+    For each reference point p_i, accumulates:
+      sin_i = Σ_j K(p_i,s_j) · sin(2ω_j)     (unnormalized; proportional to paper's s̄_i · m_i)
+      cos_i = Σ_j K(p_i,s_j) · cos(2ω_j)     (unnormalized; proportional to paper's c̄_i · m_i)
+      m_i   = Σ_j K(p_i,s_j)                  (kernel mass)
+
+    Then derives:
+      ω̄_i = ½ · (atan2(sin_i, cos_i) mod 2π) ∈ [0, π)   mean orientation
+      R_i  = √(sin_i² + cos_i²) / m_i          ∈ [0, 1]  coherence (MRL)
+      ρ_i  = m_i / Σ_k m_k                     ∈ [0, 1]  density
+
+    Points with no kernel support (m_i = 0) get ω̄_i = NaN, R_i = 0, ρ_i = 0.
+
+    Parameters
+    ----------
+    points           : (P, 2)  reference grid positions {p_i}
+    onset            : (J, 2)  saccade starting points  {s_{j0}}
+    offset           : (J, 2)  saccade end points       {s_{j1}}
+    sigma            : float   Gaussian bandwidth σ > 0, in pixels
+    grid_shape       : (ny, nx) tuple — stored on the returned OrientationField for
+                       convenient reshaping; pass yy.shape from make_reference_grid
+    points_per_chunk : int     chunk size over grid points (memory/speed trade-off)
+    segs_per_chunk   : int     chunk size over saccades   (memory/speed trade-off)
+
+    Returns
+    -------
+    OrientationField with omega_mean, R, rho (each (P,)) and grid_shape
+    """
+    n_pts = points.shape[0]
+    n_sac = onset.shape[0]
+
+    omega = _compute_orientations(onset, offset)
+
+    sin2 = np.sin(2.0 * omega)  # (J,)
+    cos2 = np.cos(2.0 * omega)  # (J,)
+
+    sin_acc  = np.zeros(n_pts, dtype=np.float64)
+    cos_acc  = np.zeros(n_pts, dtype=np.float64)
+    mass_acc = np.zeros(n_pts, dtype=np.float64)
+
+    for p0 in range(0, n_pts, points_per_chunk):
+        p1    = min(n_pts, p0 + points_per_chunk)
+        p_blk = points[p0:p1]
+
+        sin_blk  = np.zeros(p1 - p0, dtype=np.float64)
+        cos_blk  = np.zeros(p1 - p0, dtype=np.float64)
+        mass_blk = np.zeros(p1 - p0, dtype=np.float64)
+
+        for s0 in range(0, n_sac, segs_per_chunk):
+            s1    = min(n_sac, s0 + segs_per_chunk)
+            d_blk = _point_to_segment_distances(p_blk, onset[s0:s1], offset[s0:s1])
+            k_blk = _gaussian_kernel(d_blk, sigma)
+
+            mass_blk += k_blk.sum(axis=1)
+            sin_blk  += k_blk @ sin2[s0:s1]
+            cos_blk  += k_blk @ cos2[s0:s1]
+
+        sin_acc[p0:p1]  = sin_blk
+        cos_acc[p0:p1]  = cos_blk
+        mass_acc[p0:p1] = mass_blk
+
+    # ω̄_i = ½ · (atan2(sin_i, cos_i) mod 2π)  — scale-invariant, so unnormalized sums work
+    omega_mean = 0.5 * np.mod(np.arctan2(sin_acc, cos_acc), 2.0 * np.pi)
+    omega_mean = np.where(mass_acc > 0.0, omega_mean, np.nan)
+
+    # R_i = √(s̄_i² + c̄_i²)  where s̄_i = sin_i/m_i, c̄_i = cos_i/m_i
+    R = np.where(mass_acc > 0.0, np.sqrt(sin_acc**2 + cos_acc**2) / mass_acc, 0.0)
+
+    # ρ_i = m_i / Σ_k m_k
+    total_mass = mass_acc.sum()
+    rho = mass_acc / total_mass if total_mass > 0 else np.zeros_like(mass_acc)
+
+    return OrientationField(omega_mean=omega_mean, R=R, rho=rho, grid_shape=grid_shape)

heatmatch-1.0.0/heatmatch/heatmapping.py

@@ -0,0 +1,157 @@
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.cm as cm
+from matplotlib.colors import ListedColormap, Normalize
+from PIL import Image
+import math
+
+"""
+Visualization
+
+Implements the OOI-coded heatmap rendering pipeline.
+
+Public API : Heatmap
+Internal   : _make_cyclic_colormap, _opacity_from_confidence, _load_grayscale
+"""
+
+
+def _make_cyclic_colormap(base_cmap):
+    """
+    Cyclic diverging colormap for unsigned orientation display.
+
+    Concatenates the forward and reverse passes of a diverging colormap so that
+    ω = 0 and ω = π map to the same color, creating a seamless cycle over [0, π).
+    """
+    base = plt.get_cmap(base_cmap)
+    n = 256
+    forward  = base(np.linspace(0, 1, n))
+    backward = base(np.linspace(1, 0, n))
+    colors = np.vstack([forward[:-1], backward[:-1]])   # avoid seam duplicate
+    return ListedColormap(colors, name=f"{base_cmap}_cyclic")
+
+
+def _opacity_from_confidence(confidence, degree=2.0, quantile=0.8, eps=1e-12):
+    """
+    "Gentle nonlinearity" mapping a confidence signal to opacity ∈ [0, 1].
+
+    Uses a logistic function centered at the quantile-th percentile so that
+    low-confidence grid points fade toward transparency.
+    """
+    cmin, cmax = float(np.min(confidence)), float(np.max(confidence))
+    if cmax <= cmin + eps:
+        return np.zeros_like(confidence)
+    c = (confidence - cmin) / (cmax - cmin)
+    center = np.quantile(c, quantile)
+    c = np.clip(c, eps, 1.0 - eps)
+    return 1.0 / (1.0 + (center * (1.0 - c) / ((1.0 - center) * c)) ** degree)
+
+
+def _load_grayscale(path):
+    """
+    Load an image from path and return a float32 grayscale array in [0, 1].
+
+    Uses PIL for format detection, so the actual file format takes precedence
+    over the file extension (handles e.g. JPEG files named .png).
+    """
+    img = Image.open(str(path)).convert('L')   # 'L' = 8-bit grayscale
+    return np.asarray(img, dtype=np.float32) / 255.0
+
+
+class Heatmap:
+    """
+    OOI-coded heatmap renderer with two-level caching.
+
+    Wraps an OrientationField and caches intermediate results to avoid redundant
+    computation when only display parameters change:
+
+    - Background image  → loaded and converted to grayscale once at construction.
+    - Cyclic colormap   → rebuilt only when `cmap` changes.
+    - Opacity array     → rebuilt only when `opacity_density_weight`, `degree`, or `quantile` changes.
+    - OOI rotation      → always cheap (one np.mod call), never cached.
+
+    Parameters
+    ----------
+    field : OrientationField
+        Precomputed orientation field from make_orientation_field.
+    w, h  : stimulus width and height in pixels
+    image : str, path-like, or None
+        Optional path to a stimulus image. When provided it is converted to
+        grayscale once and rendered as a background; the heatmap is composited
+        on top with opacity scaled by `base_opacity`.
+    """
+
+    def __init__(self, field, w, h, image=None):
+        self._field = field
+        self._w     = w
+        self._h     = h
+
+        self._image_gray   = _load_grayscale(image) if image is not None else None
+
+        self._cmap_name    = None
+        self._cyclic_cmap  = None
+
+        self._opacity_key  = None   # (opacity_density_weight, degree, quantile)
+        self._opacity      = None
+
+    def draw(self, ax, ooi=0.0, opacity_density_weight=1.0, base_opacity=0.85,
+             cmap='coolwarm', degree=2.0, quantile=0.8):
+        """
+        Render the OOI-coded saccade heatmap onto a matplotlib Axes.
+
+        Hue encodes mean orientation ω̄_i relative to the chosen OOI.
+        Opacity encodes local confidence ρ^opacity_density_weight · R^(1−opacity_density_weight),
+        passed through a gentle nonlinearity and then scaled by base_opacity.
+
+        Parameters
+        ----------
+        ax                    : matplotlib Axes
+        ooi                   : float — Orientation of Interest in degrees, compass convention:
+                                0=east, 90=north, 180=west, 270=south (default 0.0 = horizontal).
+                                Orientations are unsigned so ooi and ooi±180 are equivalent.
+        opacity_density_weight : float in [0, 1] — blend between density and coherence for opacity:
+                                1.0 → density only, 0.0 → coherence only. Recommended 0.5–1.0.
+        base_opacity          : float in [0, 1] — global opacity ceiling applied on top of the
+                                data-derived opacity; useful when a background image is shown.
+                                The final per-point alpha = data_opacity × base_opacity.
+        cmap                  : str — base diverging colormap name (default 'coolwarm')
+        degree                : float — sharpness of the opacity nonlinearity
+        quantile              : float — center of the opacity nonlinearity
+        """
+        # -- colormap cache (invalidated on cmap change) -----------------------
+        if cmap != self._cmap_name:
+            self._cyclic_cmap = _make_cyclic_colormap(cmap)
+            self._cmap_name   = cmap
+
+        # -- opacity cache (invalidated on opacity_density_weight / degree / quantile change) --
+        opacity_key = (opacity_density_weight, degree, quantile)
+        if opacity_key != self._opacity_key:
+            confidence        = self._field.rho ** opacity_density_weight * self._field.R ** (1.0 - opacity_density_weight)
+            self._opacity     = _opacity_from_confidence(confidence, degree=degree, quantile=quantile)
+            self._opacity_key = opacity_key
+
+        # -- background image (grayscale) --------------------------------------
+        if self._image_gray is not None:
+            ax.imshow(self._image_gray, extent=(1, self._w, self._h, 1),
+                      origin='upper', cmap='gray', vmin=0.0, vmax=1.0,
+                      interpolation='bilinear')
+
+        # -- OOI rotation (always cheap) ---------------------------------------
+        omega_display = np.mod(self._field.omega_mean - np.deg2rad(ooi), math.pi)
+
+        # -- compose RGBA and render -------------------------------------------
+        norm = Normalize(vmin=0.0, vmax=math.pi)
+        sm   = cm.ScalarMappable(norm=norm, cmap=self._cyclic_cmap)
+
+        shape = self._field.grid_shape
+        rgba  = sm.to_rgba(omega_display.reshape(shape))
+        alpha = np.where(np.isnan(self._field.omega_mean.reshape(shape)),
+                         0.0,
+                         self._opacity.reshape(shape) * base_opacity)
+        rgba[..., -1] = alpha
+
+        ax.imshow(rgba, extent=(1, self._w, self._h, 1),
+                  origin='upper', interpolation='gaussian')
+        ax.set_xlim(1, self._w)
+        ax.set_ylim(self._h, 1)
+        ax.set_xticks([])
+        ax.set_yticks([])

heatmatch-1.0.0/heatmatch/matching.py

@@ -0,0 +1,99 @@
+import numpy as np
+from dataclasses import dataclass
+
+"""
+HeatMatch Similarity
+
+Computes pairwise similarity scores between two saccade orientation fields.
+
+- Locational similarity S_loc: Pearson correlation of density maps ρ, rescaled to [0, 1].
+- Directional similarity S_dir: density- and coherence-weighted sum of per-point axial
+  angular similarities, using geometric-mean overlap weights, with a density-coherence
+  trade-off parameter ∈ [0, 1].
+
+Public API : compute_similarity, SimilarityResult
+Internal   : _locational_similarity, _directional_similarity
+"""
+
+
+@dataclass
+class SimilarityResult:
+    """
+    HeatMatch similarity scores between two saccade patterns.
+
+    Attributes
+    ----------
+    s_loc : float in [0, 1] — locational similarity S_loc
+    s_dir : float in [0, 1] — directional similarity S_dir
+    """
+    s_loc: float
+    s_dir: float
+
+
+def _locational_similarity(rho_a, rho_b):
+    """
+    S_loc(A, B) = (corr(ρ^A, ρ^B) + 1) / 2  ∈ [0, 1].
+
+    Pearson correlation of the two density maps, shifted to [0, 1].
+    S_loc = 1: identical spatial layout; S_loc = 0: maximally anti-correlated.
+    """
+    corr = np.corrcoef(rho_a.ravel(), rho_b.ravel())[0, 1]
+    return float((corr + 1.0) / 2.0)
+
+
+def _directional_similarity(omega_a, omega_b, R_a, R_b, rho_a, rho_b,
+                             density_coherence_tradeoff=0.5):
+    """
+    S_dir(A, B) = Σ_i w_i · axial-sim(ω̄_i^A, ω̄_i^B) / Σ_i w_i  ∈ [0, 1].
+
+    where w_i = ρ̄_i^dct · R̄_i^(1−dct),  dct = density_coherence_tradeoff.
+
+    ρ̄_i = √(ρ_i^A · ρ_i^B) and R̄_i = √(R_i^A · R_i^B) are the geometric-mean
+    overlap weights for density and coherence.
+
+    density_coherence_tradeoff=1 weights by density only — at this extreme S_dir
+    becomes statistically redundant with S_loc since angular coherence has no
+    influence on the score. Recommended value ~0.5.
+
+    axial-sim(ω^A, ω^B) = 1 − (2/π) · δ  where δ = min(Δ, π−Δ), Δ = |ω^A − ω^B|.
+
+    Grid points with no kernel support have ω̄ = NaN and ρ = 0; their contribution
+    is zero via the ρ̄ weight. axial-sim is set to 0 for NaN inputs as a safety guard.
+    """
+    dct = density_coherence_tradeoff
+
+    Delta     = np.abs(omega_a - omega_b)
+    delta     = np.minimum(Delta, np.pi - Delta)
+    axial_sim = 1.0 - (2.0 / np.pi) * delta
+    axial_sim = np.where(np.isnan(axial_sim), 0.0, axial_sim)
+
+    rho_bar = np.sqrt(rho_a * rho_b)
+    r_bar   = np.sqrt(R_a   * R_b)
+    w = rho_bar ** dct * r_bar ** (1.0 - dct)
+    W = float(w.sum())
+    return float(np.sum(w * axial_sim) / W) if W > 0.0 else 0.0
+
+
+def compute_similarity(field_a, field_b, density_coherence_tradeoff=0.5):
+    """
+    Compute HeatMatch similarity between two saccade patterns.
+
+    Parameters
+    ----------
+    field_a, field_b : OrientationField
+        Precomputed orientation fields from make_orientation_field.
+    density_coherence_tradeoff : float in [0, 1]
+        Controls how much S_dir weights grid points by density vs. coherence.
+        At 1.0 the weight is purely density-based and angular coherence has no influence,
+        making S_dir statistically redundant with S_loc. Recommended ~0.5.
+
+    Returns
+    -------
+    SimilarityResult with s_loc and s_dir
+    """
+    s_loc = _locational_similarity(field_a.rho, field_b.rho)
+    s_dir = _directional_similarity(field_a.omega_mean, field_b.omega_mean,
+                                    field_a.R, field_b.R,
+                                    field_a.rho, field_b.rho,
+                                    density_coherence_tradeoff=density_coherence_tradeoff)
+    return SimilarityResult(s_loc=s_loc, s_dir=s_dir)

heatmatch-1.0.0/heatmatch.egg-info/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: heatmatch
+Version: 1.0.0
+Summary: Orientation-aware visualization and comparison of very dense saccade patterns (scanpath comparison for long free viewing)
+Author: Xingyu Long
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xysLong/HeatMatch
+Project-URL: Paper, https://doi.org/10.1145/3803539
+Project-URL: Data, https://osf.io/f2xhj/
+Keywords: eye-tracking,saccades,scanpath,scanpath-comparison,gaze,heatmap,visualization,orientation-field,empirical-aesthetics,art-perception
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: Pillow
+Dynamic: license-file
+
+# HeatMatch
+
+**Visualize and compare very dense saccade patterns from long free-viewing eye-tracking data.**
+
+HeatMatch turns hundreds or thousands of saccades into continuous *orientation fields*: at every location it estimates saccade density, mean orientation, and how consistently the saccades agree in orientation. From these fields it draws orientation-coded heatmaps that show *where* gaze moves and *in which direction*. It also computes a similarity score for comparing saccade patterns across participants, stimuli, or conditions, without AOIs, scanpath alignment, or manual segmentation.
+
+It was developed for 60-second viewing of paintings (empirical aesthetics, art history) and works for any static stimulus. Python implementation accompanying the paper:
+
+<table border="0" cellspacing="0" cellpadding="0"><tr>
+<td width="72%" valign="top">
+
+<blockquote>
+Xingyu Long, Jozsef Arato, Sophia Kury, Anna Miscena, and Raphael Rosenberg. 2026.<br/>
+<strong>HeatMatch: Orientation-Aware Visualization and Comparison of Very Dense Saccade Patterns.</strong><br/>
+<em>Proceedings of the ACM on Computer Graphics and Interactive Techniques</em> (PACMCGIT), 9(2), Article 18.<br/>
+<a href="https://doi.org/10.1145/3803539">https://doi.org/10.1145/3803539</a>
+</blockquote>
+
+</td>
+<td width="28%" align="center" valign="middle">
+<img src="https://raw.githubusercontent.com/xysLong/HeatMatch/main/assets/logos.png" width="200" alt="CReA Lab and Vienna Cognitive Science Hub"/>
+</td>
+</tr></table>
+
+---
+
+## Overview
+
+1. **OOI-coded heatmaps** — orientation fields visualized with researcher-defined color anchors and confidence-weighted opacity.
+2. **HeatMatch similarity** — comparison based on saccade density and orientation.
+
+![HeatMatch heatmap example](https://raw.githubusercontent.com/xysLong/HeatMatch/main/assets/example_heatmaps.jpg)
+<sub>Per-participant (columns 1–5) and aggregated (column 6) heatmaps for three paintings. Hue = mean saccade orientation relative to OOI; opacity = local confidence. Stimulus images: public domain via [Wikimedia Commons](https://commons.wikimedia.org) — see paper for details.</sub>
+
+See the [paper](https://doi.org/10.1145/3803539) for methodology.
+
+### When to use it
+
+- **Long, dense viewing.** Scanpath comparison methods such as MultiMatch or ScanMatch align scanpaths sequence by sequence. With hundreds of saccades per trial and strongly diverging paths, they become slow and hard to interpret. HeatMatch aggregates instead of aligning, so it scales to arbitrarily dense data.
+- **Orientation matters.** Fixation heatmaps and density-based metrics ignore saccade direction. HeatMatch keeps orientation, so you can ask whether gaze follows horizontal, vertical, diagonal, or symmetric structure in an image, e.g. composition lines in a painting.
+- **Group, stimulus, and individual comparisons.** In the paper, the similarity score recovers the abstract vs. still-life distinction and differences in within-painting agreement. It also reveals stable individual "saccadic signatures" that hold across paintings.
+
+It is **not** a replacement for sequence-based methods. HeatMatch is permutation-invariant (it ignores saccade order) and treats orientations as unsigned (left-to-right = right-to-left). Use it alongside MultiMatch, ScanMatch, or RQA when order or direction matters.
+
+---
+
+## Installation
+
+```bash
+pip install heatmatch
+```
+
+Dependencies: `numpy`, `matplotlib`, `Pillow`. For development, clone the repository and run `pip install -e .`.
+
+---
+
+## Quick Start
+
+```python
+import matplotlib.pyplot as plt
+from heatmatch import make_reference_grid, make_orientation_field, Heatmap, compute_similarity
+
+W, H = 2880, 2160
+onset  = ...  # (J, 2) saccade start coordinates
+offset = ...  # (J, 2) saccade end coordinates
+
+pts, xx, yy = make_reference_grid(W, H, grid_resolution=200)
+field = make_orientation_field(pts, onset, offset, sigma=50.0, grid_shape=yy.shape)
+
+fig, ax = plt.subplots()
+Heatmap(field, W, H).draw(ax, ooi=0.0)  # ooi=0 → horizontal, ooi=90 → vertical
+plt.show()
+
+# Compare two patterns (fields built on the same grid, e.g. two participants)
+result = compute_similarity(field_a, field_b)
+s = (result.s_loc + result.s_dir) / 2  # composite HeatMatch score S in [0, 1]
+print(result.s_loc, result.s_dir, s)
+```
+
+A full worked example is in [`demo.ipynb`](https://github.com/xysLong/HeatMatch/blob/main/demo.ipynb). The dataset is not included — download `data_anonymized.csv` from **[osf.io/f2xhj](https://osf.io/f2xhj/)** and place it in `tests/`.
+
+---
+
+## API
+
+### `heatmatch.fields`
+
+| | |
+|---|---|
+| `make_reference_grid(w, h, grid_resolution)` | Returns `(pts, xx, yy)`; int → square grid, `(ny, nx)` tuple → rectangular |
+| `make_orientation_field(pts, onset, offset, sigma, grid_shape, ...)` | Returns `OrientationField` with `omega_mean`, `R`, `rho` |
+
+### `heatmatch.heatmapping`
+
+| | |
+|---|---|
+| `Heatmap(field, w, h, image=None)` | Caches colormap, opacity, and (optionally) grayscale background image |
+| `Heatmap.draw(ax, ooi, opacity_density_weight, base_opacity, cmap, ...)` | Renders onto `ax` |
+
+OOI in degrees: 0 = east, 90 = north, 180 = west, 270 = south. Unsigned, so `ooi` and `ooi ± 180` are equivalent.
+
+### `heatmatch.matching`
+
+| | |
+|---|---|
+| `compute_similarity(field_a, field_b, density_coherence_tradeoff)` | Returns `SimilarityResult(s_loc, s_dir)` |
+
+---
+
+## Key Parameters
+
+| Parameter | Default | Notes |
+|---|---|---|
+| `sigma` | `50.0` | Gaussian bandwidth in px. Paper evaluates {50, 100, 150}. |
+| `grid_resolution` | `200` | Int or `(ny, nx)`. Paper uses 200. |
+| `ooi` | `0.0` | Orientation of Interest in degrees. |
+| `opacity_density_weight` | `1.0` | Density vs. coherence for opacity. Recommended 0.5–1.0. |
+| `base_opacity` | `0.85` | Global opacity ceiling; useful with a background image. |
+| `density_coherence_tradeoff` | `0.5` | Density vs. coherence for *S*_dir. At 1.0, angular information is discarded. |
+
+---
+
+## Citation
+
+```bibtex
+@article{long2026heatmatch,
+  author    = {Long, Xingyu and Arato, Jozsef and Kury, Sophia and Miscena, Anna and Rosenberg, Raphael},
+  title     = {HeatMatch: Orientation-Aware Visualization and Comparison of Very Dense Saccade Patterns},
+  journal   = {Proc. ACM Comput. Graph. Interact. Tech.},
+  year      = {2026},
+  volume    = {9},
+  number    = {2},
+  articleno = {18},
+  doi       = {10.1145/3803539},
+}
+```

heatmatch-1.0.0/heatmatch.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+heatmatch/__init__.py
+heatmatch/fields.py
+heatmatch/heatmapping.py
+heatmatch/matching.py
+heatmatch.egg-info/PKG-INFO
+heatmatch.egg-info/SOURCES.txt
+heatmatch.egg-info/dependency_links.txt
+heatmatch.egg-info/requires.txt
+heatmatch.egg-info/top_level.txt

heatmatch-1.0.0/heatmatch.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

heatmatch-1.0.0/heatmatch.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy
+matplotlib
+Pillow

heatmatch-1.0.0/heatmatch.egg-info/top_level.txt

@@ -0,0 +1 @@
+heatmatch

heatmatch-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["heatmatch"]
+
+[project]
+name = "heatmatch"
+version = "1.0.0"
+description = "Orientation-aware visualization and comparison of very dense saccade patterns (scanpath comparison for long free viewing)"
+readme = "README.md"
+license = "MIT"
+authors = [{name = "Xingyu Long"}]
+requires-python = ">=3.9"
+dependencies = [
+    "numpy",
+    "matplotlib",
+    "Pillow",
+]
+keywords = [
+    "eye-tracking", "saccades", "scanpath", "scanpath-comparison",
+    "gaze", "heatmap", "visualization", "orientation-field",
+    "empirical-aesthetics", "art-perception",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+
+[project.urls]
+Homepage = "https://github.com/xysLong/HeatMatch"
+Paper = "https://doi.org/10.1145/3803539"
+Data = "https://osf.io/f2xhj/"

heatmatch-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+