​

module  pixeltable.functions.vision

import pixeltable as pxt
from pixeltable.functions import vision as pxtv

t = pxt.get_table(...)
t.select(
    pxtv.bboxes_draw(t.img, boxes=t.boxes, labels=t.labels)
).collect()

​

udf  bboxes_clip_to_canvas()

@pxt.udf
bboxes_clip_to_canvas(
    bboxes: pxt.Json[(Json, ...)],
    format: pxt.String,
    *,
    width: pxt.Int | None = None,
    height: pxt.Int | None = None,
    min_visibility: pxt.Float = 0.0,
    min_area: pxt.Float = 0.0
) -> pxt.Json[(Json, ...)]

• bboxes (pxt.Json[(Json): List of bounding boxes, specified with absolute pixel coordinates if width/height are given, with relative coordinates otherwise. All-integer boxes are always treated as absolute and require width/height.
• format (Any): Format of the bounding box coordinates, one of ‘xyxy’, ‘xywh’, ‘cxcywh’.
• width (Any): Canvas width in absolute pixels. Required for absolute coordinates, omit for relative.
• height (Any): Canvas height in absolute pixels. Required for absolute coordinates, omit for relative.
• min_visibility (Any): Minimum fraction of the bounding box that must be visible after clipping. If the visibility is less than this value, returns None.
• min_area (Any): Minimum area of the bounding box after clipping. If the area is less than this value, returns None.

• pxt.Json[(Json, ...)]: List of clipped bounding boxes in the same format as the input. Boxes that don’t meet the min_visibility or min_area thresholds are replaced with None.

​

udf  bboxes_convert()

@pxt.udf
bboxes_convert(
    bboxes: pxt.Json[(Json, ...)],
    *,
    src_format: pxt.String,
    dst_format: pxt.String
) -> pxt.Json[(Json, ...)]

• bboxes (pxt.Json[(Json): List of bounding boxes, each with absolute pixel coordinates or relative coordinates in [0, 1]. Coordinates may be int or float; relative vs absolute is inferred (relative only when every coordinate is within [0, 1]), so absolute float coordinates such as 10.5 are supported.
• src_format (Any): Source format, one of ‘xyxy’, ‘xywh’, ‘cxcywh’.
• dst_format (Any): Destination format, one of ‘xyxy’, ‘xywh’, ‘cxcywh’.

• pxt.Json[(Json, ...)]: List of bounding boxes in dst_format.

​

udf  bboxes_crop_canvas()

@pxt.udf
bboxes_crop_canvas(
    bboxes: pxt.Json[(Json, ...)],
    format: pxt.String,
    *,
    canvas_region: pxt.Json[(Json, ...)],
    canvas_region_format: pxt.String,
    canvas_width: pxt.Int | None = None,
    canvas_height: pxt.Int | None = None
) -> pxt.Json[(Json, ...)]

• bboxes (pxt.Json[(Json): List of bounding boxes, specified with absolute pixel coordinates if canvas_width/canvas_height are given, with relative coordinates otherwise. All-integer boxes are always treated as absolute and require canvas_width/canvas_height.
• format (Any): Format of the bounding box coordinates, one of ‘xyxy’, ‘xywh’, ‘cxcywh’.
• canvas_width (Any): Canvas width in absolute pixels. Required for absolute coordinates, omit for relative.
• canvas_height (Any): Canvas height in absolute pixels. Required for absolute coordinates, omit for relative.
• canvas_region (Any): Canvas region that was cropped, either specified with absolute pixel coordinates or relative coordinates, in the format specified by canvas_region_format.
• canvas_region_format (Any): Format of the canvas_region coordinates, one of ‘xyxy’, ‘xywh’, ‘cxcywh’.

• pxt.Json[(Json, ...)]: List of adjusted bounding boxes in the same format as the input. They can extend beyond the canvas boundaries.

​

udf  bboxes_draw()

@pxt.udf
bboxes_draw(
    img: pxt.Image,
    boxes: pxt.Json[(Json[(Int, ...)], ...)],
    *,
    labels: pxt.Json[(Json, ...)] | None = None,
    color: pxt.String | None = None,
    box_colors: pxt.Json[(String, ...)] | None = None,
    alpha: pxt.Float | None = None,
    fill: pxt.Bool = False,
    fill_alpha: pxt.Float | None = None,
    width: pxt.Int = 1,
    font: pxt.String | None = None,
    font_size: pxt.Int | None = None
) -> pxt.Image

• img (pxt.Image): The image on which to draw the bounding boxes.
• boxes (pxt.Json[(Json[(Int): List of bounding boxes, each represented as [xmin, ymin, xmax, ymax].
• labels (Any): List of labels for each bounding box.
• color (Any): Single color to be used for all bounding boxes and labels.
• box_colors (Any): List of colors, one per bounding box.
• alpha (Any): Opacity (0-1) of the bounding box borders and labels. If non-None, overrides any alpha in color/box_colors.
• fill (Any): Whether to fill the bounding boxes with color.
• fill_alpha (Any): Opacity (0-1) of the bounding box fill. If non-None, overrides any alpha in color/box_colors.
• width (Any): Width of the bounding box borders.
• font (Any): Name of a system font or path to a TrueType font file, as required by PIL.ImageFont.truetype(). If None, uses the default provided by PIL.ImageFont.load_default().
• font_size (Any): Size of the font used for labels in points. Only used in conjunction with non-None font argument.

• pxt.Image: The image with bounding boxes drawn on it.

​

udf  bboxes_pad()

@pxt.udf
bboxes_pad(
    bboxes: pxt.Json[(Json, ...)],
    format: pxt.String,
    *,
    top: pxt.Int | None = None,
    bottom: pxt.Int | None = None,
    left: pxt.Int | None = None,
    right: pxt.Int | None = None,
    x: pxt.Int | None = None,
    y: pxt.Int | None = None
) -> pxt.Json[(Json, ...)]

• bboxes (pxt.Json[(Json): List of bounding boxes in absolute pixel coordinates.
• format (Any): Format of the bounding box coordinates, one of ‘xyxy’, ‘xywh’, ‘cxcywh’.
• top (Any): Amount to pad at the top, in absolute pixels.
• bottom (Any): Amount to pad at the bottom, in absolute pixels.
• left (Any): Amount to pad at the left, in absolute pixels.
• right (Any): Amount to pad at the right, in absolute pixels.
• x (Any): Amount to pad at the left and right, in absolute pixels.
• y (Any): Amount to pad at the top and bottom, in absolute pixels.

• pxt.Json[(Json, ...)]: List of padded bounding boxes in the same format as the input.

​

udf  bboxes_resize()

# Signature 1:
@pxt.udf
bboxes_resize(
    bboxes: pxt.Json[(Json, ...)],
    format: pxt.String,
    width: pxt.Int | None,
    height: pxt.Int | None,
    aspect: pxt.String | None,
    aspect_mode: pxt.String | None
) -> pxt.Json[(Json, ...)]

# Signature 2:
@pxt.udf
bboxes_resize(
    bboxes: pxt.Json[(Json, ...)],
    format: pxt.String,
    width: pxt.Float | None,
    height: pxt.Float | None,
    aspect: pxt.Float | None,
    aspect_mode: pxt.String | None
) -> pxt.Json[(Json, ...)]

• to a specified width or height (the other dimension is scaled to maintain the aspect ratio)
• to a specified aspect ratio

• bboxes (Json[(Json, ...)]): List of bounding boxes, each with absolute pixel coordinates or relative coordinates in [0, 1]. Coordinates may be int or float; relative vs absolute is inferred (relative only when every coordinate is within [0, 1]), so absolute float coordinates such as 10.5 are supported.
• format (String): Format of the bounding box coordinates, one of ‘xyxy’, ‘xywh’, ‘cxcywh’.
• width (Int | None, default: Literal(None)): Target width. Pass an int for absolute pixels or a float for relative coordinates.
• height (Int | None, default: Literal(None)): Target height. Pass an int for absolute pixels or a float for relative coordinates.
• aspect (String | None, default: Literal(None)): Target aspect ratio. Pass a str like ‘16:9’ or a float like 1.78.
• aspect (String | None, default: Literal(None)): Target aspect ratio as a string ‘W:H’ (e.g., ‘16:9’) or a float. Resizes either the width or height to match the specified aspect ratio, maintaining the other dimension. Requires aspect_mode.
• aspect_mode (String | None, default: Literal(None)): Either ‘crop’ or ‘pad’. Required when aspect is specified. If crop, reduces the oversized dimension to match the aspect ratio. If pad, extends the undersized dimension to match the aspect ratio.

• pxt.Json[(Json, ...)]: List of resized bounding boxes in the same format as the input.

​

udf  bboxes_resize_canvas()

@pxt.udf
bboxes_resize_canvas(
    bboxes: pxt.Json[(Json, ...)],
    format: pxt.String,
    *,
    canvas_width: pxt.Int | None = None,
    canvas_height: pxt.Int | None = None,
    new_canvas_width: pxt.Int | None = None,
    new_canvas_height: pxt.Int | None = None,
    canvas_scale: pxt.Float | None = None,
    canvas_scale_x: pxt.Float | None = None,
    canvas_scale_y: pxt.Float | None = None
) -> pxt.Json[(Json, ...)]

• as absolute pixel dimensions (requires canvas_width, canvas_height, new_canvas_width, new_canvas_height)
• as relative dimensions (requires at least one of canvas_scale, canvas_scale_x, canvas_scale_y)

• bboxes (pxt.Json[(Json): List of bounding boxes in absolute pixel coordinates.
• format (Any): Format of the bounding box coordinates, one of ‘xyxy’, ‘xywh’, ‘cxcywh’.
• canvas_width (Any): Original canvas width in absolute pixels.
• canvas_height (Any): Original canvas height in absolute pixels.
• new_canvas_width (Any): New canvas width in absolute pixels. Requires canvas_width/canvas_height to be specified.
• new_canvas_height (Any): New canvas height in absolute pixels. Requires canvas_width/canvas_height to be specified.
• canvas_scale (Any): Scale factor to apply to both canvas dimensions.
• canvas_scale_x (Any): Scale factor to apply to the canvas width.
• canvas_scale_y (Any): Scale factor to apply to the canvas height.

• pxt.Json[(Json, ...)]: List of adjusted bounding boxes in the same format as the input.

​

udf  bboxes_scale()

@pxt.udf
bboxes_scale(
    bboxes: pxt.Json[(Json, ...)],
    format: pxt.String,
    *,
    factor: pxt.Float | None = None,
    x_factor: pxt.Float | None = None,
    y_factor: pxt.Float | None = None
) -> pxt.Json[(Json, ...)]

• bboxes (pxt.Json[(Json): List of bounding boxes, each with absolute pixel coordinates or relative coordinates in [0, 1]. Coordinates may be int or float; relative vs absolute is inferred (relative only when every coordinate is within [0, 1]), so absolute float coordinates such as 10.5 are supported.
• format (Any): Format of the bounding box coordinates, one of ‘xyxy’, ‘xywh’, ‘cxcywh’.
• factor (Any): Scale factor to apply to both box dimensions.
• x_factor (Any): Scale factor to apply to the box width.
• y_factor (Any): Scale factor to apply to the box height.

• pxt.Json[(Json, ...)]: List of scaled bounding boxes in the same format as the input.

​

udf  eval_detections()

@pxt.udf
eval_detections(
    pred_bboxes: pxt.Json[(Json[(Int, ...)], ...)],
    pred_labels: pxt.Json[(Int, ...)],
    pred_scores: pxt.Json[(Float, ...)],
    gt_bboxes: pxt.Json[(Json[(Int, ...)], ...)],
    gt_labels: pxt.Json[(Int, ...)],
    min_iou: pxt.Float = 0.5
) -> pxt.Json[(Json[{'min_iou': Float, 'category': Int, 'tp': Json[(Int, ...)], 'fp': Json[(Int, ...)], 'scores': Json[(Float, ...)], 'num_gts': Int}], ...)]

• pred_bboxes (pxt.Json[(Json[(Int): List of predicted bounding boxes, each represented as [xmin, ymin, xmax, ymax].
• pred_labels (Any): List of predicted labels.
• pred_scores (Any): List of predicted scores.
• gt_bboxes (Any): List of ground truth bounding boxes, each represented as [xmin, ymin, xmax, ymax].
• gt_labels (Any): List of ground truth labels.
• min_iou (Any): Minimum intersection-over-union (IoU) threshold for a predicted bounding box to be considered a true positive.

• pxt.Json[(Json[{'min_iou': Float, 'category': Int, 'tp': Json[(Int, ...)], 'fp': Json[(Int, ...)], 'scores': Json[(Float, ...)], 'num_gts': Int}], ...)]: A list of dictionaries, one per label class, with the following entries:
  • min_iou (float): the value of min_iou used for the detections
  • category (int): the label class
  • tp (list[int]): 1 or 0 for each predicted bounding box of this class, indicating a true positive
  • fp (list[int]): 1 or 0 for each predicted bounding box of this class; fp[n] == 1 - tp[n]
  • scores (list[float]): the predicted scores for each bounding box of this class
  • num_gts (int): the number of ground truth bounding boxes of this class

​

udf  overlay_segmentation()

# Signature 1:
@pxt.udf
overlay_segmentation(
    img: pxt.Image,
    segmentation: pxt.Array[(None, None), int32],
    alpha: pxt.Float,
    background: pxt.Int,
    segment_colors: pxt.Json[(String, ...)] | None,
    draw_contours: pxt.Bool,
    contour_thickness: pxt.Int
) -> pxt.Image

# Signature 2:
@pxt.udf
overlay_segmentation(
    img: pxt.Image,
    segmentation: pxt.Array[(None, None, None), bool],
    ids: pxt.Array[(None,), int64] | None,
    alpha: pxt.Float,
    segment_colors: pxt.Json[(String, ...)] | None,
    draw_contours: pxt.Bool,
    contour_thickness: pxt.Int
) -> pxt.Image

• A 2D (H, W) int32 id-map where each pixel value is a segment id. This matches the panoptic output of detr_for_segmentation().
• A 3D (num_instances, H, W) boolean stack with one binary mask per instance. This matches the per-instance mask output of sam_for_segmentation(). Instances are assigned ids 1..num_instances in order; where masks overlap the highest id wins.

• img (Image): Input image.
• segmentation (Array[(None, None), int32]): Either a 2D (H, W) int32 array of segment ids, or a 3D (num_instances, H, W) boolean array of per-instance masks.
• alpha (Float, default: Literal(0.5)): Blend factor for the overlay (0.0 = only original image, 1.0 = only segmentation colors).
• background (Int, default: Literal(0)): Segment id to treat as background (not overlaid with color, showing the original image through). Only meaningful for the 2D id-map form.
• segment_colors (Json[(String, ...)] | None, default: Literal(None)): List of colors, one per segment id. If the list is shorter than the number of segments, the remaining segments will be assigned colors automatically.
• draw_contours (Bool, default: Literal(True)): If True, draw contours around each segment with full opacity.
• contour_thickness (Int, default: Literal(1)): Thickness of the contour lines in pixels.

• pxt.Image: The image with the colored segmentation overlay.