Contributing to OpenTrack

OpenTrack is an open-source project that welcomes contributions from the community. Whether you’re a developer, translator, documentation writer, or user reporting bugs, your contributions help make OpenTrack better for everyone.

Ways to Contribute

Code

Write trackers, filters, protocols, or improve core functionality

Bug Reports

Report issues and help identify problems

Documentation

Write guides, tutorials, and improve documentation

Translations

Translate OpenTrack to your language

Testing

Test new features and pre-release versions

Support

Help other users on forums and issue trackers

Getting Started

Read the Documentation

Familiarize yourself with OpenTrack:

Quick Start Guide
Hacking OpenTrack - Core development guide
Plugin API documentation

Set Up Development Environment

Build OpenTrack from source:

Building from Source

Complete build instructions for all platforms

Plugin Development

Guide to creating custom plugins

Explore the Codebase

Clone the repository and explore:

git clone https://github.com/opentrack/opentrack.git
cd opentrack

Key directories:

api/ - Plugin API interfaces
tracker-*/ - Tracker implementations
filter-*/ - Filter implementations
proto-*/ - Protocol implementations
gui/ - Main application UI
cmake/ - Build system

Join the Community

Create a GitHub account
Star the OpenTrack repository
Watch for updates

Contributing Code

Development Workflow

Fork the Repository

Create your own fork on GitHub:

Visit opentrack/opentrack
Click “Fork” in the top-right corner
Clone your fork:

git clone https://github.com/YOUR_USERNAME/opentrack.git
cd opentrack

Create a Feature Branch

Create a branch for your changes:

git checkout -b feature/my-new-feature

Branch naming conventions:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation changes
refactor/ - Code refactoring

Make Your Changes

Write your code following the project’s style:

Use consistent indentation (spaces, not tabs)
Follow existing code style
Comment complex logic
Keep commits focused and atomic

Test Your Changes

Build and test thoroughly:

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=RELEASE
make -j$(nproc)
make install

# Test the installed version
./install/bin/opentrack

Commit Your Changes

Write clear, descriptive commit messages:

git add .
git commit -m "tracker/aruco: improve marker detection in low light

- Adjust adaptive threshold parameters
- Add contrast enhancement preprocessing
- Fixes #123"

Good commit messages:

Start with component prefix (tracker/, filter/, proto/, gui/)
Use imperative mood (“add” not “added”)
Explain why, not just what
Reference issue numbers with #123

Push and Create Pull Request

Push your changes and create a PR:

git push origin feature/my-new-feature

Then on GitHub:

Navigate to your fork
Click “Pull Request”
Select your branch
Write a detailed description:
- What problem does it solve?
- How to test the changes?
- Any breaking changes?

Code Style Guidelines

C++
CMake
Qt

// Use descriptive variable names
int camera_width = 640;
double exposure_time = 0.033;

// Prefer RAII and modern C++
{
    std::lock_guard<std::mutex> lock(mutex);
    data = new_data;
}

// Use const correctness
void process_data(const double* input, double* output) const;

// Document public interfaces
/**
 * Start the tracker with the given video frame.
 * @param frame Optional widget for displaying video
 * @return status_ok() on success, error() with message on failure
 */
virtual module_status start_tracker(QFrame* frame) = 0;

# Use otr_module() for plugins
otr_module(tracker-mytracker)

# Link required libraries
target_link_libraries(opentrack-tracker-mytracker
    PRIVATE
        opentrack-api
        opentrack-cv
        ${OpenCV_LIBS}
)

# Add include directories if needed
target_include_directories(opentrack-tracker-mytracker
    PRIVATE
        ${CMAKE_CURRENT_SOURCE_DIR}
)

// Use Qt's signal/slot mechanism
connect(ui.button, &QPushButton::clicked,
        this, &MyDialog::onButtonClicked);

// Use Qt's container classes
QVector<double> values;
QString error_message;

// Support translations
QString name() override
{
    return tr("My Tracker");
}

// Handle dialog lifecycle
void MyDialog::save()
{
    s.threshold = ui.threshold_slider->value();
}

Plugin Development Guidelines

When creating new plugins:

Follow API Conventions

Implement all required virtual methods
Return proper status codes
Handle errors gracefully
Document your API usage

Performance Matters

Don’t block in hot paths
Use separate threads for computation
Profile your code
Optimize critical sections

Test Thoroughly

Test on multiple platforms
Test error conditions
Test resource cleanup
Test with various configurations

Provide Configuration

Create intuitive UI dialogs
Use sensible defaults
Save/load settings properly
Support profile import/export

Reporting Bugs

Before Reporting

Search Existing Issues

Check if the bug is already reported:

OpenTrack Issues
Search closed issues too

Verify It's a Bug

Confirm the issue:

Test with latest version
Try with default settings
Test with different profiles
Check if it’s user error

Gather Information

Collect diagnostic information:

OpenTrack version (Help → About)
Operating system and version
Hardware details (CPU, GPU, camera)
Steps to reproduce
Error messages or logs

Creating a Bug Report

Don’t be afraid to submit an issue! The OpenTrack team is friendly and welcomes bug reports.

Create a detailed bug report on GitHub Issues:

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

**Expected behavior**
What you expected to happen.

**Screenshots**
If applicable, add screenshots.

**Environment:**
 - OS: [e.g. Windows 10 21H2]
 - OpenTrack version: [e.g. 2023.1.0]
 - Tracker: [e.g. PointTracker]
 - Camera: [e.g. Logitech C920]

**Additional context**
Any other context about the problem.

Contributing Documentation

Wiki Contributions

The OpenTrack wiki is maintained in a separate repository:

Fork the Wiki Repository

git clone https://github.com/opentrack/wiki.git
cd wiki

Edit Markdown Files

Wiki pages are written in Markdown:

# Page Title

## Section

Content here...

### Subsection

More content...

Submit Pull Request

Send your documentation improvements:

git add .
git commit -m "docs: add guide for XYZ tracker"
git push origin master

Create a PR to opentrack/wiki

The user-facing wiki automatically updates when commits are merged.

Contributing Translations

OpenTrack supports multiple languages:

Supported Languages

set(opentrack_all-translations "de_DE;nl_NL;ru_RU;stub;zh_CN")

de_DE - German
nl_NL - Dutch
ru_RU - Russian
zh_CN - Chinese (Simplified)
stub - Template for new translations

Translation Workflow

Find Translation Files

Translation files are in lang/ subdirectories:

tracker-aruco/lang/de_DE.ts
tracker-aruco/lang/nl_NL.ts
gui/lang/ru_RU.ts

Edit with Qt Linguist

Use Qt Linguist to edit .ts files:

linguist tracker-aruco/lang/de_DE.ts

Or edit XML directly:

<message>
    <source>Start tracking</source>
    <translation>Tracking starten</translation>
</message>

Test Translation

Build and test:

cmake .. && make
LANG=de_DE.UTF-8 ./opentrack

Submit Translation

Create a PR with your translations:

git add */lang/*.ts
git commit -m "i18n: update German translation"
git push origin translation-updates

Adding a New Language

To add a new language:

Add language code to CMakeLists.txt:

set(opentrack_all-translations "de_DE;nl_NL;ru_RU;stub;zh_CN;fr_FR")

Create .ts files in each module’s lang/ directory
Translate using Qt Linguist
Submit PR with new language support

Testing and QA

Beta Testing

Help test new features:

Try pre-release builds:
- Check GitHub Actions for CI builds
- Test on your hardware
Report findings:
- What works well
- What doesn’t work
- Performance issues
Suggest improvements:
- UI/UX feedback
- Feature requests
- Documentation gaps

Code of Conduct

Community Guidelines

Be Respectful

Treat all contributors with respect and professionalism

Be Constructive

Provide helpful feedback and constructive criticism

Be Patient

Maintainers are volunteers with limited time

Be Collaborative

Work together to solve problems and improve the project

Recognition

Contributors are recognized in multiple ways:

Credits

Significant contributors are listed in:

AUTHORS.md - Core contributors
README.md - Credits section
Module-specific files - Component authors

Current Contributors

From AUTHORS.md:

Stanislaw Halik - Project maintainer
Chris Thompson - Rift and Razer Hydra modules
Xavier Hallade - Intel RealSense tracker
Donovan Baarda - EWMA filter
Michael Welter - Kalman filter
Attila Csipa - S2Bot tracker
Wei Shuai - Wiimote tracker
Stéphane Lenclud - Kinect Face Tracker, Easy Tracker

See full list

License

OpenTrack is licensed under the ISC license (permissive open-source):

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

By contributing, you agree to license your contributions under the same terms.

See OPENTRACK-LICENSING.txt for complete licensing information.

Resources

GitHub Repository

Main codebase and issue tracker

Wiki

User documentation and guides

Plugin API

Complete API reference

Hacking Guide

Core development guide

Questions?

If you have questions about contributing:

Issues: Ask on GitHub Issues
Discussions: Start a discussion on GitHub
Email: Contact maintainers (see AUTHORS.md)

We’re a friendly community and welcome contributions of all sizes. Don’t hesitate to get involved!

Get Started

User Guides

Trackers

Output Protocols

Filters

Advanced

​Ways to Contribute

Code

Bug Reports

Documentation

Translations

Testing

Support

​Getting Started

Building from Source

Plugin Development

​Contributing Code

​Development Workflow

​Code Style Guidelines

​Plugin Development Guidelines

Follow API Conventions

Performance Matters

Test Thoroughly

Provide Configuration

​Reporting Bugs

​Before Reporting

​Creating a Bug Report

​Contributing Documentation

​Wiki Contributions

​Contributing Translations

​Supported Languages

​Translation Workflow

​Adding a New Language

​Testing and QA

​Beta Testing

​Code of Conduct

​Community Guidelines

Be Respectful

Be Constructive

Be Patient

Be Collaborative

​Recognition

​Credits

​Current Contributors

​License

​Resources

GitHub Repository

Wiki

Plugin API

Hacking Guide

​Questions?

Ways to Contribute

Getting Started

Contributing Code

Development Workflow

Code Style Guidelines

Plugin Development Guidelines

Reporting Bugs

Before Reporting

Creating a Bug Report

Contributing Documentation

Wiki Contributions

Contributing Translations

Supported Languages

Translation Workflow

Adding a New Language

Testing and QA

Beta Testing

Code of Conduct

Community Guidelines

Recognition

Credits

Current Contributors

License

Resources

Questions?