> 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/test-and-tune-the-project.md). # Test and Tune the Project Once the complete tracking pipeline is working, the final step is to validate it under realistic conditions and tune the individual processing stages. A spatial tracking system should not only work in one position or with one person standing close to a sensor. It should behave reliably throughout the complete installation and under the conditions expected during operation. When tuning the project, work through the processing pipeline in order. A useful troubleshooting sequence is: **Alignment → Tracking Area → Input Filters → Clustering → Cluster Tracking → Cluster Filters → Zones / Local Volumes → Outputs** Problems that originate early in the pipeline should be corrected there instead of being compensated for by later processing stages. *** ## Test Under Real Conditions Test the tracking system using movement and situations that reflect the final installation. Depending on the application, this can include: * Walking through the complete tracking area * Moving through transitions between sensor coverage * Standing close to and far away from sensors * Moving quickly and slowly * Remaining stationary * Several people or objects entering the space at the same time * Temporary occlusion between tracked objects * Movement close to the boundaries of the tracking area * Entering and leaving Zones repeatedly Do not tune the system only around one convenient position. Point density, visibility, and sensor overlap can change significantly throughout the environment. *** ## Verify Sensor Alignment If tracking behaves differently in different parts of the environment, check the sensor alignment first. Display the point clouds of overlapping sensors simultaneously and use different colors so that their measurements are easy to distinguish. Inspect recognizable static structures such as: * Long walls * Floors * Ceilings * Pillars * Corners * Large permanent objects The point clouds do not need to overlap perfectly point by point, but the same physical structures should maintain a consistent spatial relationship. {% hint style="warning" %} Do not compensate for incorrect sensor alignment with filters or clustering parameters. If two sensors disagree about the position of the physical environment, correct the alignment first. {% endhint %} *** ## Refine the Tracking Area Real-world testing often reveals permanent geometry that was not obvious during the initial setup. Inspect the live point cloud and adjust the Include and Exclude geometry where necessary. Typical corrections can include: * Removing another section of a wall * Adding an Exclude around a pillar * Removing a platform or piece of furniture * Extending an Include into a useful area * Reducing an Include where unnecessary measurements remain Keep the VBO Snapshots available as a reference when modifying the tracking geometry. Whenever possible, remove predictable static geometry spatially before relying on stronger filtering. *** ## Tune the Input Filters Once the tracking area is correct, inspect the result of the Input Filter chain. Work through the filters from top to bottom. For each filter: 1. Change one parameter. 2. Observe the live point cloud. 3. Test with real people or objects. 4. Verify that unwanted measurements are removed. 5. Verify that useful measurements remain. {% hint style="warning" %} Input Filters can have a significant performance cost. Depending on the filter, Grid Studio may need to evaluate and compare millions of points every frame. Aggressive settings or unnecessarily long filter chains can therefore increase processing time and eventually affect real-time performance. Only use a filter when it produces a measurable improvement in the final tracking result. If enabling or disabling a filter makes no meaningful difference to the point cloud or clustering result, remove it from the pipeline. The goal is not to use as many filters as possible, but to use the smallest amount of processing required to produce reliable clusters. {% endhint %} For example, when tuning a Radius Outlier filter, check that isolated noise disappears without removing valid measurements from: * Feet * Hands * Objects far away from the sensors * Areas with lower point density {% hint style="success" %} Use the smallest amount of filtering required to solve the visible problem. A short and understandable filter chain is usually easier to maintain than a large number of aggressive filters. {% endhint %} *** ## Evaluate the Clustering Once the point cloud itself looks reliable, evaluate the clustering behavior. Enable the cluster visualization tools that help identify instability: * Bounding Boxes * Random cluster colors * Cluster IDs * Trace These visualizations make it easier to see not only whether an object is detected, but how that detection behaves over time. Test situations such as: * One person walking through the complete area * Two people walking close together * People crossing each other * Temporary occlusion * Movement through overlapping sensor coverage * A person standing still * A person entering and leaving the tracking area Look for problems such as: * One object splitting into several clusters * Several objects merging into one cluster * Sudden position jumps * Bounding Boxes changing unexpectedly * Clusters disappearing in specific areas If the clustering behaves poorly, verify the point cloud again before making the clustering increasingly permissive. *** ## Tune Cluster Tracking Once the clustering itself is reliable, observe how IDs behave over time. Cluster Tracking controls the association between successive clustering results. Pay particular attention to: * **Distance Tolerance** * **Id Lifetime** * **Max Id** Test whether IDs remain stable when an object: * Moves quickly * Temporarily disappears * Passes behind another object * Leaves and re-enters sensor coverage * Moves close to another tracked object Increase **Distance Tolerance** only as much as necessary to handle realistic movement and cluster-position changes. Use **Id Lifetime** to allow short interruptions without immediately losing an object's identity. Avoid values that are so permissive that an existing ID can easily be assigned to the wrong nearby object. {% hint style="info" %} Cluster Tracking affects ID association only. If the actual cluster position or Bounding Box is unstable, correct the clustering or use Cluster Filters instead. {% endhint %} *** ## Tune the Cluster Filters Cluster Filters should be tuned only after the underlying clustering result is reliable. Filters such as prediction and smoothing can improve: * Position jitter * Short interruptions * Movement continuity * Overall stability of the tracked result They should not be used to hide fundamental errors in the input data or clustering. When adjusting Cluster Filters, use the cluster Trace together with the physical movement of the tracked object. Compare: **Actual movement → Raw cluster behavior → Filtered cluster behavior** Too little smoothing may leave visible jitter. Too much smoothing can make the tracked result feel delayed or disconnected from the real movement. Prediction should similarly be tuned to improve movement continuity without causing the tracked position to overshoot or behave unrealistically. *** ## Test Trigger Zones and Presence Zones Test every Zone under realistic interaction conditions. ### Trigger Zones Because Trigger Zones operate directly on point-cloud points, test: * Entering with only part of the body or object * Movement close to the boundary * Point-count fluctuations * Remaining inside the Zone * Repeated entry and exit Adjust: * Enter Threshold * Exit Threshold * Smoothing * Advanced timing where required ### Presence Zones Because Presence Zones operate on clusters, also test: * Multiple tracked objects inside the Zone * Individual objects entering and leaving * Temporary cluster loss * ID changes * Movement close to the Zone boundary Observe the available Workflow Events: * **Occupied** * **Empty** * **Object Entered** * **Object Left** For both Zone types, the goal is reliable state changes without unnecessary flickering or excessive delay. *** ## Verify Cluster Counts Use the read-only **Cluster Count** parameters as a simple diagnostic. The Point Cloud Volume reports the number of final clusters in the complete tracking pipeline. Local Volume Objects report the number of clusters currently remaining inside their local area. Compare these values with the actual physical situation. For example: **People physically inside the room:** `8`\ **Point Cloud Volume Cluster Count:** `8` **People physically on the LED floor:** `3`\ **Local Volume Cluster Count:** `3` Unexpected counts are often an easy indication that an earlier processing stage needs attention. *** ## Test Local Tracking Areas For each local Volume, verify both the spatial selection and its coordinate output. Check that: * Only clusters inside the intended area remain * Entering and leaving the Volume changes the local Cluster Count correctly * Moving the Volume does not move the incoming global tracking data * Position and Rotation in the Volume Map Input are set to **Global** * Relative coordinates use the expected local reference * UV coordinates match the physical orientation of the Volume For UV output, test several known positions across the physical surface. For example, move through the corners and center of an LED floor and verify that the normalized output behaves as expected. If the UV orientation is incorrect, adjust the orientation of the Volume Object itself. *** ## Verify External Tracking Data Do not only verify that a protocol connection is active. Observe the outgoing tracking values while moving objects through the environment. Check: * Position * Scale * ID or Index * Object creation and removal * Coordinate space The values seen by the receiving system should correspond to the final clusters visible inside Grid Studio. If the outgoing position jumps, verify whether the same jump is already visible in the Grid Studio cluster. The Map Output reflects the tracking result; it does not stabilize the data itself. *** ## Verify Depth Images Keep the Grid Studio Image Rendering Viewer and the external receiving system visible while testing. Move people or objects throughout the projected area and inspect: * Camera framing * Near Clipping * Far Clipping * Point Size * Erode / Dilate * Smooth * Image boundaries * Areas at different distances from the Camera Test the image under the same movement and occupancy conditions expected during operation. The best-looking image is not necessarily the most useful image. Tune the rendering for the information required by the external processing system. *** ## Change One Thing at a Time {% hint style="success" %} When tuning or troubleshooting, change **one thing at a time**. Modify a parameter, test the result, and only then continue to the next change. Changing several filters, clustering parameters, or alignment values simultaneously makes it difficult to identify which change actually improved or degraded the system. {% endhint %} This is particularly important in spatial tracking projects because each processing stage affects everything that follows. *** ## Follow the Processing Order When a problem appears at the end of the pipeline, trace it back through the processing stages instead of immediately modifying the final output. Use this order: 1. **Sensor Alignment** 2. **Tracking Area** 3. **Input Filters** 4. **Clustering** 5. **Cluster Tracking** 6. **Cluster Filters** 7. **Trigger Zones / Presence Zones** 8. **Local Volumes** 9. **Tracking Outputs** 10. **Image Outputs** For example: If an OSC position jumps, first check whether the cluster jumps in the Viewport. If the cluster jumps, inspect the clustering. If the clustering suddenly changes, inspect the point cloud. If the point cloud contains inconsistent overlapping surfaces, inspect the sensor alignment. Fix the earliest stage where the problem becomes visible. *** ## Final Validation Before considering the spatial tracking setup complete, test the installation for an extended period under realistic operating conditions. Verify that: * Sensor connections remain stable * Sensor alignment remains correct * The complete useful tracking area is covered * Permanent environment geometry does not create false detections * Input Filters preserve useful measurements * Clustering remains reliable across the environment * IDs behave consistently * Cluster Filters provide the expected stability * Trigger Zones and Presence Zones react correctly * Cluster Counts remain plausible * Local Volumes select the correct tracked objects * External position outputs remain consistent * Depth images remain useful throughout the intended area The project is now ready to be integrated into the final interactive experience. For detailed information about individual filters, clustering methods, Zones, and other processing components, continue with the corresponding **Reference** documentation.