sam3_geometry.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Povl Filip Sonne-Frederiksen
//
// SPDX-License-Identifier: GPL-3.0-or-later
//
// Backend-agnostic helpers for SAM3 geometry (box) prompts: the box encoding
// the geometry encoder expects and the per-prompt token layout the decoder
// consumes. Standard library only, so they are unit-testable without a GPU.
 
#pragma once
 
#include "reusex/vision/sam3_prompt.hpp"
 
#include <array>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
namespace reusex::vision {

std::array<float, 4> sam3_box_cxcywh(const std::array<float, 4> &xyxy,
                                     int image_w, int image_h);

std::int64_t sam3_box_label(std::string_view polarity) noexcept;

int sam3_geometry_slot_len(int max_boxes) noexcept;

 
std::vector<std::uint8_t> sam3_geometry_slot_mask(int n_boxes, int slot_len);

std::optional<bool>
sam3_mask_true_is_valid(const std::vector<std::uint8_t> &mask, int real_tokens);

constexpr bool sam3_mask_value(bool valid, bool true_is_valid) noexcept {
  return valid == true_is_valid;
}

int sam3_geometry_box_count(std::size_t requested, int capacity) noexcept;

int sam3_geometry_capacity(int model_cap, int encoder_min_boxes,
                           int encoder_max_boxes, int text_len,
                           int decoder_max_len) noexcept;

bool sam3_detection_selected(
    const std::array<float, 4> &det_xyxy, const std::vector<SegmentBox> &boxes,
    const std::vector<std::array<float, 2>> &points = {},
    const std::function<bool(float, float)> &covers = {});

const std::vector<float> &sam3_point_exemplar_fracs();

std::array<float, 4> sam3_point_exemplar_box(const std::array<float, 2> &point,
                                             int image_w, int image_h,
                                             float frac);

std::vector<std::size_t>
sam3_best_detection_per_point(const std::vector<float> &scores,
                              const std::vector<std::vector<bool>> &covers);

std::vector<std::size_t>
sam3_point_prompt_selection(const std::vector<float> &scores,
                            const std::vector<std::vector<bool>> &covers,
                            const std::vector<bool> &box_selected);

class Sam3GeometryFailures {
    public:
  static constexpr int kFailuresBeforeDisable = 3;

  bool record_failure() noexcept {
    return ++consecutive_ >= kFailuresBeforeDisable;
  }
  void record_success() noexcept { consecutive_ = 0; }
  [[nodiscard]] int consecutive() const noexcept { return consecutive_; }
 
    private:
  int consecutive_ = 0;
};
 
} // namespace reusex::vision