Installation & Setup

This page covers the full installation and configuration process for the freely-walking optomotor system. For a brief prerequisites checklist, see the Quickstart page. For hardware and arena specifications, see the Rig Specs page.

System requirements

The system runs across three computers, each with a specific role:

Computer	OS	Role
Acquisition rig	Windows	Runs protocols, records video
Processing machine	Windows	Automated tracking & processing
Analysis computer	Mac / any	Manual analysis, plotting, dashboard

Software dependencies

1. freely-walking-optomotor repository

Clone the repository:

git clone https://github.com/leburnett/freely-walking-optomotor.git

2. MATLAB toolboxes

The following MATLAB toolboxes are required on all computers:

Statistics and Machine Learning Toolbox
Image Processing Toolbox
Circular Statistics Toolbox (from MATLAB File Exchange, by Philipp Berens)

3. Acquisition software

Install on the acquisition rig:

BIAS (SimpleBiasCameraInterface) — for video acquisition
G4_Display_Tools — provides the panel_com functions for LED arena control

4. Processing software

Install on the processing machine:

FlyTracker — for post-experiment tracking
JAABA — for generating stimulus videos with fly trajectories

Configuration

Step 1 — Edit the config files

MATLAB — edit config/get_config.m (one line):

cfg.project_root = '/path/to/your_data_root';

Python — edit config/config.py (one line):

PROJECT_ROOT = Path("/path/to/your_data_root")

Both files contain commented examples for Windows and Mac. The required data subdirectories (DATA/, results/, figures/) are created automatically the first time get_config() or config.py is called.

Step 2 — Add MATLAB paths

Run setup_path.m once per MATLAB session (or add it to your startup.m):

run('/path/to/freely-walking-optomotor/setup_path.m')

This adds all src/ subdirectories to the MATLAB path so that functions like get_config(), process_freely_walking_data(), and the protocol helper functions are available.

Step 3 — Install the Python environment (optional)

Note

The Python environment is not required to run experiments — experiments are run entirely in MATLAB using protocol scripts (e.g. protocol_27.m). Python is only needed for the automated processing pipeline scripts (monitor_and_copy, monitor_and_track, daily_processing) and the Dashboard.

cd freely-walking-optomotor/python/freely-walking-python
pixi install

This installs all Python dependencies (numpy, pandas, scipy, dash, etc.) into an isolated environment managed by pixi.

Verifying your setup

Run through this checklist to confirm everything is working:

Repository: The freely-walking-optomotor folder exists and contains config/get_config.m
MATLAB path: Type which get_config in the MATLAB Command Window — it should return the path to the file
Toolboxes: Type which circ_mean — it should return a path (Circular Statistics Toolbox)
Config: Run cfg = get_config() and verify that cfg.project_root points to your data folder — the DATA/, results/, and figures/ subdirectories should be created automatically

Next steps

Once your environment is set up:

Read the Quickstart to run your first experiment
See Configuration & Paths for the full config file reference and data flow details
See the Pipeline page to understand the automated processing pipeline