> For the complete documentation index, see [llms.txt](https://docs.eyepop.ai/developer-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/objects.md).

# Objects

Things found at a place in the frame, with their box, identity and nested results

An **object** is something a model found at a place in the frame: a person, a car, a face, a word on a sign. Detectors return objects, and so does every component that finds things inside them. They are listed in `objects`, on the prediction for things found in the whole frame, and on an object for things found within it.

### An object

```json
{
  "classLabel": "person",
  "confidence": 0.9775,
  "x": 503.281,
  "y": 251.718,
  "width": 166.562,
  "height": 464.765,
  "orientation": 0
}
```

At its simplest, an object answers three questions: **what** (`classLabel`), **how sure** (`confidence`) and **where** (`x`, `y`, `width`, `height`). Everything else is added by the components of the Pop.

### Fields

From the general to the specific:

| Key                         | Type             | Meaning                                                                                                                                                                                                                                 |
| --------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `classLabel`                | string           | What the object is                                                                                                                                                                                                                      |
| `confidence`                | number           | How certain the detector is, from 0 to 1                                                                                                                                                                                                |
| `category`                  | string           | The group it belongs to, such as the `categoryName` of the component that found it. See [Fields every result shares](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions.md#fields-every-result-shares) |
| `x`, `y`, `width`, `height` | number           | The axis-aligned box, in source pixels. See [Spatial Attributes](https://docs.eyepop.ai/developer-documentation/platform/response-format/spatial-attributes.md#boxes)                                                                   |
| `orientation`               | number           | The object's direction, in radians; `0` when the ability reports none. See [Orientation and outline](https://docs.eyepop.ai/developer-documentation/platform/response-format/spatial-attributes.md#orientation-and-outline)             |
| `outline`                   | array of points  | The box turned to the object's orientation                                                                                                                                                                                              |
| `trackId`                   | integer          | The object's identity across frames, when a tracking component follows it. See [Tracks](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/tracks-and-selected-predictions.md#tracks)                  |
| `objects`                   | array of objects | Objects found within this one                                                                                                                                                                                                           |
| `classes`                   | array            | Labels for this object. See [Classes and Texts](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/classes-and-texts.md)                                                                               |
| `texts`                     | array            | Text read within this object. See [Texts](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/classes-and-texts.md#texts)                                                                               |
| `keyPoints`                 | array            | Landmarks on this object. See [Key Points](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/key-points-and-meshes.md)                                                                                |
| `meshes`                    | array            | 3D surfaces on this object. See [Meshes](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/key-points-and-meshes.md#meshes)                                                                           |
| `contours`, `mask`          |                  | The object's exact shape. See [Masks, Contours and Depth](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/masks-contours-and-depth.md)                                                              |
| `raw`                       | array            | Tensor output for this object, such as an embedding. See [Raw Output](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/raw-and-details.md#raw-output)                                                |
| `details`                   | array            | Structured answers about this object. See [Details](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/raw-and-details.md#details)                                                                     |

Only `classLabel`, `confidence` and the box are always there. The rest appears when the Pop produces it.

### Objects within objects

A Pop that crops each detection and runs another model on the crop puts that model's results **inside** the object it was cropped from. Detecting people, then faces on each person, gives a person holding a face:

```json
{
  "classLabel": "person",
  "confidence": 0.9775,
  "x": 503.281, "y": 251.718, "width": 166.562, "height": 464.765,
  "objects": [
    {
      "classLabel": "face",
      "confidence": 0.7411,
      "x": 554.438, "y": 263.858, "width": 65.296, "height": 65.296
    }
  ]
}
```

The nesting is the answer to "whose face is this?": the face belongs to the person it is listed under. Two people with a face each give two persons with one face each, never a flat list of two people and two faces to match up afterwards.

Nested objects are positioned in the **full frame**, like their parent, so they can be drawn on the original image without any offset. See [Nested results use the same frame](https://docs.eyepop.ai/developer-documentation/platform/response-format/spatial-attributes.md#nested-results-use-the-same-frame).

A crop that finds nothing leaves its parent without `objects`. A person whose face was not found is a person without a nested face, not a person with an empty list.

### Example: cut out every object

The box is all you need to cut an object out of the original image. This saves one image per person found:

```python
from PIL import Image

from eyepop import EyePopSdk
from eyepop.worker.worker_types import InferenceComponent, Pop

pop = Pop(components=[InferenceComponent(ability="eyepop.person:latest")])

with EyePopSdk.sync_worker(pop=pop) as endpoint:
    prediction = endpoint.upload("lobby.jpg").predict()

image = Image.open("lobby.jpg")
for i, obj in enumerate(prediction.get("objects", [])):
    box = (obj["x"], obj["y"], obj["x"] + obj["width"], obj["y"] + obj["height"])
    image.crop(tuple(round(v) for v in box)).save(f"{obj['classLabel']}-{i}.jpg")
```

The coordinates are decimals; round them to whole pixels before cropping.

### Next steps

* [Classes and Texts](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/classes-and-texts.md) — what a classifier or a text reader adds to an object
* [Tracks and Selected Predictions](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions/tracks-and-selected-predictions.md) — the same object across frames
