Configuration

SUMMARY

Iris model wrappers use typed configuration objects for architecture-specific training and post-processing behavior. Shared Trainer settings and export or deployment options are documented with their respective workflows.

RF-DETR

RFDETR

from telekinesis.iris.models import RFDETR

model = RFDETR(
    variant="seg-medium",
    num_classes=1,
    pretrained=True,
)

Option	Default	Description
variant	"seg-medium"	Detection or segmentation model variant
num_classes	1	Number of class slots used by the model
pretrained	True	Loads pretrained model weights
resolution	None	Overrides the variant's native square input resolution
config	None	Explicit RF-DETR model configuration; cannot be combined with resolution
adapter_config	None	Optional RFDETRTrainingAdapterConfig

Detection variants are nano, small, medium, base, and large. Segmentation variants are seg-nano, seg-small, seg-medium, seg-large, seg-xlarge, and seg-2xlarge.

RFDETRTrainingAdapterConfig

Controls preprocessing, target conversion, evaluation, and validation previews.

Option	Default	Description
validation_images_to_log	4	Maximum validation predictions logged per evaluation
image_mean	(0.485, 0.456, 0.406)	Per-channel normalization mean; None disables mean normalization
image_std	(0.229, 0.224, 0.225)	Per-channel normalization standard deviation
box_format	"xyxy"	Input target box format: "xyxy" or "cxcywh"
normalize_boxes	True	Converts target boxes to normalized coordinates
background_class_id	0	Background class slot; None disables background filtering

from telekinesis.iris.models import RFDETR, RFDETRTrainingAdapterConfig

adapter_config = RFDETRTrainingAdapterConfig(
    validation_images_to_log=8,
    box_format="xyxy",
    normalize_boxes=True,
    background_class_id=0,
)

model = RFDETR(adapter_config=adapter_config)

RFDETRPostprocessConfig

Option	Default	Description
confidence_threshold	0.3	Minimum retained confidence in the range [0, 1]
max_detections	300	Maximum predictions returned per image

Properties

Property	Type	Description
model	nn.Module	Underlying RF-DETR PyTorch model
adapter	RFDETRTrainingAdapter	Cached training adapter
name	str	Public variant name
train_transforms	ResizeTransforms	Training dataset transforms
val_transforms	ResizeTransforms	Validation dataset transforms
requires_masks	bool	True for segmentation variants

SAM3-LoRA

SAM3LoRA

from telekinesis.iris.models import SAM3LoRA

model = SAM3LoRA(
    class_names=categories,
    resolution=1008,
    num_negative_prompts=2,
)

Option	Default	Description
class_names	required	Category ID-to-prompt mapping or prompt sequence
config	None	Optional SAM3LoRAConfig for model and LoRA settings
training_config	None	Optional SAM3LoRATrainingConfig
resolution	None	Convenience override for training resolution
num_negative_prompts	None	Convenience override for negative prompts per sample

training_config cannot be combined with the resolution or num_negative_prompts convenience options.

SAM3LoRAConfig

Controls checkpoint loading and where LoRA adapters are applied.

Option	Default	Description
checkpoint_path	None	Local SAM3 base checkpoint
lora_weights_path	None	Existing LoRA weights to load
load_from_hf	True	Loads base weights from Hugging Face
rank	8	LoRA rank; must be at least 1
alpha	16.0	LoRA scaling factor
dropout	0.1	LoRA dropout in the range [0, 1)
target_modules	standard projection names	Module-name suffixes eligible for LoRA replacement
apply_to_vision_encoder	True	Applies LoRA to the vision encoder
apply_to_text_encoder	True	Applies LoRA to the text encoder
apply_to_geometry_encoder	False	Applies LoRA to the geometry encoder
apply_to_detr_encoder	True	Applies LoRA to the DETR encoder
apply_to_detr_decoder	True	Applies LoRA to the DETR decoder
apply_to_mask_decoder	False	Applies LoRA to the mask decoder

The default target_modules are q_proj, k_proj, v_proj, out_proj, qkv, proj, fc1, fc2, c_fc, c_proj, linear1, and linear2. When load_from_hf=False, checkpoint_path is required.

SAM3LoRATrainingConfig

Option	Default	Description
resolution	1008	Positive square training resolution
num_negative_prompts	2	Negative category prompts sampled per example

SAM3PostprocessConfig

Option	Default	Description
confidence_threshold	0.3	Minimum retained confidence in the range [0, 1]
max_detections	300	Maximum predictions returned per image
per_prompt_nms_threshold	0.5	Per-prompt NMS IoU threshold; None disables NMS
prompt_conflict_policy	"multi_label"	"multi_label" retains overlaps; "best_prompt" resolves them
cross_prompt_iou_threshold	0.8	IoU used to identify cross-prompt conflicts

Properties

Property	Type	Description
model	nn.Module	Underlying SAM3 PyTorch model
adapter	SAM3LoRATrainingAdapter	Cached prompted-training adapter
name	str	Always "sam3-lora"
train_transforms	None	Preprocessing is handled by the adapter
val_transforms	None	Preprocessing is handled by the adapter
requires_masks	bool	Always True

See Train and Resume a Model for Trainer settings and Export and Deploy for export and deployment options.