> 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/temporal-context/select-operators.md).

# Select Operators

Run deep analysis once per tracked object, on the frame that shows it best

`select_crop` and `select_full` are [forward](https://docs.eyepop.ai/developer-documentation/platform/pop/pop-forwarding.md) operators for a `tracking` component. Instead of running their targets on every frame, they pick each track's **most relevant detection** and run the targets once, on the past frame where that detection was seen. They differ only in what the targets receive:

| Operator      | The targets run on                        | Use it when the analysis is about                                                      |
| ------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- |
| `select_crop` | a crop of the selected detection          | the object itself: e.g. a car's make and model, a person's appearance                  |
| `select_full` | the whole frame the detection was seen on | the object in its surroundings: e.g. where it is, what it is doing, what is next to it |

Everything else — how relevance is judged, when a selection is reported, and how the results come back — is the same for both.

```
detector ──crop──▶ tracking ──select_crop / select_full──▶ deep analysis
 every frame       every frame                             once per selection
```

{% hint style="info" %}
Requires Python SDK **3.24.0** or Node SDK **3.23.0**, or newer.
{% endhint %}

### A first example

Track people, and run face detection once per person on the frame where a face is seen best. This is `select_crop`; the [`select_full`](#what-the-targets-receive) variant follows below:

{% tabs %}
{% tab title="Python" %}

```python
from eyepop.worker.worker_types import (
    CropForward, InferenceComponent, Pop, SelectForward, TrackingComponent,
)

pop = Pop(components=[
    InferenceComponent(
        ability="eyepop.person:latest",
        forward=CropForward(targets=[TrackingComponent(
            reidModel="eyepop.person.reid:latest",
            forward=SelectForward(
                relevancyModel="eyepop.person.face.short-range:latest",
                targets=[InferenceComponent(ability="eyepop.person.face.short-range:latest")],
            ),
        )]),
    ),
])
```

{% endtab %}

{% tab title="Node" %}

```typescript
import { ForwardOperatorType, PopComponentType, SelectMode } from '@eyepop.ai/eyepop'

const pop = {
    components: [{
        type: PopComponentType.INFERENCE,
        ability: 'eyepop.person:latest',
        forward: {
            operator: { type: ForwardOperatorType.CROP },
            targets: [{
                type: PopComponentType.TRACKING,
                reidModel: 'eyepop.person.reid:latest',
                forward: {
                    operator: {
                        type: ForwardOperatorType.SELECT_CROP,
                        select: {
                            mode: SelectMode.MOST_RELEVANT,
                            relevancyModel: 'eyepop.person.face.short-range:latest',
                        }
                    },
                    targets: [{ type: PopComponentType.INFERENCE, ability: 'eyepop.person.face.short-range:latest' }],
                },
            }],
        },
    }],
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "components": [{
    "type": "inference",
    "ability": "eyepop.person:latest",
    "forward": {
      "operator": { "type": "crop" },
      "targets": [{
        "type": "tracking",
        "reidModel": "eyepop.person.reid:latest",
        "forward": {
          "operator": {
            "type": "select_crop",
            "select": {
              "mode": "most_relevant",
              "relevancyModel": "eyepop.person.face.short-range:latest",
            }
          },
          "targets": [{ "type": "inference", "ability": "eyepop.person.face.short-range:latest" }]
        }
      }]
    }
  }]
}
```

{% endtab %}
{% endtabs %}

### Relevancy with and without Relevancy Model

For every track, the operator keeps the best detection seen so far and the frame it was seen on. `select.mode` is `most_relevant`, the only mode, and what counts as relevant depends on whether you name a relevancy model:

* **Without one**, relevance comes from the tracked object: a confident, large detection beats a small, uncertain one, and obstruction, occlusion and poor visibility counts for less.
* **With `relevancyModel`** (or `relevancyModelUuid`), that ability runs on every tracked object and its result determines the relevancy instead of the tracked object itself.

A relevancy model runs on every frame, so it belongs on the efficient side: pick a small, fast ability.

### When a selection is reported

Both select operators support options that control the timing and frequency of selections.

| Option                   | Effect                                                                                                                                              |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minTrackLengthSeconds`  | Tracks shorter than this are never selected — a guard against flicker and objects that only clip the frame.                                         |
| `intervalSeconds`        | The first selection comes this long after the track starts, then at most one per interval, and only when a more relevant detection turned up since. |
| *(no `intervalSeconds`)* | Each track is selected once, when it ends.                                                                                                          |

Either way, the end of a track reports a final selection if its best detection improved since the last one. Use an interval when a track can live for a long time — a car waiting at a drive-through window — and you want an answer before it leaves. Leave it out when objects pass through and one answer per object is enough.

Here is the same example modified to only select tracks longer than one second and checking the relevant selection every 10 seconds instead of at the track end only:

{% tabs %}
{% tab title="Python" %}

```python
from eyepop.worker.worker_types import (
    CropForward, InferenceComponent, Pop, SelectForward, TrackingComponent,
)

pop = Pop(components=[
    InferenceComponent(
        ability="eyepop.person:latest",
        forward=CropForward(targets=[TrackingComponent(
            reidModel="eyepop.person.reid:latest",
            forward=SelectForward(
                relevancyModel="eyepop.person.face.short-range:latest",
                minTrackLengthSeconds=1,
                intervalSeconds=10,
                targets=[InferenceComponent(ability="eyepop.person.face.short-range:latest")],
            ),
        )]),
    ),
])
```

{% endtab %}

{% tab title="Node" %}

```typescript
import { ForwardOperatorType, PopComponentType, SelectMode } from '@eyepop.ai/eyepop'

const pop = {
    components: [{
        type: PopComponentType.INFERENCE,
        ability: 'eyepop.person:latest',
        forward: {
            operator: { type: ForwardOperatorType.CROP },
            targets: [{
                type: PopComponentType.TRACKING,
                reidModel: 'eyepop.person.reid:latest',
                forward: {
                    operator: {
                        type: ForwardOperatorType.SELECT_CROP,
                        select: {
                            mode: SelectMode.MOST_RELEVANT,
                            minTrackLengthSeconds: 1,
                            intervalSeconds: 10,
                            relevancyModel: 'eyepop.person.face.short-range:latest',
                        }
                    },
                    targets: [{ type: PopComponentType.INFERENCE, ability: 'eyepop.person.face.short-range:latest' }],
                },
            }],
        },
    }],
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "components": [{
    "type": "inference",
    "ability": "eyepop.person:latest",
    "forward": {
      "operator": { "type": "crop" },
      "targets": [{
        "type": "tracking",
        "reidModel": "eyepop.person.reid:latest",
        "forward": {
          "operator": {
            "type": "select_crop",
            "select": {
              "mode": "most_relevant",
              "minTrackLengthSeconds": 1,
              "intervalSeconds": 10,
              "relevancyModel": "eyepop.person.face.short-range:latest"
            }
          },
          "targets": [{ "type": "inference", "ability": "eyepop.person.face.short-range:latest" }]
        }
      }]
    }
  }]
}
```

{% endtab %}
{% endtabs %}

### What the targets receive

Both operators hand the targets the frame the selected detection was seen on — not the current one. The past frame is held by the platform while the track lives, so the targets see exactly what the tracker saw.

**`select_crop`** cuts the selected detection out of that frame. `crop.boxPadding` grows the box before cutting and `crop.orientationTargetAngle` rotates the crop, exactly as on a [`crop`](https://docs.eyepop.ai/developer-documentation/platform/pop/pop-forwarding.md#operators) forward. `crop.maxItems` does not apply, since a selection is always one detection.

**`select_full`** passes that whole frame and takes no `crop` options. The selected prediction still carries the selected detection with its `trackId`, and the targets' results sit at the frame level beside it, as they would for any whole-frame stage. A depth map produced by a `select_full` target enriches the selected frame's objects, because the map and the objects describe the same past frame.

{% tabs %}
{% tab title="Python" %}

```python
SelectForward(
    full=True,
    minTrackLengthSeconds=1,
    targets=[InferenceComponent(ability="eyepop.gemini-4-argon.classify:latest",
                                params={"prompts": [{"prompt": "a person at the checkout", "label": "checkout"},
                                                    {"prompt": "a person in an aisle", "label": "aisle"},
                                                    {"prompt": "a person at the entrance", "label": "entrance"}]})],
)
```

{% endtab %}

{% tab title="Node" %}

```typescript
{
    operator: {
        type: ForwardOperatorType.SELECT_FULL,
        select: { mode: SelectMode.MOST_RELEVANT, minTrackLengthSeconds: 1 },
    },
    targets: [{
        type: PopComponentType.INFERENCE,
        ability: 'eyepop.gemini-4-argon.classify:latest',
        params: {
            prompts: [
                { prompt: 'a person at the checkout', label: 'checkout' },
                { prompt: 'a person in an aisle', label: 'aisle' },
                { prompt: 'a person at the entrance', label: 'entrance' },
            ],
        },
    }],
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "operator": {
    "type": "select_full",
    "select": { "mode": "most_relevant", "minTrackLengthSeconds": 1 }
  },
  "targets": [{
    "type": "inference",
    "ability": "eyepop.gemini-4-argon.classify:latest",
    "params": {
      "prompts": [
        { "prompt": "a person at the checkout", "label": "checkout" },
        { "prompt": "a person in an aisle", "label": "aisle" },
        { "prompt": "a person at the entrance", "label": "entrance" }
      ]
    }
  }]
}
```

{% endtab %}
{% endtabs %}

If selections come due faster than the targets can work through them, they wait in a queue; past 64 waiting, the oldest are dropped with a warning. The live predictions never wait for the targets.

### Selected predictions

The best frame of a track is only known after the fact, so its results arrive **late**, after predictions for later frames have gone out. They come on the same stream as every other prediction, as a **selected prediction**:

| Field                  | Description                                                                                                                                                                                  |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `selected`             | `true` on a selected prediction, absent on every other.                                                                                                                                      |
| `timestamp`, `seconds` | The past frame that was selected.                                                                                                                                                            |
| `objects`              | One object: the selected detection, with its `trackId`. For `select_crop` the targets' results are nested under it; for `select_full` they are on the prediction itself, at the frame level. |

{% tabs %}
{% tab title="Python" %}

```python
while result := job.predict():
    if result.get("selected"):
        handle_selection(result)  # deep analysis for one track, about a past frame
    else:
        handle_frame(result)      # the live, per-frame picture
```

{% endtab %}

{% tab title="Node" %}

```typescript
for await (const prediction of results) {
    if (prediction.selected) {
        handleSelection(prediction)
    } else {
        handleFrame(prediction)
    }
}
```

{% endtab %}
{% endtabs %}

Two consequences to plan for:

* **The stream is no longer in timestamp order.** A selected prediction is not the stream's progress: skip it where you draw or count frames. The SDKs' renderers already do.
* **Join on `trackId`.** It ties a selection to the live predictions of the same object.

### Rules

* `select_crop` and `select_full` go on a `tracking` component's forward and nowhere else.
* A select operator requires a `select` block, and `select` is rejected on every other operator.
* `crop` options are accepted on `select_crop` only, except the `crop.maxItems` option.
* Name at most one of `relevancyModel` and `relevancyModelUuid`.
* `minTrackLengthSeconds` must not be negative; `intervalSeconds` must be positive.

Both SDKs check all of these except the first when the Pop is built; the platform checks the first when it compiles the Pop.

### Next steps

* [Example: Make and Model Insights from Car Drive-Bys](https://docs.eyepop.ai/developer-documentation/platform/temporal-context/example-car-make-and-model.md) — a custom VLM ability, once per car
* [Example: Best Face-ID Vector from Walk-Bys](https://docs.eyepop.ai/developer-documentation/platform/temporal-context/example-face-id-from-walk-bys.md) — one face-ID vector per person
* [Forwarding](https://docs.eyepop.ai/developer-documentation/platform/pop/pop-forwarding.md) — the attribute reference for every forward operator
* [Components](https://docs.eyepop.ai/developer-documentation/platform/pop/pop-components.md#tracking) — tuning the tracker the selection is built on
