> ## 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, collection, and clip 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, Clip
```

| 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.                             |
| `Clip`        | `timestamp.at`, optional `timestamp.until`, `mention` | Temporal 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:

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

### Video clips (Mk1 only)

Perceptron Mk1 additionally emits self-closing `<clip />` tags for video temporal segments:

```html theme={null}
<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](/perceptron-mk1/capabilities/video-clipping)).

## 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](/perceptron-mk1/concepts/coordinates) page walks through the math and usage tips.