> 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/applications/people-and-object-tracking.md). # People & Object Tracking People and object tracking is one of the most common applications for spatial sensing in Grid Studio. Unlike a small, well-defined interaction surface, a people-tracking system usually needs to remain reliable across a larger environment, different sensor distances, changing point densities, occlusion, and multiple moving objects. This page focuses on the design decisions that are specific to people and object tracking. For the step-by-step setup of sensors, Point Cloud Volumes, filters, and clustering, see **Building an Interactive Tracking Project**. *** ### What Makes People Tracking Different A reliable people-tracking system needs to do more than simply create a cluster when someone enters the point cloud. A useful tracking result should ideally maintain several properties at the same time: * One person should normally produce one cluster. * Two nearby people should remain separate clusters. * A person should remain detectable while moving through the complete tracking area. * Short periods of occlusion or incomplete sensor data should not immediately destroy the tracked identity. * Position data should remain stable enough for the intended interaction. * The system should continue to work as point density changes across the environment. These requirements can compete with each other. A configuration that produces extremely stable clusters may feel less responsive. A configuration that reacts very quickly may produce more position jitter or ID changes. The correct balance depends on what the tracking data will ultimately be used for. *** ### Design Sensor Coverage, Not Just Sensor Range The maximum measurement distance of a sensor does not automatically define the useful tracking range. A sensor may technically return measurements from a large distance while providing too few useful points at that distance for reliable clustering. When planning sensor placement, consider: * Point density across the tracking area * Sensor distance * Viewing angle * Physical obstacles * Expected number of people * Areas where people can occlude each other * Important interaction areas * Transitions between sensor coverage The goal is not simply to make every part of the room visible. The goal is to provide enough useful spatial information wherever reliable tracking is required. {% hint style="info" %} Always evaluate sensor coverage based on the final tracking result rather than the nominal range of the sensor. {% endhint %} *** ### Use Multiple Sensors to Reduce Occlusion One of the main advantages of a multi-sensor installation is the ability to observe the same physical area from different directions. If one person stands behind another from the perspective of a single sensor, part of the second person may become invisible. A sensor observing the same area from another direction can provide measurements that are missing from the first view. Additional sensors can therefore improve: * Coverage * Point density * Detection during occlusion * Transitions across large environments * Reliability in crowded areas However, more sensors are not automatically better. Every additional sensor also adds point data that needs to be processed. Poorly aligned overlapping sensors can even make the resulting point cloud harder to cluster. Use additional sensors where they solve an actual coverage or occlusion problem. *** ### Plan Overlap Where It Matters Not every part of an installation needs the same amount of sensor overlap. Prioritize overlap in areas where tracking reliability is particularly important, such as: * Main interaction areas * Entrances and exits * Areas with many people * Transitions between sensor coverage * Locations where architecture creates significant occlusion Less important or rarely occupied parts of the environment may not require the same level of redundancy. This can reduce unnecessary point processing while keeping the important parts of the installation robust. *** ### Combine Different Sensor Types When Useful A people-tracking Point Cloud Volume does not need to contain only one type of sensor. Once aligned, measurements from 2D and 3D sensors exist in the same project coordinate system and can contribute to the same clustering result. A 2D LiDAR can therefore be used as an additional scan layer in an environment that is otherwise covered by 3D sensors. This can be useful when a specific height or part of the tracking area benefits from additional measurement density. The decision should be based on the missing spatial information, not on keeping the sensor technologies separated. *** ### Track Only the Space That Matters Large sensor coverage does not mean the complete measured environment needs to participate in people tracking. Areas where people cannot or should not be detected can usually be removed before clustering. Examples include: * Space behind walls or scenery * Areas behind barriers * Technical spaces * Furniture or permanent structures * Parts of the venue that are irrelevant to the experience Reducing the active tracking area has several benefits: * Fewer irrelevant points * Fewer false clusters * Less processing * Easier clustering configuration * Easier debugging A smaller, well-defined tracking area is usually preferable to processing everything the sensors can see. *** ### Tune for the Complete Tracking Area Point density is rarely uniform throughout a large installation. A clustering configuration that works perfectly close to a sensor may fail at the opposite end of the room. When tuning people tracking, test deliberately in difficult areas: * Maximum useful sensor distance * Areas with lower point density * Sensor transition zones * Locations with strong occlusion * Areas seen from difficult angles Do not optimize the system only around the easiest position. {% hint style="success" %} A useful configuration should be designed around the most difficult part of the tracking area that still needs to work reliably. {% endhint %} *** ### Evaluate the Behavior of a Person, Not Just the Bounding Box A Bounding Box appearing around a person is only the first indication that clustering works. Observe what happens while the person moves. Useful tests include: * Standing still * Walking slowly * Moving quickly * Turning around * Changing body pose * Moving close to another person * Crossing another person's path * Entering overlapping sensor coverage * Being temporarily occluded Use the Viewport diagnostics while testing: * Random cluster colors * Cluster IDs * Trace * Bounding Boxes A reliable configuration should avoid unnecessary splitting, merging, jumping, and ID changes. *** ### Balance Position Stability and Identity Different applications place different importance on position and identity. For an interactive LED floor, the most important information may be: **Where is the person right now?** Long-term identity may be less important. For another experience, the system may need to know: **Is this still the same tracked person?** In that case, stable IDs become much more important. This affects how parameters such as the following should be tuned: * Distance Tolerance * Id Lifetime * Prediction * Smoothing A more permissive ID configuration may survive short occlusions better, but can also increase the chance of assigning an existing ID to the wrong nearby person. More smoothing can provide stable positions, but also introduces a less immediate response. Tune these systems according to the requirements of the application rather than maximizing every form of stability. *** ### Crowded Areas Need Different Attention Crowded spaces create additional challenges. People may: * Occlude each other * Walk very close together * Temporarily merge into similar point groups * Cross paths * Produce rapidly changing visible surfaces In these areas, sensor placement can be as important as clustering configuration. Observing the crowd from several useful directions often provides more benefit than attempting to solve every problem through increasingly permissive cluster settings. If people consistently merge or disappear in one physical area, investigate sensor visibility and point density before changing the clustering significantly. *** ### Track Once, Use the Result Many Times A reliable global people-tracking result can be reused throughout the project. For example, the same final clusters can drive: * Presence Zones * Occupancy logic * Global tracking output * Local Volume Objects * LED floor interactions * Projection areas * Relative coordinate outputs * UV coordinate outputs There is usually no reason to create another complete people-tracking pipeline simply because one part of the installation requires a different output. A useful architectural principle is: **Track globally once, then create local views of the result where required.** For example: **Global People Tracking → Final Clusters → Local Volume → LED Floor UV Output** and at the same time: **Global People Tracking → Presence Zone → Workflow Logic** and: **Global People Tracking → Cluster Map Output → External Tracking System** All of these can use the same final tracked objects. *** ### Typical Architectures #### Small Interactive Room A small room may only require a few sensors and one shared tracking result: **Spatial Sensors → Point Cloud Volume → People Clustering → Presence Zones / Tracking Output** The main focus is usually good coverage and straightforward cluster stability. #### Large Venue A larger environment may use several overlapping sensors: **Multiple Spatial Sensors → Global Point Cloud Volume → People Clustering → Cluster Tracking → Cluster Filters** The final result can then feed multiple local Volumes and external systems. The primary challenges become sensor alignment, transitions between coverage, occlusion, and performance. #### High-Occupancy Area Crowded installations benefit from sensor coverage from several directions. The focus should be on: **Useful overlap → reliable separation → stable IDs → controlled smoothing and prediction** Strong sensor geometry usually provides a better foundation than trying to compensate for poor visibility with cluster settings alone. *** ### Common Failure Patterns #### One Person Splits into Multiple Clusters Check: * Point density * Missing sensor coverage * Input Filters * Clustering configuration * Occlusion of different parts of the person #### Several People Merge into One Cluster Check: * Whether the clustering is too permissive * Whether the people can actually be spatially separated by the sensors * Sensor placement and viewing directions * Point density in the affected area #### IDs Change When People Cross Check: * Cluster Tracking * Distance Tolerance * Id Lifetime * Whether the underlying clusters remain separated during the crossing An ID configuration cannot reliably preserve two identities if the clustering itself has temporarily merged both people into one object. #### Tracking Works Close to a Sensor but Fails Further Away The configuration may have been tuned for high point density. Test the clustering and Input Filters in the lower-density part of the tracking area. Additional sensor coverage may also be required. #### Tracking Jumps Between Sensors Check the sensor alignment first. Misaligned overlapping point clouds can cause the apparent center or shape of a person to change as different sensors contribute more or fewer measurements. #### False Clusters Appear Near Permanent Geometry Check: * Include and Exclude geometry * Occluders * Remaining floor measurements * Background or point-cleanup filters Removing the unwanted environmental data is usually preferable to trying to reject the resulting false clusters later. *** ### Design for the Final Experience There is no single ideal people-tracking configuration. A tracking system for reactive lighting may prioritize low latency and position responsiveness. A system that associates persistent content with individual visitors may prioritize stable IDs. A crowded event space may prioritize separation and occlusion resistance. A large interactive environment may prioritize consistent behavior across many sensor transitions. Start with the requirements of the experience, then design sensor coverage, clustering, ID behavior, and output around those requirements. For the practical setup process, see **Building an Interactive Tracking Project**. For detailed configuration of individual clustering methods, Cluster Tracking, and Cluster Filters, see the corresponding **Reference** documentation.