AI API¶

Detection¶

detection ¶

Detection module for object detection training, evaluation, and inference.

Unified interface for object detection across multiple frameworks

Examples:

>>> from nectar.ai.detection import Detector, TrainingConfig
>>>
>>> # Quick inference (auto-detects framework)
>>> detector = Detector("yolov8n.pt")
>>> detector.load()
>>> result = detector.detect(image)
>>> for det in result:
...     print(f"{det.class_name}: {det.confidence:.2f}")
>>>
>>> # Or use specific model classes for advanced usage
>>> from nectar.ai.detection import UltralyticsModel
>>> model = UltralyticsModel("yolov8n.pt")
>>> model.load_model()
>>> result = model.detect(image, conf=0.5)
>>>
>>> # Training
>>> config = TrainingConfig(
...     dataset_path="/path/to/dataset",
...     epochs=100,
...     batch_size=16,
...     tensorboard=True,
... )
>>> result = detector.train(config)

Framework ¶

Bases: Enum

Supported model frameworks for detection, segmentation, and classification.

EvaluationConfig `dataclass` ¶

EvaluationConfig(model_path: str = '', dataset_path: str = '', framework: str = '', output_dir: str = 'outputs/evaluations', dataset_type: str = 'auto', split: str = 'test', conf_threshold: float = 0.5, iou_threshold: float = 0.5, device: str = 'auto', batch_size: int = 16, num_samples: Optional[int] = None, imgsz: Optional[int] = None, prediction_samples_max: int = 4)

Configuration for model evaluation.

Parameters:

Name	Type	Description	Default
`model_path`	`str`	Path to model checkpoint.	`''`
`dataset_path`	`str`	Path to evaluation dataset.	`''`
`framework`	`str`	Model framework ('ultralytics', 'transformers', 'rfdetr').	`''`
`output_dir`	`str`	Directory for outputs. Defaults to "outputs/evaluations".	`'outputs/evaluations'`
`dataset_type`	`str`	Dataset format ('coco', 'yolo', 'auto'). Defaults to "auto".	`'auto'`
`split`	`str`	Dataset split to evaluate ('train', 'valid', 'test'). Defaults to "test".	`'test'`
`conf_threshold`	`float`	Confidence threshold. Defaults to 0.5.	`0.5`
`iou_threshold`	`float`	IoU threshold for metrics. Defaults to 0.5.	`0.5`
`device`	`str`	Device specification. Defaults to "auto".	`'auto'`
`batch_size`	`int`	Batch size for evaluation. Defaults to 16.	`16`
`num_samples`	`Optional[int]`	Limit number of samples. Defaults to None (all).	`None`

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary.

from_dict `classmethod` ¶

from_dict(data: Dict[str, Any]) -> EvaluationConfig

Create from dictionary.

from_yaml `classmethod` ¶

from_yaml(path: str) -> EvaluationConfig

Load from YAML file.

EvaluationMetrics `dataclass` ¶

EvaluationMetrics(map50: float = 0.0, map50_95: float = 0.0, mar50: float = 0.0, mar50_95: float = 0.0, precision: float = 0.0, recall: float = 0.0, f1_score: float = 0.0, inference_time_per_image: float = 0.0, total_detections: int = 0, per_class_metrics: List[Dict] = list(), visualizations: Dict[str, str] = dict())

Evaluation metrics.

Parameters:

Name	Type	Description	Default
`map50`	`float`	Mean Average Precision at IoU=0.5.	`0.0`
`map50_95`	`float`	Mean Average Precision at IoU=0.5:0.95.	`0.0`
`mar50`	`float`	Mean Average Recall at IoU=0.5.	`0.0`
`mar50_95`	`float`	Mean Average Recall at IoU=0.5:0.95.	`0.0`
`precision`	`float`	Precision at IoU=0.5.	`0.0`
`recall`	`float`	Recall at IoU=0.5.	`0.0`
`f1_score`	`float`	F1 Score at IoU=0.5.	`0.0`
`inference_time_per_image`	`float`	Average inference time per image in seconds.	`0.0`
`total_detections`	`int`	Total number of detections.	`0`
`per_class_metrics`	`List[Dict]`	Per-class metrics breakdown.	`list()`
`visualizations`	`Dict[str, str]`	Paths to generated visualizations.	`dict()`

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary.

save_json ¶

save_json(path: str) -> None

Save metrics to JSON file.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to save JSON file.	required

summary ¶

summary() -> str

Get formatted summary string.

Returns:

Type	Description
`str`	Metrics summary.

TrainingConfig `dataclass` ¶

TrainingConfig(dataset_path: str = '', epochs: int = 10, batch_size: int = 16, learning_rate: float = 0.001, output_dir: str = (lambda: str(DEFAULT_OUTPUT_DIR))(), device: str = 'auto', seed: int = 42, tensorboard: bool = True, save_period: int = 1, push_to_hub: bool = False, hub_model_id: Optional[str] = None, multi_gpu: bool = False, mixed_precision: str = 'no', gradient_accumulation_steps: int = 1, max_train_samples: Optional[int] = None, max_eval_samples: Optional[int] = None, max_test_samples: Optional[int] = None, train_split: float = 0.8, val_split: float = 0.2, test_split: float = 0.0, dataset_format: Optional[str] = None, framework: str = '', model: str = '', from_scratch: bool = False, imgsz: Optional[Union[int, List[int]]] = None, early_stopping_patience: Optional[int] = None, early_stopping_delta: float = 0.0, early_stopping_metric: str = 'eval_loss', early_stopping_mode: str = 'min', weight_decay: float = 0.0001, lr_scheduler_type: str = 'linear', warmup_steps: int = 10, warmup_ratio: float = 0.1, max_grad_norm: float = 1.0, optimizer_type: Optional[str] = None, dropout: float = 0.0, warmup_epochs: float = 3.0, warmup_momentum: float = 0.8, lrf: float = 0.01, freeze: Optional[Union[int, List[int]]] = None, cos_lr: bool = False, rfdetr_size: Optional[str] = None, lr_encoder: Optional[float] = None, use_ema: bool = True, gradient_checkpointing: bool = False, drop_path: float = 0.0, drop_mode: str = 'standard', drop_schedule: str = 'constant', cutoff_epoch: int = 0, freeze_encoder: bool = False, layer_norm: bool = False, rms_norm: bool = False, backbone_lora: bool = False, multi_scale: bool = False, force_no_pretrain: bool = False, ema_decay: float = 0.9997, ema_tau: float = 0.0, lr_vit_layer_decay: float = 0.8, lr_component_decay: float = 1.0, sync_bn: bool = True, num_workers: int = 2, set_cost_class: float = 2.0, set_cost_bbox: float = 5.0, set_cost_giou: float = 2.0, start_epoch: int = 0, gc_batch_frequency: int = 100, early_stopping_use_ema: bool = False, gc_per_accumulation: bool = True, evaluate: bool = False, resume: bool = False)

Configuration for model training.

Comprehensive configuration supporting multiple frameworks with common and framework-specific parameters.

Parameters:

Name	Type	Description	Default
`dataset_path`	`str`	Path to the training dataset.	`''`
`epochs`	`int`	Number of training epochs.	`10`
`batch_size`	`int`	Batch size per device. Defaults to 16.	`16`
`learning_rate`	`float`	Initial learning rate. Defaults to 0.001.	`0.001`
`output_dir`	`str`	Directory for outputs. Defaults to "outputs".	`(lambda: str(DEFAULT_OUTPUT_DIR))()`
`device`	`str`	Device specification ('auto', 'cpu', 'cuda', 'cuda:0'). Defaults to "auto".	`'auto'`
`seed`	`int`	Random seed for reproducibility. Defaults to 42.	`42`

Examples:

>>> config = TrainingConfig(
...     dataset_path="/path/to/dataset",
...     epochs=100,
...     batch_size=16,
...     tensorboard=True,
... )
>>> config.to_yaml("config.yaml")

to_dict ¶

to_dict() -> Dict[str, Any]

Convert configuration to dictionary.

Returns:

Type	Description
`Dict[str, Any]`	Configuration as dictionary.

to_yaml ¶

to_yaml(path: str) -> None

Save configuration to YAML file.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to save YAML file.	required

from_dict `classmethod` ¶

from_dict(data: Dict[str, Any]) -> TrainingConfig

Create configuration from dictionary.

Parameters:

Name	Type	Description	Default
`data`	`Dict[str, Any]`	Configuration dictionary.	required

Returns:

Type	Description
`TrainingConfig`	New TrainingConfig instance.

from_yaml `classmethod` ¶

from_yaml(path: str) -> TrainingConfig

Load configuration from YAML file.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to YAML file.	required

Returns:

Type	Description
`TrainingConfig`	New TrainingConfig instance.

TrainingMetrics `dataclass` ¶

TrainingMetrics(epoch: int, train_loss: float, val_loss: Optional[float] = None, map50: Optional[float] = None, map50_95: Optional[float] = None, precision: Optional[float] = None, recall: Optional[float] = None, f1_score: Optional[float] = None, learning_rate: Optional[float] = None)

Training metrics for a single epoch.

Parameters:

Name	Type	Description	Default
`epoch`	`int`	Epoch number (1-indexed).	required
`train_loss`	`float`	Training loss.	required
`val_loss`	`Optional[float]`	Validation loss.	`None`
`map50`	`Optional[float]`	mAP at IoU=0.5.	`None`
`map50_95`	`Optional[float]`	mAP at IoU=0.5:0.95.	`None`
`precision`	`Optional[float]`	Precision at IoU=0.5.	`None`
`recall`	`Optional[float]`	Recall at IoU=0.5.	`None`
`f1_score`	`Optional[float]`	F1 score at IoU=0.5.	`None`
`learning_rate`	`Optional[float]`	Current learning rate.	`None`

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary.

TrainingResult `dataclass` ¶

TrainingResult(model_path: str = '', metrics: Dict[str, float] = dict(), training_time: float = 0.0, best_epoch: int = 0, final_metrics: Optional[TrainingMetrics] = None, history: List[TrainingMetrics] = list(), config: Optional[TrainingConfig] = None)

Result of a training run.

Parameters:

Name	Type	Description	Default
`model_path`	`str`	Path to best model checkpoint.	`''`
`metrics`	`Dict[str, float]`	Final training metrics.	`dict()`
`training_time`	`float`	Total training time in seconds.	`0.0`
`best_epoch`	`int`	Epoch with best performance.	`0`
`final_metrics`	`Optional[TrainingMetrics]`	Metrics from final epoch.	`None`
`history`	`List[TrainingMetrics]`	Metrics history for all epochs.	`list()`
`config`	`Optional[TrainingConfig]`	Training configuration used.	`None`

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary.

save_json ¶

save_json(path: str) -> None

Save result to JSON file.

ConfigurationError ¶

ConfigurationError(message: str, field: str = None, value: any = None)

Bases: DetectionError

Exception raised for configuration errors.

Parameters:

Name	Type	Description	Default
`message`	`str`	Error message.	required
`field`	`str`	Configuration field that caused the error.	`None`
`value`	`any`	Invalid value provided.	`None`

DatasetError ¶

DatasetError(message: str, dataset_path: str = None)

Bases: DetectionError

Exception raised for dataset-related errors.

Raised when dataset loading, parsing, or conversion fails.

Parameters:

Name	Type	Description	Default
`message`	`str`	Error message.	required
`dataset_path`	`str`	Path to the problematic dataset.	`None`

DetectionError ¶

Bases: AIError

Base exception for all detection module errors.

Examples:

>>> try:
...     detector.detect(image)
... except DetectionError as e:
...     logger.error(f"Detection failed: {e}")

DeviceError ¶

DeviceError(message: str, device: str = None)

Bases: DetectionError

Exception raised for device-related errors.

Parameters:

Name	Type	Description	Default
`message`	`str`	Error message.	required
`device`	`str`	Device that caused the error.	`None`

EvaluationError ¶

EvaluationError(message: str, sample: str = None)

Bases: DetectionError

Exception raised during evaluation.

Parameters:

Name	Type	Description	Default
`message`	`str`	Error message.	required
`sample`	`str`	Sample that caused the error.	`None`

FrameworkError ¶

FrameworkError(message: str, framework: str, original_error: Exception = None)

Bases: DetectionError

Exception raised for framework-specific errors.

Parameters:

Name	Type	Description	Default
`message`	`str`	Error message.	required
`framework`	`str`	Name of the framework.	required
`original_error`	`Exception`	Original exception from the framework.	`None`

HuggingFaceError ¶

HuggingFaceError(message: str, repo_id: str = None, operation: str = None)

Bases: DetectionError

Exception raised for HuggingFace Hub operations.

Raised when model upload/download or repository operations fail.

Parameters:

Name	Type	Description	Default
`message`	`str`	Error message.	required
`repo_id`	`str`	Repository ID involved.	`None`
`operation`	`str`	Operation that failed ('upload', 'download', 'create').	`None`

ModelNotLoadedError ¶

ModelNotLoadedError(message: str = 'Model not loaded. Call load() first.')

Bases: AIError

Raised when inference/train is called before load().

PostProcessingError ¶

PostProcessingError(message: str, strategy: str = None)

Bases: DetectionError

Exception raised during post-processing.

Parameters:

Name	Type	Description	Default
`message`	`str`	Error message.	required
`strategy`	`str`	Name of the strategy that failed.	`None`

SlicingError ¶

SlicingError(message: str, slice_idx: int = None)

Bases: DetectionError

Exception raised during slicing inference.

Parameters:

Name	Type	Description	Default
`message`	`str`	Error message.	required
`slice_idx`	`int`	Index of the problematic slice.	`None`

TrainingError ¶

TrainingError(message: str, epoch: int = None, step: int = None)

Bases: AIError

Raised when a training run fails.

Detection `dataclass` ¶

Detection(xyxy: ndarray, confidence: float, class_id: int, class_name: str = '')

Single object detection result.

Represents a detected object with bounding box, confidence score, class identification, and computed geometric properties.

Parameters:

Name	Type	Description	Default
`xyxy`	`ndarray`	Bounding box coordinates as [x1, y1, x2, y2] in pixel coordinates.	required
`confidence`	`float`	Detection confidence score in range [0.0, 1.0].	required
`class_id`	`int`	Class identifier (zero-indexed).	required
`class_name`	`str`	Human-readable class name. Defaults to empty string.	`''`

Attributes:

Name	Type	Description
`center`	`Tuple[float, float]`	Center point (x, y) of the bounding box.
`width`	`int`	Width of bounding box in pixels.
`height`	`int`	Height of bounding box in pixels.
`area`	`int`	Area of bounding box in square pixels.

Examples:

>>> det = Detection(
...     xyxy=np.array([100, 100, 200, 200]),
...     confidence=0.95,
...     class_id=0,
...     class_name="person"
... )
>>> det.center
(150.0, 150.0)
>>> det.area
10000

center `property` ¶

center: Tuple[float, float]

Tuple[float, float]: Center point (x, y) of the bounding box.

width `property` ¶

width: int

int: Width of bounding box in pixels.

height `property` ¶

height: int

int: Height of bounding box in pixels.

area `property` ¶

area: int

int: Area of bounding box in square pixels.

bbox `property` ¶

bbox: List[int]

List[int]: Bounding box as [x1, y1, x2, y2] integers.

to_dict ¶

to_dict() -> Dict[str, Any]

Convert detection to dictionary format.

Returns:

Type	Description
`Dict[str, Any]`	Dictionary with xyxy, confidence, class_id, and class_name.

from_dict `classmethod` ¶

from_dict(data: Dict[str, Any]) -> Detection

Create Detection from dictionary.

Parameters:

Name	Type	Description	Default
`data`	`Dict[str, Any]`	Dictionary with xyxy, confidence, class_id, and optionally class_name.	required

Returns:

Type	Description
`Detection`	New Detection instance.

DetectionInput `dataclass` ¶

DetectionInput(image: Union[ImageType, BatchImageType], conf_threshold: float = 0.5, iou_threshold: float = 0.5, device: Optional[str] = None, imgsz: Optional[int] = None)

Input for detection models, supporting single images and batches.

Parameters:

Name	Type	Description	Default
`image`	`Union[ImageType, BatchImageType]`	Input image(s). Can be path, numpy array, tensor, PIL Image, or list.	required
`conf_threshold`	`float`	Confidence threshold. Defaults to 0.5.	`0.5`
`iou_threshold`	`float`	IoU threshold for NMS. Defaults to 0.5.	`0.5`
`device`	`Optional[str]`	Device to run inference on. Defaults to None (auto-detect).	`None`

Attributes:

Name	Type	Description
`is_batch`	`bool`	True if input contains multiple images.

is_batch `property` ¶

is_batch: bool

bool: Check if input contains a batch of images.

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary format.

Returns:

Type	Description
`Dict[str, Any]`	Dictionary with configuration values.

DetectionResult `dataclass` ¶

DetectionResult(detections: List[Detection] = list(), image: Optional[ndarray] = None, inference_time: float = 0.0, image_path: Optional[str] = None, model_name: Optional[str] = None)

Container for detection results from a single image.

Iteration, filtering, and conversion methods

Parameters:

Name	Type	Description	Default
`detections`	`List[Detection]`	List of Detection objects.	`list()`
`image`	`Optional[ndarray]`	Original image (BGR format). Defaults to None.	`None`
`inference_time`	`float`	Inference time in seconds. Defaults to 0.0.	`0.0`
`image_path`	`Optional[str]`	Path to source image. Defaults to None.	`None`
`model_name`	`Optional[str]`	Name of the model used. Defaults to None.	`None`

Examples:

>>> result = detector.detect(image)
>>> len(result)  # Number of detections
5
>>> for det in result:
...     print(det.class_name, det.confidence)
>>> persons = result.filter_by_class(["person"])
>>> high_conf = result.filter_by_confidence(0.8)

filter_by_class ¶

filter_by_class(class_names: List[str]) -> DetectionResult

Filter detections by class names.

Parameters:

Name	Type	Description	Default
`class_names`	`List[str]`	List of class names to keep.	required

Returns:

Type	Description
`DetectionResult`	New DetectionResult with filtered detections.

filter_by_confidence ¶

filter_by_confidence(threshold: float) -> DetectionResult

Filter detections by confidence threshold.

Parameters:

Name	Type	Description	Default
`threshold`	`float`	Minimum confidence threshold.	required

Returns:

Type	Description
`DetectionResult`	New DetectionResult with filtered detections.

filter_by_class_id ¶

filter_by_class_id(class_ids: List[int]) -> DetectionResult

Filter detections by class IDs.

Parameters:

Name	Type	Description	Default
`class_ids`	`List[int]`	List of class IDs to keep.	required

Returns:

Type	Description
`DetectionResult`	New DetectionResult with filtered detections.

to_supervision ¶

to_supervision() -> Detections

Convert to supervision Detections object.

Returns:

Type	Description
`Detections`	Supervision Detections object.

Raises:

Type	Description
`ImportError`	If supervision is not installed.

from_supervision `classmethod` ¶

from_supervision(detections: Detections, class_names: Dict[int, str], inference_time: float = 0.0, image_path: Optional[str] = None, model_name: Optional[str] = None, image: Optional[ndarray] = None) -> DetectionResult

Create DetectionResult from supervision Detections.

Parameters:

Name	Type	Description	Default
`detections`	`Detections`	Supervision Detections object.	required
`class_names`	`Dict[int, str]`	Mapping from class ID to class name.	required
`inference_time`	`float`	Inference time in seconds.	`0.0`
`image_path`	`Optional[str]`	Path to source image.	`None`
`model_name`	`Optional[str]`	Name of the model used.	`None`
`image`	`Optional[ndarray]`	Original image.	`None`

Returns:

Type	Description
`DetectionResult`	New DetectionResult instance.

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary format.

Returns:

Type	Description
`Dict[str, Any]`	Dictionary representation.

Prediction `dataclass` ¶

Prediction(detections: Optional[Detections] = None, batch_detections: Optional[List[Detections]] = None, results: Optional[List[DetectionResult]] = None, inference_time: float = 0.0, image_path: Optional[Union[str, List[str]]] = None, model_name: Optional[str] = None)

Model prediction output for single image or batch.

Unified prediction container supporting both supervision Detections and converted DetectionResult formats.

Parameters:

Name	Type	Description	Default
`detections`	`Optional[Detections]`	Single image detections (supervision format).	`None`
`batch_detections`	`Optional[List[Detections]]`	Batch detections (supervision format).	`None`
`results`	`Optional[List[DetectionResult]]`	Converted detection results.	`None`
`inference_time`	`float`	Total inference time in seconds.	`0.0`
`image_path`	`Optional[Union[str, List[str]]]`	Source image path(s).	`None`
`model_name`	`Optional[str]`	Name of the model used.	`None`

is_batch `property` ¶

is_batch: bool

bool: Check if prediction is for a batch of images.

num_detections `property` ¶

num_detections: int

int: Total number of detections across all images.

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary format.

Returns:

Type	Description
`Dict[str, Any]`	Dictionary representation.

from_detections `classmethod` ¶

from_detections(detections: Detections, class_names: Dict[int, str], inference_time: float, image_path: str, model_name: Optional[str] = None) -> Prediction

Create Prediction from supervision Detections.

Parameters:

Name	Type	Description	Default
`detections`	`Detections`	Supervision Detections object.	required
`class_names`	`Dict[int, str]`	Mapping from class ID to class name.	required
`inference_time`	`float`	Inference time in seconds.	required
`image_path`	`str`	Path to source image.	required
`model_name`	`Optional[str]`	Name of the model used.	`None`

Returns:

Type	Description
`Prediction`	New Prediction instance.

from_batch_detections `classmethod` ¶

from_batch_detections(batch_detections: List[Detections], class_names: Dict[int, str], inference_time: float, image_paths: List[str], model_name: Optional[str] = None) -> Prediction

Create Prediction from batch of supervision Detections.

Parameters:

Name	Type	Description	Default
`batch_detections`	`List[Detections]`	List of supervision Detections objects.	required
`class_names`	`Dict[int, str]`	Mapping from class ID to class name.	required
`inference_time`	`float`	Total inference time in seconds.	required
`image_paths`	`List[str]`	Paths to source images.	required
`model_name`	`Optional[str]`	Name of the model used.	`None`

Returns:

Type	Description
`Prediction`	New Prediction instance.

Detector ¶

Detector(model_source: str, framework: Optional[Union[Framework, str]] = None, device: str = 'auto', confidence_threshold: float = 0.25, hf_token: Optional[str] = None, **kwargs)

Unified detector with factory pattern for creating model instances.

Supports auto-detection from model name or explicit framework specification.

Parameters:

Name	Type	Description	Default
`model_source`	`str`	Model path, name, or HuggingFace ID.	required
`framework`	`Optional[Union[Framework, str]]`	Explicit framework. Auto-detects if not provided.	`None`
`device`	`str`	Device ('auto', 'cpu', 'cuda', '0'). Defaults to 'auto'.	`'auto'`
`confidence_threshold`	`float`	Default confidence threshold. Defaults to 0.25.	`0.25`
`**kwargs`		Additional arguments passed to the model constructor.	`{}`

Attributes:

Name	Type	Description
`framework`	`Framework`	The framework being used.
`class_names`	`Dict[int, str]`	Class ID to name mapping.
`is_loaded`	`bool`	Whether model is loaded.

Examples:

>>> detector = Detector("yolov8n.pt")
>>> detector.load()
>>> result = detector.detect(image)
>>>
>>> # Explicit framework
>>> detector = Detector("model.pt", framework="ultralytics")
>>>
>>> # Using enum
>>> detector = Detector("facebook/detr-resnet-50", framework=Framework.TRANSFORMERS)

framework `property` ¶

framework: Framework

Framework: The framework being used.

is_loaded `property` ¶

is_loaded: bool

bool: Check if model is loaded.

class_names `property` ¶

class_names: Dict[int, str]

Dict[int, str]: Class ID to name mapping.

model `property` ¶

model: BaseDetectionModel

BaseDetectionModel: Underlying model for advanced usage.

register `classmethod` ¶

register(framework: Union[Framework, str], builder: BuilderFunc) -> None

Register a framework builder.

Parameters:

Name	Type	Description	Default
`framework`	`Union[Framework, str]`	Framework identifier.	required
`builder`	`BuilderFunc`	Factory function (model_name, **kwargs) -> BaseDetectionModel.	required

available_frameworks `classmethod` ¶

available_frameworks() -> List[str]

Get registered frameworks.

Returns:

Type	Description
`List[str]`	Available framework names.

load ¶

load(model_path: Optional[str] = None) -> bool

Load the model.

Parameters:

Name	Type	Description	Default
`model_path`	`Optional[str]`	Override model path.	`None`

Returns:

Type	Description
`bool`	True if loaded successfully.

detect ¶

detect(image: Union[ndarray, str, Path], conf: Optional[float] = None, iou: Optional[float] = None) -> DetectionResult

Run detection on a single image.

Parameters:

Name	Type	Description	Default
`image`	`Union[ndarray, str, Path]`	Input image (BGR format or path).	required
`conf`	`Optional[float]`	Confidence threshold.	`None`
`iou`	`Optional[float]`	IoU threshold for NMS.	`None`

Returns:

Type	Description
`DetectionResult`	Detection results.

Raises:

Type	Description
`RuntimeError`	If model not loaded.

detect_batch ¶

detect_batch(images: List[Union[ndarray, str, Path]], conf: Optional[float] = None, iou: Optional[float] = None) -> List[DetectionResult]

Run detection on multiple images.

Parameters:

Name	Type	Description	Default
`images`	`List[Union[ndarray, str, Path]]`	List of input images.	required
`conf`	`Optional[float]`	Confidence threshold.	`None`
`iou`	`Optional[float]`	IoU threshold.	`None`

Returns:

Type	Description
`List[DetectionResult]`	List of detection results.

train ¶

train(config: TrainingConfig) -> Dict[str, Any]

Train the model.

Parameters:

Name	Type	Description	Default
`config`	`TrainingConfig`	Training configuration.	required

Returns:

Type	Description
`Dict[str, Any]`	Training results with model_path and metrics.

evaluate ¶

evaluate(config: EvaluationConfig) -> Dict[str, Any]

Evaluate the model.

Parameters:

Name	Type	Description	Default
`config`	`EvaluationConfig`	Evaluation configuration.	required

Returns:

Type	Description
`Dict[str, Any]`	Evaluation metrics.

draw_detections ¶

draw_detections(image: ndarray, result: DetectionResult, show_labels: bool = True, show_confidence: bool = True, show_class: bool = True, annotator_type: str = 'box', thickness: int = 2, text_scale: float = 0.5) -> ndarray

Draw detection annotations on image.

Parameters:

Name	Type	Description	Default
`image`	`ndarray`	Input image (BGR).	required
`result`	`DetectionResult`	Detection results.	required
`show_labels`	`bool`	Show labels.	`True`
`show_confidence`	`bool`	Show confidence.	`True`
`show_class`	`bool`	Show class names.	`True`
`annotator_type`	`str`	Style: 'box', 'round_box', 'color'.	`'box'`
`thickness`	`int`	Line thickness.	`2`
`text_scale`	`float`	Text scale.	`0.5`

Returns:

Type	Description
`ndarray`	Annotated image.

enable_slicing ¶

enable_slicing(config: Optional[Dict[str, Any]] = None) -> None

Enable slicing inference for high-resolution images.

disable_slicing ¶

disable_slicing() -> None

Disable slicing inference.

ModelLoader ¶

Utility for loading models from local storage or Hugging Face.

from_huggingface `staticmethod` ¶

from_huggingface(repo_id: str, filename: Optional[str] = None, cache_dir: Optional[str] = None, token: Optional[str] = None) -> str

Download and load model from Hugging Face.

Supports two formats: 1. Separate args: repo_id="org/repo", filename="model.pt" 2. Combined: repo_id="org/repo:model.pt"

from_path `staticmethod` ¶

from_path(model_path: str) -> str

Validate and return absolute local model path.

load `staticmethod` ¶

load(model_source: str, cache_dir: Optional[str] = None, token: Optional[str] = None) -> str

Smart loader for local paths or Hugging Face user/repo:file.pt.

DeviceManager ¶

DeviceManager()

Manager for device allocation and memory.

Examples:

>>> manager = DeviceManager()
>>> device = manager.get_best_device()
>>> manager.log_memory_usage()
>>> manager.clear_cache()

Initialize device manager.

get_best_device ¶

get_best_device(prefer_gpu: bool = True, min_memory_gb: float = 0.0) -> device

Get best available device.

Parameters:

Name	Type	Description	Default
`prefer_gpu`	`bool`	Prefer GPU over CPU. Defaults to True.	`True`
`min_memory_gb`	`float`	Minimum GPU memory required. Defaults to 0.0.	`0.0`

Returns:

Type	Description
`device`	Best available device.

get_memory_info ¶

get_memory_info(device: Optional[device] = None) -> dict

Get memory information for device.

Parameters:

Name	Type	Description	Default
`device`	`Optional[device]`	Device to query. Defaults to current CUDA device.	`None`

Returns:

Type	Description
`dict`	Memory information.

log_memory_usage ¶

log_memory_usage(device: Optional[device] = None) -> None

Log memory usage to logger.

Parameters:

Name	Type	Description	Default
`device`	`Optional[device]`	Device to query.	`None`

clear_cache ¶

clear_cache() -> None

Clear GPU cache.

set_memory_fraction ¶

set_memory_fraction(fraction: float = 0.9) -> None

Set maximum memory fraction per GPU.

Parameters:

Name	Type	Description	Default
`fraction`	`float`	Fraction of GPU memory to use (0.0 to 1.0). Defaults to 0.9.	`0.9`

HuggingFaceUploader ¶

HuggingFaceUploader(repo_id: str, local_dir: str, token: Optional[str] = None, repo_type: str = 'model', private: bool = True)

Handles uploading models and artifacts to HuggingFace Hub.

Parameters:

Name	Type	Description	Default
`repo_id`	`str`	HuggingFace Hub repository ID (username/repo_name).	required
`local_dir`	`str`	Local directory containing files to upload.	required
`token`	`Optional[str]`	HuggingFace API token. Uses HF_TOKEN env var if not provided.	`None`
`repo_type`	`str`	Repository type ('model', 'dataset', 'space'). Defaults to 'model'.	`'model'`
`private`	`bool`	Make repository private. Defaults to True.	`True`

Examples:

>>> uploader = HuggingFaceUploader(
...     repo_id="user/my-model",
...     local_dir="outputs/",
...     private=True,
... )
>>> uploader.ensure_repo_exists()
>>> uploader.upload(commit_message="Training checkpoint")

Initialize uploader.

ensure_repo_exists ¶

ensure_repo_exists() -> bool

Ensure repository exists, creating if needed.

Returns:

Type	Description
`bool`	True if repository exists or was created.

upload ¶

upload(commit_message: str, ignore_patterns: Optional[List[str]] = None, path_in_repo: Optional[str] = None) -> Dict[str, Any]

Upload directory contents to HuggingFace Hub.

Parameters:

Name	Type	Description	Default
`commit_message`	`str`	Commit message.	required
`ignore_patterns`	`Optional[List[str]]`	Patterns to ignore (e.g., ["*.log"]).	`None`
`path_in_repo`	`Optional[str]`	Target path in repository.	`None`

Returns:

Type	Description
`Dict[str, Any]`	Upload response.

upload_file ¶

upload_file(file_path: str, path_in_repo: str, commit_message: str) -> Dict[str, Any]

Upload a single file.

Parameters:

Name	Type	Description	Default
`file_path`	`str`	Local file path.	required
`path_in_repo`	`str`	Target path in repository.	required
`commit_message`	`str`	Commit message.	required

Returns:

Type	Description
`Dict[str, Any]`	Upload response.

TensorBoardManager ¶

TensorBoardManager()

Manages TensorBoard server lifecycle.

Handles starting and stopping TensorBoard server processes with proper cleanup and error handling.

Examples:

>>> manager = TensorBoardManager()
>>> manager.start_server(log_dir="outputs", port=6006)
>>> # ... training ...
>>> manager.stop_server()

Initialize TensorBoard manager.

start_server ¶

start_server(log_dir: str, port: int = 6006, is_main_process: bool = True) -> None

Start TensorBoard server in the background.

Parameters:

Name	Type	Description	Default
`log_dir`	`str`	Directory containing TensorBoard logs.	required
`port`	`int`	Port to run TensorBoard on. Defaults to 6006.	`6006`
`is_main_process`	`bool`	Only start server if this is the main process. Defaults to True.	`True`

Notes

The server process is automatically cleaned up on exit via atexit.

stop_server ¶

stop_server() -> None

Stop TensorBoard server if it's running.

Notes

This method is safe to call multiple times and when the server is not running.

BaseDetectionModel ¶

BaseDetectionModel(model_name: str, framework: str = '')

Bases: ABC

Abstract base class for all detection models.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	Name or path of the model.	required
`framework`	`str`	Framework identifier ('ultralytics', 'transformers', 'rfdetr').	`''`

Attributes:

Name	Type	Description
`model_name`	`str`	Model name or path.
`framework`	`str`	Framework identifier.
`model`	`Any`	Underlying model instance (set after load_model()).
`class_names`	`Dict[int, str]`	Mapping from class ID to class name.
`slicing_config`	`Optional[SlicingConfig]`	Slicing configuration if enabled.

Examples:

>>> class MyModel(BaseDetectionModel):
...     def load_model(self, path=None):
...         self.model = load_my_model(path or self.model_name)
...         self.class_names = {0: "object"}
...
...     def _predict_single(self, input):
...         # Run inference
...         pass
...
...     def train(self, config):
...         # Train model
...         pass
...
...     def save(self, path):
...         # Save model
...         pass

Initialize the detection model.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	Name or path of the model.	required
`framework`	`str`	Framework identifier. Defaults to empty string.	`''`

is_loaded `property` ¶

is_loaded: bool

bool: Check if model is loaded and ready for inference.

load_model `abstractmethod` ¶

load_model(model_path: Optional[str] = None) -> None

Load model weights.

Parameters:

Name	Type	Description	Default
`model_path`	`Optional[str]`	Path to model weights. Uses model_name if not provided.	`None`

Raises:

Type	Description
`FileNotFoundError`	If model file doesn't exist.
`RuntimeError`	If model loading fails.

train `abstractmethod` ¶

train(config: TrainingConfig) -> TrainingResult

Train the model.

Parameters:

Name	Type	Description	Default
`config`	`TrainingConfig`	Training configuration.	required

Returns:

Type	Description
`TrainingResult`	Training results including model path and metrics.

save `abstractmethod` ¶

save(save_path: str) -> str

Save model weights.

Parameters:

Name	Type	Description	Default
`save_path`	`str`	Directory to save model.	required

Returns:

Type	Description
`str`	Path to saved model.

predict ¶

predict(detection_input: DetectionInput) -> Prediction

Run inference on image(s).

Parameters:

Name	Type	Description	Default
`detection_input`	`DetectionInput`	Detection input with image(s) and parameters.	required

Returns:

Type	Description
`Prediction`	Prediction results.

Raises:

Type	Description
`ModelNotLoadedError`	If model is not loaded.

Examples:

>>> # Single image
>>> result = model.predict(DetectionInput(image=image, conf_threshold=0.5))
>>> for det in result.results[0]:
...     print(det.class_name, det.confidence)

>>> # Batch
>>> result = model.predict(DetectionInput(image=[img1, img2]))
>>> print(f"Batch inference time: {result.inference_time:.3f}s")

detect ¶

detect(image: Union[ndarray, str, Path], conf: Optional[float] = None, iou: Optional[float] = None) -> DetectionResult

Convenience for single image detection.

Parameters:

Name	Type	Description	Default
`image`	`Union[ndarray, str, Path]`	Input image (BGR format, path, or file path).	required
`conf`	`Optional[float]`	Confidence threshold. Defaults to 0.5.	`None`
`iou`	`Optional[float]`	IoU threshold. Defaults to 0.5.	`None`

Returns:

Type	Description
`DetectionResult`	Detection results.

Examples:

>>> result = model.detect(image, conf=0.5)
>>> for det in result:
...     print(f"{det.class_name}: {det.confidence:.2f}")

detect_batch ¶

detect_batch(images: List[Union[ndarray, str, Path]], conf: Optional[float] = None, iou: Optional[float] = None) -> List[DetectionResult]

Convenience method for batch detection.

Parameters:

Name	Type	Description	Default
`images`	`List[Union[ndarray, str, Path]]`	List of input images.	required
`conf`	`Optional[float]`	Confidence threshold. Defaults to 0.5.	`None`
`iou`	`Optional[float]`	IoU threshold. Defaults to 0.5.	`None`

Returns:

Type	Description
`List[DetectionResult]`	List of detection results.

enable_slicing ¶

enable_slicing(slicing_config: Optional[Union[Dict[str, Any], Any]] = None) -> None

Enable slicing-based inference.

Parameters:

Name	Type	Description	Default
`slicing_config`	`Optional[Union[Dict, SlicingConfig]]`	Slicing configuration. Uses defaults if not provided.	`None`

Examples:

>>> model.enable_slicing({
...     "strategy": "grid",
...     "slice_size": (640, 640),
...     "overlap_ratio": 0.2,
... })

disable_slicing ¶

disable_slicing() -> None

Disable slicing-based inference.

draw_detections ¶

draw_detections(image: ndarray, result: DetectionResult, show_labels: bool = True, show_confidence: bool = True, show_class: bool = True, annotator_type: str = 'box', thickness: int = 2, text_scale: float = 0.5) -> ndarray

Draw detection annotations on image.

Parameters:

Name	Type	Description	Default
`image`	`ndarray`	Input image (BGR format).	required
`result`	`DetectionResult`	Detection results to draw.	required
`show_labels`	`bool`	Whether to show labels. Defaults to True.	`True`
`show_confidence`	`bool`	Whether to show confidence. Defaults to True.	`True`
`show_class`	`bool`	Whether to show class names. Defaults to True.	`True`
`annotator_type`	`str`	Annotator type ('box', 'round_box', 'color'). Defaults to 'box'.	`'box'`
`thickness`	`int`	Line thickness. Defaults to 2.	`2`
`text_scale`	`float`	Text scale. Defaults to 0.5.	`0.5`

Returns:

Type	Description
`ndarray`	Annotated image.

Examples:

>>> result = model.detect(image)
>>> annotated = model.draw_detections(image, result)
>>> cv2.imshow("Detections", annotated)

evaluate ¶

evaluate(config: EvaluationConfig) -> EvaluationMetrics

Evaluate the model on a dataset.

Parameters:

Name	Type	Description	Default
`config`	`EvaluationConfig`	Evaluation configuration.	required

Returns:

Type	Description
`EvaluationMetrics`	Evaluation metrics.

from_pretrained `classmethod` ¶

from_pretrained(model_name: str, **kwargs) -> BaseDetectionModel

Create model from pretrained weights.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	Model name or path.	required
`**kwargs`		Additional configuration.	`{}`

Returns:

Type	Description
`BaseDetectionModel`	Loaded model instance.

ObjectDetectionEvaluator ¶

ObjectDetectionEvaluator(model: Any, config: EvaluationConfig)

Evaluator for object detection models.

Runs inference at a low confidence threshold to capture all predictions (like Ultralytics), then computes metrics at the user-specified threshold.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Detection model implementing predict() method.	required
`config`	`EvaluationConfig`	Evaluation configuration.	required

set_post_processor ¶

set_post_processor(filter_strategy=None)

Attach a post-processing filter applied at the user's operating point.

Currently supports nectar.ai.detection.postprocess.PerClassConfidenceFilter. When set, it replaces the single conf_threshold filter for P/R/F1 reporting and for the prediction sample plot. mAP curves still use raw predictions.

CocoDetectionDataset ¶

CocoDetectionDataset(img_dir: str, annotations_file: str, image_processor: Any, train: bool = True, max_samples: Optional[int] = None, seed: int = 42)

Bases: Dataset

COCO format dataset for object detection.

Parameters:

Name	Type	Description	Default
`img_dir`	`str`	Directory containing images.	required
`annotations_file`	`str`	Path to COCO format annotations JSON.	required
`image_processor`	`Any`	Image processor (e.g., from HuggingFace).	required
`train`	`bool`	Whether this is training dataset. Defaults to True.	`True`
`max_samples`	`int`	Maximum number of samples to use.	`None`
`seed`	`int`	Random seed for sampling. Defaults to 42.	`42`

Examples:

>>> from transformers import AutoImageProcessor
>>> processor = AutoImageProcessor.from_pretrained("facebook/detr-resnet-50")
>>> dataset = CocoDetectionDataset("data/train", "annotations.json", processor)

RFDETRModel ¶

RFDETRModel(model_name: str = 'rfdetr-medium', rfdetr_size: Optional[str] = None, resolution: Optional[int] = None, from_scratch: bool = False)

Bases: BaseDetectionModel

RF-DETR model wrapper.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	Model name ('rfdetr-medium') or checkpoint path.	`'rfdetr-medium'`
`rfdetr_size`	`str`	Explicit model size (nano, small, medium, large).	`None`
`resolution`	`int`	Image resolution. Defaults to model's default.	`None`
`from_scratch`	`bool`	Train from scratch. Defaults to False.	`False`

Examples:

>>> model = RFDETRModel("rfdetr-medium")
>>> model.load_model()
>>> result = model.detect(image)

load_model ¶

load_model(model_path: Optional[str] = None) -> None

Load RF-DETR model.

update_class_names_from_dataset ¶

update_class_names_from_dataset(dataset_path: str) -> None

Update class names from dataset annotations (COCO or YOLO).

train ¶

train(config: TrainingConfig, is_main_process: bool = True) -> Dict[str, Any]

Train RF-DETR model.

save ¶

save(save_path: str) -> str

Save model state dict.

TransformersModel ¶

TransformersModel(model_name: str = 'facebook/detr-resnet-50', from_scratch: bool = False)

Bases: BaseDetectionModel

HuggingFace Transformers detection model.

Supports DETR, RT-DETR, Conditional DETR and other transformer-based object detection models from HuggingFace.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	Model name or HuggingFace model ID (e.g., 'facebook/detr-resnet-50').	`'facebook/detr-resnet-50'`
`from_scratch`	`bool`	Train from scratch. Defaults to False.	`False`

Examples:

>>> model = TransformersModel("facebook/detr-resnet-50")
>>> model.load_model()
>>> result = model.detect(image)

load_model ¶

load_model(model_path: Optional[str] = None, id2label: Optional[Dict[int, str]] = None, label2id: Optional[Dict[str, int]] = None, imgsz: int = 640) -> None

Load model from path or HuggingFace Hub.

Parameters:

Name	Type	Description	Default
`model_path`	`str`	Model path or HuggingFace ID.	`None`
`id2label`	`dict`	Class ID to label mapping.	`None`
`label2id`	`dict`	Label to class ID mapping.	`None`
`imgsz`	`int`	Image size. Defaults to 640.	`640`

train ¶

train(config: TrainingConfig) -> Dict[str, Any]

Train transformer model using HuggingFace Trainer.

save ¶

save(save_path: str) -> str

Save model and processor.

UltralyticsModel ¶

UltralyticsModel(model_name: str = 'yolov8n.pt', from_scratch: bool = False)

Bases: BaseDetectionModel

Ultralytics YOLO model wrapper.

Supports YOLOv8, YOLOv10, YOLO11 and other Ultralytics models for training, prediction, and evaluation.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	Model name or path (e.g., 'yolov8n.pt', 'path/to/model.pt').	`'yolov8n.pt'`
`from_scratch`	`bool`	Train from scratch without pretrained weights. Defaults to False.	`False`

Examples:

>>> model = UltralyticsModel("yolov8n.pt")
>>> model.load_model()
>>> result = model.detect(image, conf=0.5)

load_model ¶

load_model(model_path: Optional[str] = None) -> None

Load YOLO model from path or model name.

train ¶

train(config: TrainingConfig) -> Dict[str, Any]

Train YOLO model.

save ¶

save(save_path: str) -> str

Save model to path.

BaseMergingStrategy ¶

BaseMergingStrategy(iou_threshold: float = 0.5)

Bases: ABC

Abstract base class for detection merging strategies.

Parameters:

Name	Type	Description	Default
`iou_threshold`	`float`	IoU threshold for considering boxes as overlapping.	`0.5`

merge_boxes `abstractmethod` ¶

merge_boxes(detections: Detections) -> Tuple[Detections, List[List[int]], int]

Merge overlapping bounding boxes.

Returns (merged detections, merge groups, number merged).

NMMStrategy ¶

NMMStrategy(iou_threshold: float = 0.5)

Bases: BaseMergingStrategy

Non-Maximum Merging.

Merges overlapping boxes by averaging coordinates instead of suppressing lower-confidence detections. Uses supervision's optimized with_nmm().

Parameters:

Name	Type	Description	Default
`iou_threshold`	`float`	IoU threshold for merging. Defaults to 0.5.	`0.5`

NMSStrategy ¶

NMSStrategy(iou_threshold: float = 0.5, class_agnostic: bool = False)

Bases: BaseMergingStrategy

Standard Non-Maximum Suppression.

Removes overlapping detections by keeping the highest confidence detection and suppressing overlapping ones.

Parameters:

Name	Type	Description	Default
`iou_threshold`	`float`	IoU threshold for suppression. Defaults to 0.5.	`0.5`
`class_agnostic`	`bool`	If True, apply NMS across all classes. Defaults to False.	`False`

Examples:

>>> strategy = NMSStrategy(iou_threshold=0.5)
>>> merged, groups, count = strategy.merge_boxes(detections)

Initialize NMS strategy.

merge_boxes ¶

merge_boxes(detections: Detections) -> Tuple[Detections, List[List[int]], int]

Apply NMS to detections.

Parameters:

Name	Type	Description	Default
`detections`	`Detections`	Input detections.	required

Returns:

Type	Description
`Tuple[Detections, List[List[int]], int]`	Merged detections, merge groups, number merged.

PerClassConfidenceFilter ¶

PerClassConfidenceFilter(threshold_mapping: Optional[Dict[int, float]] = None, default_threshold: float = 0.25, csv_path: Optional[str] = None)

Filter detections using per-class confidence thresholds.

Thresholds can be provided as a dict or loaded from a CSV file (e.g. pr_analysis_results.csv from evaluation).

Parameters:

Name	Type	Description	Default
`threshold_mapping`	`dict`	Mapping of class_id to confidence threshold.	`None`
`default_threshold`	`float`	Default threshold for classes not in mapping. Defaults to 0.25.	`0.25`
`csv_path`	`str`	Path to CSV with columns class_id and optimal_threshold.	`None`

SoftNMSStrategy ¶

SoftNMSStrategy(iou_threshold: float = 0.5, sigma: float = 0.5, score_threshold: float = 0.001)

Bases: BaseMergingStrategy

Soft Non-Maximum Suppression.

Gradually reduces confidence of overlapping detections using a Gaussian decay function instead of hard suppression.

Parameters:

Name	Type	Description	Default
`iou_threshold`	`float`	IoU threshold to start decaying. Defaults to 0.5.	`0.5`
`sigma`	`float`	Gaussian sigma for decay. Defaults to 0.5.	`0.5`
`score_threshold`	`float`	Minimum score to keep. Defaults to 0.001.	`0.001`

Examples:

>>> strategy = SoftNMSStrategy(iou_threshold=0.5, sigma=0.5)
>>> merged, groups, count = strategy.merge_boxes(detections)

Initialize Soft-NMS strategy.

merge_boxes ¶

merge_boxes(detections: Detections) -> Tuple[Detections, List[List[int]], int]

Apply Soft-NMS to detections.

Parameters:

Name	Type	Description	Default
`detections`	`Detections`	Input detections.	required

Returns:

Type	Description
`Tuple[Detections, List[List[int]], int]`	Merged detections, merge groups, number removed.

WBFStrategy ¶

WBFStrategy(iou_threshold: float = 0.5, skip_box_threshold: float = 0.0, conf_type: str = 'avg')

Bases: BaseMergingStrategy

Weighted Boxes Fusion.

Fuses overlapping boxes by weighted coordinate averaging. Uses cluster-based matching: a new box joins a cluster if it overlaps with any box already in the cluster.

Parameters:

Name	Type	Description	Default
`iou_threshold`	`float`	IoU threshold for fusion. Defaults to 0.5.	`0.5`
`skip_box_threshold`	`float`	Minimum confidence to consider. Defaults to 0.0.	`0.0`
`conf_type`	`str`	Score fusion method: "avg" or "max". Defaults to "avg".	`'avg'`

SlicingConfig `dataclass` ¶

SlicingConfig(strategy: SlicingStrategy = NONE, slice_size: Tuple[int, int] = (640, 640), overlap_ratio: float = 0.2, iou_threshold: float = 0.5, conf_threshold: float = 0.25, min_slice_area_ratio: float = 0.01, max_slices: int = 64, adaptive_threshold: float = 0.3, clustering_eps: float = 50, clustering_min_samples: int = 2, merge_strategy: str = 'nms', include_full_image: bool = True)

Configuration for slicing-based inference.

Parameters:

Name	Type	Description	Default
`strategy`	`SlicingStrategy`	Slicing strategy to use. Defaults to NONE.	`NONE`
`slice_size`	`Tuple[int, int]`	Size of each slice (height, width). Defaults to (640, 640).	`(640, 640)`
`overlap_ratio`	`float`	Overlap between slices (0.0 to 1.0). Defaults to 0.2.	`0.2`
`iou_threshold`	`float`	IoU threshold for merging overlapping detections. Defaults to 0.5.	`0.5`
`conf_threshold`	`float`	Confidence threshold for detections. Defaults to 0.25.	`0.25`
`min_slice_area_ratio`	`float`	Minimum slice area as ratio of original. Defaults to 0.01.	`0.01`
`max_slices`	`int`	Maximum number of slices to prevent memory issues. Defaults to 64.	`64`
`adaptive_threshold`	`float`	Threshold for adaptive slicing density. Defaults to 0.3.	`0.3`
`clustering_eps`	`float`	DBSCAN epsilon for clustering strategy. Defaults to 50.	`50`
`clustering_min_samples`	`int`	DBSCAN min samples for clustering. Defaults to 2.	`2`
`merge_strategy`	`str`	How to merge overlapping detections ('nms', 'nmm'). Defaults to 'nms'.	`'nms'`
`include_full_image`	`bool`	Include full image as final slice for context. Defaults to True.	`True`

Examples:

>>> config = SlicingConfig(
...     strategy=SlicingStrategy.GRID,
...     slice_size=(640, 640),
...     overlap_ratio=0.2,
... )

from_dict `classmethod` ¶

from_dict(config_dict: Dict[str, Any]) -> SlicingConfig

Create SlicingConfig from dictionary.

Parameters:

Name	Type	Description	Default
`config_dict`	`Dict[str, Any]`	Configuration dictionary.	required

Returns:

Type	Description
`SlicingConfig`	New SlicingConfig instance.

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary.

Returns:

Type	Description
`Dict[str, Any]`	Configuration dictionary.

grid `classmethod` ¶

grid(slice_size: Tuple[int, int] = (640, 640), overlap_ratio: float = 0.2) -> SlicingConfig

Create grid slicing configuration.

Parameters:

Name	Type	Description	Default
`slice_size`	`Tuple[int, int]`	Size of each slice. Defaults to (640, 640).	`(640, 640)`
`overlap_ratio`	`float`	Overlap between slices. Defaults to 0.2.	`0.2`

Returns:

Type	Description
`SlicingConfig`	Grid slicing configuration.

adaptive `classmethod` ¶

adaptive(slice_size: Tuple[int, int] = (640, 640), threshold: float = 0.3) -> SlicingConfig

Create adaptive slicing configuration.

Parameters:

Name	Type	Description	Default
`slice_size`	`Tuple[int, int]`	Size of each slice. Defaults to (640, 640).	`(640, 640)`
`threshold`	`float`	Adaptive threshold. Defaults to 0.3.	`0.3`

Returns:

Type	Description
`SlicingConfig`	Adaptive slicing configuration.

SlicingInference ¶

SlicingInference(config: SlicingConfig)

Handler for slicing-based inference.

Manages slicing, inference, and merging of detection results across image slices using configurable post-processing strategies.

Parameters:

Name	Type	Description	Default
`config`	`SlicingConfig`	Slicing configuration.	required

Examples:

>>> config = SlicingConfig(strategy=SlicingStrategy.GRID)
>>> slicer = SlicingInference(config)
>>> detections = slicer.run_sliced_inference(
...     image, model.predict_callback
... )

Initialize slicing inference handler.

run_sliced_inference ¶

run_sliced_inference(image: Union[ndarray, Image, str, Path], inference_callback: Callable[[ndarray], Detections], initial_detections: Optional[Detections] = None) -> Detections

Run inference on sliced image and merge results.

Parameters:

Name	Type	Description	Default
`image`	`Union[ndarray, Image, str, Path]`	Input image.	required
`inference_callback`	`Callable`	Function that takes image array and returns sv.Detections.	required
`initial_detections`	`Optional[Detections]`	Initial detections for adaptive/clustering strategies.	`None`

Returns:

Type	Description
`Detections`	Merged detections from all slices.

Examples:

>>> def predict(img):
...     return model.predict(img).detections
>>> merged = slicer.run_sliced_inference(image, predict)

SlicingStrategy ¶

Bases: Enum

Available slicing strategies.

get_device ¶

get_device(device: Optional[str] = None) -> device

Get torch device from string specification.

Parameters:

Name	Type	Description	Default
`device`	`Optional[str]`	Device specification. Options: - None or "auto": Auto-detect (CUDA > MPS > CPU) - "cpu": CPU - "cuda": First CUDA device - "cuda:N": Specific CUDA device - "mps": Metal Performance Shaders (Apple Silicon) - "N": Specific CUDA device by index	`None`

Returns:

Type	Description
`device`	Resolved device.

Examples:

>>> device = get_device("auto")
>>> device = get_device("cuda:0")
>>> device = get_device("cpu")

load_detection_dataset ¶

load_detection_dataset(dataset_path: str, dataset_type: str = 'auto', split: str = 'test') -> DetectionDataset

Load detection dataset for evaluation.

Parameters:

Name	Type	Description	Default
`dataset_path`	`str`	Path to dataset directory.	required
`dataset_type`	`str`	Dataset type ('coco', 'yolo', 'auto'). Defaults to 'auto'.	`'auto'`
`split`	`str`	Dataset split. Defaults to 'test'.	`'test'`

Returns:

Type	Description
`DetectionDataset`	Loaded dataset.

Segmentation¶

segmentation ¶

Nectar SDK - Image Segmentation Module.

Supports instance segmentation (Ultralytics, RF-DETR, Mask2Former) and semantic segmentation (SegFormer) via a unified API.

Examples:

>>> from nectar.ai.segmentation import Segmentor
>>> segmentor = Segmentor("yolov8n-seg.pt")
>>> segmentor.load()
>>> result = segmentor.segment(image)

SegEvaluationConfig `dataclass` ¶

SegEvaluationConfig(model_path: str = '', dataset_path: str = '', framework: str = '', output_dir: str = 'outputs/evaluations', dataset_type: str = 'auto', split: str = 'test', conf_threshold: float = 0.5, iou_threshold: float = 0.5, device: str = 'auto', batch_size: int = 16, num_samples: Optional[int] = None, imgsz: Optional[int] = None, prediction_samples_max: int = 4)

Configuration for segmentation model evaluation.

Parameters:

Name	Type	Description	Default
`model_path`	`str`	Path to model checkpoint.	`''`
`dataset_path`	`str`	Path to evaluation dataset.	`''`
`framework`	`str`	Model framework.	`''`
`output_dir`	`str`	Directory for outputs.	`'outputs/evaluations'`

SegEvaluationMetrics `dataclass` ¶

SegEvaluationMetrics(map50: float = 0.0, map50_95: float = 0.0, mar50: float = 0.0, mar50_95: float = 0.0, precision: float = 0.0, recall: float = 0.0, f1_score: float = 0.0, mean_iou: float = 0.0, pixel_accuracy: float = 0.0, inference_time_per_image: float = 0.0, total_segmentations: int = 0, per_class_metrics: List[Dict] = list(), per_class_iou: Dict[str, float] = dict(), visualizations: Dict[str, str] = dict())

Segmentation evaluation metrics.

Supports both instance segmentation (mask mAP) and semantic segmentation (mIoU).

SegTrainingConfig `dataclass` ¶

SegTrainingConfig(dataset_path: str = '', epochs: int = 10, batch_size: int = 16, learning_rate: float = 0.001, output_dir: str = (lambda: str(DEFAULT_OUTPUT_DIR))(), device: str = 'auto', seed: int = 42, tensorboard: bool = True, save_period: int = 1, push_to_hub: bool = False, hub_model_id: Optional[str] = None, multi_gpu: bool = False, mixed_precision: str = 'no', gradient_accumulation_steps: int = 1, max_train_samples: Optional[int] = None, max_eval_samples: Optional[int] = None, max_test_samples: Optional[int] = None, train_split: float = 0.8, val_split: float = 0.2, test_split: float = 0.0, dataset_format: Optional[str] = None, framework: str = '', model: str = '', from_scratch: bool = False, imgsz: Optional[Union[int, List[int]]] = None, early_stopping_patience: Optional[int] = None, early_stopping_delta: float = 0.0, early_stopping_metric: str = 'eval_loss', early_stopping_mode: str = 'min', weight_decay: float = 0.0001, lr_scheduler_type: str = 'linear', warmup_steps: int = 10, warmup_ratio: float = 0.1, max_grad_norm: float = 1.0, optimizer_type: Optional[str] = None, dropout: float = 0.0, warmup_epochs: float = 3.0, warmup_momentum: float = 0.8, lrf: float = 0.01, freeze: Optional[Union[int, List[int]]] = None, cos_lr: bool = False, rfdetr_size: Optional[str] = None, lr_encoder: Optional[float] = None, use_ema: bool = True, gradient_checkpointing: bool = False, drop_path: float = 0.0, drop_mode: str = 'standard', drop_schedule: str = 'constant', cutoff_epoch: int = 0, freeze_encoder: bool = False, layer_norm: bool = False, rms_norm: bool = False, backbone_lora: bool = False, multi_scale: bool = False, force_no_pretrain: bool = False, ema_decay: float = 0.9997, ema_tau: float = 0.0, lr_vit_layer_decay: float = 0.8, lr_component_decay: float = 1.0, sync_bn: bool = True, num_workers: int = 2, set_cost_class: float = 2.0, set_cost_bbox: float = 5.0, set_cost_giou: float = 2.0, start_epoch: int = 0, gc_batch_frequency: int = 100, early_stopping_use_ema: bool = False, gc_per_accumulation: bool = True, evaluate: bool = False, resume: bool = False)

Configuration for segmentation model training.

Parameters:

Name	Type	Description	Default
`dataset_path`	`str`	Path to the training dataset.	`''`
`epochs`	`int`	Number of training epochs.	`10`
`batch_size`	`int`	Batch size per device.	`16`
`learning_rate`	`float`	Initial learning rate.	`0.001`
`output_dir`	`str`	Directory for outputs.	`(lambda: str(DEFAULT_OUTPUT_DIR))()`
`device`	`str`	Device specification.	`'auto'`
`seed`	`int`	Random seed.	`42`

Segmentation `dataclass` ¶

Segmentation(xyxy: ndarray, confidence: float, class_id: int, class_name: str = '', mask: Optional[ndarray] = None)

Single instance segmentation result.

Parameters:

Name	Type	Description	Default
`xyxy`	`ndarray`	Bounding box coordinates as [x1, y1, x2, y2] in pixel coordinates.	required
`confidence`	`float`	Detection confidence score in range [0.0, 1.0].	required
`class_id`	`int`	Class identifier (zero-indexed).	required
`class_name`	`str`	Human-readable class name.	`''`
`mask`	`Optional[ndarray]`	Binary mask of shape (H, W) with dtype bool or uint8.	`None`

center `property` ¶

center: Tuple[float, float]

Center point (x, y) of the bounding box.

width `property` ¶

width: int

Width of bounding box in pixels.

height `property` ¶

height: int

Height of bounding box in pixels.

area `property` ¶

area: int

Area of bounding box in square pixels.

mask_area `property` ¶

mask_area: int

Area of the mask in pixels (number of True pixels).

bbox `property` ¶

bbox: List[int]

Bounding box as [x1, y1, x2, y2] integers.

polygon `property` ¶

polygon: Optional[List[List[int]]]

Extract polygon contour from binary mask.

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary (mask excluded for serialization).

from_dict `classmethod` ¶

from_dict(data: Dict[str, Any]) -> Segmentation

Create Segmentation from dictionary (without mask).

SegmentationInput `dataclass` ¶

SegmentationInput(image: Union[ImageType, BatchImageType], conf_threshold: float = 0.5, iou_threshold: float = 0.5, device: Optional[str] = None, imgsz: Optional[int] = None)

Input for segmentation models.

Parameters:

Name	Type	Description	Default
`image`	`Union[ImageType, BatchImageType]`	Input image(s).	required
`conf_threshold`	`float`	Confidence threshold.	`0.5`
`iou_threshold`	`float`	IoU threshold for NMS.	`0.5`
`device`	`Optional[str]`	Device to run inference on.	`None`
`imgsz`	`Optional[int]`	Image size for inference.	`None`

is_batch `property` ¶

is_batch: bool

Check if input contains a batch of images.

SegmentationResult `dataclass` ¶

SegmentationResult(segmentations: List[Segmentation] = list(), semantic_map: Optional[ndarray] = None, image: Optional[ndarray] = None, inference_time: float = 0.0, image_path: Optional[str] = None, model_name: Optional[str] = None)

Container for segmentation results from a single image.

Parameters:

Name	Type	Description	Default
`segmentations`	`List[Segmentation]`	List of instance segmentation results.	`list()`
`semantic_map`	`Optional[ndarray]`	Pixel-level class map of shape (H, W) for semantic segmentation.	`None`
`image`	`Optional[ndarray]`	Original image (BGR format).	`None`
`inference_time`	`float`	Inference time in seconds.	`0.0`
`image_path`	`Optional[str]`	Path to source image.	`None`
`model_name`	`Optional[str]`	Name of the model used.	`None`

is_semantic `property` ¶

is_semantic: bool

True if this result contains a semantic segmentation map.

filter_by_class ¶

filter_by_class(class_names: List[str]) -> SegmentationResult

Filter instance segmentations by class names.

filter_by_confidence ¶

filter_by_confidence(threshold: float) -> SegmentationResult

Filter instance segmentations by confidence threshold.

to_supervision ¶

to_supervision() -> Detections

Convert instance segmentations to supervision Detections with masks.

from_supervision `classmethod` ¶

from_supervision(detections: Detections, class_names: Dict[int, str], inference_time: float = 0.0, image_path: Optional[str] = None, model_name: Optional[str] = None, image: Optional[ndarray] = None) -> SegmentationResult

Create SegmentationResult from supervision Detections.

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary.

SegPrediction `dataclass` ¶

SegPrediction(detections: Optional[Detections] = None, batch_detections: Optional[List[Detections]] = None, results: Optional[List[SegmentationResult]] = None, inference_time: float = 0.0, image_path: Optional[Union[str, List[str]]] = None, model_name: Optional[str] = None)

Model prediction output for segmentation.

Parameters:

Name	Type	Description	Default
`detections`	`Optional[Detections]`	Single image detections with masks (supervision format).	`None`
`batch_detections`	`Optional[List[Detections]]`	Batch detections with masks.	`None`
`results`	`Optional[List[SegmentationResult]]`	Converted segmentation results.	`None`
`inference_time`	`float`	Total inference time in seconds.	`0.0`
`image_path`	`Optional[Union[str, List[str]]]`	Source image path(s).	`None`
`model_name`	`Optional[str]`	Name of the model used.	`None`

from_detections `classmethod` ¶

from_detections(detections: Detections, class_names: Dict[int, str], inference_time: float, image_path: str, model_name: Optional[str] = None) -> SegPrediction

Create SegPrediction from supervision Detections (with masks).

from_batch_detections `classmethod` ¶

from_batch_detections(batch_detections: List[Detections], class_names: Dict[int, str], inference_time: float, image_paths: List[str], model_name: Optional[str] = None) -> SegPrediction

Create SegPrediction from batch of supervision Detections.

from_semantic `classmethod` ¶

from_semantic(semantic_map: ndarray, class_names: Dict[int, str], inference_time: float, image_path: str, model_name: Optional[str] = None) -> SegPrediction

Create SegPrediction from a semantic segmentation map.

BaseSegmentationModel ¶

BaseSegmentationModel(model_name: str, framework: str = '')

Bases: ABC

Abstract base class for all segmentation models.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	Name or path of the model.	required
`framework`	`str`	Framework identifier ('ultralytics', 'transformers', 'rfdetr').	`''`

load_model `abstractmethod` ¶

load_model(model_path: Optional[str] = None) -> None

Load model weights.

train `abstractmethod` ¶

train(config: SegTrainingConfig) -> TrainingResult

Train the model.

save `abstractmethod` ¶

save(save_path: str) -> str

Save model weights.

predict ¶

predict(seg_input: SegmentationInput) -> SegPrediction

Run inference on image(s).

Parameters:

Name	Type	Description	Default
`seg_input`	`SegmentationInput`	Segmentation input with image(s) and parameters.	required

Returns:

Type	Description
`SegPrediction`	Prediction results.

segment ¶

segment(image: Union[ndarray, str, Path], conf: Optional[float] = None, iou: Optional[float] = None) -> SegmentationResult

Convenience method for single image segmentation.

Parameters:

Name	Type	Description	Default
`image`	`Union[ndarray, str, Path]`	Input image.	required
`conf`	`Optional[float]`	Confidence threshold.	`None`
`iou`	`Optional[float]`	IoU threshold.	`None`

Returns:

Type	Description
`SegmentationResult`	Segmentation results.

segment_batch ¶

segment_batch(images: List[Union[ndarray, str, Path]], conf: Optional[float] = None, iou: Optional[float] = None) -> List[SegmentationResult]

Convenience method for batch segmentation.

draw_segmentations ¶

draw_segmentations(image: ndarray, result: SegmentationResult, show_labels: bool = True, show_confidence: bool = True, show_masks: bool = True, show_boxes: bool = False, opacity: float = 0.4, text_scale: float = 0.5, thickness: int = 2) -> ndarray

Draw segmentation annotations on image.

Parameters:

Name	Type	Description	Default
`image`	`ndarray`	Input image (BGR format).	required
`result`	`SegmentationResult`	Segmentation results.	required
`show_labels`	`bool`	Show labels.	`True`
`show_confidence`	`bool`	Show confidence scores.	`True`
`show_masks`	`bool`	Show mask overlays.	`True`
`show_boxes`	`bool`	Show bounding boxes.	`False`
`opacity`	`float`	Mask overlay opacity.	`0.4`
`text_scale`	`float`	Text scale.	`0.5`
`thickness`	`int`	Line thickness.	`2`

Returns:

Type	Description
`ndarray`	Annotated image.

evaluate ¶

evaluate(config: SegEvaluationConfig) -> SegEvaluationMetrics

Evaluate the model on a dataset.

from_pretrained `classmethod` ¶

from_pretrained(model_name: str, **kwargs) -> BaseSegmentationModel

Create model from pretrained weights.

RoboflowSegHandler ¶

RoboflowSegHandler(output_dir: str, api_key: str, verbose: bool = True)

Bases: BaseDatasetHandler

Download Roboflow segmentation datasets in YOLO-seg or COCO format.

Parameters:

Name	Type	Description	Default
`output_dir`	`str`	Output directory for downloaded dataset.	required
`api_key`	`str`	Roboflow API key.	required
`verbose`	`bool`	Print progress information.	`True`

Examples:

>>> handler = RoboflowSegHandler("data/my_seg", api_key="key")
>>> handler.download(workspace="ws", project="proj", version=1, format_type="yolov8")

download ¶

download(workspace: str, project: str, version: int, format_type: str = 'yolov8', **kwargs) -> Path

Download a Roboflow segmentation project.

Parameters:

Name	Type	Description	Default
`workspace`	`str`	Roboflow workspace name.	required
`project`	`str`	Project name.	required
`version`	`int`	Dataset version number.	required
`format_type`	`str`	Export format. `"yolov8"` for YOLO-seg, `"coco"` for COCO with segmentation polygons. Defaults to `"yolov8"`.	`'yolov8'`

Returns:

Type	Description
`Path`	Path to downloaded dataset directory.

convert ¶

convert(format: str, **kwargs) -> Optional[str]

Return path to data.yaml if YOLO, else None.

SegDatasetAnalyzer ¶

SegDatasetAnalyzer(dataset_path: str, output_dir: Optional[str] = None, verbose: bool = True)

Analyze segmentation dataset distribution and generate visualizations.

Supports both YOLO-seg (polygon labels) and COCO (with segmentation field).

Parameters:

Name	Type	Description	Default
`dataset_path`	`str`	Path to dataset directory.	required
`output_dir`	`str`	Output directory for reports and plots.	`None`
`verbose`	`bool`	Print progress information.	`True`

analyze ¶

analyze() -> Dict

Run analysis and generate plots + JSON report.

Returns:

Type	Description
`dict`	Analysis results.

SegDatasetHandlerRegistry ¶

Bases: HandlerRegistry

Registry for segmentation dataset download handlers.

SegFormatConverter ¶

SegFormatConverter(source_dir: str, target_dir: str, verbose: bool = True, num_workers: Optional[int] = None)

Convert segmentation datasets between COCO (with polygon masks) and YOLO-seg formats.

YOLO-seg label format: class_id x1 y1 x2 y2 ... xN yN (normalized polygon). COCO-seg annotation: "segmentation": [[x1,y1,...]], "bbox", "area".

Parameters:

Name	Type	Description	Default
`source_dir`	`str`	Path to source dataset directory.	required
`target_dir`	`str`	Path to target output directory.	required
`verbose`	`bool`	Print progress information.	`True`
`num_workers`	`int`	Parallel workers for conversion.	`None`

convert ¶

convert(target_format: str, splits: Optional[List[str]] = None, copy_images: bool = True, num_workers: Optional[int] = None) -> str

Convert dataset to target format.

Parameters:

Name	Type	Description	Default
`target_format`	`str`	`"coco"` or `"yolo"`.	required
`splits`	`list of str`	Splits to convert. Auto-detects if None.	`None`
`copy_images`	`bool`	Copy images to target directory.	`True`
`num_workers`	`int`	Override parallel workers.	`None`

Returns:

Type	Description
`str`	Path to converted dataset or generated config file.

yolo_seg_to_coco ¶

yolo_seg_to_coco(splits: Optional[List[str]] = None, copy_images: bool = True, num_workers: Optional[int] = None) -> str

Convert YOLO-seg dataset to COCO format with segmentation annotations.

Returns:

Type	Description
`str`	Path to target directory.

coco_to_yolo_seg ¶

coco_to_yolo_seg(splits: Optional[List[str]] = None, copy_images: bool = True, num_workers: Optional[int] = None) -> str

Convert COCO dataset (with segmentation polygons) to YOLO-seg format.

Returns:

Type	Description
`str`	Path to generated `data.yaml`.

UltralyticsSegHandler ¶

UltralyticsSegHandler(output_dir: str, dataset_name: str, verbose: bool = True)

Bases: BaseDatasetHandler

Download and manage Ultralytics-hosted segmentation datasets.

Works with any dataset supported by the Ultralytics auto-download mechanism (e.g. crack-seg). The dataset is downloaded in YOLO-seg format and can optionally be converted to COCO with segmentation polygons.

Parameters:

Name	Type	Description	Default
`output_dir`	`str`	Output directory for the processed dataset.	required
`dataset_name`	`str`	Ultralytics dataset identifier (e.g. `"crack-seg"`).	required
`verbose`	`bool`	Print progress information.	`True`

Examples:

>>> handler = UltralyticsSegHandler("data/crack-seg", "crack-seg")
>>> handler.download_and_convert(output_format="coco")

download ¶

download(**kwargs) -> Path

Download dataset via Ultralytics auto-download.

Returns:

Type	Description
`Path`	Path to the downloaded dataset directory.

convert ¶

convert(format: str, **kwargs) -> Optional[str]

Convert the downloaded dataset to the requested format.

Parameters:

Name	Type	Description	Default
`format`	`str`	Target format (`"yolo"` or `"coco"`).	required

Returns:

Type	Description
`str or None`	Path to `data.yaml` (YOLO) or target dir (COCO).

download_and_convert ¶

download_and_convert(output_format: str = 'yolo', splits: Optional[List[str]] = None, num_workers: Optional[int] = None) -> Tuple[str, Dict[str, str]]

Download dataset and optionally convert to COCO format.

Parameters:

Name	Type	Description	Default
`output_format`	`str`	`"yolo"`, `"coco"`, or `"both"`.	`'yolo'`
`splits`	`list of str`	Unused, kept for API compatibility.	`None`
`num_workers`	`int`	Parallel workers for conversion.	`None`

Returns:

Type	Description
`tuple of (str, dict)`	`(yaml_path, coco_annotation_paths)`

SegmentationEvaluator ¶

SegmentationEvaluator(model: Any, config: SegEvaluationConfig)

Evaluator for segmentation models.

Runs inference at a low confidence threshold (like Ultralytics), then computes metrics at the user-specified threshold and generates rich evaluation visualizations.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Segmentation model implementing `predict(SegmentationInput)`.	required
`config`	`SegEvaluationConfig`	Evaluation configuration.	required

set_post_processor ¶

set_post_processor(filter_strategy=None)

Attach a post-processing filter applied at the user's operating point.

Currently supports nectar.ai.detection.postprocess.PerClassConfidenceFilter (the same instance type used by the detection evaluator). When set, it replaces the single conf_threshold filter for P/R/F1 reporting and for the prediction sample plot. mAP curves still use raw predictions.

RFDETRSegModel ¶

RFDETRSegModel(model_name: str = 'rfdetr-seg-medium', rfdetr_size: Optional[str] = None, resolution: Optional[int] = None, from_scratch: bool = False)

Bases: BaseSegmentationModel

RF-DETR instance segmentation model wrapper.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	Model name ('rfdetr-seg-medium') or checkpoint path.	`'rfdetr-seg-medium'`
`rfdetr_size`	`str`	Explicit model size (nano, small, medium, large, xlarge, 2xlarge).	`None`
`resolution`	`int`	Image resolution.	`None`
`from_scratch`	`bool`	Train from scratch.	`False`

load_model ¶

load_model(model_path: Optional[str] = None) -> None

Load RF-DETR segmentation model.

update_class_names_from_dataset ¶

update_class_names_from_dataset(dataset_path: str) -> None

Update class names from dataset annotations (COCO or YOLO).

train ¶

train(config: SegTrainingConfig) -> Dict[str, Any]

Train RF-DETR segmentation model.

save ¶

save(save_path: str) -> str

Save model to path.

TransformersSegModel ¶

TransformersSegModel(model_name: str = 'facebook/mask2former-swin-large-cityscapes-instance', mode: Optional[str] = None, from_scratch: bool = False)

Bases: BaseSegmentationModel

HuggingFace Transformers segmentation model.

Supports both instance segmentation (Mask2Former, MaskFormer) and semantic segmentation (SegFormer, SegGPT, etc.).

The mode is auto-detected from the model configuration.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	Model name or HuggingFace model ID.	`'facebook/mask2former-swin-large-cityscapes-instance'`
`mode`	`str`	Segmentation mode ('instance' or 'semantic'). Auto-detected if not given.	`None`
`from_scratch`	`bool`	Train from scratch.	`False`

mode `property` ¶

mode: str

Segmentation mode: 'instance' or 'semantic'.

load_model ¶

load_model(model_path: Optional[str] = None, id2label: Optional[Dict[int, str]] = None, label2id: Optional[Dict[str, int]] = None, imgsz: int = 640) -> None

Load segmentation model from path or HuggingFace Hub.

train ¶

train(config: SegTrainingConfig) -> Dict[str, Any]

Train segmentation model using HuggingFace Trainer.

save ¶

save(save_path: str) -> str

Save model and processor.

UltralyticsSegModel ¶

UltralyticsSegModel(model_name: str = 'yolov8n-seg.pt', from_scratch: bool = False)

Bases: BaseSegmentationModel

Ultralytics YOLO segmentation model wrapper.

Supports YOLOv8-seg, YOLO11-seg, YOLO26-seg and other Ultralytics segmentation models.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	Model name or path (e.g., 'yolov8n-seg.pt').	`'yolov8n-seg.pt'`
`from_scratch`	`bool`	Train from scratch without pretrained weights.	`False`

load_model ¶

load_model(model_path: Optional[str] = None) -> None

Load YOLO segmentation model.

train ¶

train(config: SegTrainingConfig) -> Dict[str, Any]

Train YOLO segmentation model.

save ¶

save(save_path: str) -> str

Save model to path.

Segmentor ¶

Segmentor(model_source: str, framework: Optional[Union[Framework, str]] = None, device: str = 'auto', confidence_threshold: float = 0.25, hf_token: Optional[str] = None, **kwargs)

Unified segmentor with factory pattern for creating model instances.

Supports auto-detection from model name or explicit framework specification.

Parameters:

Name	Type	Description	Default
`model_source`	`str`	Model path, name, or HuggingFace ID.	required
`framework`	`Optional[Union[Framework, str]]`	Explicit framework. Auto-detects if not provided.	`None`
`device`	`str`	Device ('auto', 'cpu', 'cuda', '0').	`'auto'`
`confidence_threshold`	`float`	Default confidence threshold.	`0.25`
`**kwargs`		Additional arguments passed to the model constructor.	`{}`

Examples:

>>> segmentor = Segmentor("yolov8n-seg.pt")
>>> segmentor.load()
>>> result = segmentor.segment(image)

model `property` ¶

model: BaseSegmentationModel

Underlying model for advanced usage.

register `classmethod` ¶

register(framework: Union[Framework, str], builder: BuilderFunc) -> None

Register a framework builder.

available_frameworks `classmethod` ¶

available_frameworks() -> List[str]

Get registered frameworks.

load ¶

load(model_path: Optional[str] = None) -> bool

Load the model.

segment ¶

segment(image: Union[ndarray, str, Path], conf: Optional[float] = None, iou: Optional[float] = None) -> SegmentationResult

Run segmentation on a single image.

segment_batch ¶

segment_batch(images: List[Union[ndarray, str, Path]], conf: Optional[float] = None, iou: Optional[float] = None) -> List[SegmentationResult]

Run segmentation on multiple images.

train ¶

train(config: SegTrainingConfig) -> Dict[str, Any]

Train the model.

evaluate ¶

evaluate(config: SegEvaluationConfig) -> Dict[str, Any]

Evaluate the model.

draw_segmentations ¶

draw_segmentations(image: ndarray, result: SegmentationResult, show_labels: bool = True, show_confidence: bool = True, show_masks: bool = True, show_boxes: bool = False, opacity: float = 0.4, text_scale: float = 0.5, thickness: int = 2) -> ndarray

Draw segmentation annotations on image.

Classification¶

classification ¶

Nectar SDK - Image Classification Module.

Supports image classification via Ultralytics YOLO-cls and HuggingFace Transformers (ViT, etc.) behind one Classifier.

Examples:

>>> from nectar.ai.classification import Classifier
>>> classifier = Classifier("yolo26n-cls.pt")
>>> classifier.load()
>>> result = classifier.classify(image)

ClsEvaluationConfig `dataclass` ¶

ClsEvaluationConfig(model_path: str = '', dataset_path: str = '', framework: str = '', output_dir: str = 'outputs/evaluations', dataset_type: str = 'auto', split: str = 'test', device: str = 'auto', batch_size: int = 16, num_samples: Optional[int] = None, imgsz: Optional[int] = 224, topk: int = 5, conf_threshold: float = 0.0, prediction_samples_max: int = 16)

Configuration for classification model evaluation.

Parameters:

Name	Type	Description	Default
`model_path`	`str`	Path to model checkpoint.	`''`
`dataset_path`	`str`	Path to evaluation dataset (ImageFolder root).	`''`
`framework`	`str`	Model framework.	`''`
`output_dir`	`str`	Directory for outputs.	`'outputs/evaluations'`

ClsEvaluationMetrics `dataclass` ¶

ClsEvaluationMetrics(top1_accuracy: float = 0.0, top5_accuracy: float = 0.0, precision_macro: float = 0.0, recall_macro: float = 0.0, f1_macro: float = 0.0, precision_weighted: float = 0.0, recall_weighted: float = 0.0, f1_weighted: float = 0.0, inference_time_per_image: float = 0.0, total_samples: int = 0, per_class_metrics: List[Dict] = list(), visualizations: Dict[str, str] = dict())

Classification evaluation metrics.

ClsTrainingConfig `dataclass` ¶

ClsTrainingConfig(dataset_path: str = '', epochs: int = 10, batch_size: int = 16, learning_rate: float = 0.001, output_dir: str = (lambda: str(DEFAULT_OUTPUT_DIR))(), device: str = 'auto', seed: int = 42, tensorboard: bool = True, save_period: int = 1, push_to_hub: bool = False, hub_model_id: Optional[str] = None, multi_gpu: bool = False, mixed_precision: str = 'no', gradient_accumulation_steps: int = 1, max_train_samples: Optional[int] = None, max_eval_samples: Optional[int] = None, max_test_samples: Optional[int] = None, train_split: float = 0.8, val_split: float = 0.2, test_split: float = 0.0, dataset_format: Optional[str] = None, framework: str = '', model: str = '', from_scratch: bool = False, imgsz: Optional[Union[int, List[int]]] = 224, early_stopping_patience: Optional[int] = None, early_stopping_delta: float = 0.0, early_stopping_metric: str = 'eval_accuracy', early_stopping_mode: str = 'max', weight_decay: float = 0.0001, lr_scheduler_type: str = 'linear', warmup_steps: int = 0, warmup_ratio: float = 0.1, max_grad_norm: float = 1.0, optimizer_type: Optional[str] = None, dropout: float = 0.0, warmup_epochs: float = 3.0, warmup_momentum: float = 0.8, lrf: float = 0.01, freeze: Optional[Union[int, List[int]]] = None, cos_lr: bool = False, erasing: float = 0.4, fliplr: float = 0.5, flipud: float = 0.0, hsv_h: float = 0.015, hsv_s: float = 0.7, hsv_v: float = 0.4, gc_per_accumulation: bool = True, evaluate: bool = False, resume: bool = False, num_workers: int = 2)

Configuration for classification model training.

Parameters:

Name	Type	Description	Default
`dataset_path`	`str`	Path to ImageFolder root or HF dataset.	`''`
`epochs`	`int`	Number of training epochs.	`10`
`batch_size`	`int`	Batch size per device.	`16`
`learning_rate`	`float`	Initial learning rate.	`0.001`
`output_dir`	`str`	Directory for outputs.	`(lambda: str(DEFAULT_OUTPUT_DIR))()`
`device`	`str`	Device specification.	`'auto'`
`seed`	`int`	Random seed.	`42`

Classification `dataclass` ¶

Classification(class_id: int, class_name: str = '', confidence: float = 0.0)

Single class prediction entry.

Parameters:

Name	Type	Description	Default
`class_id`	`int`	Class identifier (zero-indexed).	required
`class_name`	`str`	Human-readable class name.	`''`
`confidence`	`float`	Prediction confidence in range [0.0, 1.0].	`0.0`

ClassificationInput `dataclass` ¶

ClassificationInput(image: Union[ImageType, BatchImageType], device: Optional[str] = None, topk: int = 5, imgsz: Optional[int] = None)

Input for classification models.

Parameters:

Name	Type	Description	Default
`image`	`Union[ImageType, BatchImageType]`	Input image(s).	required
`device`	`Optional[str]`	Device to run inference on.	`None`
`topk`	`int`	Number of top predictions to return.	`5`
`imgsz`	`Optional[int]`	Image size for inference.	`None`

ClassificationResult `dataclass` ¶

ClassificationResult(predictions: List[Classification] = list(), probs: Optional[ndarray] = None, image: Optional[ndarray] = None, inference_time: float = 0.0, image_path: Optional[str] = None, model_name: Optional[str] = None)

Classification result for a single image.

Parameters:

Name	Type	Description	Default
`predictions`	`List[Classification]`	Top-k predictions sorted by confidence descending.	`list()`
`probs`	`Optional[ndarray]`	Full class probability vector of shape (C,).	`None`
`image`	`Optional[ndarray]`	Original image (BGR).	`None`
`inference_time`	`float`	Inference time in seconds.	`0.0`
`image_path`	`Optional[str]`	Path to source image.	`None`
`model_name`	`Optional[str]`	Name of the model used.	`None`

topk ¶

topk(k: int = 5) -> ClassificationResult

Return a result limited to the top-k predictions.

from_probs `classmethod` ¶

from_probs(probs: ndarray, class_names: Dict[int, str], topk: int = 5, inference_time: float = 0.0, image_path: Optional[str] = None, model_name: Optional[str] = None, image: Optional[ndarray] = None) -> ClassificationResult

Build a result from a full probability vector.

ClsPrediction `dataclass` ¶

ClsPrediction(result: Optional[ClassificationResult] = None, results: Optional[List[ClassificationResult]] = None, inference_time: float = 0.0, image_path: Optional[Union[str, List[str]]] = None, model_name: Optional[str] = None)

Model prediction output for classification.

Parameters:

Name	Type	Description	Default
`result`	`Optional[ClassificationResult]`	Single-image result.	`None`
`results`	`Optional[List[ClassificationResult]]`	Batch results.	`None`
`inference_time`	`float`	Total inference time in seconds.	`0.0`
`image_path`	`Optional[Union[str, List[str]]]`	Source image path(s).	`None`
`model_name`	`Optional[str]`	Name of the model used.	`None`

Classifier ¶

Classifier(model_source: str, framework: Optional[Union[Framework, str]] = None, device: str = 'auto', topk: int = 5, hf_token: Optional[str] = None, **kwargs)

Unified classifier with factory pattern for creating model instances.

Supports auto-detection from model name or explicit framework specification.

Parameters:

Name	Type	Description	Default
`model_source`	`str`	Model path, name, or HuggingFace ID.	required
`framework`	`Optional[Union[Framework, str]]`	Explicit framework. Auto-detects if not provided.	`None`
`device`	`str`	Device ('auto', 'cpu', 'cuda', '0').	`'auto'`
`topk`	`int`	Default number of top predictions to return.	`5`
`**kwargs`		Additional arguments passed to the model constructor.	`{}`

Examples:

>>> classifier = Classifier("yolo26n-cls.pt")
>>> classifier.load()
>>> result = classifier.classify(image)

model `property` ¶

model: BaseClassificationModel

Underlying model for advanced usage.

register `classmethod` ¶

register(framework: Union[Framework, str], builder: BuilderFunc) -> None

Register a framework builder.

available_frameworks `classmethod` ¶

available_frameworks() -> List[str]

Get registered frameworks.

load ¶

load(model_path: Optional[str] = None) -> bool

Load the model.

classify ¶

classify(image: Union[ndarray, str, Path], topk: Optional[int] = None) -> ClassificationResult

Run classification on a single image.

classify_batch ¶

classify_batch(images: List[Union[ndarray, str, Path]], topk: Optional[int] = None) -> List[ClassificationResult]

Run classification on multiple images.

train ¶

train(config: ClsTrainingConfig) -> Dict[str, Any]

Train the model.

evaluate ¶

evaluate(config: ClsEvaluationConfig) -> ClsEvaluationMetrics

Evaluate the model.

draw_classification ¶

draw_classification(image: ndarray, result: ClassificationResult, show_confidence: bool = True, topk: int = 3, text_scale: float = 0.6, thickness: int = 2) -> ndarray

Overlay top-k class labels on the image.

BaseClassificationModel ¶

BaseClassificationModel(model_name: str, framework: str = '')

Bases: ABC

Abstract base class for all classification models.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	Name or path of the model.	required
`framework`	`str`	Framework identifier ('ultralytics', 'transformers').	`''`

load_model `abstractmethod` ¶

load_model(model_path: Optional[str] = None) -> None

Load model weights.

train `abstractmethod` ¶

train(config: ClsTrainingConfig) -> Dict[str, Any]

Train the model.

save `abstractmethod` ¶

save(save_path: str) -> str

Save model weights.

predict ¶

predict(cls_input: ClassificationInput) -> ClsPrediction

Run inference on image(s).

classify ¶

classify(image: Union[ndarray, str, Path], topk: int = 5) -> ClassificationResult

Convenience method for single-image classification.

classify_batch ¶

classify_batch(images: List[Union[ndarray, str, Path]], topk: int = 5) -> List[ClassificationResult]

Convenience method for batch classification.

draw_classification ¶

draw_classification(image: ndarray, result: ClassificationResult, show_confidence: bool = True, topk: int = 3, text_scale: float = 0.6, thickness: int = 2) -> ndarray

Overlay top-k class labels on the image.

Parameters:

Name	Type	Description	Default
`image`	`ndarray`	Input image (BGR).	required
`result`	`ClassificationResult`	Classification results.	required
`show_confidence`	`bool`	Include confidence scores.	`True`
`topk`	`int`	Number of labels to draw.	`3`
`text_scale`	`float`	OpenCV text scale.	`0.6`
`thickness`	`int`	Text thickness.	`2`

Returns:

Type	Description
`ndarray`	Annotated image.

evaluate ¶

evaluate(config: ClsEvaluationConfig) -> ClsEvaluationMetrics

Evaluate the model on a dataset.

from_pretrained `classmethod` ¶

from_pretrained(model_name: str, **kwargs) -> BaseClassificationModel

Create model from pretrained weights.

ClsDatasetAnalyzer ¶

ClsDatasetAnalyzer(dataset_path: str, output_dir: Optional[str] = None)

Analyze ImageFolder classification datasets.

analyze ¶

analyze() -> Dict[str, Any]

Compute class distribution stats and optionally write JSON/plots.

ClsDatasetHandlerRegistry ¶

Bases: HandlerRegistry

Registry for classification dataset download handlers.

ClsFormatConverter ¶

ClsFormatConverter(input_path: str, output_path: str, verbose: bool = True)

Helpers to normalize classification dataset layouts.

normalize_split_names ¶

normalize_split_names() -> str

Copy dataset ensuring splits are named train/val/test.

Maps valid/validation → val.

HuggingFaceClsHandler ¶

HuggingFaceClsHandler(output_dir: str, token: Optional[str] = None)

Bases: BaseDatasetHandler

Download a HuggingFace image-classification dataset as ImageFolder.

ImageFolderDetector ¶

ImageFolderDetector(dataset_path: str)

Detect and validate ImageFolder classification layout.

is_imagefolder ¶

is_imagefolder() -> bool

Return True if path looks like ImageFolder (with or without splits).

count_samples ¶

count_samples() -> Dict[str, Dict[str, int]]

Return {split: {class_name: count}}.

RoboflowClsHandler ¶

RoboflowClsHandler(output_dir: str, api_key: Optional[str] = None)

Bases: BaseDatasetHandler

Download a Roboflow classification project as ImageFolder / folder structure.

UltralyticsClsHandler ¶

UltralyticsClsHandler(output_dir: str, verbose: bool = True)

Bases: BaseDatasetHandler

Download Ultralytics classification datasets (cifar10, mnist160, …).

Uses ultralytics.data.utils.check_cls_dataset which auto-downloads on first use per the Ultralytics classify dataset docs.

Downloads are forced into nectar/ai/data/ultralytics/ (not the global Ultralytics datasets_dir), then materialized under output_dir.

download ¶

download(dataset: str = 'mnist160', max_samples: Optional[int] = None, seed: int = 42, **kwargs) -> str

Download (or reuse cache) an Ultralytics classification dataset.

Parameters:

Name	Type	Description	Default
`dataset`	`str`	Built-in name (`mnist160`, `cifar10`, `imagenette`, …).	`'mnist160'`
`max_samples`	`int`	If set, write a balanced subset with at most this many images per split (train/test) instead of the full dataset. Prefer this for smoke tests — CIFAR-10 is 60k images.	`None`
`seed`	`int`	RNG seed for subset sampling.	`42`

convert ¶

convert(format: str = 'imagefolder', **kwargs) -> str

Classification datasets are already ImageFolder — no conversion needed.

ClassificationEvaluator ¶

ClassificationEvaluator(model: Any, config: ClsEvaluationConfig)

Evaluator for classification models.

curves, confusion matrix, error/performance analysis, JSON/CSV reports.

TransformersClsModel ¶

TransformersClsModel(model_name: str = 'google/vit-base-patch16-224-in21k', from_scratch: bool = False)

Bases: BaseClassificationModel

HuggingFace Transformers image classification model.

Uses AutoModelForImageClassification + AutoImageProcessor (ViT, BEiT, etc.).

Parameters:

Name	Type	Description	Default
`model_name`	`str`	HuggingFace model ID (e.g. 'google/vit-base-patch16-224-in21k').	`'google/vit-base-patch16-224-in21k'`
`from_scratch`	`bool`	Initialize from config without pretrained weights.	`False`

load_model ¶

load_model(model_path: Optional[str] = None, id2label: Optional[Dict[int, str]] = None, label2id: Optional[Dict[str, int]] = None, imgsz: int = 224) -> None

Load model and image processor from path or Hub.

train ¶

train(config: ClsTrainingConfig) -> Dict[str, Any]

Train using HuggingFace Trainer (official image-classification flow).

save ¶

save(save_path: str) -> str

Save model and processor with save_pretrained.

UltralyticsClsModel ¶

UltralyticsClsModel(model_name: str = 'yolo26n-cls.pt', from_scratch: bool = False)

Bases: BaseClassificationModel

Ultralytics YOLO classification model wrapper.

Supports YOLO-cls models (e.g. yolo26n-cls.pt, yolov8n-cls.pt).

Parameters:

Name	Type	Description	Default
`model_name`	`str`	Model name or path (e.g., 'yolo26n-cls.pt').	`'yolo26n-cls.pt'`
`from_scratch`	`bool`	Train from scratch without pretrained weights.	`False`

load_model ¶

load_model(model_path: Optional[str] = None) -> None

Load YOLO classification model.

train ¶

train(config: ClsTrainingConfig) -> Dict[str, Any]

Train YOLO classification model.

save ¶

save(save_path: str) -> str

Save model to path.

AI API¶

Detection¶

detection ¶

Framework ¶

EvaluationConfig dataclass ¶

to_dict ¶

from_dict classmethod ¶

from_yaml classmethod ¶

EvaluationMetrics dataclass ¶

to_dict ¶

save_json ¶

summary ¶

TrainingConfig dataclass ¶

to_dict ¶

to_yaml ¶

from_dict classmethod ¶

from_yaml classmethod ¶

TrainingMetrics dataclass ¶

to_dict ¶

TrainingResult dataclass ¶

to_dict ¶

save_json ¶

ConfigurationError ¶

DatasetError ¶

DetectionError ¶

DeviceError ¶

EvaluationError ¶

FrameworkError ¶

HuggingFaceError ¶

ModelNotLoadedError ¶

PostProcessingError ¶

SlicingError ¶

TrainingError ¶

Detection dataclass ¶

center property ¶

width property ¶

height property ¶

area property ¶

bbox property ¶

to_dict ¶

from_dict classmethod ¶

DetectionInput dataclass ¶

is_batch property ¶

to_dict ¶

DetectionResult dataclass ¶

filter_by_class ¶

filter_by_confidence ¶

filter_by_class_id ¶

to_supervision ¶

from_supervision classmethod ¶

to_dict ¶

Prediction dataclass ¶

is_batch property ¶

num_detections property ¶

to_dict ¶

from_detections classmethod ¶

from_batch_detections classmethod ¶

Detector ¶

framework property ¶

is_loaded property ¶

class_names property ¶

model property ¶

register classmethod ¶

available_frameworks classmethod ¶

load ¶

detect ¶

detect_batch ¶

train ¶

evaluate ¶

draw_detections ¶

enable_slicing ¶

disable_slicing ¶

ModelLoader ¶

from_huggingface staticmethod ¶

from_path staticmethod ¶

load staticmethod ¶

DeviceManager ¶

get_best_device ¶

get_memory_info ¶

log_memory_usage ¶

EvaluationConfig `dataclass` ¶

from_dict `classmethod` ¶

from_yaml `classmethod` ¶

EvaluationMetrics `dataclass` ¶

TrainingConfig `dataclass` ¶

from_dict `classmethod` ¶

from_yaml `classmethod` ¶

TrainingMetrics `dataclass` ¶

TrainingResult `dataclass` ¶

Detection `dataclass` ¶

center `property` ¶

width `property` ¶

height `property` ¶

area `property` ¶

bbox `property` ¶

from_dict `classmethod` ¶

DetectionInput `dataclass` ¶

is_batch `property` ¶

DetectionResult `dataclass` ¶

from_supervision `classmethod` ¶

Prediction `dataclass` ¶

is_batch `property` ¶

num_detections `property` ¶

from_detections `classmethod` ¶

from_batch_detections `classmethod` ¶

framework `property` ¶

is_loaded `property` ¶

class_names `property` ¶

model `property` ¶

register `classmethod` ¶

available_frameworks `classmethod` ¶

from_huggingface `staticmethod` ¶

from_path `staticmethod` ¶

load `staticmethod` ¶

is_loaded `property` ¶

load_model `abstractmethod` ¶

train `abstractmethod` ¶

save `abstractmethod` ¶

from_pretrained `classmethod` ¶

merge_boxes `abstractmethod` ¶

SlicingConfig `dataclass` ¶

from_dict `classmethod` ¶

grid `classmethod` ¶

adaptive `classmethod` ¶

SegEvaluationConfig `dataclass` ¶

SegEvaluationMetrics `dataclass` ¶

SegTrainingConfig `dataclass` ¶

Segmentation `dataclass` ¶

center `property` ¶

width `property` ¶

height `property` ¶

area `property` ¶

mask_area `property` ¶

bbox `property` ¶

polygon `property` ¶