Skip to main content
Perceptron models emit canonical HTML tags for structured spatial annotations. The SDK maps those tags to Python data classes so you can work with them directly. In this example, the model returns a BoundingBox class for a defect: 
from perceptron import perceive, image, text

@perceive(expects="box")
def locate_defect(frame):
    return image(frame) + text("Return a bounding box around the defect.")

result = locate_defect("part.png")

print(result.points[0].top_left)    # BoundingBox.top_left -> SinglePoint
print(result.points[0].mention)     # Model-provided label

​
Data classes

from perceptron import SinglePoint, BoundingBox, Polygon, Collection
TypeKey fieldsExample use
SinglePointx, y, optional t, mentionButton taps, defect centroids, laser alignments.
BoundingBoxtop_left, bottom_right, optional metadataObject detection overlays, cropping regions.
Polygonhull (list of SinglePoint), optional metadataSegmentation masks, irregular outlines, exclusion zones.
Collectionpoints, optional metadataGrouped annotations such as multi-part equipment or layered regions.
  • x, y: integers on Perceptron’s normalized 0–1000 grid (see below).
  • t: optional timestamp for frames or temporal reasoning.
  • mention: optional model-provided label.
  • top_left, bottom_right: SinglePoint corners that define a BoundingBox.
  • hull: ordered list of SinglePoint values outlining a polygon.
  • points: list of child annotations contained in a Collection.

​
Canonical tags

The SDK’s serializer and parser share the same HTML-style format the models emit: 
<point mention="button center" t=12.5> (120,200) </point>
<point_box mention="defect"> (100,150) (300,350) </point_box>
<polygon mention="drone"> (20,40) (60,40) (60,80) (20,80) </polygon>
<collection mention="wing">
  <point> (120,90) </point>
  <polygon> (100,150) (180,160) (170,210) (110,205) </polygon>
</collection>
  • Attributes (mention, t) live on the tag.
  • Whitespace around coordinates is ignored.
  • Collections can nest any mix of point, box, or polygon tags.

​
Collections in code

from perceptron import Collection, Polygon, SinglePoint

assembly = Collection(
    mention="inspection-drone",
    points=[
        SinglePoint(220, 180, mention="center"),
        Polygon([
            SinglePoint(120, 90),
            SinglePoint(260, 95),
            SinglePoint(275, 180),
            SinglePoint(135, 185),
        ]),
    ],
)
Collections preserve child metadata and let you propagate attributes to individual elements later—reuse them whenever you need grouped annotations or hierarchical references.

​
Metadata fields

point = SinglePoint(120, 200, t=12.5, mention="button center")
  • mention carries the model’s textual label.
  • t stores optional timestamps (handy for video frames).
  • Fields persist through serialization and are safe to log or display.

​
Normalized coordinates

All annotations live on a 0–1000 grid so they can be reprojected onto any render size. Convert them back to pixels with PerceiveResult.points_to_pixels(width, height) or the standalone helpers in perceptron.pointing.geometry. The Coordinate system concept page walks through the math and usage tips.