Houdini 20.0 Nodes Geometry nodes

Cluster Points geometry node

Higher-level node to cluster points based on their positions (or any vector attribute).

On this page
Since 12.0


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 cluster value).

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.

Threshold attribute

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 impacttime attribute 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 (P) and impacttime, to control clustering, with a higher Weight value for impacttime to 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.

Rest Position

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


Output Attribute

The name of the attribute to set on the points. This attribute will contain the cluster number the point belongs to. The default is cluster.


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.

Cluster points

Output the input points with a cluster attribute on each point containing the cluster number the point belongs to.

Average points

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


Outputs bounding boxes for the clusters.

Color Output

Add random color (Cd) attributes to cluster of points.


Do not color the points.

Colored Particles

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.

Colored Points

Color the points by cluster.

Cluster Filter

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.

Control Attributes

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.

Control Attribute

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.

Cluster settings

Build Clusters

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.

Refinement iterations

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.

Threshold Attribute

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.

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

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.

Averaging settings

Copy point attributes from cluster

The average points representing the clusters will have the attributes of the cluster points attribute transferred 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 scale.

Padding min

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.

Padding max

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.


Animated source points Example for Cluster Points geometry node

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.

  1. Cache the impact points geometry to disk using a ROP Output driver and File node combination.

    (The example file may not cache to disk for the sake of simplicity.)

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

  3. 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 $NFRAMES variable, 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.

See also

Geometry nodes