> For the complete documentation index, see [llms.txt](https://docs.imerit.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.imerit.net/3d-multi-sensor-fusion/labeling/3d-multi-sensor-fusion-labeling-editor/key-features/cuboid-grouping.md).

# Cuboid Grouping

Cuboid Grouping allows users to link multiple cuboids that move together in the real world - maintaining their relative positions throughout a sequence. This is particularly useful when tracking objects that are physically connected or consistently aligned. The grouping helps improve annotation accuracy, ensures spatial consistency, and reduces the need for manual frame-by-frame adjustments. It’s a good and lean feature, enhancing both annotation quality and workflow efficiency without adding complexity.

{% hint style="success" %} <img src="/files/mXHEiGg35kYjwl0I4r5p" alt="" data-size="line"> Useful when tracking objects that are physically connected or consistently aligned.
{% endhint %}

![](/files/ebb938bdbe79ebca671989bb0291625299f44c8b)

***

## Use Case

**Agri-Tech – Tractor with a Towed Implement**

* Grouping ensures the implement maintains a fixed offset behind the tractor across the sequence, saving time and reducing annotation drift.

**Autonomous Driving – Cabin and a Trailer**

* Helps track multi-part vehicles moving together while preserving their orientation and spacing.

## Benefits

* **Good:** Maintains consistent spatial relationships between grouped cuboids, improving annotation accuracy across frames - while still allowing individual cuboids to be adjusted for bends, slopes, or load changes without breaking the group.
* **Lean:** Reduces manual alignment work, especially in sequences where linked objects appear across long spans.
* **Flexible:** Grouping can be applied and ungrouped selectively over any frame range, offering precise control.
* **Transparent:** The Group Information row and hover tooltips show at a glance which frames a group is active on and who's grouped with whom, without opening the grouping dialogue.

***

## Steps to Use Cuboid Grouping

{% stepper %}
{% step %}

#### Multi-select cuboids

Hold Ctrl and multi-select the cuboids you want to group.
{% endstep %}

{% step %}

#### Create the group

Hover over the cuboid that should lead the group, right-click, and choose "Group" from the context menu.

* The context menu displays the **Leader** name to avoid ambiguity
* For a first-time grouping, the selected cuboids are grouped across the full sequence.
* For subsequent groupings, a confirmation message shows the applicable frame range and prevents selecting a range where both annotations aren't present.
  {% endstep %}

{% step %}

#### Select the group

Click once on any cuboid to select the whole group. The bounding envelope shows a white border, distinguishing it from an individually selected cuboid (yellow border). This distinction holds across BEV, 3D, and orthographic views.
{% endstep %}

{% step %}

#### Edit an individual cuboid within the group

Click a second time on the specific cuboid to select it for editing; this opens the orthogonal views.

* Adjust position, dimensions, yaw, pitch, or roll as needed.
* The edit applies to the current frame and propagates backward/forward through interpolation until the next cuboid-level keyframe - consistent with standard cuboid keyframing behavior.
* The bounding envelope updates immediately to reflect the change on that frame.
  {% endstep %}

{% step %}

#### **Track group activity in the timeline**

When a grouped annotation is selected, a Group Information row appears below the attribute rows.

* Colored frames indicate the group is active; empty/dark frames indicate it isn't.
* Each group ID gets a distinct color; if the annotation belongs to different groups across different ranges, each range shows its own color.
* Hover over a colored frame to see a tooltip listing the other annotations grouped with the selected one on that frame (the selected annotation itself is excluded).
  {% endstep %}

{% step %}

#### **Ungroup only when needed**

No need to ungroup unless the objects in the sequence become grouped with different partners later on.
{% endstep %}
{% endstepper %}

***

## Why The Leader Matters

The leader cuboid acts as the reference point for the entire group - every other cuboid's position, orientation, and dimensions are tracked as an *offset relative to the leader*. This means:

* Choosing a leader that is well-tracked and stable across the sequence (e.g., the tractor rather than the implement) keeps the group's relative positioning accurate and predictable till manual adjustments are made to invidivually grouped cuboids.
* A poorly chosen leader - one that's harder to track consistently, or more prone to per-frame adjustment - can introduce unexpected drift across the rest of the group, since every member's offset is calculated from it.

{% hint style="success" icon="lightbulb" %}
Tip: As a rule of thumb, choose the object that moves most predictably or is easiest to annotate accurately as the leader - not necessarily the "primary" object in the real-world sense.
{% endhint %}