> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/spatial-interactive-experiences/building-an-interactive-tracking-project/configure-clustering.md).

# Configure Clustering

After the tracking area has been defined and the point cloud has been cleaned, the next step is to turn the remaining measurements into detected objects or interactions.

Clustering groups spatially related points into larger tracked elements.

Depending on the application, these may represent things such as:

* People
* Objects
* Hands
* Touch interactions

The appropriate clustering method depends primarily on **what the project should detect**, not on whether the contributing sensors are 2D or 3D.

***

## Add a Clustering Method

Clustering is configured directly in the Point Cloud Volume.

To add a clustering method:

1. Select the **Point Cloud Volume** in the Project Tree.
2. Open **Pipeline** in the Inspector.
3. Locate **Clustering**.
4. Click the **+** button.
5. Select the clustering method appropriate for the application.

<figure><img src="/files/3SOoko15P5t7o5nP5rQt" alt=""><figcaption></figcaption></figure>

The available clustering methods are designed for different types of spatial detection.

The individual methods and their parameters are covered in detail in the **Clustering** reference.

***

## Choose the Method Based on the Application

Do not choose a clustering method simply because the project uses a particular type of sensor.

Once the sensors have been aligned and combined inside the Point Cloud Volume, their measurements exist in the same spatial environment.

For example, a people-tracking Point Cloud Volume may contain:

* 3D LiDAR data
* 2D LiDAR data
* or a combination of both

A suitable 3D clustering method can process all of these measurements together.

A touch installation, on the other hand, requires a clustering method designed around much smaller interactions and a different spatial setup.

The important question is:

**What should the resulting clusters represent?**

{% hint style="info" %}
A Point Cloud Volume should generally be designed around one analysis or detection goal.

Although multiple clustering methods can be added, there is usually little benefit in running several different clustering systems within the same Point Cloud Volume.
{% endhint %}

***

## Inspect the Detected Clusters

Once a clustering method has been added, Grid Studio immediately processes the current point cloud.

If the configured clustering method finds valid groups of points, the detected clusters become visible directly in the **Viewport**, typically as Bounding Boxes around the detected objects.

For tuning and debugging, the cluster display can expose additional information.

Useful visualization options include:

* **Random cluster colors** — display individual cluster Bounding Boxes using different colors.
* **Cluster IDs** — show the ID currently assigned to each detected cluster.
* **Trace** — visualize the recent movement path of a cluster.

<figure><img src="/files/3EgvncxmmV1obHLxSdrK" alt=""><figcaption></figcaption></figure>

These options are particularly useful when evaluating the stability of the clustering and ID assignment.

For example, random colors and visible IDs make it much easier to recognize when a tracked object unexpectedly changes from one cluster to another or receives a new ID.

The Trace visualization can help identify:

* Sudden position jumps
* Unstable cluster centers
* Incorrect associations between frames
* Tracking behavior during movement and temporary occlusion

{% hint style="success" %}
When tuning clustering, enable cluster IDs and use clearly distinguishable cluster colors. This makes ID changes and unexpected cluster jumps much easier to recognize than by looking at the Bounding Boxes alone.
{% endhint %}

Walk through the tracking area or move suitable objects through the sensor coverage and observe how the clusters behave over time, not only whether a Bounding Box is created.

{% hint style="info" %}
You can further customize the appearance of cluster IDs in the Viewport.

Open the **Project Settings** and go to **3D Widget** to adjust properties such as the **Label Color** and **Label Size**.

This can make cluster IDs easier to read when tuning or debugging the tracking result.
{% endhint %}

<figure><img src="/files/Es6Jd1aV3WdLvPWqPd1a" alt=""><figcaption></figcaption></figure>

***

## Tune the Detection

The clustering parameters determine which groups of points are considered valid detections.

The exact controls depend on the selected clustering method, but the general tuning process should remain the same:

1. Start with a clean point cloud.
2. Add the clustering method.
3. Observe the resulting clusters in the Viewport.
4. Adjust one parameter at a time.
5. Test with realistic objects or people inside the tracking area.
6. Verify the result across different parts of the sensor coverage.

Do not tune clustering only around one position close to a sensor.

<figure><img src="/files/5VNOnYuXtoytxtDhFpk7" alt=""><figcaption></figcaption></figure>

Point density can change significantly across the tracking area depending on sensor distance, viewing angle, overlap, and occlusion.

The clustering configuration should work reliably throughout the area that matters for the installation.

***

## Understand the Result

The clustering stage turns groups of point measurements into spatial objects.

Depending on the selected method and configuration, a cluster can provide information such as:

* Position
* Bounding Box
* ID

These clusters form the basis for later processing and interaction.

For example, they can be used by:

* **Presence Zones**
* Map Outputs
* Local Volume Objects
* Cluster Count
* External tracking-data outputs

{% hint style="info" %}
A **Trigger Zone** does not require clustering because it reacts directly to points in the point cloud.

A **Presence Zone**, on the other hand, operates on the resulting clusters and therefore requires a working clustering pipeline.
{% endhint %}

***

## Do Not Compensate for Bad Point Data with Clustering

If clustering behaves poorly, first inspect the point cloud itself.

Common causes of unstable clustering include:

* Permanent geometry remaining inside the tracking area
* Excessive floor measurements
* Isolated sensor noise
* Missing sensor coverage
* Incorrect sensor alignment
* Overly aggressive point filtering

It is usually better to correct problems earlier in the pipeline than to compensate for them with increasingly extreme clustering parameters.

A good clustering result starts with useful and consistent point data.

***

## Verify the Clustering

Before continuing, test the clustering under realistic conditions.

Verify that:

* Intended objects create clusters reliably.
* One object does not unnecessarily split into several clusters.
* Separate objects do not merge unexpectedly.
* Detection works across the useful tracking area.
* Temporary occlusion does not immediately make the result unusable.
* Bounding Boxes and positions correspond reasonably to the physical objects.

At this stage, the raw clustering result does not necessarily need to be perfectly smooth or stable over time.

Additional processing can be applied after clustering to improve the tracked result.

Continue with **Refine the Tracked Clusters**.