Contributing to OpenTrack

Guidelines for contributing code, translations, documentation, and bug reports to the OpenTrack project

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

1. Read the Documentation

   Familiarize yourself with OpenTrack:

   • Quick Start Guide
   • Hacking OpenTrack - Core development guide
   • Plugin API documentation
2. Set Up Development Environment

   Build OpenTrack from source:

   Building from Source

   Complete build instructions for all platforms

   Plugin Development

   Guide to creating custom plugins

3. 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
4. Join the Community

   • Create a GitHub account
   • Star the OpenTrack repository
   • Watch for updates

Contributing Code

Development Workflow

1. Fork the Repository

   Create your own fork on GitHub:

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

   git clone https://github.com/YOUR_USERNAME/opentrack.git
   cd opentrack
   
2. 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
3. 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
4. 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
   
5. 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
6. Push and Create Pull Request

   Push your changes and create a PR:

   git push origin feature/my-new-feature
   

   Then on GitHub:

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

Code Style Guidelines

C++

// 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;

CMake

# 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}
)

Qt

// 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

1. Search Existing Issues

   Check if the bug is already reported:

   • OpenTrack Issues
   • Search closed issues too
2. 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
3. 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:

1. Fork the Wiki Repository

   git clone https://github.com/opentrack/wiki.git
   cd wiki
   
2. Edit Markdown Files

   Wiki pages are written in Markdown:

   # Page Title
   
   ## Section
   
   Content here...
   
   ### Subsection
   
   More content...
   
3. 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

1. 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
   
2. 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>
   
3. Test Translation

   Build and test:

   cmake .. && make
   LANG=de_DE.UTF-8 ./opentrack
   
4. 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:

1. Add language code to CMakeLists.txt:

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

2. Create .ts files in each module’s lang/ directory

3. Translate using Qt Linguist

4. Submit PR with new language support

Testing and QA

Beta Testing

Help test new features:

1. Try pre-release builds:

   • Check GitHub Actions for CI builds
   • Test on your hardware

2. Report findings:

   • What works well
   • What doesn’t work
   • Performance issues

3. 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!