Skip to content
This repository was archived by the owner on Nov 16, 2026. It is now read-only.
AegeanWorksPublic archive

About

[ARCHIVED] NeuroOptic is a research-grade visual oscillator for brainwave entrainment: configurable 1-120 Hz frequencies, hardware-aware safety limits and drift-free phase accumulation.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

NeuroOptic

NeuroOptic social preview

License AIKit Integrated

NeuroOptic is a research-grade visual oscillator for brainwave entrainment: configurable 1-120 Hz frequencies, hardware-aware safety limits and drift-free phase accumulation.

Archived: Retired by owner request after final delivery: validation unification, sham-seed reproducibility and Nyquist fail-loudly preflight shipped; all commits pushed (archived 2026-11-16). This project is read-only; its GitHub repository is archived.

⚡ 30-Second Cold-Start Quick Reference

  • Runtime Prerequisites: Python 3.10+ with glfw, PyOpenGL, numpy and customtkinter (see requirements.txt).
  • Canonical Regression Shield Gate:
    python -m unittest discover

🛠️ AIKit Commands (run from the AIKit folder)

Role Command
Status, task and gates python aikit.py status NeuroOptic
Phase 4: every gate python aikit.py check NeuroOptic
Repair memory and map, then check python aikit.py fix NeuroOptic
Resume an interrupted task python aikit.py resume NeuroOptic

📦 What's Inside

NeuroOptic/
├── .gitignore                 <- transient AIKit state excluded
├── README.md
├── assets/
├── COMMERCIAL.md
├── core/                      <- decoupled protocol mechanics & safety gates (ADR-271)
├── LICENSE
├── LICENSES/                 <- REUSE license texts
├── REUSE.toml                <- Machine-readable SPDX metadata
├── entrainment_engine.py      <- GLFW/OpenGL entrainment engine and CLI
├── launcher.py                <- customtkinter GUI controller
├── requirements.txt
├── start.bat                  <- 1-click Windows batch launcher (PRINCIPLE-011)
├── start.py                   <- 1-click starter with safe defaults & dry-run
├── test_entrainment_engine.py <- unit tests for the engine's pure logic
├── test_launcher.py           <- automated headless tests for the controller
├── test_mechanics.py          <- unit tests for headless protocol mechanics
├── test_start.py              <- unit tests for one-click starter
└── .aikit/                    <- this project's memory: record, ledger, decisions, map

Generalized Visual Entrainment Engine

NeuroOptic is a research-grade visual oscillator designed for precise brainwave entrainment. It supports configurable frequencies (1–120 Hz) with hardware-aware safety limits and drift-free phase accumulation.

Features

  • Precision Oscillator: 0.01 Hz resolution using a monotonic high-resolution clock.
  • Hardware-Aware: Automatically detects monitor refresh rates and enforces Nyquist safety limits (e.g., Max 30Hz on a 60Hz screen).
  • Waveforms:
    • Sine: Physiological oscillatory mimicry (Default).
    • Square: Strong entrainment (Binary On/Off).
    • Triangle: Linear fade in/out.
    • AM Carrier: High-frequency carrier modulated at target frequency.
  • Stimulation Modes:
    • Full Screen: Standard entrainment.
    • Split Hemifield: Independent Left/Right control for binocular beats or lateralized stimulation.
    • Peripheral Ring: Foveal sparing stimulation.
    • Quadrants: Retinotopic mapping support (Top-Left, Bottom-Right, etc.).
  • Research & Sham Control:
    • Detune: Frequency drifts slightly to prevent entrainment.
    • Low Amp: Sub-threshold intensity.
    • Jitter: Randomized phase timing.
    • Static: Non-flickering control (0.5 hold, SINE phase 0).
  • Tech Stack: Python, GLFW, OpenGL (VSync enabled).

Installation

  1. Install dependencies:
    pip install -r requirements.txt

Usage

⚡ One-Click Start (Zero-Friction Onboarding)

Launch NeuroOptic instantly with verified bio-safe presets (PRINCIPLE-011):

# Windows: double-click start.bat or run:
start.bat

# Multi-platform 1-click launch to GUI:
python start.py

# 1-click start safe 40Hz Gamma entrainment directly (5s ramp):
# fails with a Why/Fix remediation on displays under 85 Hz (Nyquist: 40 Hz needs refresh >= 85 Hz)
python start.py --quick

# 1-click start safe 10Hz Alpha entrainment directly (5s ramp, valid on every display):
python start.py --alpha

# Headless parameter & dependency validation (checks against your detected refresh rate):
python start.py --dry-run

Graphical Interface (Recommended)

Launch the GUI controller:

python launcher.py

Command Line Interface

Run the engine via command line:

# Default (40Hz Gamma, Sine wave)
python entrainment_engine.py

# Custom Frequency (e.g., 10Hz Alpha)
python entrainment_engine.py --freq 10.0

# Square Wave (Strong entrainment)
python entrainment_engine.py --freq 40.0 --waveform square

# Amplitude Modulated
python entrainment_engine.py --freq 40.0 --waveform am

# Split Hemifield (Binocular Beats: Left 10Hz, Right 11Hz)
python entrainment_engine.py --mode split --freq 10.0 --freq-right 11.0

# Research Mode (Sham: Detuned Frequency)
python entrainment_engine.py --freq 40.0 --sham detune

# Session Control (10 min session, 5s ramp-up)
python entrainment_engine.py --duration 600 --ramp 5.0

# Declarative Protocol Execution (Subagent & Research automation)
python entrainment_engine.py --protocol protocol.json

# Headless Protocol Validation (Dry-run without display)
python entrainment_engine.py --protocol protocol.json --dry-run

🎨 Brand Assets

AI-Generated Brand Artwork. The banner and logo are AI-generated brand assets. They are illustrative and may not literally depict every feature or the full project scope.

📜 License

Free for personal use under the Aegean License 1.1 (AL-1.1); see LICENSE. Any commercial use needs the Aegean Commercial License 1.0 (ACL-1.0); see COMMERCIAL.md.

Screenshots

NeuroOptic redesigned controller - Protocol & Session tab

commit bff3d7b · 2026-11-16

NeuroOptic controller before redesign

commit bff3d7b · 2026-11-16

NeuroOptic controller at 2026-11-03

commit 36f9038 · 2026-11-03

About

[ARCHIVED] NeuroOptic is a research-grade visual oscillator for brainwave entrainment: configurable 1-120 Hz frequencies, hardware-aware safety limits and drift-free phase accumulation.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages