> 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/touch-designer-integration/point-cloud-interaction/data-chop.md).

# Data CHOP

Access point, tracking, and camera data as CHOP channels, with object   selection, timeout handling, and receiver diagnostics.

The SPNet Data CHOP receives SPNet data and exposes numeric values as channels for parameter control and instancing.

It supports point clouds, tracking objects, and cameras. The selected Data Type determines which channels are available.

The operator receives data directly over the network and requires no wired input.

### Data page

| Parameter   | Default       | Description                                                                              |
| ----------- | ------------- | ---------------------------------------------------------------------------------------- |
| Data Type   | `Points`      | Selects the object family and its output channels.                                       |
| Output Mode | `All Objects` | Outputs all selected objects, a single object, or receiver diagnostics.                  |
| Object Type | `Any`         | Selects an object type in Single Object mode.                                            |
| Object ID   | `1`           | Integer ID of the object to select in Single Object mode.                                |
| Timeout ms  | `1000`        | Expires data after this duration without received packets. Set to `0` to disable expiry. |

#### Data Type

| Option   | Included data                                                                            |
| -------- | ---------------------------------------------------------------------------------------- |
| Points   | Points received through SPNet Point Data, including position, size, and color.           |
| Tracking | Tracking objects such as Movables, Rigid Bodies, and Tracked Points.                     |
| Cameras  | Camera and Extended Camera objects, using the common camera channel set described below. |
| All      | Combines all supported object families and their channels.                               |

Use a specific Data Type to keep the output focused on the values your network needs.

All provides the combined channel set. Fields unavailable for a particular object use fallback values.

#### Output Mode

**All Objects**

Outputs one sample per object.

For example, three incoming points produce three samples in each channel:

* Sample 0 contains the first point's values.
* Sample 1 contains the second point's values.
* Sample 2 contains the third point's values.

These samples represent objects at the current moment.

Objects are identified by their type and ID. Duplicate entries with the same type and ID produce one output sample.

The output is sorted by object type code and ID. Sample indices can change when objects appear or disappear.

{% hint style="info" %}
Use the transmitted type and ID when retaining state for an object across updates.
{% endhint %}

**Single Object**

Outputs one object selected using Object ID and, where applicable, Object Type.

For example, to receive Movable ID `1`:

| Parameter   | Value           |
| ----------- | --------------- |
| Data Type   | `Tracking`      |
| Output Mode | `Single Object` |
| Object Type | `Movable`       |
| Object ID   | `1`             |

This mode is useful for controlling one Geometry COMP or another individual target.

**Diagnostics**

Outputs receiver status, counters, rates, and timing information.

Object properties are replaced by diagnostic channels. Object Type and Object ID are not used in this mode.

#### Object Type

Available options are:

* Any
* Point
* Tracked Point
* Rotation
* Movable
* Rigid Body
* Camera
* Extended Camera
* Other Tracking

Object Type is available in Single Object mode when Data Type is Tracking, Cameras, or All.

With Data Type set to Points, the operator selects point IDs directly and disables Object Type.

With Any selected, the numeric ID must identify one object within the selected data family. If multiple object types share that ID, choose the type explicitly.

#### Object ID

Enter the object's integer ID.

| Object family        | ID range            |
| -------------------- | ------------------- |
| Points               | `0` to `4294967295` |
| Tracking and cameras | 0 to `32767`        |

Object ID is available only in Single Object mode.

If no matching object is present, the CHOP outputs an inactive placeholder.

#### Timeout ms

Defines when data expires based on the time since the shared receiver last received a packet.

| Value  | Behavior                                    |
| ------ | ------------------------------------------- |
| `1000` | Expires after one second without packets.   |
| `5000` | Expires after five seconds without packets. |
| `0`    | Disables expiry based on packet age.        |

The supported range is `0` to `60000` milliseconds.

{% hint style="info" %}
Timeout does not delay incoming data. It determines when previously received data is considered stale.
{% endhint %}

### Connection page

| Parameter         | Default        | Description                                                                                                             |
| ----------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Port              | `37373`        | UDP destination port used by the sender.                                                                                |
| Bind Address      | `0.0.0.0`      | Local address to listen on. The default listens on all local interfaces.                                                |
| Multicast Group   | `237.37.37.37` | Multicast group to join. Leave empty for a unicast-only connection.                                                     |
| Interface Address | `0.0.0.0`      | Local network adapter address used for multicast reception. The default uses the operating system's selected interface. |

For multicast, configure the sender and receiver with the same group and port.

For unicast, configure the sender to target the TouchDesigner computer's IPv4 address and clear Multicast Group.

Interface Address refers to an address on the receiving computer.

SPNet operators with identical Connection settings share one native receiver.

### Output channels

#### Common channels

These channels are available for every Data Type in All Objects and Single Object modes.

| Channels         | Description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| `id`             | Object ID.                                                             |
| `type`           | Numeric SPNet object type code.                                        |
| `active`         | `1` for a currently available object; `0` for an inactive placeholder. |
| `id_hi`, `id_lo` | Upper and lower 16-bit portions of the ID.                             |
| `tx`, `ty`, `tz` | Position in meters, converted to TouchDesigner coordinates.            |
| `rx`, `ry`, `rz` | Rotation in TouchDesigner XYZ Euler degrees.                           |

#### Points

Additional channels:

| Channels           | Description                     |
| ------------------ | ------------------------------- |
| `sx`, `sy`, `sz`   | XYZ point dimensions in meters. |
| `r`, `g`, `b`, `a` | RGBA point color.               |

For instancing, a base object measuring one unit across an axis becomes one meter across that axis when its instance scale is `1`.

#### Tracking

Additional channels:

| Channels               | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `qx`, `qy`, `qz`, `qw` | Normalized quaternion in TouchDesigner coordinates. |
| `sx`, `sy`, `sz`       | XYZ size values.                                    |

#### Cameras

Additional channels:

| Channels               | Description                                                                                  |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| `qx`, `qy`, `qz`, `qw` | Normalized quaternion in TouchDesigner coordinates.                                          |
| `fovx`                 | Horizontal field of view in degrees.                                                         |
| `focus`, `zoom`        | Received focus and zoom metadata.                                                            |
| `k1`, `k2`, `k3`       | Radial distortion coefficients.                                                              |
| `p1`, `p2`             | Additional received lens coefficients.                                                       |
| `centerx`, `centery`   | Transmitted center-shift values in panel millimeters, using the SPNet coordinate convention. |

The dedicated SPNet Camera CHOP provides the camera-ready projection and rendering controls used by the generated camera rig.

### Coordinates and rotation

Position conversion is applied automatically:

| Grid Studio | TouchDesigner |
| ----------- | ------------- |
| X           | X             |
| Y           | Y             |
| Z           | −Z            |

Connect `rx`, `ry`, and `rz` to Rotate X, Y, and Z using **Rotate Order = XYZ**.

The Data CHOP prepares these rotations for TouchDesigner, including conversion from the received radians to degrees.

### Missing or expired data

In All Objects and Single Object modes, an empty result produces one placeholder sample:

| Channel                | Value |
| ---------------------- | ----- |
| `active`               | `0`   |
| `id`                   | `-1`  |
| Other numeric channels | `0`   |

For instancing, assign the `active` channel to the Geometry COMP's **Active** instance parameter.

{% hint style="info" %}
Active reflects received object presence and timeout status. The sender's visibility flag is ignored.
{% endhint %}

### Full-resolution point IDs

CHOP channels use 32-bit floating-point values. Large point IDs may therefore be rounded in the `id` channel.

The `id_hi` and `id_lo` channels preserve the full ID as two exact 16-bit values.

Reconstruct the ID using integer arithmetic in a suitable consumer, such as Python:

```
ID = id_hi × 65536 + id_lo
```

### Diagnostic channels

Diagnostics mode outputs one sample per channel.

| Channels                      | Description                                                       |
| ----------------------------- | ----------------------------------------------------------------- |
| `receiving`                   | Indicates the receiver is receiving and its data has not expired. |
| `timed_out`                   | Indicates that the configured packet timeout has elapsed.         |
| `active_count`                | Number of currently available objects in the selected Data Type.  |
| `point_count`                 | Number of points in the receiver snapshot.                        |
| `tracking_count`              | Number of non-camera tracking objects in the receiver snapshot.   |
| `camera_count`                | Number of camera objects in the receiver snapshot.                |
| `packets`, `bytes`, `objects` | Receiver packet, byte, and decoded-object counters.               |
| `decode_errors`               | Number of decode errors.                                          |
| `packets_per_second`          | Incoming packet rate.                                             |
| `bytes_per_second`            | Incoming byte rate.                                               |
| `objects_per_second`          | Decoded-object rate.                                              |
| `packet_age_ms`               | Time since the last received packet, in milliseconds.             |
| `decode_us`                   | Last decode duration, in microseconds.                            |
| `ingest_us`                   | Last ingest duration, in microseconds.                            |
| `publish_us`                  | Last snapshot publication duration, in microseconds.              |

Receiver counters and packet timing describe the shared connection. The snapshot counts can remain populated after a timeout; use receiving, timed\_out, and active\_count to assess current availability.