TrackForgex

Copy Markdown View Source

Elixir CI docs License: MIT

A port of trackforge from Rust to Elixir using Rustler. An open-source multi-object tracking library for real-time video analysis, currently implementing the ByteTrack algorithm.

Features

  • Port of trackforge: Direct port of the Rust tracking library to Elixir, maintaining feature parity and performance characteristics
  • ByteTrack implementation: Currently implements only the ByteTrack algorithm
  • High performance: Rust-based NIF implementation ensuring low overhead and fast execution
  • Elixir-friendly API: Clean, idiomatic Elixir interface with comprehensive types and documentation
  • Flexible configuration: Configurable thresholds for track initialization, matching, and confidence scoring
  • Extensible architecture: Designed to, in the future, support additional trackers from trackforge (e.g., DeepSORT, FairMOT)

Installation

Add track_forgex to your list of dependencies in mix.exs:

def deps do
  [
    {:track_forgex, "~> 0.1.0"}
  ]
end

After installing, you need to compile the NIF:

mix deps.compile

Quick Start

Basic Usage

iex> # Create a ByteTracker instance with custom settings
iex> settings = %TrackForgex.Trackers.ByteTrack.Settings{
...>   track_thresh: 0.5,
...>   track_buffer: 30,
...>   match_thresh: 0.8,
...>   det_thresh: 0.6
...> }
iex> tracker = TrackForgex.Trackers.ByteTrack.new(settings)
iex> # Process detections from a detector
iex> detections = [
...>   %TrackForgex.Utils.Detection{
...>     bbox: %TrackForgex.Utils.BBox{x: 10.0, y: 20.0, w: 100.0, h: 50.0},
...>     score: 0.9,
...>     class_id: 0
...>   },
...>   %TrackForgex.Utils.Detection{
...>     bbox: %TrackForgex.Utils.BBox{x: 150.0, y: 30.0, w: 80.0, h: 60.0},
...>     score: 0.85,
...>     class_id: 0
...>   }
...> ]
iex> # Update tracker and get results
iex> results = TrackForgex.Trackers.ByteTrack.update(tracker, detections)
iex> # Results contain track IDs, states, and positions
iex> results
[
  %TrackForgex.Trackers.ByteTrack.DetectionResult{
    bbox: %TrackForgex.Utils.BBox{x: 10.0, y: 20.0, w: 100.0, h: 50.0},
    score: 0.8999999761581421,
    class_id: 0,
    track_id: 1,
    state: :tracked,
    is_activated: true,
    frame_id: 1,
    start_frame: 1,
    tracklet_len: 0
  },
  %TrackForgex.Trackers.ByteTrack.DetectionResult{
    bbox: %TrackForgex.Utils.BBox{x: 150.0, y: 30.0, w: 80.0, h: 60.0},
    score: 0.8500000238418579,
    class_id: 0,
    track_id: 2,
    state: :tracked,
    is_activated: true,
    frame_id: 1,
    start_frame: 1,
    tracklet_len: 0
  }
]

Configuration

The Settings struct allows you to tune the tracking behavior:

settings = %TrackForgex.Trackers.ByteTrack.Settings{
  track_thresh: 0.5,      # Threshold for high-confidence detections
  track_buffer: 30,       # Frames to keep a lost track alive
  match_thresh: 0.8,      # IoU threshold for matching
  det_thresh: 0.6         # Detection threshold for new tracks
}

Detection States

Each detection result includes the current tracking state:

  • :new - New track that hasn't been confirmed yet
  • :tracked - Confirmed track being actively tracked
  • :lost - Track that has been lost but preserved
  • :removed - Track that has been removed

Development

Prerequisites

  • Elixir 1.18+
  • Rust stable
  • Devenv (optional, for reproducible environments)

Setup

# Install dependencies
mix deps.get

# Compile the NIF
mix deps.compile

# Run tests
mix test

# Run code quality checks
mix check

Project Structure

track_forgex/
├── lib/
│   ├── track_forgex.ex         # Main module with common utilities
│   ├── native.ex               # NIF interface (Rustler) for trackforge bindings
│   ├── utils.ex                # BBox and Detection structs
│   └── trackers/
│       ├── byte_track.ex       # ByteTrack implementation (currently available)
│       └── [other_trackers]    # Additional trackers from trackforge (future)
├── native/
│   └── track_forgex/
│       └── src/
│           └── lib.rs          # Rust NIF implementation wrapping trackforge
├── test/
│   └── test_helper.exs
├── mix.exs
└── README.md

Architecture

TrackForgex is a thin Elixir wrapper around the trackforge Rust library. The architecture follows the Rustler pattern:

  1. Native Module (lib/native.ex): Defines the Elixir-side NIF interface that marshals data between Elixir and Rust
  2. Rust Layer (native/track_forgex/src/lib.rs): Implements the trackforge library functions, converting between Rust and Elixir types
  3. Elixir API (lib/trackers/byte_track.ex): Provides a clean, idiomatic Elixir interface to the tracker functionality
  4. Data Models (lib/utils.ex): Defines Elixir structs for bounding boxes, detections, and tracker results

This design allows for maximum performance (via Rust) while maintaining the benefits of Elixir's Ecosystem.

Rust Development

For Rust-specific development:

cd native/track_forgex
cargo build

License

MIT License - see LICENSE file for details

Changelog

See CHANGELOG.md for a list of changes.

Contributing

Contributions are welcome! Please ensure all tests pass before submitting a pull request.

# Format code
mix format

# Run checks
mix check

# Run tests with coverage
mix test --cover

Acknowledgments