Pointing basics - Perceptron Docs

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

Type	Key fields	Example use
`SinglePoint`	`x`, `y`, optional `t`, `mention`	Button taps, defect centroids, laser alignments.
`BoundingBox`	`top_left`, `bottom_right`, optional metadata	Object detection overlays, cropping regions.
`Polygon`	`hull` (list of `SinglePoint`), optional metadata	Segmentation masks, irregular outlines, exclusion zones.
`Collection`	`points`, optional metadata	Grouped 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"> (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.

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.

​Data classes

​Canonical tags

​Collections in code

​Metadata fields

​Normalized coordinates

Data classes

Canonical tags

Collections in code

Metadata fields

Normalized coordinates