SAM3SegmentConverter

Converter

DashAI.back.converters.segmentation.SAM3SegmentConverter

---

Detect a prompted object in every image and append ranked columns.

Runs a promptable segmenter over the image column and appends, for every row, up to max_masks ranked pairs of columns: segment_i holds the i-th highest scoring detected object rendered as its own masked image, and seg_score_i holds that object's confidence. When keep_binary_mask is enabled, mask_i columns are appended too. The row count never changes: an image with fewer detected objects than max_masks simply leaves the remaining segment_i and seg_score_i (and, when enabled, mask_i) cells null for that row.

Because CHANGES_ROW_COUNT is false, the converter job folds the columns this converter produces back into the dataset with rebuild_dataset_with_transformed_columns, which preserves every column left out of the scope untouched, but treats any scoped column absent from this converter's own return value as removed. transform therefore returns every column of its input unchanged, verbatim, alongside the new ranked columns, rather than only the columns it actually computes. The scope is expected to cover only the image column (and any other image column the segmenter should also run over); the image to segment among the scoped columns is chosen through the image_column schema field.

Parameters

prompt : string, default=

Text describing the object to find in each image, for example 'cow'. Passed verbatim to the segmenter.

image_column : integer, default=1

1 based index, among the columns selected in the scope, of the image column to segment.

max_masks : integer, default=1

Maximum number of detected instances kept per image. Instances are ranked by descending confidence score, and only the top max_masks are kept. This also fixes the number of segment_i, seg_score_i, and, when keep_binary_mask is enabled, mask_i columns the converter produces, so the output schema depends on this configuration.

min_score : number, default=0.5

Minimum confidence score an instance must have to be kept.

mask_threshold : number, default=0.5

Probability above which a pixel counts as part of the detected object. Lower values grow every mask, higher values tighten it. Unrelated to min_score, which drops whole instances by their confidence.

min_area_fraction : number, default=0.0

Minimum fraction of the image area an instance's mask must cover to be kept.

crop_to_bbox : boolean, default=True

When enabled, each emitted segment image is cropped to the detected object's bounding box instead of keeping the full original image size.

background_fill : string, default=black

Fill applied to every pixel outside the detected object in the emitted segment image: 'black', 'white', or 'blur'.

keep_binary_mask : boolean, default=False

When enabled, an additional column with the object's binary mask as its own image is kept for each detected object.

on_no_detection : string, default=empty

What to do when no instance is detected in an image: 'empty' leaves every segment and score cell null for that row, 'keep_original' fills segment_1 with the unmodified source image and seg_score_1 with 0.0 while leaving the rest null, or 'error' to stop.

device : string, default=CPU

Device the segmentation model runs on. SAM 3 is a large model, so a GPU is considerably faster than the CPU.

Methods

download(cls, report: Optional[Callable[[Optional[float], Optional[str]], NoneType]] = None) -> None

Defined on SAM3SegmentConverter

Log in to HuggingFace before downloading these gated weights.

Parameters

report : ProgressReporter, optional

Progress callback forwarded to HFPretrainedDownloadMixin.download.

fit(self, x: 'DashAIDataset', y: 'DashAIDataset' = None) -> 'SAM3SegmentConverter'

Defined on SAM3SegmentConverter

Record the incoming column types. No model state is learned.

Parameters

x : DashAIDataset

The scoped dataset the converter will later transform, normally just the image column.

y : DashAIDataset, optional

Ignored. Defaults to None.

Returns

SAM3SegmentConverter

The fitted converter instance (self).

get_output_type(self, column_name: str = None) -> DashAI.back.types.dashai_data_type.DashAIDataType

Defined on SAM3SegmentConverter

Return the DashAI type produced for a given output column.

Parameters

column_name : str, optional

Name of the column to look up. Defaults to None.

Returns

DashAIDataType

DashAIImage() for a segment_i or mask_i column, Float(pa.float64()) for a seg_score_i column, and the recorded type from self.column_types for any other column.

transform(self, x: 'DashAIDataset', y: 'DashAIDataset' = None) -> 'DashAIDataset'

Defined on SAM3SegmentConverter

Segment every image and append ranked segment and score columns.

Parameters

x : DashAIDataset

The scoped dataset to segment, normally just the image column.

y : DashAIDataset, optional

Ignored. Defaults to None.

Returns

DashAIDataset

Every column of x unchanged, in its original position, plus segment_i and seg_score_i columns (and, when keep_binary_mask is true, mask_i) for every rank from 1 to max_masks. Every scoped column must come back out, not just the image column: the converter job folds this return value into the dataset with rebuild_dataset_with_transformed_columns, which treats any scoped column absent from this output as removed. Row count is unchanged, so this is a straight column graft onto x's own Arrow table, never a rebuild through pandas.

component_dir(cls) -> pathlib.Path

Defined on DownloadableMixin

Return this component's own storage directory.

Returns

pathlib.Path

<COMPONENT_PATH>/<ClassName>.

delete(cls) -> None

Defined on DownloadableMixin

Remove the component's downloaded artifacts.

get_credential(self, name: str)

Defined on ConfigObject

Resolve a registered credential component by name.

Parameters

name : str

Credential component class name (e.g. "HuggingFaceCredential").

Returns

BaseCredential

An instance of the requested credential component.

get_metadata(cls) -> 'Dict[str, Any]'

Defined on BaseConverter

Get metadata for the converter, used by the DashAI frontend.

Parameters

cls : type

The converter class (injected automatically by Python for classmethods).

Returns

Dict[str, Any]

Dictionary containing display name, short description, image preview path, category, icon, color, and whether the converter is supervised.

get_schema(cls) -> dict

Defined on ConfigObject

Generates the component related Json Schema.

Returns

dict

Dictionary representing the Json Schema of the component.

hf_repos(cls)

Defined on HFPretrainedDownloadMixin

Derive the single repo entry from MODEL_NAME.

Returns

list of tuple of (str, str)

[(MODEL_NAME, "model")] or an empty list when unset.

is_downloaded(cls) -> bool

Defined on HFDownloadableMixin

Return whether all repo directories exist and are non-empty.

Returns

bool

True when every repo listed in hf_repos() has a non-empty local directory; False otherwise (including when the list is empty).

validate_and_transform(self, raw_data: dict) -> dict

Defined on ConfigObject

It takes the data given by the user to initialize the model and returns it with all the objects that the model needs to work.

Parameters

raw_data : dict

A dictionary with the data provided by the user to initialize the model.

Returns

dict

A validated dictionary with the necessary objects.