InferenceHandle Struct

Interface for SAM3 segmentation inference. More...

Declaration

struct moveit_pro::behaviors::GetMasks2DFromExemplar::InferenceHandle { ... }

Included Headers

#include <get_masks_2d_from_exemplar.hpp>

Derived Structs

struct	SAM3DetectHandle
	Default implementation using SAM3Detect. More...

Public Destructor Index

	~InferenceHandle ()=default

Public Member Functions Index

tl::expected< void, std::string >	load (const std::filesystem::path &bundle_manifest, std::string_view runtime_id)=0
	Load a runtime variant from a SAM3 model bundle. More...
tl::expected< moveit_pro_ml::SAM3DetectResult, std::string >	predict (const moveit_pro_ml::data::Tensor< float, moveit_pro_ml::data::format::NCHW > &image, std::string_view text_prompt, const std::vector< moveit_pro_ml::SAM3Box > &box_prompts, float confidence_threshold=0.5f) const =0
	Run SAM3 prediction with text and box prompts. More...
void	requestTerminate () const =0
	Request termination of any in-flight predict() call. More...
void	clearTerminate () const =0
	Clear a previously-set terminate flag. More...
std::optional< moveit_pro_ml::Device >	servingDevice () const
	The device actually serving inference, if known. More...

Description

Interface for SAM3 segmentation inference.

This interface allows dependency injection of different SAM3 implementations for testing with GoogleMock. Follows the same pattern as SAM2 automasking.

See Also

moveit_pro_ml::SAM3Detect for the underlying model implementation

Definition at line 182 of file get_masks_2d_from_exemplar.hpp.

Public Destructor

~InferenceHandle()

virtual moveit_pro::behaviors::GetMasks2DFromExemplar::InferenceHandle::~InferenceHandle ()

virtual default

Definition at line 184 of file get_masks_2d_from_exemplar.hpp.

Public Member Functions

clearTerminate()

virtual void moveit_pro::behaviors::GetMasks2DFromExemplar::InferenceHandle::clearTerminate ()

Clear a previously-set terminate flag.

Must be called before predict() if the previous predict() was halted, otherwise the next run aborts immediately. The behavior calls this at the start of doWork() before signalling that halt is allowed via notifyCanHalt().

Definition at line 235 of file get_masks_2d_from_exemplar.hpp.

load()

virtual tl::expected< void, std::string > moveit_pro::behaviors::GetMasks2DFromExemplar::InferenceHandle::load (const std::filesystem::path & bundle_manifest, std::string_view runtime_id)

Load a runtime variant from a SAM3 model bundle.

Idempotent: called from every doWork(), and once a model is loaded every later call returns immediately. The model therefore latches for the handle's lifetime — the arguments are read on the first call only.

That means this is not the place a changed bundle or runtime is detected. The caller compares the ports against what it latched and fails the Behavior, because swapping models mid-run would mean a multi-second uninterruptible load at an arbitrary point in an Objective.

A failed load leaves the handle empty, so the next call retries rather than reporting a model that was never built.

Parameters

bundle_manifest	Path to the relocatable versioned bundle manifest.
runtime_id	Runtime variant to select from the bundle.

Returns

An error message if model initialization fails.

Definition at line 204 of file get_masks_2d_from_exemplar.hpp.

predict()

virtual tl::expected< moveit_pro_ml::SAM3DetectResult, std::string > moveit_pro::behaviors::GetMasks2DFromExemplar::InferenceHandle::predict (const moveit_pro_ml::data::Tensor< float, moveit_pro_ml::data::format::NCHW > & image, std::string_view text_prompt, const std::vector< moveit_pro_ml::SAM3Box > & box_prompts, float confidence_threshold=0.5f)

Run SAM3 prediction with text and box prompts.

Parameters

image	Input image to segment in NCHW format [1, 3, 1008, 1008] (RGB float normalized to [-1,1])
text_prompt	Text description for segmentation (can be empty)
box_prompts	Bounding box prompts in normalized CXCYWH format
confidence_threshold	Minimum confidence score to keep a mask (default 0.5)

Returns

Expected containing masks and scores, or error message

Definition at line 217 of file get_masks_2d_from_exemplar.hpp.

requestTerminate()

virtual void moveit_pro::behaviors::GetMasks2DFromExemplar::InferenceHandle::requestTerminate ()

Request termination of any in-flight predict() call.

Thread-safe; intended to be called from the behavior's doHalt() handler while another thread is blocked inside predict(). The terminate flag is sticky; the caller is responsible for calling clearTerminate() before the next predict() so a stale flag does not abort it.

Definition at line 227 of file get_masks_2d_from_exemplar.hpp.

servingDevice()

virtual std::optional< moveit_pro_ml::Device > moveit_pro::behaviors::GetMasks2DFromExemplar::InferenceHandle::servingDevice ()

inline virtual

The device actually serving inference, if known.

Defaults to unknown so test doubles need not implement it. The behavior uses this to surface an operator-facing warning when inference silently fell back to CPU.

Definition at line 242 of file get_masks_2d_from_exemplar.hpp.

---

The documentation for this struct was generated from the following file:

• get_masks_2d_from_exemplar.hpp

---

Generated via doxygen2docusaurus 2.2.2 by Doxygen 1.9.8.