Track a box
track_boxTrack an object seeded by a box at time at. x1>x0 and y1>y0. Specify the range and fps (null samples every frame of the footage, for a follow or a cover; 8 to look); do not lower fps or split a long clip. Coordinates are source pixels and times source seconds unless you say otherwise: pass points read off a preview with space preview and its previewId (the seed's time is then the preview's), film pixels with space film, and a film second with atSpace timeline. The answer ends with a json block giving the seed and the result in source, film and film_norm, with the source and timeline seconds, and warns about coordinates that look wrong. Every frame is checked: the answer gives a quality verdict, the flagged ranges (a corner drifting off the surface, a jump, the tracker unsure) and amber tiles on the sheet for them. Fix a flagged track with autoReseed true (it tracks those frames again from the last good frame), more seeds where the object looks different, or edit_track (free: it fixes a frame and fades the fix into its neighbours). read_track reads every frame's corners and quality. Uses about 9.7 credits a minute of the range, billed by the second. Read builtin-object-tracking first.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"assetId": "<assetId>",
"startTime": "<startTime>",
"endTime": "<endTime>",
"fps": "<fps>",
"label": "<label>",
"detail": "<detail>",
"at": "<at>",
"box": "<box>",
"space": "<space>",
"previewId": "<previewId>",
"clipId": "<clipId>",
"atSpace": "<atSpace>",
"seeds": "<seeds>",
"autoReseed": "<autoReseed>",
"snap": "<snap>",
"snapRadius": "<snapRadius>",
"projectId": "<projectId>"
},
"name": "track_box"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| at | Yes | ||
| box | Yes | ||
| fps | Yes | Samples a second, 1 to 30. null samples every frame of the footage on its own frame times (every second frame of 50 or 60 fps footage): use it for a pin, a cover or a follow. 8 is enough to look. An fps above the footage's repeats frames. | |
| snap | Yes | true: move the seed onto the picture first (corners onto the surface's real corners, a box onto the object's edges, points onto the nearest corner), as the snap tool does; each move is in the answer, and a point with weak evidence stays put. Use it on corners read off a preview. null or false: the seed as given. | |
| label | Yes | ||
| seeds | Yes | More seeds besides at's, up to 8, in the call's space and atSpace: where the object looks different (it turns, comes back after leaving, changes size). Each seed is tracked to its neighbours and the walks are joined into one track where they meet, keeping the better frame. null tracks from at's seed alone. | |
| space | Yes | The space of this call's coordinates. null or source: pixels of the asset file. preview: pixels of a preview image you were shown, with previewId; its time is that preview's time. film: scene pixels from the frame's centre; film_norm: 0 to 1 of the frame; clip: the clip's own picture (with clipId). The tool converts them to the asset's pixels through the film's real transforms. | |
| clipId | Yes | The film clip that plays this asset, when space or atSpace needs one and several clips play it. null picks the clip that shows the asset at that time. | |
| detail | Yes | brief: the track id, its verdict and the flagged ranges, with no contact sheet. normal (null): the answer and its contact sheet. full: the same, as normal for now. | |
| assetId | Yes | ||
| atSpace | Yes | What this call's times are. null or source: seconds into the asset file. timeline: seconds of the film, read through the clip that plays the asset then (clipId to pick one). | |
| endTime | Yes | ||
| previewId | Yes | With space preview or preview_norm: the previewId the preview_frame, preview_range or preview_timeline answer printed. Else null. | |
| projectId | Yes | The project this call runs on without changing the open project. null (or leaving it out) uses the open project. wait_for_jobs takes the projectId of the calls that started the jobs. | |
| startTime | Yes | ||
| autoReseed | Yes | true: where the quality check flags frames (a corner drifting, a jump, the tracker unsure), track them again from the last good frame before them, and keep the better frames. The answer says where it reseeded. Each reseed uses credits for the frames it reads. null or false: no reseeding. | |
| snapRadius | Yes | How far snap may move a point, in source pixels, up to 64. null: 12. |