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, Clip
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.
Cliptimestamp.at, optional timestamp.until, mentionTemporal moments or spans in video — sports highlights, event localization, action segmentation.
  • 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.
  • timestamp.at, timestamp.until: clip start (and optional end) in seconds. When until is None, the clip refers to a single moment rather than a range.

​
Canonical tags

The SDK’s serializer and parser share the same HTML-style format the models emit: 
<point mention="button center"> (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.
  • Coordinates are integers on the 0–1000 grid.
  • Collections can nest any mix of point, box, or polygon tags.

​
Video clips (Mk1 only)

Perceptron Mk1 additionally emits self-closing <clip /> tags for video temporal segments: 
<clip mention="goal celebration" t="42 seconds" />
<clip mention="rally" t="12.5 seconds 18 seconds" />
  • <clip /> is self-closing — the timestamp is the t attribute, not body text. Values are whitespace-separated with the literal unit seconds. One number = a moment, two numbers = a range.
  • Collections can nest <clip /> tags alongside spatial primitives.
  • The SDK parses clips into Clip objects when you set expects="clip" (see Video Clipping).

​
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.