> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perceptron.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Pointing basics

> Understand Perceptron point, box, polygon, and collection types and when to choose each for your application.

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:

```python theme={null}
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

```python theme={null}
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:

```html theme={null}
<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

```python theme={null}
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

```python theme={null}
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](/isaac-0.2/concepts/coordinates) page walks through the math and usage tips.