---
title: Cumulus User Guide
description: Cumulus turns one or more depth-camera point clouds into stable people clusters with persistent IDs.
---

This guide describes `Cumulus`, a TouchDesigner `.tox` component for turning one or more depth-camera point clouds into stable, person-sized clusters with persistent cluster IDs.

## General Purpose

Cumulus is meant for interactive installations, stage systems, spatial interfaces, and other TouchDesigner projects that need reliable real-time people positions from depth cameras. It combines source setup, camera alignment, scene cropping, masking, point-cloud cleanup, clustering, ID persistence, experimental skeleton association, recording/playback, smoothing, simulation, and reusable presets in one component.

The component outputs cluster centroids, bounds, velocity, optional head positions, associated skeleton joint tables, a prepared point-cloud view with per-point source and cluster ID attributes, and diagnostic info channels. Downstream networks can use these outputs for visuals, interaction zones, motion logic, analytics, or debugging.

## Native Plugin Note

The Windows `.tox` embeds native TouchDesigner C++ CHOP plugins, including `Clustering.dll`, so the component can run without a separate plugin folder. TouchDesigner loads these DLLs when the component opens. Antivirus and IT security tools may scan or block native DLL loading at that time even if the `.tox` file itself scans clean.


## Main Features

| Feature | What it provides |
| --- | --- |
| Multi-source depth input | Use several Kinect or Orbbec-style point-cloud sources and align them into one shared space. |
| Per-source calibration controls | Adjust translation, rotation, scale, pivot, color, active state, binning, and time delay per source. |
| Global scene controls | Crop the overall capture volume and switch between setup/calibration views. |
| Mask volumes | Add repeated include/exclude mask blocks, including optional POP geometry masks, for precise cleanup after the broad scene crop. |
| Point-cloud cleanup | Reduce density and remove local noise before clustering. |
| Real-time clustering | Convert raw XYZ points into person-sized cluster slots with centroid, velocity, bounds, head, and OBB data. |
| Persistent cluster IDs | Keep cluster IDs stable through motion, short occlusions, validation delays, and ghost hold time. |
| Body tracking input (experimental) | Use body-tracking CHOP data as a skeleton/joint signal alongside point-cloud clustering (Orbbec only). |
| Body tracking output (experimental) | Output body-tracking joints associated with cluster IDs (Orbbec only). |
| Recording/playback | Record and replay point-cloud plus skeleton input streams for testing and debugging. |
| 1 Euro smoothing | Smooth centroid, bounds, velocity, head outputs, and skeletons with separate response controls. |
| Simulator | Test behavior without live depth cameras using synthetic moving bodies. |
| Config/save system | Save and load reusable component settings as JSON files. |
| Diagnostics | Monitor status, cook time, point counts, cluster counts, and dropped-cluster metrics. |

## Basic Workflow

1. Add one or more depth point-cloud sources on the `Sources` page. Kinect and Orbbec sources are currently supported.
2. Use experimental Plane Calibration as a helper to snap sources to visible room planes, then fine tune per-source transforms manually.
3. Set the scene size and masks so only the capture volume remains.
4. Tune point-cloud cleanup, clustering, and cluster ID assignment until one person creates one stable slot.
5. Save settings from the `Presets` page.

## Guide Pages

| Page | Use it for |
| --- | --- |
| [Outputs](/outputs) | Slot conventions, connector outputs, `CHOP_clustering` channels, info channels, and status codes. |
| [Parameters](/parameters) | Core source, scene, mask, clustering, tracking, filtering, output, camera, setup, and about controls. |
| [Calibration Parameters](/calibration-parameters) | Camera source setup, source transforms, scene crop, masks, and multi-camera Ethernet setup. |
| [Plane Calibration (Experimental)](/plane-calibration) | Plane-only helper workflow for aligning sources to visible room walls/floor before manual fine tuning. |
| [Body Tracking (Experimental)](/bodytracking-parameters) | Body-tracking setup, skeleton input, skeleton split, human output behavior, and skeleton smoothing. |
| [Save And Load Settings](/presets-save-system-parameters) | Save/load controls, config files, and what is preserved. |
| [Simulator Parameters](/simulator-parameters) | Synthetic point-cloud controls for testing without cameras. |
| [Recorder Parameters](/recorder-parameters) | Recording and playback controls for repeatable tuning/debugging. |
| [Tuning](/tuning) | Practical setup, clustering, ID stability, and 1 Euro filtering guidance. |