Classes
struct	EngineBuildProfiles
	The full set of per-engine build recipes. More...
struct	EngineProfile
	Per-engine TensorRT build recipe, deserialized from engine-build.json. More...
struct	PrepProgress
	Best-effort progress report emitted during preparation. More...
struct	Sam3AssetOptions
	Controls where the managed SAM3 model lives and how it is fetched. More...
class	Sam3PrepCancelled
	Thrown by prepare_sam3_model() when Sam3AssetOptions::cancel was raised. More...

Typedefs
using	ProgressCallback = std::function<void(const PrepProgress &)>

Enumerations
enum class	PrepState { absent , not_built , downloading , building , ready , error }
	Lifecycle state of the managed SAM3 model on this device. More...

Functions
std::optional< EngineProfile >	text_only_fallback (const std::string &engine_name, const EngineProfile &profile)
	The text-only fallback for an engine whose geometry-prompt profile cannot be built: an export that bakes the prompt length or box count into its graph (the TorchScript exporter can constant-fold the trace shape) builds only at that shape.
std::optional< std::string >	profile_shape_conflict (const std::vector< long long > &network_dims, const EngineProfile::ShapeProfile &profile)
	Why an optimization profile cannot apply to a network input whose dims are network_dims (-1 = dynamic): a rank mismatch, or a static dim the profile's min or max does not equal.
bool	is_shape_build_error (const std::vector< std::string > &builder_errors)
	Whether a failed TensorRT build's error messages point at the profile's shapes (a dimension, reshape or profile error) rather than at resources: any message about memory, allocation or disk makes it a resource failure.
const char *	to_string (PrepState state)
const std::vector< std::string > &	required_engines ()
	The detector engines every SAM3 model needs (vision encoder, text encoder, geometry encoder, decoder).
std::filesystem::path	resolve_models_dir (const std::filesystem::path &explicit_dir={})
	Resolve the base models directory: explicit models_dir > $REUSEX_MODELS_DIR > $XDG_CACHE_HOME/reusex/models (falling back to $HOME/.cache/reusex/models).
std::filesystem::path	sam3_onnx_dir (const Sam3AssetOptions &opts)
	The directory holding the portable ONNX + tokenizer.json + tracker-meta.json.
std::filesystem::path	sam3_engine_dir (const Sam3AssetOptions &opts)
	The device-specific engine cache directory for the managed SAM3 model (keyed by GPU + TensorRT version).
std::vector< std::string >	missing_onnx_files (const std::filesystem::path &onnx_dir)
	Files the ONNX directory still lacks before it counts as a complete bundle (empty ⟹ complete).
std::vector< std::string >	missing_engine_files (const std::filesystem::path &onnx_dir, const std::filesystem::path &engine_dir)
	Files the engine directory still lacks before it is loadable (empty ⟹ ready): the required_engines(), an engine for every optional graph whose ONNX is present, tokenizer.json, and — when a tracker engine is present and the ONNX dir carries one — tracker-meta.json.
EngineBuildProfiles	load_engine_build_profiles (const std::filesystem::path &onnx_dir)
	The engine-build recipe for an ONNX dir: its own engine-build.json when present and at least as new (recipe_version) as the canonical recipe embedded at build time, else that built-in recipe (EngineBuildProfiles::builtin()).
std::vector< std::string >	stale_engines (const std::filesystem::path &onnx_dir, const std::filesystem::path &engine_dir)
	Built engines (names, without .engine) whose recipe differs from the one load_engine_build_profiles() now selects.
std::vector< std::string >	fallback_engines (const std::filesystem::path &engine_dir)
	Engines (names, without .engine) the engine directory's stamp records as built text-only because their geometry-prompt profile failed with a shape error (EngineBuildProfiles::fallback_engines).
std::vector< std::string >	fallback_engines_to_retry (const std::filesystem::path &onnx_dir, const std::filesystem::path &engine_dir)
	The fallback_engines() whose recipe profile is worth building again: the ONNX it failed against has changed since (its sha256 differs from the stamp's fallback_onnx_sha256, or the stamp predates fingerprints).
PrepProgress	sam3_status (const Sam3AssetOptions &opts)
	Non-blocking status probe: is the managed model already loadable, and in what state?
std::filesystem::path	prepare_sam3_model (const Sam3AssetOptions &opts, const ProgressCallback &cb={})
	Ensure the managed SAM3 model is ready and return a directory that vision::create_model_from_path can load:

Variables
constexpr int	kGeometryTraceBoxes = 8
	The box count the in-repo exporter traces the geometry encoder at (export_detector.GEOM_NUM_BOXES, tied to build_engines.GEOM_MAX_BOXES).

Typedef Documentation

◆ ProgressCallback

using reusex::vision::sam3::ProgressCallback = std::function<void(const PrepProgress &)>

Definition at line 48 of file sam3_assets.hpp.

Enumeration Type Documentation

◆ PrepState

enum class reusex::vision::sam3::PrepState

strong

Lifecycle state of the managed SAM3 model on this device.

Enumerator
absent	the (complete) ONNX bundle is not on disk yet
not_built	ONNX present, device engines not built, no build running.
downloading	fetching the portable ONNX bundle
building	compiling GPU-specific TensorRT engines from ONNX
ready	engines (or ONNX, for CPU) present and loadable
error	preparation failed (see message)

Definition at line 19 of file sam3_assets.hpp.

Function Documentation

◆ fallback_engines()

std::vector< std::string > reusex::vision::sam3::fallback_engines ( const std::filesystem::path & engine_dir )

Engines (names, without .engine) the engine directory's stamp records as built text-only because their geometry-prompt profile failed with a shape error (EngineBuildProfiles::fallback_engines).

They load and serve text prompts. Empty when there is no stamp or it cannot be read.

References fallback_engines().

Referenced by fallback_engines().

◆ fallback_engines_to_retry()

std::vector< std::string > reusex::vision::sam3::fallback_engines_to_retry	(	const std::filesystem::path &	onnx_dir,
		const std::filesystem::path &	engine_dir )

The fallback_engines() whose recipe profile is worth building again: the ONNX it failed against has changed since (its sha256 differs from the stamp's fallback_onnx_sha256, or the stamp predates fingerprints).

A changed recipe needs no entry here: stale_engines() already rebuilds such an engine from scratch. Everything else stays text-only for good — the failure is a deterministic property of the ONNX graph against the profile, so retrying it every session would only re-run a multi-minute build that fails again. To force a retry anyway, delete the engine file (<engine_dir>/<name>.engine): it is then missing and rebuilt.

References fallback_engines_to_retry().

Referenced by fallback_engines_to_retry().

◆ is_shape_build_error()

bool reusex::vision::sam3::is_shape_build_error ( const std::vector< std::string > & builder_errors )

Whether a failed TensorRT build's error messages point at the profile's shapes (a dimension, reshape or profile error) rather than at resources: any message about memory, allocation or disk makes it a resource failure.

No messages ⟹ false (unknown is not a shape error).

References is_shape_build_error().

Referenced by is_shape_build_error().

◆ load_engine_build_profiles()

EngineBuildProfiles reusex::vision::sam3::load_engine_build_profiles ( const std::filesystem::path & onnx_dir )

The engine-build recipe for an ONNX dir: its own engine-build.json when present and at least as new (recipe_version) as the canonical recipe embedded at build time, else that built-in recipe (EngineBuildProfiles::builtin()).

The newer-wins rule lets a recipe change reach managed installs whose downloaded bundle ships an older recipe.

References load_engine_build_profiles().

Referenced by load_engine_build_profiles().

◆ missing_engine_files()

std::vector< std::string > reusex::vision::sam3::missing_engine_files	(	const std::filesystem::path &	onnx_dir,
		const std::filesystem::path &	engine_dir )

Files the engine directory still lacks before it is loadable (empty ⟹ ready): the required_engines(), an engine for every optional graph whose ONNX is present, tokenizer.json, and — when a tracker engine is present and the ONNX dir carries one — tracker-meta.json.

A stale engine (see stale_engines()) counts as missing, so it is rebuilt. Pure disk check; no TensorRT needed.

References missing_engine_files().

Referenced by missing_engine_files().

◆ missing_onnx_files()

std::vector< std::string > reusex::vision::sam3::missing_onnx_files ( const std::filesystem::path & onnx_dir )

Files the ONNX directory still lacks before it counts as a complete bundle (empty ⟹ complete).

A downloaded bundle records its manifest as bundle-manifest.json; then every non-optional file it lists is required. Every bundle — downloaded or a local make export — must hold the required_engines() ONNX plus tokenizer.json. Checks presence only (sha256 is verified once, at download time, before the atomic publish).

References missing_onnx_files().

Referenced by missing_onnx_files().

◆ prepare_sam3_model()

std::filesystem::path reusex::vision::sam3::prepare_sam3_model	(	const Sam3AssetOptions &	opts,
		const ProgressCallback &	cb = {} )

Ensure the managed SAM3 model is ready and return a directory that vision::create_model_from_path can load:

use_cuda → downloads ONNX if missing, builds any missing engines, and returns the engine cache dir;
otherwise → downloads ONNX if missing and returns the ONNX dir.

The ONNX bundle is downloaded into a private staging directory and renamed into place only after every manifest file is present and sha256-verified, so an interrupted download is retried from scratch rather than mistaken for a complete one. Downloads are serialized process-wide, and two processes racing on the same models dir resolve by rename-if-absent. A pre-provided $REUSEX_SAM3_ONNX_DIR is never downloaded into: if incomplete it is a hard error naming the missing files.

Blocking and potentially slow (a full engine build is minutes). Reports progress via cb. Throws std::runtime_error on failure and Sam3PrepCancelled when opts.cancel is raised.

References prepare_sam3_model().

Referenced by prepare_sam3_model().

◆ profile_shape_conflict()

std::optional< std::string > reusex::vision::sam3::profile_shape_conflict	(	const std::vector< long long > &	network_dims,
		const EngineProfile::ShapeProfile &	profile )

Why an optimization profile cannot apply to a network input whose dims are network_dims (-1 = dynamic): a rank mismatch, or a static dim the profile's min or max does not equal.

std::nullopt when it fits. Used to tell a baked-shape export from other build failures before building.

References profile_shape_conflict().

Referenced by profile_shape_conflict().

◆ required_engines()

const std::vector< std::string > & reusex::vision::sam3::required_engines ( )

The detector engines every SAM3 model needs (vision encoder, text encoder, geometry encoder, decoder).

Anything else in engine-build.json (the video tracker graphs) is optional: built when its ONNX is present, skipped otherwise.

References required_engines().

Referenced by required_engines().

◆ resolve_models_dir()

std::filesystem::path reusex::vision::sam3::resolve_models_dir ( const std::filesystem::path & explicit_dir = {} )

Resolve the base models directory: explicit models_dir > $REUSEX_MODELS_DIR > $XDG_CACHE_HOME/reusex/models (falling back to $HOME/.cache/reusex/models).

References resolve_models_dir().

Referenced by resolve_models_dir().

◆ sam3_engine_dir()

std::filesystem::path reusex::vision::sam3::sam3_engine_dir ( const Sam3AssetOptions & opts )

The device-specific engine cache directory for the managed SAM3 model (keyed by GPU + TensorRT version).

Only meaningful in a TensorRT build.

References sam3_engine_dir().

Referenced by sam3_engine_dir().

◆ sam3_onnx_dir()

std::filesystem::path reusex::vision::sam3::sam3_onnx_dir ( const Sam3AssetOptions & opts )

The directory holding the portable ONNX + tokenizer.json + tracker-meta.json.

engine-build.json for the managed SAM3 model. Honors $REUSEX_SAM3_ONNX_DIR (a pre-provided export) over the managed location.

References sam3_onnx_dir().

Referenced by sam3_onnx_dir().

◆ sam3_status()

PrepProgress reusex::vision::sam3::sam3_status ( const Sam3AssetOptions & opts )

Non-blocking status probe: is the managed model already loadable, and in what state?

Does no downloading or building, and knows nothing about work in flight — so it reports absent / not_built / ready (or error for a CUDA request in a build without TensorRT), never downloading / building; a caller that runs preparation tracks those itself.

References sam3_status().

Referenced by sam3_status().

◆ stale_engines()

std::vector< std::string > reusex::vision::sam3::stale_engines	(	const std::filesystem::path &	onnx_dir,
		const std::filesystem::path &	engine_dir )

Built engines (names, without .engine) whose recipe differs from the one load_engine_build_profiles() now selects.

An engine directory records the recipe its engines were built from as engine-build.json; a directory built before that stamp existed is compared with the ONNX dir's own engine-build.json (what the builder used then), and with no such file is assumed current. Engines not built yet are missing, not stale.

References stale_engines().

Referenced by stale_engines().

◆ text_only_fallback()

std::optional< EngineProfile > reusex::vision::sam3::text_only_fallback	(	const std::string &	engine_name,
		const EngineProfile &	profile )

The text-only fallback for an engine whose geometry-prompt profile cannot be built: an export that bakes the prompt length or box count into its graph (the TorchScript exporter can constant-fold the trace shape) builds only at that shape.

For decoder the prompt length is pinned to its minimum (the 32 text tokens); for geometry-encoder the box count is pinned to its maximum (the trace shape, 8). The result is recipe v1's shape for that engine: text segmentation keeps working and TensorRTSam3's capability check turns geometry prompts off. std::nullopt for every other engine (it has no geometry dimension to give up).

References text_only_fallback().

Referenced by text_only_fallback().

◆ to_string()

const char * reusex::vision::sam3::to_string ( PrepState state )

References to_string().

Referenced by to_string().

Variable Documentation

◆ kGeometryTraceBoxes

int reusex::vision::sam3::kGeometryTraceBoxes = 8

inlineconstexpr

The box count the in-repo exporter traces the geometry encoder at (export_detector.GEOM_NUM_BOXES, tied to build_engines.GEOM_MAX_BOXES).

text_only_fallback() pins the encoder's box axis to the profile max on the assumption that the two agree; a test checks the built-in recipe against it.

Definition at line 120 of file EngineBuildProfiles.hpp.

Classes

Typedefs

Enumerations

Functions

Variables