Detected Object

Schema for localized objects detected in an image in Gen AI applications.

This module defines a generic detected region (a text line, a handwritten line, a table, and so on) located by a polygon in pixel coordinates of the source image.

DetectedObject

Bases: BaseModel

A region detected in an image, located by a polygon in pixel coordinates.

The polygon is the canonical geometry, so rotated or perspective-skewed regions keep their shape. Coordinates are pixels of the source image, whose size is carried by the producing result (such as OcrResult.image_width and OcrResult.image_height), with the origin at the top-left corner. Use from_bounding_box to build an object from an axis-aligned box and to_bounding_box to obtain the axis-aligned envelope.

Attributes:

Name	Type	Description
class_name	str	The kind of detected region, such as the values in DetectedObjectClass.
polygon	list[Point2D]	The region outline as (x, y) points in pixels, each coordinate at least 0.0, with at least three points. Four-point polygons are ordered top-left, top-right, bottom-right, bottom-left when built with from_bounding_box.
confidence	float | None	Confidence score of the detection, between 0.0 and 1.0. None when the producer does not score the region. Defaults to None.
content	str | None	The textual content of the region, such as the transcribed line text or a table rendered as HTML. Defaults to None.
metadata	dict[str, Any]	Producer-specific attributes, such as the keys in DetectedObjectMetadataKey. Defaults to an empty dictionary.

from_bounding_box(bounding_box, class_name, content=None, confidence=None, metadata=None) classmethod

Creates a detected object from an axis-aligned box in pixels.

Parameters:

Name	Type	Description	Default
bounding_box	XYXY	The (x_min, y_min, x_max, y_max) edges in pixels.	required
class_name	str	The kind of detected region.	required
content	str | None	The textual content of the region. Defaults to None.	None
confidence	float | None	Confidence score of the detection. Defaults to None.	None
metadata	dict[str, Any] | None	Producer-specific attributes. Defaults to None.	None

Returns:

Name	Type	Description
DetectedObject	DetectedObject	The detected object whose polygon is the box corners ordered top-left, top-right, bottom-right, bottom-left.

Raises:

Type	Description
ValidationError	If an edge is negative or confidence is out of range.

to_bounding_box()

Returns the axis-aligned envelope of the polygon.

Returns:

Name	Type	Description
XYXY	XYXY	The (x_min, y_min, x_max, y_max) edges in pixels.