> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/annotations/video-annotation.md).

# Video Annotation

Video annotation adds time, identity, and state to geometry. A production result must explain when an object exists, how it moves or changes shape, where keyframes were placed, and when object-level or scene-level properties change.

### Read the video Workbench

![Video Annotation Workbench with timeline](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FZbNuylb5fa8iMiHXNaj9%2Fvideo-workbench.png?alt=media\&token=4bbc9cd5-e611-408a-a3a4-a70035401a98)

*The video editor combines the active frame, canvas, ontology, object inspector, playback, track rows, keyframes, temporal ranges, and workflow action.*

| Area                        | Use it for                                                                                                           |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Canvas                      | Create and refine geometry on the active frame.                                                                      |
| Objects and Classes         | Select identities, create annotations, and set object properties.                                                    |
| Item properties             | Label the complete video or time-varying whole-scene state.                                                          |
| Frame and playback controls | Move by exact frame, play, pause, and review transitions.                                                            |
| Timeline                    | Inspect object tracks, dynamic-property child rows, Item Property rows, active ranges, keyframes, and interpolation. |
| Tracking controls           | Enable model-assisted Auto-Tracking or deterministic interpolation between keyframes.                                |
| Workflow action             | Submit, review, reject, return, or complete according to the current stage.                                          |

### Annotate one tracked object

{% stepper %}
{% step %}

#### 1. Choose an authoritative start frame

Move to the first frame that satisfies the project's visibility and inclusion policy. Do not start only from the easiest frame unless the policy permits a later first state.
{% endstep %}

{% step %}

#### 2. Create the object

Choose the class and required geometry, draw the instance, and complete its static properties.
{% endstep %}

{% step %}

#### 3. Propagate

Use full, forward, or backward Auto-Tracking, interpolation, or manual keyframes according to the motion, deformation, occlusion, and source quality.
{% endstep %}

{% step %}

#### 4. Protect identity

Scrub through crossings, occlusion, disappearance, re-entry, camera cuts, blur, scale changes, and similar neighboring objects.
{% endstep %}

{% step %}

#### 5. Set temporal state

Add Dynamic class-property values to the selected object and Dynamic Item Properties to the sequence only at frames where the state becomes known or changes.
{% endstep %}

{% step %}

#### 6. Review the timeline

Confirm first and last qualifying frames, gaps, keyframes, hidden ranges, state transitions, mask stability, and track identity before routing the task.
{% endstep %}
{% endstepper %}

### Dynamic class properties

A Dynamic class property belongs to one tracked annotation. The object identity stays stable while the value changes by frame.

**Example:** one Person track has Helmet status **Not visible** at entry, **Present** after the head becomes clear, and **Absent** after the helmet is removed.

1. Create the property with **Dynamic** enabled in the ontology or from the Workbench property flow.
2. Select the object on the frame where the initial value becomes valid.
3. Set the value in the object inspector. Unitlab creates a property keyframe and a child row beneath the object track.
4. Move to the frame where the state changes and set the new value.
5. Expand the object row, inspect the resulting value ranges, and adjust transition boundaries if required by policy.

A non-dynamic class property applies one value to the object without a frame-by-frame value history.

### Dynamic Item Properties

A Dynamic Item Property belongs to the complete video, medical sequence, or Data Group—not to one object. Use it for Weather, Camera state, Scene, Traffic density, Procedure phase, or Overall quality.

1. Open **Item properties** at the top of the inspector.
2. Add or select an Item Property created with **Dynamic** enabled.
3. Set the first value at its authoritative frame. The property appears as an independent timeline row.
4. Move later and set the next value. Unitlab divides the timeline into value ranges.
5. Expand nested Item Properties to inspect conditional child rows, then select or resize ranges to correct temporal boundaries.

Static Item Properties appear as a single whole-item range. Dynamic Item Properties remain independent of object tracks even when their values use nested conditional logic.

### Review a dense or multiview timeline

![Multiview video Workbench with synchronized panels and a dense timeline](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FuWV2FdAcECE2UrevUndn%2Fmultiview-video-workbench.png?alt=media\&token=77ad56ff-14dd-430b-9d53-cb23ba63956d)

*Multiview video keeps camera context synchronized while the timeline remains the control center for identities, ranges, keyframes, dynamic properties, and review.*

Use a stable camera-slot order and define synchronization tolerance before annotation. Decide whether identity is view-local or event-level and how cross-view relations are represented. A passive panel provides context; the active panel and selected timeline row determine what is being edited.

### Tracking and timeline reference

Video uses the spatial annotation toolset plus time:

* frame counter and frame-by-frame navigation;
* playback;
* object track rows;
* timeline zoom from 1× to 10×;
* loop control;
* keyframes;
* track-level review;
* synchronized multiview video layouts.

Common video workflows include:

* construction and mining scenes with person tracks and a dynamic `Helmet status` property;
* agriculture with two synchronized camera angles;
* factory inspection with four camera angles;
* self-driving data with many vehicle and person tracks;
* a construction sequence in which annotations propagate across frames.

### Auto-Tracking

Auto-Tracking uses machine learning to predict an object across frames. The user starts with one or more annotated objects, chooses a tracking direction, runs tracking, then reviews the propagated results and keyframes on the timeline.

Use Auto-Tracking when motion is continuous enough for model proposals to reduce repeated drawing. Review after occlusion, re-entry, camera cuts, scale changes, blur, and interactions between similar objects.

### Full, forward, and backward tracking

Right-clicking a supported object opens **Auto track** with three directional actions:

| Action                    | Range                                                                                            | Typical use                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| **Track full annotation** | Runs in both directions from the selected frame across the annotation’s available temporal range | The seed object is created in the middle of a sequence and the complete track is required     |
| **Track forward**         | Runs from the selected frame toward later frames                                                 | The first reliable appearance of the object is known, or only future motion needs propagation |
| **Track backward**        | Runs from the selected frame toward earlier frames                                               | The clearest object appearance occurs later and earlier frames need to be recovered           |

Direction availability follows the current position. **Track backward** is unavailable at the first frame, and **Track forward** is unavailable when no later frame remains. Full tracking provides bidirectional propagation from a single reliable seed.

The same commands are available from a selected timeline segment. While a track is running, the segment menu changes from **Tracking** to **Stop Tracking**, allowing the user to end an active tracking operation.

### Multi-object tracking

Unitlab can track several objects in one operation:

1. The annotator holds **Command** on macOS or **Ctrl** on Windows/Linux and right-clicks objects to build a multi-selection.
2. The context menu reports the number of selected objects.
3. The annotator chooses **Auto track**.
4. The annotator selects **Track full annotation**, **Track forward**, or **Track backward**.
5. Unitlab submits the selected supported tracks together and writes each result back to its own object track.
6. The annotator reviews every result on the timeline and corrects individual tracks where identities diverge.

The multi-object menu also provides group actions such as bring all to front, send all to back, duplicate all, and delete all. Group tracking preserves separate object identities; it does not merge the selected objects into one annotation.

### Interpolation

The live control describes Interpolation as “Tween between keyframes.” It is deterministic propagation between manually defined states and is appropriate when an annotator can place reliable keyframes around smooth motion.

### Auto-Tracking versus interpolation

| Question                      | Auto-Tracking                                        | Interpolation                              |
| ----------------------------- | ---------------------------------------------------- | ------------------------------------------ |
| Source of intermediate labels | Model predictions                                    | Geometry between keyframes                 |
| Best fit                      | Complex but trackable motion                         | Smooth movement between known states       |
| Main risk                     | Identity drift or confident false proposals          | Missing non-linear motion or shape change  |
| Review focus                  | Track identity, occlusion, re-entry, false positives | Keyframe placement and motion between keys |

### Dynamic properties

Class properties can be marked **Dynamic** in video and medical annotation. This enables temporal labeling across frames: a dynamic property stores frame-aware values instead of one value for the complete object track. For example, a person can remain the same tracked instance while `Helmet status` changes from `Not visible` to `Present` and later to `Absent`.

Dynamic class-property flow:

1. Create or edit the property and enable **Dynamic**.
2. Select the annotated object at the frame where the value becomes known or changes.
3. Set the single-choice, multi-choice, or text value in the object inspector.
4. Unitlab creates a property keyframe for that object and displays the property as a child row beneath the object track.
5. Move to a later frame and change the value to create another temporal state.
6. Expand the object row on the timeline to inspect the property ranges and their transition points.

A non-dynamic class property applies to the object without a frame-by-frame value history. Dynamic properties are used when the object identity remains stable but its state changes across the sequence.

### Dynamic Item Properties

Item Properties describe the complete datasource rather than one annotation object. They can also be marked **Dynamic** for video and medical work, enabling temporal labeling across frames for whole-scene or whole-frame state—for example `Weather`, `Camera state`, `Scene`, `Traffic density`, `Procedure phase`, or `Overall quality`.

Dynamic Item Property flow:

1. Open **Item properties** at the top of the Objects inspector.
2. Add or select an Item Property whose **Dynamic** setting is enabled.
3. Set the value at the current frame. The first value creates an item-property range from that frame across the available sequence.
4. Move to another frame and set a different value. Unitlab creates a new keyframe and divides the timeline into value ranges.
5. Expand nested Item Properties to inspect conditional child values beneath the parent range.
6. Select a range on the timeline to jump to it, inspect its label/color, and adjust the temporal boundaries when required.

Static Item Properties appear as one full-item range. Dynamic Item Properties appear as independent timeline rows and are not attached to one object track. Class properties and Item Properties can both use nested conditional logic; their timeline placement distinguishes object state from item-level scene state.

### Timeline UX and user flow

The video and medical timeline is the temporal control center for geometry, object state, and item-level state.

**Timeline structure**

* The header shows the editable current-frame number, total frames, previous/play/next controls, the Tracking settings menu, timeline zoom from 1× to 10×, and loop control.
* The left column lists tracks by class and geometry. Bounding boxes, cuboids, polygons, masks/brushes, skeletons, points, polylines, instances, Item Properties, and dynamic annotation properties can have timeline rows.
* Parent object and Item Property rows can be expanded to reveal nested dynamic-property rows.
* Colored bars show active ranges. Diamond markers show keyframes. Explicit interpolation spans are connected visually between their source keyframes.
* The vertical playhead and numbered badge identify the active frame.

**Navigation and selection**

1. Enter a frame number, use previous/play/next, press **←/→**, click the timeline, or drag the numbered playhead to move through the sequence.
2. Click a track label or bar to select the corresponding annotation. The canvas and object inspector synchronize to that selection.
3. Enable **Auto zoom on timeline click** in View Settings to center the selected annotation automatically.
4. Use the 1×–10× timeline zoom and horizontal scrolling to inspect dense keyframes; vertical scrolling keeps the track-label column synchronized with the rows.

**Range editing and contextual actions**

* Drag a segment’s left or right handle to change where the annotation or property range begins or ends.
* Right-click a geometry segment to start/stop Tracking, hide/show the segment, delete it, or access mask interpolation when applicable.
* Hidden ranges remain part of the annotation history but are not rendered in their hidden interval.
* Selecting an object on the canvas selects its timeline row; selecting its timeline row selects the object on the canvas.
* Read-only release and passive Multiview panels show timeline context without exposing mutation actions.

**Tracking settings**

The **Tracking** menu contains two independent switches:

* **Auto-Tracking — Predict later frames with ML:** new supported annotations can immediately start model-assisted propagation.
* **Interpolation — Tween between keyframes:** geometry is generated between manually defined keyframes.

These settings can be used separately. Auto-Tracking follows visual evidence; interpolation follows the geometry defined at its surrounding keyframes.

### Mask interpolation

Video mask interpolation is distinct from general object interpolation. The user places or edits segmentation keyframes, then uses the **Interpolate mask** timeline action to materialize intermediate masks between them. Generated in-between masks remain reviewable. This is most useful for smooth boundary motion and still needs correction around occlusion, topology changes, rapid deformation, and scene cuts.

When a mask segment contains at least two manually created keyframes, its context menu exposes **Interpolate mask**. After intermediate masks are materialized, **Clear interpolation** removes the generated in-between frames while preserving the source keyframes.

### Final quality review

* inspect the complete temporal range, not only one representative frame;
* verify object identity through crossings, occlusion, cuts, and re-entry;
* compare Auto-Tracking predictions against manual evidence at difficult transitions;
* verify interpolation around nonlinear motion and shape changes;
* confirm each Dynamic property transition begins and ends on the intended frames;
* confirm Dynamic Item Properties are not accidentally attached to one object;
* review mask interpolation around topology changes and rapid deformation;
* identify the exact object and frame interval when rejecting work to rework.