|On this page|
This is a higher-level node that can output clustered points with a cluster attribute and optionally cluster center points. For the lower-level clustering node this node is based on, see the Cluster node.
This node creates a
cluster integer attribute on the points which indicates the cluster number the point belongs to (all points in the same cluster will have the same
This node uses the K-means clustering algorithm to group the points.
Change the Seed to change the clustering
The K-means clustering algorithm used by this node is sensitive to the randomly chosen initial cluster centers, especially when you create a small number of clusters. For example, if you have geometry divided into two parts that are far from each other, you might end up with all the points of part A in one cluster, and the points of part B divided into many clusters, just because none of the initial centers happened to be near part A.
In this case you can change the Seed parameter until you get a better clustering.
This node lets you cluster by blending multiple attributes (by increasing the Control attributes parameter). Each attribute has a Weight parameter controlling its linear contribution to the proximity measurement that controls which cluster each point goes into.
For some attributes, you may find that a linear scale is not what you want. The example that motivated the threshold feature is clustering points by impact time. For example:
You use an Impact Analysis DOP to create points where RBD objects hit the ground, in order to create dust clouds. The impact points have an
impacttimeattribute containing a time stamp of when the impact occurred.
You want to cluster the impact points to put them in separate fluid simulation boxes.
You want to sort by location (so points close to each other are in the same box), but also by impact time (so impact points that occur far apart from each other in time are in separate boxes, even if they occur at the same place).
You could use two "control attributes", position (
impacttime, to control clustering, with a higher Weight value for
impacttimeto group the points by impact time, then by position.
However, the linear nature of the Weight parameter may make it difficult to pick the right weight value to get the behavior you want, where impacts that are "close enough" in time go into the same box, but otherwise are clustered separately.
This is what the threshold feature is useful for. Instead of a linear weight, it adds a high "penalty" to the final distance calculation if the distance of a certain attribute is more than a certain amount (the threshold).
In this example, the red points represent early impacts, and the green points represent later impacts. You can see that in some places points impacts that overlap in position are sorted into different boxes based on different impact times.
Points to cluster
The input points to sort into clusters. This node will create an attribute (by default called
cluster) on each point containing the cluster number the point belongs to.
Calculate the cluster centers based on the points in this input instead of the points to cluster. This is useful for calculating the cluster centers from a decimated point cloud (for performance) or from the point positions at a different frame (using the Timeshift node).
The name of the attribute to set on the points. This attribute will contain the cluster number the point belongs to. The default is
Whether to output clustered points, cluster centers with
scale attribute, both clustered points and cluster centers in groups, or the bounding boxes of the clusters.
Output the input points with a cluster attribute on each point containing the cluster number the point belongs to.
Output the cluster centers as points. The points have a
scale vector attribute describing the bounding box of the points in the cluster.
Outputs both the clustered input points (in a group named
clusterpoints) and the cluster center points (in a group named
Outputs bounding boxes for the clusters.
Add random color (
Cd) attributes to cluster of points.
Do not color the points.
Color the points by cluster and create a particle system out of them. This option is for backwards compatibility with versions where points were only displayed when in particle systems.
Color the points by cluster.
Only outputs clusters where the cluster number matches this pattern. For example, setting this to
3 4 will only output the points in clusters 3 and 4.
The pattern can use the same pattern matching syntax as other surface nodes that let you specify point/primitive numbers. For example,
3-6 will output clusters 3, 4, 5, and 6.
The number of vector attributes to blend together to determine which points should be grouped together. The default is to use the position attribute (
P), so the node will cluster together points that are near each other.
The name of a vector attribute to use to cluster points. Points with close values of this attribute will be grouped together.
The strength of a particular vector attribute in controlling which points should be grouped together. This is a linear scale. For a more discrete grouping method, use the threshold.
If the incoming geometry already has a point attribute with the specified output name, you can skip cluster building and just use it. This allows you to take advantage of the other options for setting up cluster simulations.
The number of clusters to group the input points into.
Changing this will usually generate different groupings and cluster number assignments.
The K-means clustering algorithm starts with random cluster centers and then iterates to refine the cluster centers. Changing the initial positions can potentially change the groups.
Higher numbers give more accurate clustering but take longer to compute.
The K-means clustering algorithm starts with random cluster centers, assigns points to clusters based on their distance from the centers, then moves to centers based on the points in the cluster and repeats. This iterative process usually converges toward more accurate clusters.
Use the value of this float or integer attribute as a threshold, where points that aren’t "close enough" (within the Goal threshold) in this attribute will not be grouped together, even if they are close according to the control attribute.
The strength of the Threshold Attribute. Set this to
0 to turn off the threshold.
The initial "cutoff" value of the threshold attribute, used in the first clustering iteration. The threshold value works better if it’s high at first (so the control attribute dominates) and lowers toward the Goal threshold at each iteration. As a rule of thumb, start by setting this to 4 times the Goal threshold.
The "cutoff" value of the threshold attribute, used in the final clustering iteration. Points with values farther apart than this value will be unlikely to end up in the same cluster.
Copy point attributes from cluster
The average points representing the clusters will have the attributes of the cluster points attribute transfered onto them.
Max Sample Count
The number of nearest points to contribute to the point attribute of the center. A value of 1 will just use the closest point.
Size Attribute name
When Output is "Average points" or "Both", the node adds a vector attribute with this name to the cluster center points, describing the bounding box of the points in the cluster. The default is
Amount of padding to add to the negative X, negative Y, and negative Z sides of bounding boxes and/or the
scale attribute on cluster center points.
Amount of padding to add to the positive X, positive Y, and positive Z sides of bounding boxes and/or the
scale attribute on cluster center points.
If you cluster point source geometry with a changing number of points, the clusters and cluster numbers can change randomly at each frame and you’ll get strange results. To prevent this, you must use a couple of tricks to create the clusters based on the final number of points, and only create the clusters that are needed.
First, connect the second input of the Cluster Points node to specify a set of point positions at which the Cluster Points node should cluster the points. This is called the rest position.
For example, the Impact analysis tool creates points from RBD object collisions. The number of points in the resulting geometry increases as more RBD objects collide.
(The example file may not cache to disk for the sake of simplicity.)
Branch a Timeshift node from the File node, and connect the output of the Timeshift to the Cluster Points node’s second (rest position) input.
Set the Timeshift node’s Frame parameter to the frame you want to cluster at, usually the last frame of the effect. You can use the
$NFRAMESvariable, which always contains the number of the last frame in the scene.
Second, to create the smoke boxes only as they're needed you must turn on Continuous on the Smoke Object node. This will create a new smoke box on each instance point at every frame. To work around this so the boxes only get created at the frame where the cluster center appears, the example file uses a For Each SOP to delete every cluster center at every frame except the frame where it first appears.
See also how to make scattered points stick for how to make scattered point positions and numbers consistent across frames on deforming geometry.