OSCR

Retinal curl as a functional signal for heading estimation beyond the focus of expansion.

Code ↔ Paper

7 matches between paragraphs of the paper and lines of its authors' code, computed by the harvester (lexical-v1). Click a colored paragraph or line to see its counterpart.

The 7 matches
  1. [1] § Results › Simulation results ↔ Python tree/curl-neural_model/ring_attractor_heading_v1.py, lines 144 to 266 · score 0.94 · Phase Portrait, drift dynamics, decoded heading, straight ahead prior, neural activity, ring attractor · Report a mismatch
  2. [2] § Results › Simulation results ↔ Python tree/curl-neural_model/ring_attractor_heading_v1.py, lines 144 to 266 · score 0.93 · neuron preferred headings, Phase portrait, sensory prior competition, normalized amplitude, straight ahead prior, ring position · Report a mismatch
  3. [3] § Appendix 2 › Neural network model of gaze-contingent heading bias ↔ Python tree/curl-neural_model/ring_attractor_heading_v1.py, lines 1 to 89 · score 0.92 · weak straight ahead, gaze modulated, bias emerges, neural model, heading representation, cortical · Report a mismatch
  4. [4] § Appendix 2 › Bias generation as sensory–prior competition ↔ Python tree/curl-neural_model/ring_attractor_heading_v1.py, lines 1 to 89 · score 0.83 · allows sensory evidence, weak straight ahead, weak prior, interaction, attractor, opposite · Report a mismatch
  5. [5] § Appendix 2 › Heading estimation and 3D path reconstruction ↔ Python tree/curl-neural_model/ring_attractor_heading_v1.py, lines 713 to 761 · score 0.71 · focal length, ring attractor, smoothed, horizontal, pixels, field · Report a mismatch
  6. [6] § Methods › Displays and conditions ↔ eLife-VOR-RA-2026-110770/3D_stimulus_generator.py, lines 102 to 163 · score 0.58 · simplex noise, stimulus generator, shaders, motion · Report a mismatch
  7. [7] § Appendix 2 › Local motion encoding ↔ Python tree/curl-neural_model/ring_attractor_heading_v1.py, lines 713 to 761 · score 0.51 · optical flow, encoding, V1, MT, motion, model · Report a mismatch

Paper

Loaded from Europe PMC by your browser; OSCR does not store it: doi.org · Europe PMC

The paper is loaded when this pane is shown.

The authors' code

Python · 947 lines · 40 KB · no license · 6 matches

  1. #!/usr/bin/env python3
  2. """
  3. Neural Heading Estimator with Inhibitory Recurrent Push-Pull Mechanism
  5. This script adds plotting and saving features to curl_recurrent_heading_network.py
  7. -----------------------------------------------------------
  8. Eliminates the explicit Kaway term by using asymmetric recurrent connectivity
  9. to naturally create push-pull dynamics in the ring attractor.
  11. Key changes:
  12. 1. Removed Kaway parameter entirely
  13. 2. Added asymmetric recurrent weights that create natural opposition
  14. 3. Simplified parameter space
  15. 4. More biologically plausible connectivity
  17. Neurophysiological basis:
  18. Biologically plausible: Uses asymmetric recurrent connectivity instead of artificial "anti-gaze" lobe
  20. - Cortical circuits often have asymmetric lateral connections
  21. - Inhibition can spread preferentially in specific directions
  22. - Natural push-pull emerges from network dynamics rather than explicit coding
  24. ┌─────────────────────────────────────────────────────────────┐
  25. │ VISUAL PROCESSING │
  26. │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
  27. │ │ V1 │ -> │ MT │ -> │ MSTd │ │
  28. │ │ Orientation │ │ Direction │ │ Flow Pattern │ │
  29. │ │ Selectivity│ │ Selectivity│ │ Analysis │ │
  30. │ └─────────────┘ └─────────────┘ └─────────────────┘ │
  31. └─────────────────────────────┬───────────────────────────────┘
  32. │
  33. Curl Signal (ω̄)
  34. │
  35. ┌─────────────────────────────────────────────────────────────┐
  36. │ PARIETAL CORTEX (PPC) - Ring Attractor │
  37. │ │
  38. │ ┌─────────────────────────────────────────────────────┐ │
  39. │ │ Heading Representation │ │
  40. │ │ │ │
  41. │ │ [← Left] ○────○────○────○────○────○────○ [Right →] │
  42. │ │ -θmax │ │ │ │ │ +θmax │ │
  43. │ │ △ △ △ △ △ │ │
  44. │ │ │ │ │ │ │ │ │
  45. │ │ Gaze-Inhibited Input │ Prior Input │ │
  46. │ │ (Kp × ω̄) │ (Straight-ahead) │ │
  47. │ │ │ │ │
  48. │ │ Asymmetric Recurrent Connections │ │
  49. │ │ (Stronger inhibition away from center) │ │
  50. │ └─────────────────────────────────────────────────────┘ │
  51. │ │
  52. │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
  53. │ │ Eye Position│ │ Motor Plan │ │ Vestibular │ │
  54. │ │ Signals │ │ Integration │ │ Integration│ │
  55. │ └─────────────┘ └─────────────┘ └─────────────┘ │
  56. └─────────────────────────────────────────────────────────────┘
  59. Parameter Space Revelation
  60. The key parameters are actually:
  62. I0 (prior strength) - determines flexibility
  63. K_p (inhibition gain) - determines bias magnitude
  64. sigma_prior - determines spatial scale of prior
  65. Bias emerges from gaze-modulated inhibition interacting with a weak straight-ahead prior and slightly asymmetric recurrent connectivity in PPC.
  67. Revised Neurophysiological Story
  68. The bias emerges from:
  69. Gaze-modulated inhibition from MSTd to PPC
  70. Weak straight-ahead prior in PPC
  71. Standard center-surround recurrence in cortical circuits
  73. the essential mechanism is sensory-prior competition, plus asymmetric recurrence (not determinant).
  74. This is actually a more elegant and biologically plausible explanation!
  75. The system needs to be flexible enough (weak prior) to allow sensory evidence to shift the heading representation away from gaze.
  77. """
  79. import argparse
  80. import csv
  81. import math
  82. import os
  83. from dataclasses import dataclass
  84. from typing import Optional, Tuple
  86. import cv2
  87. import numpy as np
  89. import matplotlib.pyplot as plt # Added for plotting
  92. # ---------------------------- I/O helpers ---------------------------- #
  94. def load_gaze_csv(gaze_csv_path: str):
  95. xs, ys, vis = [], [], []
  96. has_visible = False
  97. with open(gaze_csv_path, "r", newline="") as f:
  98. reader = csv.DictReader(f)
  99. fields = [fn.strip() for fn in (reader.fieldnames or [])]
  100. required = {"x_px_ui", "y_px_ui"}
  101. if not required.issubset(set(fields)):
  102. raise ValueError(f"gaze_csv must contain columns {required}, found: {fields}")
  103. has_visible = ("visible" in fields)
  104. for row in reader:
  105. try:
  106. x = float(row["x_px_ui"]) ; y = float(row["y_px_ui"])
  107. except Exception:
  108. x, y = float("nan"), float("nan")
  109. xs.append(x) ; ys.append(y)
  110. if has_visible:
  111. try:
  112. v = int(float(row["visible"]))
  113. except Exception:
  114. v = 1
  115. vis.append(v)
  116. return {
  117. "x": np.array(xs, dtype=np.float32),
  118. "y": np.array(ys, dtype=np.float32),
  119. "visible": (np.array(vis, dtype=np.int32) if has_visible else None),
  120. }
  122. def get_gaze_for_abs_frame(gaze_data, abs_idx: int, w: int, h: int,
  123. last_valid: Optional[Tuple[float, float]]) -> Tuple[float, float, Optional[Tuple[float, float]]]:
  124. if gaze_data is None:
  125. return (w/2.0), (h/2.0), ((w/2.0), (h/2.0))
  126. n = gaze_data["x"].shape[0]
  127. idx = min(abs_idx, n - 1) if n > 0 else 0
  128. gx = float(gaze_data["x"][idx]) if n > 0 else float("nan")
  129. gy = float(gaze_data["y"][idx]) if n > 0 else float("nan")
  130. visible = True
  131. if gaze_data.get("visible") is not None and n > 0:
  132. visible = bool(int(gaze_data["visible"][idx]))
  134. def valid(x, y):
  135. return (not (math.isnan(x) or math.isnan(y))) and (0 <= x < w) and (0 <= y < h)
  137. if visible and valid(gx, gy):
  138. return gx, gy, (gx, gy)
  139. if last_valid is not None and valid(*last_valid):
  140. return last_valid[0], last_valid[1], last_valid
  141. return (w / 2.0), (h / 2.0), (w / 2.0, h / 2.0)
  144. # --- NEW CLASS FOR DATA COLLECTION ---
  145. class DataCollector:
  146. def __init__(self, phi):
  147. # self.n_units = n_units
  148. self.phi = phi
  149. self.history_x = [] # Neural activity over time
  150. self.history_I_total = [] # total activity
  151. self.history_I_gaze = [] # gaze inhibition
  152. self.history_I_prior = [] # prior
  153. self.history_theta = [] # Decoded heading over time
  154. # self.history_omega = [] # Input curl over time
  156. def collect(self, x, I_total, I_gaze, I_prior, theta):
  157. self.history_x.append(x.copy())
  158. self.history_I_total.append(I_total.copy())
  159. self.history_I_gaze.append(I_gaze.copy())
  160. self.history_I_prior.append(I_prior.copy())
  161. self.history_theta.append(theta)
  162. # self.history_omega.append(omega)
  164. def export_to_csv(self, prefix="heading_model"):
  165. # 1. Save Activity Matrix (Rows=Frames, Cols=Neurons)
  166. # Header: time, unit_1_pxl, unit_2_pxl, ...
  167. header = ["frame"] + [f"unit_{p:.2f}" for p in self.phi]
  169. with open(f"{prefix}_activity.csv", "w", newline="") as f:
  170. writer = csv.writer(f)
  171. writer.writerow(header)
  172. for i, row in enumerate(self.history_x):
  173. writer.writerow([i] + list(row))
  175. # New: Detailed Input CSV
  176. header = ["frame", "type"] + [f"unit_{p:.2f}" for p in self.phi]
  177. with open(f"{prefix}_inputs.csv", "w", newline="") as f:
  178. writer = csv.writer(f)
  179. writer.writerow(header)
  180. for i in range(len(self.history_I_total)):
  181. # Write three rows per frame so she can filter by 'type'
  182. writer.writerow([i, "total"] + list(self.history_I_total[i]))
  183. writer.writerow([i, "gaze_inhibition"] + list(self.history_I_gaze[i]))
  184. writer.writerow([i, "prior"] + list(self.history_I_prior[i]))
  186. # 3. Save Summary Dynamics (For Phase Portrait)
  187. with open(f"{prefix}_dynamics.csv", "w", newline="") as f:
  188. writer = csv.writer(f)
  189. writer.writerow(["frame", "theta_hat", "d_theta_dt"])
  190. thetas = self.history_theta
  191. for i in range(len(thetas)):
  192. d_dt = (thetas[i] - thetas[i-1]) if i > 0 else 0
  193. writer.writerow([i, thetas[i], d_dt])
  195. print(f"Data exported to {prefix}_activity.csv, _inputs.csv, and _dynamics.csv")
  197. def save_plots(self, filename="diagnostic_plots.png",px2deg=1.0):
  198. if not self.history_x: return
  200. X = np.array(self.history_x)
  201. I_total = np.array(self.history_I_total)
  202. I_gaze = np.array(self.history_I_gaze)
  203. I_prior = np.array(self.history_I_prior)
  204. thetas = np.array(self.history_theta)
  206. fig, axes = plt.subplots(2, 2, figsize=(12, 10))
  208. # 1. Kymograph (Space-Time Heatmap)
  209. ax = axes[0, 0]
  210. y_min = self.phi[0] * px2deg
  211. y_max = self.phi[-1] * px2deg
  212. im = ax.imshow(X.T, aspect='auto', extent=[0, len(X), y_min, y_max], origin='lower', cmap='viridis')
  213. ax.plot(thetas*px2deg, color='white', linestyle='--', alpha=0.5, label='Decoded Heading')
  214. ax.set_title("Kymograph (Neural Activity over Time)")
  215. ax.set_ylabel("Neuron Preferred Heading (pixels)")
  216. ax.set_xlabel("Frame Index")
  217. # --- TO RESTRICT THE VIEW ---
  218. #ax.set_ylim(-90, 90)
  219. plt.colorbar(im, ax=ax)
  221. # 2. Phase Portrait (Delta Theta vs Theta)
  222. ax = axes[0, 1]
  223. d_theta = np.diff(thetas)
  224. ax.scatter(thetas[:-1], d_theta, c=np.arange(len(d_theta)), cmap='plasma', s=5, alpha=0.6)
  225. ax.axhline(0, color='black', lw=1)
  226. ax.set_title("Phase Portrait (Drift Dynamics)")
  227. ax.set_xlabel("Heading Estimate (theta -pixels-)")
  228. ax.set_ylabel("Change in Heading (d_theta/dt)")
  230. # 3. Snapshot of Input vs Activity (Final Frame)
  231. # This is the "Mechanistic Proof" showing the balance of forces
  232. ax = axes[1, 0]
  233. phi_deg = self.phi * px2deg
  235. # Plot Neural Activity (The Result)
  236. #ax.plot(phi_deg, X[-1] / (np.max(X[-1]) + 1e-9), label='Neural Activity (Bump)', color='black', lw=3)
  237. ax.plot(phi_deg, I_total[-1] / (np.max(I_total[-1]) + 1e-9), label='Neural Activity (Bump)', color='black', lw=3)
  238. # Plot Gaze Inhibition (The Pull/Sensory) - Normalize to show shape
  239. ax.plot(phi_deg, I_gaze[-1] / (np.max(np.abs(I_gaze[-1])) + 1e-9),
  240. label='Gaze Inhibition (Pull)', color='red', linestyle='--', alpha=0.8)
  242. # Plot Prior (The Push/Internal) - Normalize to show shape
  243. ax.plot(phi_deg, I_prior[-1] / (np.max(np.abs(I_prior[-1])) + 1e-9),
  244. label='Straight-Ahead Prior (Push)', color='blue', linestyle=':', alpha=0.8)
  246. ax.axvline(0, color='gray', lw=0.5, alpha=0.5) # Center line
  247. ax.set_title("Mechanism: Sensory-Prior Competition")
  248. ax.set_xlabel("Ring Position (deg)")
  249. ax.set_ylabel("Normalized Amplitude")
  250. ax.legend(fontsize='small', loc='upper right')
  252. # 4. Circular Variance (Coherence of the bump)
  253. ax = axes[1, 1]
  254. # Calculate coherence: R = |sum(x * exp(i*phi))| / sum(x)
  255. ang = 2 * np.pi * (self.phi - self.phi[0]) / (self.phi[-1] - self.phi[0])
  256. z = np.array([np.sum(xt * np.exp(1j * ang)) / np.sum(xt) for xt in X])
  257. coherence = np.abs(z)
  258. ax.plot(coherence, color='blue')
  259. ax.set_ylim([0, 1.1])
  260. ax.set_title("Bump Coherence (1 - Circular Variance)")
  261. ax.set_ylabel("Coherence (0 to 1)")
  262. ax.set_xlabel("Frame Index")
  264. plt.tight_layout()
  265. plt.savefig(filename)
  266. print(f"Analysis plots saved to {filename}")
  269. # ---------------------------- Sampling ------------------------------- #
  271. def sample_points_relative_cam(h: int, w: int, N: int, R_pixels: float, seed: int = 42) -> np.ndarray:
  272. rng = np.random.default_rng(seed)
  273. pts = []
  274. Rint = max(1, int(round(R_pixels)))
  275. tries = 0
  276. while len(pts) < N and tries < 300 * N:
  277. dx = rng.integers(-Rint, Rint + 1)
  278. dy = rng.integers(-Rint, Rint + 1)
  279. if dx*dx + dy*dy <= R_pixels*R_pixels:
  280. pts.append((int(dx), int(dy)))
  281. tries += 1
  282. while len(pts) < N:
  283. pts.append((0, 0))
  284. return np.array(pts, dtype=np.int32)
  286. # --------------------------- MT-like encode -------------------------- #
  288. angles = np.deg2rad(np.arange(0, 360, 45, dtype=np.float32))
  289. E_DIRS = np.stack([np.cos(angles), np.sin(angles)], axis=1).astype(np.float32) # (8,2)
  291. def encode_direction_pools(flow_xy: np.ndarray, points_abs: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
  292. """Rectified cosine energy in 8 sectors at the absolute points (MT-like pools)."""
  293. N = points_abs.shape[0]
  294. H, W = flow_xy.shape[:2]
  295. xs = np.clip(points_abs[:, 0], 0, W - 1)
  296. ys = np.clip(points_abs[:, 1], 0, H - 1)
  297. uvs = flow_xy[ys, xs, :].astype(np.float32) # (N,2)
  298. mk = np.maximum(0.0, uvs @ E_DIRS.T) # (N,8) mk: 8 numbers per sample, showing how much motion aligns with each direction
  299. spd = np.sqrt(np.sum(uvs**2, axis=1) + 1e-8) # overall speed at each sample
  300. return mk, spd
  302. def vector_from_sectors(m: np.ndarray, eps: float = 1e-6) -> np.ndarray:
  303. """Estimate a 2D velocity vector from 8 sector energies for each sample."""
  304. total = np.sum(m, axis=1, keepdims=True) + eps
  305. v = (m @ E_DIRS) / total # (N,2)
  306. return v
  308. # ------------------------ MSTd-like curl code ------------------------ #
  310. @dataclass
  311. class CurlCode:
  312. omega_bar: float # signed mean tangential component around gaze
  313. mean_speed: float # mean |v| from sector reconstruction
  314. n_used: int # number of samples used (excludes near-center)
  316. def curl_from_tangential(mk: np.ndarray, points_abs: np.ndarray, gaze_xy: Tuple[float, float],
  317. r_min_px: float = 4.0, trim_q: float = 0.1, eps: float = 1e-6) -> CurlCode:
  318. """Compute a gaze-centered curl proxy via tangential projection."""
  319. v_est = vector_from_sectors(mk) # (N,2)
  320. gx, gy = gaze_xy
  321. r = points_abs.astype(np.float32) - np.array([[gx, gy]], dtype=np.float32) # (N,2)
  322. r2 = np.sum(r*r, axis=1)
  323. keep = r2 > (r_min_px * r_min_px)
  324. r = r[keep]
  325. v = v_est[keep]
  326. if r.shape[0] == 0:
  327. return CurlCode(omega_bar=0.0, mean_speed=0.0, n_used=0)
  328. r_norm = np.sqrt(np.sum(r*r, axis=1, keepdims=True)) + eps
  329. t_hat = np.concatenate([-r[:, 1:2], r[:, 0:1]], axis=1) / r_norm
  330. omega_samples = np.sum(v * t_hat, axis=1)
  332. # to correct discrepancy for distances
  333. #mean_eccentricity = np.mean(r_norm)
  334. #omega_samples = omega_samples / (mean_eccentricity + eps)
  337. # DEBUG: Check if sign matches expected biological convention
  338. #gaze_az_px = gx - (400/2) # Approximate gaze azimuth
  339. #print(f"DEBUG: Gaze az: {gaze_az_px:+.1f}, mean omega: {np.mean(omega_samples):+.4f}")
  341. ql, qh = np.quantile(omega_samples, [trim_q, 1 - trim_q])
  342. mask = (omega_samples >= ql) & (omega_samples <= qh)
  343. if np.any(mask):
  344. omega_bar = float(np.mean(omega_samples[mask]))
  345. else:
  346. omega_bar = float(np.mean(omega_samples))
  347. mean_speed = float(np.mean(np.sqrt(np.sum(v*v, axis=1))))
  348. return CurlCode(omega_bar=omega_bar, mean_speed=mean_speed, n_used=int(r.shape[0]))
  350. # ------------------------ Ring-attractor dynamics -------------------- #
  352. @dataclass
  353. class RingParams:
  354. n_units: int
  355. az_range_px: float # ring spans [-az_range_px, +az_range_px]
  356. tau: float # time constant (seconds)
  357. recurrent_gain: float
  358. sigma_exc: float # px
  359. sigma_inh: float # px
  360. sigma_kappa: float # width of gaze input lobe (px)
  361. asymmetry_strength: float # New: controls push-pull asymmetry
  363. class RingAttractor:
  364. def __init__(self, params: RingParams, seed: int = 0):
  365. self.p = params
  366. self.phi = np.linspace(-self.p.az_range_px, self.p.az_range_px, self.p.n_units, endpoint=False).astype(np.float32)
  368. # Create asymmetric Mexican hat connectivity for natural push-pull
  369. W = self._create_asymmetric_connectivity()
  370. self.W = W
  372. # Store connectivity patterns for visualization
  373. self.connection_profiles = self._compute_connection_profiles()
  375. # Seed a centered bump
  376. d0 = np.array([self._circ_dist(phi_i, 0.0) for phi_i in self.phi], dtype=np.float32)
  377. self.x = np.exp(-(d0**2) / (2 * (self.p.sigma_exc**2) + 1e-6)).astype(np.float32)
  378. self.x /= (np.max(self.x) + 1e-6)
  380. def _create_asymmetric_connectivity(self) -> np.ndarray:
  381. d = self._circ_dist_matrix(self.phi)
  383. # Base Mexican hat
  384. Ae = 1.9 # Excitatory amplitude
  385. Ai = 1.0 # Inhibitory amplitude
  387. Wexc = Ae * np.exp(-(d**2) / (2 * (self.p.sigma_exc**2) + 1e-6))
  388. Winh = Ai * np.exp(-(d**2) / (2 * (self.p.sigma_inh**2) + 1e-6))
  389. W_base = Wexc - Winh
  391. # Wexc = np.exp(-(d**2) / (2 * (self.p.sigma_exc**2) + 1e-6))
  392. # Winh = np.exp(-(d**2) / (2 * (self.p.sigma_inh**2) + 1e-6))
  393. # W_base = Wexc - Winh
  395. # More pronounced asymmetry: directional bias
  396. asymmetry_mod = np.ones_like(W_base)
  397. center_idx = self.p.n_units // 2
  399. for i in range(self.p.n_units):
  400. for j in range(self.p.n_units):
  401. # Create left-right asymmetry based on position relative to center
  402. if self.phi[j] > self.phi[i]: # j is right of i
  403. if W_base[i, j] < 0: # inhibitory connection
  404. asymmetry_mod[i, j] += self.p.asymmetry_strength#*sign_lr
  405. elif self.phi[j] < self.phi[i]: # j is left of i
  406. if W_base[i, j] < 0: # inhibitory connection
  407. asymmetry_mod[i, j] += self.p.asymmetry_strength*.5 #sign_lr # *.5 weaker
  409. W_asym = W_base * asymmetry_mod
  411. # Normalize to control stability
  412. v = np.random.default_rng(seed=42).standard_normal(size=(self.p.n_units, 1)).astype(np.float32)
  413. for _ in range(25):
  414. v = W_asym @ v
  415. v_norm = np.linalg.norm(v) + 1e-6
  416. v /= v_norm
  417. #lam = float((v.T @ (W_asym @ v)) / (v.T @ v)) # gives a warning
  418. lam = ((v.T @ (W_asym @ v)) / (v.T @ v)).item()
  419. W_normalized = (self.p.recurrent_gain / (abs(lam) + 1e-6)) * W_asym
  421. return W_normalized.astype(np.float32)
  423. def _compute_connection_profiles(self) -> dict:
  424. """Compute connection patterns for visualization."""
  425. profiles = {}
  427. # Profile from center unit
  428. center_idx = self.p.n_units // 2
  429. profiles['from_center'] = self.W[center_idx, :]
  431. # Profile from left unit (negative azimuth)
  432. left_idx = int(self.p.n_units * 0.25)
  433. profiles['from_left'] = self.W[left_idx, :]
  435. # Profile from right unit (positive azimuth)
  436. right_idx = int(self.p.n_units * 0.75)
  437. profiles['from_right'] = self.W[right_idx, :]
  439. return profiles
  441. @staticmethod
  442. def _circ_dist_matrix(phi: np.ndarray) -> np.ndarray:
  443. R = float(np.max(phi) - np.min(phi)) / 2.0
  444. ang = 2 * np.pi * (phi - (-R)) / (2 * R + 1e-9)
  445. diff = ang[:, None] - ang[None, :]
  446. diff = (diff + np.pi) % (2 * np.pi) - np.pi
  447. d = np.abs(diff) * (R / np.pi)
  448. return d.astype(np.float32)
  450. def _circ_dist(self, a: float, b: float) -> float:
  451. R = float(self.p.az_range_px)
  452. ang_a = 2 * np.pi * (a - (-R)) / (2 * R + 1e-9)
  453. ang_b = 2 * np.pi * (b - (-R)) / (2 * R + 1e-9)
  454. d = (ang_a - ang_b + np.pi) % (2 * np.pi) - np.pi
  455. return float(abs(d) * (R / np.pi))
  457. def step(self, dt: float, omega_bar: float, gaze_az_px: float, Kp: float,
  458. noise_std: float = 0.0, *,
  459. I0: float = 0.0, sigma_prior: Optional[float] = None, theta_prior_px: float = 0.0):
  460. """Step the ring dynamics """
  462. # Only gaze-centered inhibitory input
  463. d_g = np.array([self._circ_dist(phi_i, gaze_az_px) for phi_i in self.phi], dtype=np.float32)
  464. kappa_gaze = np.exp(-(d_g**2) / (2 * (self.p.sigma_kappa**2) + 1e-6))
  466. #I = (-Kp * float(omega_bar)) * kappa_gaze
  467. # Always inhibit at gaze position, use |ω̄| for strength
  469. I_gaze = (-Kp * abs(float(omega_bar))) * kappa_gaze # I_gaze,j in equation
  472. # Baseline prior (straight-ahead expectation)
  473. #if I0 > 0.0:
  474. if sigma_prior is None:
  475. sigma_prior = self.p.sigma_kappa
  476. d_p = np.array([self._circ_dist(phi_i, theta_prior_px) for phi_i in self.phi], dtype=np.float32)
  477. I_prior = I0 * np.exp(-(d_p**2) / (2 * (sigma_prior**2) + 1e-6))
  478. I_total = I_gaze + I_prior
  480. if noise_std > 0:
  481. I_total += np.random.normal(0.0, noise_std, size=I_total.shape).astype(np.float32)
  483. # Euler update - push-pull emerges from recurrent weights
  484. xdot = -self.x + (self.W @ self.x) + I_total
  485. self.x = self.x + (dt / self.p.tau) * xdot
  486. #print(f"I0={I0}, max_activity={np.max(self.x)}, bump_pos={self.decode_theta_px()}")
  488. # Rectify & mild normalization
  489. # TEMPORARILY REMOVE:
  490. self.x = np.maximum(self.x, 0.0)
  492. total = np.sum(self.x)
  493. if total > 1e-6:
  494. self.x /= (1.0 + 0.0 * total)
  496. return I_total, I_gaze, I_prior
  498. def decode_theta_px(self) -> float:
  499. R = float(self.p.az_range_px)
  500. ang = 2 * np.pi * (self.phi - (-R)) / (2 * R + 1e-9)
  501. z = np.sum(self.x * np.exp(1j * ang))
  502. if np.abs(z) < 1e-9:
  503. return 0.0
  504. ang_mean = float(np.angle(z))
  505. theta_px = -R + (ang_mean % (2 * np.pi)) * (2 * R) / (2 * np.pi)
  506. if theta_px > R:
  507. theta_px -= 2 * R
  508. return float(theta_px)
  512. # --------------------------- Visualization ---------------------------- #
  514. def _render_connectivity_panel(width: int, height: int, ring: RingAttractor,
  515. gaze_az_px: float, omega_bar: float, Kp: float,
  516. I0: float, sigma_prior: float) -> np.ndarray:
  517. """Simplified visualization showing only essential inputs and activity."""
  518. panel = np.full((height, width, 3), 40, dtype=np.uint8)
  520. n_units = ring.p.n_units
  521. phi = ring.phi
  523. # Normalize for display
  524. def normalize_profile(prof):
  525. prof = prof.copy()
  526. max_val = np.max(np.abs(prof)) + 1e-6
  527. return np.clip(prof / max_val, 0, 1)
  529. xs = np.linspace(0, width-1, n_units).astype(np.int32)
  531. # 1. Current neural activity (most important)
  532. activity_norm = normalize_profile(ring.x)
  534. # 2. Input profiles (simplified)
  535. d_g = np.array([ring._circ_dist(phi_i, gaze_az_px) for phi_i in phi], dtype=np.float32)
  536. kappa_gaze = np.exp(-(d_g**2) / (2 * (ring.p.sigma_kappa**2) + 1e-6))
  537. gaze_input = (-Kp * float(omega_bar)) * kappa_gaze
  538. gaze_norm = normalize_profile(gaze_input)
  540. # Prior input (only show if significant)
  541. if I0 > 0.1: # Only show prior if it's substantial
  542. d_p = np.array([ring._circ_dist(phi_i, 0.0) for phi_i in phi], dtype=np.float32)
  543. prior_input = I0 * np.exp(-(d_p**2) / (2 * (sigma_prior**2) + 1e-6))
  544. prior_norm = normalize_profile(prior_input)
  545. else:
  546. prior_norm = np.zeros_like(phi)
  548. # Plot in single row: activity + inputs
  549. row_height = height - 20
  550. y_offset = 10
  552. # Neural activity (white - most important)
  553. for i in range(n_units-1):
  554. y1 = int((1.0 - activity_norm[i]) * row_height + y_offset)
  555. y2 = int((1.0 - activity_norm[i+1]) * row_height + y_offset)
  556. cv2.line(panel, (xs[i], y1), (xs[i+1], y2), (255, 255, 255), 2, cv2.LINE_AA)
  558. # Gaze input (red)
  559. for i in range(n_units-1):
  560. y1 = int((1.0 - gaze_norm[i]) * row_height + y_offset)
  561. y2 = int((1.0 - gaze_norm[i+1]) * row_height + y_offset)
  562. cv2.line(panel, (xs[i], y1), (xs[i+1], y2), (0, 0, 200), 1, cv2.LINE_AA)
  564. # Prior input (gray, only if significant)
  565. if I0 > 0.1:
  566. for i in range(n_units-1):
  567. y1 = int((1.0 - prior_norm[i]) * row_height + y_offset)
  568. y2 = int((1.0 - prior_norm[i+1]) * row_height + y_offset)
  569. cv2.line(panel, (xs[i], y1), (xs[i+1], y2), (100, 100, 100), 1, cv2.LINE_AA)
  571. # Add vertical line at gaze position
  572. gaze_idx = np.argmin(np.abs(phi - gaze_az_px))
  573. gaze_x = xs[gaze_idx]
  574. cv2.line(panel, (gaze_x, y_offset), (gaze_x, y_offset + row_height), (0, 255, 255), 1)
  576. # Add vertical line at current heading
  577. theta_px = ring.decode_theta_px()
  578. theta_idx = np.argmin(np.abs(phi - theta_px))
  579. theta_x = xs[theta_idx]
  580. cv2.line(panel, (theta_x, y_offset), (theta_x, y_offset + row_height), (0, 0, 255), 1)
  582. # Simple labels
  583. cv2.putText(panel, "Activity(white) GazeIn(red) Gaze|->(yellow) Heading|->(red)",
  584. (5, height-5), cv2.FONT_HERSHEY_SIMPLEX, 0.3, (255,255,255), 1)
  586. # Border
  587. cv2.rectangle(panel, (0,0), (width-1, height-1), (80,80,80), 1)
  589. overlay = cv2.cvtColor(panel, cv2.COLOR_BGR2BGRA)
  590. overlay[:, :, 3] = int(0.8 * 255)
  591. return overlay
  592. # --------------------------- Main routine ---------------------------- #
  595. def run(
  596. video_path: str,
  597. gaze_csv: Optional[str],
  598. output_csv: str,
  599. display: bool,
  600. step: int,
  601. resize_width: int,
  602. sample_count: int,
  603. sample_radius_frac: float,
  604. pyr_scale: float,
  605. levels: int,
  606. winsize: int,
  607. iterations: int,
  608. poly_n: int,
  609. poly_sigma: float,
  610. seed: int,
  611. Kp: float,
  612. smooth_alpha: float,
  613. omega_sign: float,
  614. # Ring params
  615. n_units: int,
  616. az_range_frac: float,
  617. tau_ms: float,
  618. recurrent_gain: float,
  619. sigma_exc_frac: float,
  620. sigma_inh_frac: float,
  621. sigma_kappa_frac: float,
  622. asymmetry_strength: float,
  623. I0: float,
  624. sigma_prior_frac: float,
  625. noise_std: float,
  626. show_kappa: bool,
  627. ):
  629. if not os.path.isfile(video_path):
  630. raise FileNotFoundError(f"Cannot find video: {video_path}")
  632. # 1. Extract the name (e.g., 'trial_0' from 'path/to/trial_0.mp4')
  633. video_base_name = os.path.splitext(os.path.basename(video_path))[0]
  635. gaze_data = load_gaze_csv(gaze_csv) if gaze_csv else None
  637. cap = cv2.VideoCapture(video_path)
  638. if not cap.isOpened():
  639. raise FileNotFoundError(f"Cannot open video: {video_path}")
  641. ok, frame0 = cap.read()
  642. if not ok:
  643. raise RuntimeError("Empty video or cannot read first frame.")
  645. fps = cap.get(cv2.CAP_PROP_FPS) # usually 30 fps
  646. if fps <= 1e-3 or math.isnan(fps):
  647. fps = 60.0
  648. dt_frame = float(step) / float(fps)
  650. if resize_width > 0 and frame0.shape[1] != resize_width:
  651. scale = resize_width / frame0.shape[1]
  652. frame0 = cv2.resize(frame0, (int(frame0.shape[1] * scale), int(frame0.shape[0] * scale)), interpolation=cv2.INTER_AREA)
  653. gray0 = cv2.cvtColor(frame0, cv2.COLOR_BGR2GRAY)
  654. h, w = gray0.shape[:2]
  656. cx_cam = w / 2.0
  657. cy_cam = h / 2.0
  659. R_samples = sample_radius_frac * min(h, w) * 0.5
  660. points_rel_cam = sample_points_relative_cam(h, w, sample_count, R_pixels=R_samples, seed=seed)
  662. # Define your camera's horizontal FOV (e.g., 90 degrees)
  663. H_FOV = 100.0
  664. # Redefine the ring to span -90 to 90 degrees instead of pixels
  666. az_range_px = az_range_frac * (w * 0.5) # 0.9 -> 360 default
  667. az_range_px2deg = ((H_FOV/2)/(w/2))
  669. sigma_exc = sigma_exc_frac * az_range_px # sigma 0.10 default
  670. sigma_inh = sigma_inh_frac * az_range_px # sigma 0.3 default
  671. sigma_kappa = sigma_kappa_frac * az_range_px # sigma_kappa controls the SPATIAL SPREAD of the gaze-centered inhibition.
  672. #Small sigma_kappa: Narrow Gaussian → Localized inhibition only at exact gaze position
  674. I0 = max(I0, 1e-6) # Ensure some minimal prior
  675. asymmetry_strength = min(asymmetry_strength,1.0) # max value of 1
  676. sigma_prior = sigma_prior_frac * az_range_px #az_range_px
  678. ring = RingAttractor(
  679. RingParams(
  680. n_units=n_units, # default 180
  681. az_range_px=az_range_px, #az_range_px,
  682. tau=float(tau_ms) / 1000.0, # time constant
  683. recurrent_gain=recurrent_gain,
  684. sigma_exc=sigma_exc,
  685. sigma_inh=sigma_inh,
  686. sigma_kappa=sigma_kappa,
  687. asymmetry_strength=asymmetry_strength,
  688. ),
  689. seed=seed,
  690. )
  691. #print(ring.phi)
  692. collector = DataCollector(ring.phi)
  694. os.makedirs(os.path.dirname(output_csv) or ".", exist_ok=True)
  695. writer = csv.writer(open(output_csv, "w", newline=""))
  696. writer.writerow([
  697. "frame_proc", "frame_abs",
  698. "theta_px", "pred_px",
  699. "omega_bar", "mean_speed", "n_used", "asymmetry_strength","I0",
  700. "cx_gaze", "cy_gaze"
  701. ])
  703. prev_gray = gray0
  704. abs_frame_idx = 0
  705. proc_frame_idx = 0
  706. last_valid_gaze: Optional[Tuple[float, float]] = None
  707. omega_prev: Optional[float] = None
  709. color_pts = (200, 200, 200)
  710. color_pred = (0, 0, 255)
  711. color_gaze = (0, 255, 255)
  713. while True:
  714. video_ended = False
  715. for _ in range(step):
  716. ok, frame = cap.read()
  717. abs_frame_idx += 1
  718. if not ok:
  719. video_ended = True
  720. break # break for
  721. #cap.release()
  722. #if display:
  723. # cv2.destroyAllWindows()
  724. #return
  725. if video_ended:
  726. print("End of video reached.")
  727. break # break while
  728. if resize_width > 0 and frame.shape[1] != resize_width:
  729. scale = resize_width / frame.shape[1]
  730. frame = cv2.resize(frame, (int(frame.shape[1] * scale), int(frame.shape[0] * scale)), interpolation=cv2.INTER_AREA)
  731. gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
  733. cx_gaze, cy_gaze, last_valid_gaze = get_gaze_for_abs_frame(
  734. gaze_data, abs_frame_idx, w, h, last_valid_gaze
  735. )
  737. flow = cv2.calcOpticalFlowFarneback( # compute flow field
  738. prev_gray, gray, None,
  739. pyr_scale=pyr_scale, levels=levels, winsize=winsize,
  740. iterations=iterations, poly_n=poly_n, poly_sigma=poly_sigma, flags=0
  741. )
  743. points_abs = np.empty_like(points_rel_cam)
  744. points_abs[:, 0] = np.round(points_rel_cam[:, 0] + cx_gaze).astype(np.int32)
  745. points_abs[:, 1] = np.round(points_rel_cam[:, 1] + cy_gaze).astype(np.int32)
  746. points_abs[:, 0] = np.clip(points_abs[:, 0], 0, w - 1)
  747. points_abs[:, 1] = np.clip(points_abs[:, 1], 0, h - 1)
  749. mk, spd = encode_direction_pools(flow, points_abs) # mt-like motion computation
  751. curl = curl_from_tangential(mk, points_abs, (cx_gaze, cy_gaze)) # compute curl
  752. omega = curl.omega_bar
  753. omega *= float(omega_sign) # mean curl
  755. if smooth_alpha > 0.0 and omega_prev is not None: # default 0.15
  756. omega = (1.0 - smooth_alpha) * omega_prev + smooth_alpha * omega
  757. omega_prev = omega
  759. gaze_az_px = float(cx_gaze - cx_cam) # Gaze horizontal position relative to image center in pixel coordinates of the ring attractor space
  760. #gaze_az_deg = math.degrees(math.atan(gaze_az_px / focal_length_px))
  761. #print(gaze_az_deg)
  763. # we pass now gaze_az_deg
  764. I_total, I_gaze, I_prior = ring.step(
  765. dt=dt_frame, omega_bar=omega, gaze_az_px=gaze_az_px, Kp=Kp, noise_std=noise_std,
  766. I0=I0, sigma_prior=sigma_prior, theta_prior_px=0.0,
  767. )
  769. theta_px = ring.decode_theta_px()
  770. pred_px = cx_cam + theta_px
  772. # Collect data for plotting
  773. collector.collect(x=ring.x, I_total=I_total, I_gaze=I_gaze, I_prior=I_prior, theta=theta_px)
  775. # writer.writerow([
  776. # proc_frame_idx, abs_frame_idx,
  777. # theta_px, pred_px,
  778. # omega, curl.mean_speed, curl.n_used, asymmetry_strength,
  779. # cx_gaze, cy_gaze
  780. # ])
  782. writer.writerow([
  783. proc_frame_idx,
  784. abs_frame_idx,
  785. f"{theta_px:.3f}",
  786. f"{pred_px:.3f}",
  787. f"{omega:.3f}",
  788. f"{curl.mean_speed:.3f}",
  789. curl.n_used,
  790. f"{asymmetry_strength:.1f}",
  791. f"{I0:.3f}",
  792. f"{cx_gaze:.3f}",
  793. f"{cy_gaze:.3f}",
  794. ])
  796. if display:
  797. vis = frame.copy()
  799. # Draw sample points
  800. for (x, y) in points_abs:
  801. cv2.circle(vis, (int(x), int(y)), 1, color_pts, -1)
  803. # Draw gaze point
  804. cv2.circle(vis, (int(round(cx_gaze)), int(round(cy_gaze))), 4, color_gaze, -1)
  806. # Draw heading prediction (red circle on the horizontal midline)
  807. cy_mid = int(round(cy_cam))
  808. cv2.circle(vis, (int(round(pred_px)), cy_mid), 6, color_pred, 2)
  810. # Add HUD text
  811. cv2.putText(vis, f"Proc {proc_frame_idx} | Abs {abs_frame_idx}", (10, 20),
  812. cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0,0,0), 2)
  813. cv2.putText(vis, f"omega={omega:+.4f} theta_px={theta_px:+.1f}", (10, 40),
  814. cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0,0,0), 2)
  815. cv2.putText(vis, f"Kp={Kp:.3f} asym={asymmetry_strength:.2f} n={ring.p.n_units}", (10, 60),
  816. cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0,0,0), 2)
  818. if show_kappa:
  819. # Use the new connectivity visualization
  820. panel = _render_connectivity_panel(
  821. width=400, height=200, ring=ring,
  822. gaze_az_px=gaze_az_px, omega_bar=omega, Kp=Kp,
  823. I0=I0, sigma_prior=sigma_prior
  824. )
  826. ph, pw = panel.shape[:2]
  827. y0 = max(0, vis.shape[0]-ph-8)
  828. x0 = 8
  829. roi = vis[y0:y0+ph, x0:x0+pw]
  830. if panel.shape[2] == 4:
  831. alpha = panel[:, :, 3:4] / 255.0
  832. roi[:] = (alpha * panel[:, :, :3] + (1 - alpha) * roi).astype(np.uint8)
  833. else:
  834. roi[:] = panel
  836. # Show the main visualization window
  837. cv2.imshow("Neural ring - recurrent push-pull", vis)
  838. key = cv2.waitKey(1) & 0xFF
  839. if key == 27 or key == ord('q'):
  840. break
  842. prev_gray = gray
  843. proc_frame_idx += 1
  844. print(f"Finalizing... saving plots to heading_analysis_results.png")
  845. #collector.save_plots("heading_analysis_results.png",px2deg=az_range_px2deg)
  846. collector.save_plots(f"{video_base_name}_plots.png")
  847. collector.export_to_csv(video_base_name)
  848. # Also save the connectivity for the weight profile
  849. np.savetxt(f"{video_base_name}_connectivity.csv",
  850. ring.W[ring.p.n_units // 2, :], delimiter=",")
  852. cap.release()
  854. if display:
  855. cv2.destroyAllWindows()
  856. # --------------------------- CLI entrypoint -------------------------- #
  858. def parse_args():
  859. p = argparse.ArgumentParser(
  860. description="Neural heading estimator with recurrent push-pull (no Kaway)"
  861. )
  862. p.add_argument("--video", required=True, help="Path to input video file")
  863. p.add_argument("--gaze_csv", default=None, help="Optional CSV with x_px_ui,y_px_ui,(optional)visible")
  864. p.add_argument("--output_csv", default="heading_recurrent_pp.csv", help="Output CSV path")
  865. p.add_argument("--display", action="store_true", help="Show visualization window")
  867. # Frame processing
  868. p.add_argument("--step", type=int, default=1, help="Process every Nth frame")
  869. p.add_argument("--resize_width", type=int, default=0, help="Resize frames to this width (0=off)")
  871. # Sampling near gaze
  872. p.add_argument("--sample_count", type=int, default=400, help="Number of gaze-centered sample points")
  873. p.add_argument("--sample_radius_frac", type=float, default=0.85, help="Sampling radius as fraction of min(h,w)/2")
  875. # Farnebäck params
  876. p.add_argument("--pyr_scale", type=float, default=0.5)
  877. p.add_argument("--levels", type=int, default=3)
  878. p.add_argument("--winsize", type=int, default=15)
  879. p.add_argument("--iterations", type=int, default=3)
  880. p.add_argument("--poly_n", type=int, default=5)
  881. p.add_argument("--poly_sigma", type=float, default=1.2)
  883. # Controller gain & sign
  884. p.add_argument("--Kp", type=float, default=0.4, help="Coupling from ω̄ to gaze-centered inhibitory lobe")
  885. p.add_argument("--omega_sign", type=float, default=1.0, help="Multiply ω̄ by this sign (+1 or -1)")
  887. # Smoothing
  888. p.add_argument("--smooth_alpha", type=float, default=0.15, help="EMA for ω̄ (0 disables)")
  890. # Ring params
  891. p.add_argument("--n_units", type=int, default=181, help="Number of ring units")
  892. p.add_argument("--az_range_frac", type=float, default=0.9, help="Heading range as fraction of half image width")
  893. p.add_argument("--az_range_deg", type=float, default=90.0, help="Heading range as deg (close to screen degs)")
  894. p.add_argument("--tau_ms", type=float, default=60.0, help="Ring time constant (ms)")
  895. p.add_argument("--recurrent_gain", type=float, default=0.95, help="Recurrent gain (stability <~1)")
  896. p.add_argument("--sigma_exc_frac", type=float, default=0.10, help="Excitatory kernel width (fraction of az_range_px)")
  897. p.add_argument("--sigma_inh_frac", type=float, default=0.35, help="Inhibitory kernel width (fraction of az_range_px)")
  898. p.add_argument("--sigma_kappa_frac", type=float, default=0.12, help="Input lobe width (fraction of az_range_px)")
  900. # New parameter for push-pull asymmetry
  901. p.add_argument("--asymmetry_strength", type=float, default=0.0,
  902. help="Strength of asymmetric connectivity for push-pull (0=symmetric, 0.3=moderate asymmetry)")
  904. # Baseline prior
  905. p.add_argument("--I0", type=float, default=0.12, help="Baseline prior amplitude (Gaussian at straight-ahead)")
  906. p.add_argument("--sigma_prior_frac", type=float, default=0.18, help="Baseline prior width (fraction of az_range_px)")
  908. p.add_argument("--noise_std", type=float, default=0.0, help="Additive input noise std")
  909. p.add_argument("--show_kappa", action="store_true", help="Show input lobe profiles")
  910. p.add_argument("--seed", type=int, default=42, help="RNG seed")
  912. return p.parse_args()
  914. if __name__ == "__main__":
  915. args = parse_args()
  916. run(
  917. video_path=args.video,
  918. gaze_csv=args.gaze_csv,
  919. output_csv=args.output_csv,
  920. display=args.display,
  921. step=args.step,
  922. resize_width=args.resize_width,
  923. sample_count=args.sample_count,
  924. sample_radius_frac=args.sample_radius_frac,
  925. pyr_scale=args.pyr_scale,
  926. levels=args.levels,
  927. winsize=args.winsize,
  928. iterations=args.iterations,
  929. poly_n=args.poly_n,
  930. poly_sigma=args.poly_sigma,
  931. seed=args.seed,
  932. Kp=args.Kp,
  933. smooth_alpha=args.smooth_alpha,
  934. omega_sign=args.omega_sign,
  935. n_units=args.n_units,
  936. az_range_frac=args.az_range_frac,
  937. tau_ms=args.tau_ms,
  938. recurrent_gain=args.recurrent_gain,
  939. sigma_exc_frac=args.sigma_exc_frac,
  940. sigma_inh_frac=args.sigma_inh_frac,
  941. sigma_kappa_frac=args.sigma_kappa_frac,
  942. asymmetry_strength=args.asymmetry_strength, # New argument
  943. I0=args.I0,
  944. sigma_prior_frac=args.sigma_prior_frac,
  945. noise_std=args.noise_std,
  946. show_kappa=args.show_kappa,
  947. )

ring_attractor_heading_v1.py, no license · at the source

Overview

Authors: Kontessa I Zorpala1, Joan López-Moliner1
ORCID iDs: Joan López-Moliner
  1. Vision and Control of Action Group, Department of Cognition, Development and Psychology of Education and Institute of Neurosciences, Universitat de Barcelona, Barcelona, Spain
Institutions: Universitat de Barcelona (Spain)
Journal: eLife, volume 15, article RP110770
Dates: published online 25 September 2026
Type: Research article · Language: English
License: CC BY
Identifiers: DOI 10.7554/elife.110770 · PMID 42788718 · PMCID PMC13614786 · OpenAlex W7154654837
Open access: gold, a free copy (OpenAlex)
Status: code verified (how the code is found and verified)
Categories: behavior only (modality), human (organism), cognitive (subfield)
Methods: Connectivity, Spectral & time-frequency, Smoothing, state filtering, decompositions, Physiology & signal measures
Keywords: Human
MeSH: Eye Movements*, Fixation, Ocular*, Motion Perception*, Retina*, Adult, Female, Humans (* major topic)
Topic: Visual perception and processing mechanisms (Cognitive Neuroscience, Neuroscience), according to OpenAlex
Funding: MICIU (PREP2023-001890); Agencia Estatal de Investigación (MICIU/AEI/10.13039/501100011, PID2023-150081NB-I00)
Citations: not cited yet (Europe PMC); 73 references in the paper

Abstract

Prevailing models aiming at explaining heading assume that humans need to recover the Focus of Expansion (FoE) while accounting for eye-movement-induced rotation. We propose an alternative: the visual system utilizes mean retinal curl from fixations as a surrogate signal for heading, rendering the explicit recovery of the FoE unnecessary. Stationary participants viewed simulated walking paths on a large screen while fixating on points on the projected ground texture at varying eccentricities – a natural behavior inducing sustained retinal curl. Participants continuously reported perceived heading in 3D scene coordinates. To isolate the role of retinal curl, we employed a real-time manipulation that kept translational flow constant while the foveal curl component was either unaltered, canceled, or over-canceled. Under natural conditions (unaltered), participants exhibited systematic heading biases opposite the direction of gaze. Crucially, these biases vanished when we canceled the expected curl and flipped when we over-canceled it, identifying retinal curl as the specific driver of perceptual bias. We modeled these results using a simple feedback controller and a ring-attractor neural network featuring gaze-contingent inhibition and a ‘straight-ahead’ prior. These findings suggest that the brain exploits the geometry of gaze stabilization to simplify navigation, treating retinal curl as a functional signal rather than noise to be filtered.

Reproduced under the paper's license (CC BY), from the paper cited above.

Repositories

Its files are read in the Code ↔ Paper reader above, with 7 matches between paragraphs and lines of code.

OSF b37rg

License: none: the authors keep all their rights
State: the link answers, verified on 28 September 2026
Evidence: files inventoried
Languages: R (7), Quarto (5), Shell (1), Python (1)
Size: 38 files, 14 scripts
Software Heritage: not checked
Found in: “Data availability”
Holds: README, documentation, 5 notebooks
Not found: license file, CITATION.cff, environment file, tests, continuous integration
Tools: data.table (3 files), ggplot2 (2 files), lmerTest (2 files), Matplotlib (1 file), NumPy (1 file), OpenCV (1 file), patchwork (1 file), tidyverse (1 file)
Availability: 1 check, the latest on 28 September 2026: the link answers (HTTP 200)
  • 28 September 2026: the link answers (HTTP 200)
15 files
At the source: doi.org/10.17605/OSF.IO/B37RG

supp:PMC13614786/elife-110770-code1.zip

License: none: the authors keep all their rights
State: the link answers, verified on 28 September 2026
Evidence: files inventoried
Languages: Python (1)
Size: 1 file, 1 script
Software Heritage: not checked
Found in: the supplementary material
Not found: README, license file, CITATION.cff, environment file, tests, continuous integration, documentation
Tools: NumPy (1 file)
Availability: 1 check, the latest on 28 September 2026: the link answers (HTTP 200)
  • 28 September 2026: the link answers (HTTP 200)
1 file
At the source: pmc-oa-opendata.s3.amazonaws.com/PMC13614786.1/elife-110770-code1.zip

The paper's code and data availability statement is in the Data section.

Tracing map

Proposed by the machine: these links were found in the paper and verified at the source, without human review. The map will receive a Zenodo DOI once one of the paper's authors has validated it with their ORCID.

What the map holds:

  • 2 repositories of the authors' code, each at its verified commit, with its license and how the link was found in the paper;
  • 15 scripts, each with its path and the digest of its content;
  • 7 matches between paragraphs of the paper and lines of the code (method lexical-v1);
  • neither the text of the paper nor the code itself.

Its JSON (tracing-map.json) is deposited on Zenodo with its DOI once the map is validated.

Data

No dataset and no data link were found in the paper.

Data availability

All the data and code for the analysis are available through this link: https://doi.org/10.17605/OSF.IO/B37RG.

The following dataset was generated:

López-Moliner J, Zorpala KI. 2026. Beyond the Focus of Expansion: Retinal curl as a functional signal for heading estimation. Open Science Framework.

Reproduced under the paper's license (CC BY), from the paper cited above.

Versions

The history of this record: each version stored by the harvester or made by a correction of its authors or of the maintainers of its code, and what changed in its facts. The texts of the paper (its abstract, its availability statements) are not part of it; versions that changed only those are not listed.

Version 1, 28 September 2026: the first record

Recorded: type, language, journal, volume, pages, dates, 2 authors, 1 keyword, 7 MeSH terms, 2 funders, 71 references.

Cite

This paper

Zorpala, K. I., & López-Moliner, J. (2026). Retinal curl as a functional signal for heading estimation beyond the focus of expansion. eLife, 15, RP110770. https://doi.org/10.7554/elife.110770

BibTeX

@article{zorpala2026retinal,
author = {Zorpala, Kontessa I and López-Moliner, Joan},
title = {{Retinal curl as a functional signal for heading estimation beyond the focus of expansion}},
journal = {eLife},
year = {2026},
month = sep,
volume = {15},
pages = {RP110770},
publisher = {eLife Sciences Publications, Ltd},
issn = {2050-084X},
doi = {10.7554/elife.110770},
url = {https://doi.org/10.7554/elife.110770},
pmid = {42788718},
pmcid = {PMC13614786}
}

RIS

TY - JOUR
AU - Zorpala, Kontessa I
AU - López-Moliner, Joan
TI - Retinal curl as a functional signal for heading estimation beyond the focus of expansion
T2 - eLife
J2 - eLife
PY - 2026
DA - 2026/09/25
VL - 15
SP - RP110770
SN - 2050-084X
PB - eLife Sciences Publications, Ltd
DO - 10.7554/elife.110770
UR - https://doi.org/10.7554/elife.110770
LA - en
ER -

CSL-JSON

{
"id": "10.7554/elife.110770",
"type": "article-journal",
"title": "Retinal curl as a functional signal for heading estimation beyond the focus of expansion",
"container-title": "eLife",
"author": [
{
"family": "Zorpala",
"given": "Kontessa I"
},
{
"family": "López-Moliner",
"given": "Joan"
}
],
"container-title-short": "eLife",
"volume": "15",
"page": "RP110770",
"DOI": "10.7554/elife.110770",
"PMID": "42788718",
"PMCID": "PMC13614786",
"ISSN": "2050-084X",
"publisher": "eLife Sciences Publications, Ltd",
"URL": "https://doi.org/10.7554/elife.110770",
"language": "en",
"issued": {
"date-parts": [
[
2026,
9,
25
]
]
}
}

The tracing map gets a citation of its own once an author has validated it and it has a DOI.

Similar papers

The papers with a page that share the most with this one: the tools found in their code, their categories, datasets, cited references and authors, the rarest counting most.

[1] doi:10.1038/s41598-022-16371-4 [code]
Distributed encoding of curvilinear self-motion across spiral optic flow patterns.
Journal: Scientific reports
In common: behavior only, 13 references
[2] doi:10.1038/s41467-022-33245-5 [code]
Causal contribution of optic flow signal in Macaque extrastriate visual cortex for roll perception.
Journal: Nature communications
In common: cognitive, 13 references
[3] doi:10.1038/s41598-026-35805-x
The effect of unilateral cortical blindness on lane position and gaze behavior in a virtual reality steering task.
Journal: Scientific reports
In common: cognitive, 9 references
[4] doi:10.1167/jov.23.2.8 [code]
Temporal stability of human heading perception.
Journal: Journal of vision
In common: cognitive, 9 references
[5] doi:10.7554/elife.82410 [code]
Retinal motion statistics during natural locomotion.
Journal: eLife
In common: behavior only, cognitive, 7 references
[6] doi:10.1038/s41598-026-56170-9 [code]
Path integration from optic flow and the role of eye movements.
Journal: Scientific reports
In common: cognitive, 5 references
[7] doi:10.3389/fnins.2024.1441285 [code]
Accuracy optimized neural networks do not effectively model optic flow tuning in brain area MSTd.
Journal: Frontiers in neuroscience
In common: NumPy, 5 references
[8] doi:10.1167/jov.25.13.10 [code]
Distinct temporal dynamics of judging scene-relative object motion and estimating heading from optic flow.
Journal: Journal of vision
In common: cognitive, 4 references
[9] doi:10.1016/j.isci.2023.108307
Psychophysical measurement of perceived motion flow of naturalistic scenes.
Journal: iScience
In common: behavior only, 4 references
[10] doi:10.1073/pnas.2412954122 [code]
Active vision in freely moving marmosets using head-mounted eye tracking.
Journal: Proceedings of the National Academy of Sciences of the United States of America
In common: OpenCV, Matplotlib, NumPy, behavior only, cognitive, 2 references

Contribute

The authors of this paper can claim it, correct its record and validate its tracing map, and the maintainers of its code (its owner, or a public member of its organization) correct what it says of their repository; anyone signed in can ask for its removal. Every request goes to OSCR's own machine, which answers it; your account page follows them.

Sign in with ORCID to claim this paper as one of its authors, correct its record or validate its tracing map: when the paper's metadata lists your ORCID iD, you are recognized at once. Maintainers of its code: sign in with GitHub, then claim the repository on your account page.

Add the badge to the code's README

OSCR: the badge of this paper

If you are an author or a maintainer of this paper's code, you can add this badge. It says what OSCR knows of the paper (its code, its validated tracing map) and links the code to this page. Paste one of these snippets under the README's title. Keep the two marks around it, so that the badge can be replaced in place and is never added twice. OSCR changes nothing in your repository.

Markdown
<!-- oscr-badge:start -->
[![OSCR](https://openscicode.org/badge/doi/10.7554/elife.110770.svg)](https://openscicode.org/badge/doi/10.7554/elife.110770)
<!-- oscr-badge:end -->
reStructuredText
.. oscr-badge:start

.. image:: https://openscicode.org/badge/doi/10.7554/elife.110770.svg
   :target: https://openscicode.org/badge/doi/10.7554/elife.110770
   :alt: OSCR

.. oscr-badge:end
HTML
<!-- oscr-badge:start -->
<a href="https://openscicode.org/badge/doi/10.7554/elife.110770"><img src="https://openscicode.org/badge/doi/10.7554/elife.110770.svg" alt="OSCR"></a>
<!-- oscr-badge:end -->

If you choose to, you can have the badge kept up to date for you, with oscr badge --write from the command line or with the GitHub Action in your repository's workflows. Every other form and option (a card, AsciiDoc, LaTeX, shields.io) is on the badge page.

Request its removal

To ask OSCR to remove this record, the copies of its authors' scripts or its tracing map, use the removal request page: signed in, you say who you are, what to remove and why, then review and confirm the request. Published rules decide every request (how).

Discussion, reproductions, activity

Discussion: code errors and mismatches between the code and the paper about this paper and its code, from readers and its authors, beside the paper and its tracing map.

Report a mismatch between the code and the paper · Report a code error (signed in)

Reproductions: reports from readers who ran the authors' code and did not get the paper's result, what they ran, with which environment, commit and data.

Report a reproduction failure (signed in)

Activity: what happens around this paper: new versions of its record, its map's validation, discussions and reproductions. It opens with sign-in.