Pointing basics

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

• 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

<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)

<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),
        ]),
    ],
)

​

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