|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.