instances (nodebox)

Instances: pack a geometry into a piece (instances.pack), place a piece set on target points (instances.to_points) and take a population or piece set apart (instances.unpack). A piece is one point whose Mesh holds a geometry whole, as the node that made it left it: a geometry whose elements are counted on the device (what geometry.triangulate makes) keeps its counts there, and draining the piece set (Geometry.drain) drains the geometries its records hold with it, so a CPU reader reads each piece's elements; geometry.merge with pack puts several together into a piece set. The copies instances.to_points makes are a population, which the output node draws as instanced draws, one per piece and material, and export saves as a population asset; any other points stand as one entity each. A piece keeps the material it was packed with: copies of a set of several pieces index the records detail.labels.Mesh lists, each record stating its piece's material as material and the most copies of the piece there can be as capacity, and a copy that carries a Material of its own (its target point's, or the one to_points was given) wears that instead. Each piece's draw reserves that many slots. With match on and the target points' values read where the node cooks, a piece's capacity is the number of target points holding its value, so the draws of a population of several pieces together reserve its matched copies' slots; target points the device rewrites as time moves state one per target point for every piece. Populations merged with geometry.merge stay one population: its copies draw as one instanced draw per distinct piece and material among them, the same as one to_points of all the pieces.

instances.pack, instances.to_points and instances.unpack are the nodes of that chain, with points.pose composing the instance attributes (P, orient, scale, N, v, up, pscale, rot, trans, pivot) the copies stand at. Target points merged from parts that did not all carry an instance attribute hold its identity on the points that lacked it (geometry.merge: scale and pscale 1, orient unrotated), so each part's points pose as they did alone.

instances.from_elements makes a piece set from elements: the entities io.import answers, or any points carrying parent and a pose. Every element that draws becomes a piece holding its mesh asset and material, posed through its parents, and the detail bounds is the box the pieces span. It is the inverse of instances.unpack with op "elements".

instances.cull keeps the instances a mask field or point attribute reads above a threshold (or, inverted, the rest), every attribute coming along.

Earlier nodes of the nodebox stand a source on points (instances.on_points), deal one of several sources to each point (instances.pick_random, instances.pick_by_attribute), vary and move the copies (instances.randomize_transform, instances.transform, instances.set_material) and merge them into one geometry (instances.realize). The points they make carry a Mesh and stand as entities through the output node.

instances.place, instances.variants, instances.turn and instances.sources are the parts the others are built from: a transform written onto points, a variant index written onto points, the product of two rotations, and the geometries a population stands (the ones given, else the ones its points carry).