Elements

Vision elements are the overlays rendered on top of the image — rectangles, circles, segments, text, and so on. The controller lets you add, retrieve, update, and remove individual elements at any time.

danger

All add/remove/refresh operations require a base image to be set first. Calling them without a prior setImage() or sendCapture() will throw an error.

---

Adding elements

addElement()

Adds a single vision element, optionally assigning it to a named group.

addElement(ve: Ve.VisionElement, groupKey?: string, options?: IElementsOptions): Promise<void>;

addElements()

Adds multiple vision elements at once to the same group.

addElements(veList: Ve.VisionElement[], groupKey?: string, options?: IElementsOptions): Promise<void>;

addElementsDictionary()

Adds a full dictionary of elements, with each key becoming a group and each value being the list of elements in that group. The most efficient way to add elements to multiple groups in one call.

addElementsDictionary(dict: Record<string, Ve.VisionElement[]>, options?: IElementsOptions): Promise<void>;

var ctrl = Visu.page0.display1.getController();
var rect = new Ve.Rect2d(100, 100, 200, 150, 0);
var pt   = new Ve.Point2d(320, 240);

// Add to a named group
await ctrl.addElement(rect, "Detections");

// Add multiple groups at once
await ctrl.addElementsDictionary({
    "Detections": [rect],
    "Keypoints":  [pt],
});

Group keys

The groupKey controls how elements are organized in the Objects Tree panel visible in the full-screen view. Each unique key becomes a collapsible group header. Elements added without a key (or with "") land in the default group and appear ungrouped — without a header row.

// "Detections" and "ROI" appear as two separate collapsible groups
await ctrl.addElementsDictionary({
    "Detections": [rect1, rect2],
    "ROI":        [roiRect],
});

// This element has no group header — appears directly in the tree
await ctrl.addElement(pt);

See Objects Tree Panel for a full description of the panel, bidirectional canvas sync, and bulk visibility controls.

note

Element IDs must be unique across all groups. Attempting to add an element whose ID already exists in the scene will throw a duplicate-ID error.

---

Retrieving elements

getElement()

Returns a single element by its numeric ID. Throws if the ID is not found.

getElement(id: number): Ve.VisionElement;

getElements()

Returns a list of elements. If ids is omitted, returns all elements in the scene.

getElements(ids?: number[]): Ve.VisionElement[];

// Get all elements
var all = ctrl.getElements();

// Get specific elements by ID
var subset = ctrl.getElements([1, 2, 3]);

---

Removing elements

removeElement()

Removes a single element by ID.

removeElement(id: number): Promise<void>;

removeElements()

Removes multiple elements by ID in a single operation.

removeElements(ids: number[]): Promise<void>;

---

Refreshing elements

Use the refresh methods when you have modified the properties of existing elements via getElement() and need to push those changes to the display.

refresh()

Re-converts all elements in the scene and broadcasts the full update to the client.

refresh(): Promise<void>;

refreshElement()

Re-converts a single element by ID.

refreshElement(id: number, options?: IElementsOptions): Promise<void>;

refreshElements()

Re-converts a subset of elements by ID.

refreshElements(ids: number[], options?: IElementsOptions): Promise<void>;

// Modify an element in-place, then refresh it
var rect = ctrl.getElement(1);
rect.setWidth(300);
await ctrl.refreshElement(1);

---

Clearing elements

clearElements()

Removes all elements from the scene but keeps the current image.

clearElements(): void;

clear()

Removes everything — image, elements, and any pending updates. The display is returned to an empty state.

clear(): void;

---

IElementsOptions

All add and refresh methods accept an optional IElementsOptions object:

Option	Type	Default	Description
skipFullRefresh	boolean	false	When true, skips the full scene tree walk and only converts the new/updated elements

danger

Only set skipFullRefresh: true when you are certain the affected elements have no parent/child dependencies on other elements in the scene (i.e. no parentId links). If any element uses a Rect2d parent as a reference frame and you skip the tree walk, the child positions will be wrong.