ViAiTracker^LT

namespace ViAi {

/// @brief Everything the tracker needs: which model to load and the tracking parameters.
///
/// Each member matches a key of the [tracker] section of ViAiTracker.cfg (given in brackets). The model members
/// are fixed once a ViAiTracker is created; the tracking parameters can be changed at any time with
/// ViAiTracker::setConfig(). The defaults are the values the models were trained with.
struct ViAiTrackerConfig {
    // ------------------------------------------------------------------ model (fixed when the tracker is created)

    /// @brief [model] Model to run: "ts" - fastest; "bs" more accurate.
    std::string model = "ts";

    /// @brief [precision] Engine precision: "fp32", "fp16" (ts only), "fp16mix" or "amp").
    std::string precision = "fp16mix";

    /// @brief [models_dir] Folder holding the model file ViAiTracker_<model>_<precision>.run.
    ///
    /// A relative path in the cfg file is relative to the cfg file's folder.
    std::string modelsDir = "models";

    /// @brief [device] Index of the CUDA GPU that runs the model.
    int device = 0;

    // ------------------------------------------------------------------ tracking (can change while tracking)

    /// @brief [search_factor] Size of the search region, as a multiple of the target size.
    ///
    /// Every frame a square region of side searchFactor x sqrt(w x h) is cut around the previous target position.
    /// Larger values let the tracker follow faster motion but make the target smaller inside the fixed-size
    /// network input.
    float searchFactor = 3.5f;

    /// @brief [update_interval] Online template update period, in frames (bs only; no effect on ts).
    ///
    /// Every updateInterval frames the current target appearance replaces the second template (if the score
    /// reaches updateThreshold).
    int updateInterval = 25;

    /// @brief [update_threshold] Minimum score (0..1) a frame must reach to be used for a template update (bs only).
    ///
    /// Avoids learning a template from a frame where the target is occluded or lost.
    float updateThreshold = 0.6f;

    /// @brief Reads the [tracker] section of a ViAiTracker.cfg file.
    ///
    /// Other sections belong to the application and are skipped.
    /// @param path Path of the cfg file; relative paths inside it are resolved against its folder.
    /// @return The configuration, already checked with validate().
    /// @throws std::runtime_error if the file cannot be read, or [tracker] has an unknown key or an invalid value.
    static ViAiTrackerConfig load(const std::string& path);

    /// @brief Checks the model / precision combination and the parameter ranges.
    /// @throws std::runtime_error with a readable message on the first problem found.
    void validate() const;
};

/// @brief Output of ViAiTracker::track() for one frame.
struct ViAiTrackerResult {
    /// @brief Estimated target box in image pixels (x, y = top-left corner, width, height).
    cv::Rect2f box;

    /// @brief Tracking confidence, 0..1. Low values mean the target is probably occluded or lost.
    float score = 0;
};

/// @brief Single-object tracker.
///
/// Usage: construct from a ViAiTrackerConfig, call init() with the target box on the first frame, then track()
/// on every following frame.
class ViAiTracker {
public:
    /// @brief Loads the model named by the configuration.
    /// @param config Model, precision, models folder, device and tracking parameters.
    /// @throws std::runtime_error if the configuration is invalid, the model file is missing or cannot be loaded.
    explicit ViAiTracker(const ViAiTrackerConfig& config);

    /// @brief Releases the engines and the GPU / NPU memory.
    ~ViAiTracker();

    ViAiTracker(const ViAiTracker&) = delete;
    ViAiTracker& operator=(const ViAiTracker&) = delete;

    /// @brief Starts tracking a target.
    /// @param bgr Image containing the target, BGR 8UC3 as delivered by OpenCV.
    /// @param box Target box in pixels (x, y = top-left corner, width, height).
    void init(const cv::Mat& bgr, const cv::Rect2f& box);

    /// @brief Locates the target in the next frame.
    /// @param bgr Next video frame, BGR 8UC3.
    /// @return Target box and confidence score.
    ViAiTrackerResult track(const cv::Mat& bgr);

    /// @brief Current configuration.
    /// @return Reference to the configuration used by track().
    const ViAiTrackerConfig& config() const;

    /// @brief Changes the tracking parameters (searchFactor, updateInterval, updateThreshold); takes effect from
    /// the next track() call.
    /// @param config New configuration; its model members must equal the current ones.
    /// @throws std::runtime_error if a model member differs (create a new tracker for another model) or a
    /// parameter is out of range.
    void setConfig(const ViAiTrackerConfig& config);

private:
    /// @brief Gives VIAITEC's internal tools (src/ViAiTrackerDev.h) read access to the implementation.
    friend struct ViAiTrackerDevAccess;

    /// @brief Implementation (model description, engines, tracking state), defined in ViAiTracker.cpp.
    struct Impl;

    /// @brief Owns the implementation.
    std::unique_ptr<Impl> impl_;
};

}  // namespace ViAi