Cursor

Overview

Cursor is a Python project for recording, analyzing, and experimenting with cursor/mouse movement data. It provides tools for capturing mouse interactions, processing recordings, and running experiments on cursor behavior patterns.

Table of Contents

• Cursor
  • Overview
  • Table of Contents
  • Prerequisites
  • Setup
  • Configuration
  • Testing
  • Running
    • Recorder
    • Experiments
  • Tools
  • Data Handling
    • Remove small recording files
    • Share directory over local network

Prerequisites

• Python 3.14

• pip and virtualenv (or pyenv)

  sudo apt install python3-pyqt5 libcairo2-dev pkg-config python3-dev python3-tk

Setup

Using uv for setup

curl -LsSf https://astral.sh/uv/install.sh | sh
uv self update

uv python install 3.14
uv venv --python 3.14
uv sync
source .venv/bin/activate

uv pip install -e .

git submodule update --init

Configuration

Copy and customize the configuration file for your environment:

cp config.ini config_local.ini
# Adjust paths to data folder. Within data folder, we expect "recordings" and "experiments" folders

Testing

Run tests with code coverage and linting:

# Linux/macOS
py.test --cov cursor -v
ruff format --check .

# Run a single test
pytest tests/test_renderer.py::test_ascii_renderer

# Windows
python -m pytest --cov=cursor . -v

Running

Recorder

Record cursor movements:

pip install -e .
cursor_recorder

Experiments

Run experiments on cursor data:

pip install -e .
cd experiments
python file.py

Tools

See tools for more information on available tools.

Data Handling

Remove small recording files

Remove recording files smaller than 3KB:

cd data/recordings
find . -name "*.json" -type 'f' -size -3k -delete

Share directory over local network

Share a directory via SSHFS:

sshfs marcel@plot470s.local:/home/marcel/share/ ./share