Partition
Partition elements into indexed groups by attribute, text structure, or spatial proximity.
What it does
Partition assigns index attributes, @index, @id, @total and @u, to every shape in a collection according to how they are grouped. With Group By at None each shape gets a sequential index. With any other Group By, shapes sharing a group (the same word, the same colour, the same grid cell) receive the same index, and @u gives a normalised 0–1 position through the groups for driving colour, size, or timing per group.
Group By covers three families: attribute-based (an existing column, text structure such as Words or Lines, or a Custom attribute name typed in), bucketed (Size, or Distance from a point, into equal bands), and spatial (Spatial Grid, Row/Column, Voronoi cells from reference points, position Along a reference curve, or Proximity clustering). Hierarchical adds per-group numbering (@group_index, @local_index, @local_total, @local_u) alongside the overall index.
When to use it
Numbering, colouring, or staggering shapes by word or line in a text layout.
Bucketing shapes by size, by distance from a point, or into a grid.
Clustering nearby shapes together (Proximity), or assigning shapes to the nearest of several seed points (Voronoi).
An index or normalised position (
@u) driving another node's parameters: colour ramps, per-group offsets, staggered animation.
| Parameter | Type | Default | What it does |
|---|---|---|---|
input | Collection | — | Shapes to add index attributes to |
reference_points | Collection or Vec3[] | — | Reference points for Voronoi grouping (seed positions) |
reference_curve | Curve | — | Reference curve for Along Path grouping |
group_by | String | "None" | How to group shapes for indexing |
custom_attribute | String | "" | Attribute name to group by (e.g., @layer, @category) |
split | Boolean | false | When enabled, output becomes a list of sub-collections (one per group) instead of the annotated collection |
hierarchical | Boolean | false | Add @group_index, @local_index, @local_total, @local_u per group |
offset | Number | 0 | Offset added to final index: final = group_idx * stride + offset. Renumbers ids — does NOT reorder groups (sort the rows for that). |
stride | Number | 1 | Multiplier for index spacing: final = group_idx * stride + offset. Renumbers ids — does NOT reorder groups, so -1 will not reverse a run; sort the rows for that. |
wrap | Number | 0 | Wrap index using modulo (0 = no wrap) — folds several groups onto one id. Renumbers, does not reorder. |
size_buckets | Number | 5 | Number of equal-area buckets for Size grouping |
reference_point | Vec2 | (0, 0) | Distance reference point (X, Y) |
bands | Number | 5 | Number of equal-distance bands |
grid_columns | Number | 4 | Number of grid columns |
grid_rows | Number | 4 | Number of grid rows |
grid_detection | String | "Auto" | Auto-detect rows/columns or specify manually. One of: Auto, Manual. |
manual_columns | Number | 4 | Number of columns (Manual mode) |
cluster_radius | Number | 50 | Maximum distance between shapes to be considered in the same cluster |
min_neighbors | Number | 0 | Minimum neighbors within radius to form a cluster core. 0 = all points cluster (connected components). Higher values filter sparse outliers to noise group -1 (DBSCAN). |
strength | Number | 1 | Effect strength / wet-dry (0 = no effect, 1 = full). Editable, wirable, keyframable. |
Gotchas
The Group By dropdown also lists any groupable attribute already present on the input, prefixed with @ (for example @layer). Picking one is identical to choosing Custom and typing that name, and only dense integer, boolean, or text columns are listed. Colour and Size are always offered; presets such as Words or Lines appear only once the matching attribute is present.
Proximity clustering treats Min Neighbors as an optional density filter. At 0, every shape within Cluster Radius of another joins a cluster. Raise it and shapes with too few nearby neighbours are dropped into a separate "noise" group rather than forming their own small cluster.
Voronoi needs points wired into Reference Points, and Along Path needs a curve wired into Reference Curve. Both pins appear only after the matching Group By mode is picked.
Split is meant to turn the output into a list of sub-collections, one per group, instead of the single annotated collection. That behaviour is not wired up yet: turning Split on returns the same annotated collection, without the index-shaping controls (Offset, Stride, Wrap), which apply only to the non-split output.
Worked example
Add a Partition and wire in a collection of shapes (or a Text node's output).
Set Group By to Words (or Lines) to index shapes per word instead of per character.
Read @u (the Normalized output) into a Colour node's ramp position, so each word gets a distinct colour across the group.
Turn on Hierarchical for per-group local numbering alongside the overall index.
See also
Sort · Separate · Color Map · Attributes