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
  • Troubleshooting
    • Import errors on Linux/macOS
    • Virtual environment issues
    • Test failures on Windows

Prerequisites

• Python 3.14
• pip and virtualenv (or pyenv)
• System dependencies:
  • 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

source .venv/bin/activate

uv pip install -r requirements.txt
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 [email protected]:/home/marcel/share/ ./share

Troubleshooting

Import errors on Linux/macOS

If you encounter PyQt5 import errors, ensure system dependencies are installed:

# macOS
brew install pyqt5

# Ubuntu/Debian
sudo apt install python3-pyqt5 libcairo2-dev pkg-config python3-dev python3-tk

Virtual environment issues

If you encounter permission or environment conflicts, ensure you're using the correct virtual environment:

pyenv activate cursor
which python  # Should point to your virtualenv

Test failures on Windows

Make sure to use python -m pytest on Windows instead of py.test directly.