added progress from previous repo host

README.md

@@ -1,3 +1,100 @@
-# adaptive_filtering
+# Pupil Capture screen surface
 
-Adaptive filtering of eye_tracking data
+This small Python program fills the primary screen and displays four unique
+`tag36h11` AprilTags in its corners. It has no third-party dependencies; the
+standard Python installation used on Windows normally includes Tkinter.
+
+## Run
+
+Close or move anything important from the primary screen, then run:
+
+```powershell
+python show_apriltag_surface.py
+```
+
+Press `Esc` or `Q` to close it. For a preview in a normal resizable window:
+
+```powershell
+python show_apriltag_surface.py --windowed
+```
+
+By default, every marker is flush with both adjacent screen edges. Useful
+options include `--tag-size 240`, `--margin 32`, and
+`--tag-ids 10 11 12 13`. The requested size is rounded down to a multiple of
+10 pixels so that the source grid is always scaled without interpolation.
+
+## Define the surface in Pupil Capture
+
+1. Start this program and look at the screen through the headset.
+2. Enable **Surface Tracker** in Pupil Capture.
+3. Confirm all four markers are outlined/detected in the World window.
+4. Select **Add surface**, name it (for example, `screen`), then freeze the
+   scene and edit the surface corners to match the usable screen area.
+5. Keep this program running whenever the surface should remain trackable.
+
+If detection is unreliable, increase `--tag-size`, reduce glare, and ensure
+the world camera can see the markers. Do not reuse any of these four marker IDs
+elsewhere in the camera's view.
+
+For the next integration step, enable Pupil Capture's **Network API** plugin
+and keep **Surface Tracker** active. Surface-relative gaze is broadcast on a
+topic beginning with `surfaces.`; its normalized `(x, y)` coordinates use the
+bottom-left as `(0, 0)` and the top-right as `(1, 1)`.
+
+## Live gaze visualization
+
+Set the `screen` surface Width to `2560` and Height to `1440`, keep Surface
+Tracker and Network API enabled, and install the two network dependencies once:
+
+```powershell
+python -m pip install -r requirements.txt
+```
+
+Then close the marker-only program and run:
+
+```powershell
+python visualize_surface_gaze.py
+```
+
+This program displays the same four corner tags, subscribes to
+`surfaces.screen`, draws a red gaze dot, and prints rows containing Pupil
+timestamp, screen x, screen y, and confidence. Coordinates are converted to
+the Windows top-left origin. It connects to `127.0.0.1:50020` by default;
+use `--host 192.168.0.47` only when this script runs on another computer.
+
+The displayed point passes through a 5-sample median filter, exponential
+smoothing, and a 3-pixel dead zone. Terminal rows contain timestamp, raw x,
+raw y, filtered x, filtered y, and confidence. For a steadier but slower point:
+
+```powershell
+python visualize_surface_gaze.py --smoothing 0.10 --median-window 7
+```
+
+For a more responsive point, use `--smoothing 0.30 --median-window 3`.
+
+## Guided gaze exercises
+
+With Pupil Capture configured the same way, run:
+
+```powershell
+python gaze_exercises.py
+```
+
+Press Space to begin and between blocks. The sequence contains 10 three-second
+steady fixations, 10 rapid target acquisitions, 20 two-color selective-attention
+trials, and three 10-second smooth-pursuit paths. A live yellow dot shows the
+raw gaze when the program is run with `--cursor`; it is hidden by default. No
+median or smoothing filter is applied, and every received sample that meets the
+`--confidence` threshold is written to a timestamped CSV in `results/`, including
+the target, gaze coordinates, pixel error, and whether gaze was on target. During
+every color trial, green is the target and red is the distractor.
+
+Visualize the newest result file with:
+
+```powershell
+python visualize_results.py
+```
+
+Or select a particular run with `python visualize_results.py results\file.csv`.
+The script opens a six-panel dashboard, prints summary statistics, and saves a
+`*_dashboard.png` beside the source CSV. Use `--no-show` to only save the PNG.