elements.link (procNode)

Parent elements under other elements: make parts of a graph the children of other parts, building the hierarchy of entities the graph exports. The elements from picks receive the link and the elements to picks are linked to: each of them a group of that name, else the elements whose by attribute holds that name (by "name" picks hand-placed elements by name; from takes a list). Two groups are joined on the key attribute by: a receiving element links to the target holding the same value of it, however many elements there are. Without by, every receiving element links to the first target. field "parent", the default, writes the target's id as the element's parent, which a hierarchy of entities is made of: io.export writes each element as an entity under the entity of its parent in the bundle or scene it saves. Component.field writes the target's id into that field of the element's component instead, adding the component to an element that holds none. The parent column is marked as holding point ids, so a join of geometries keeps the links.

The match runs on the CPU over the key columns once. A name that is neither a group nor a value of the by attribute (name when by is empty) is refused, naming it; points without an id are refused.

Inputs

• geometry (Geometry). The elements, as points carrying an id and the attributes from, to and by name.
• from (String | List<String>). Default "". The elements that receive the link: a group, a name or a list of names. Empty picks every element.
• to (String). Default "". The elements linked to: a group, or a name. Empty picks every element; the first picked element is the target unless by joins two groups.
• by (String). Default "". The key attribute. Between two groups, a receiving element links to the target that holds the same value of it. Selecting by values, the attribute the names are looked up in; empty means name.
• field (String). Default "parent". What the target's id is written into: "parent", or Component.field (the form core.entity.read takes) for a field of a component.
• unsupported (one of refuse, report). Default "refuse". What happens to a receiving element whose key no target holds: refuse, naming the count and the first key, or leave it unlinked and list it in report.

Outputs

• geometry: the elements with the link written: parent (the target's id, -1 for an element that receives none and held none before) or the component column named by field.
• report: a list with one row { attribute, count, value } when receiving elements found no target under unsupported = "report", and empty otherwise.

Example

local rig = g.elements.entity({ name = "Rig" })
local arm = g.elements.entity({ name = "Arm", P = vector.create(1, 0, 0) })
local both = g.core.concat({ geometries = { rig, arm } })
local linked = g.elements.link({ geometry = both, from = "Arm", to = "Rig" })

linked.geometry holds parent -1 on the rig and 0, the rig's id, on the arm. With field = "Wire.to" the arm carries Wire = { to = 0 } instead.