> 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/events-dat.md).

# Events DAT

Inspect live SPNet data, receive active and inactive transitions, and configure object filters, event history, timeout, and network reception.

The SPNet Events DAT receives point, tracking, and camera data and presents it as a table.

It provides three output modes:

* **Live Data:** Current object values.
* **Events:** Retained active and inactive transitions.
* **Diagnostics:** Shared receiver status and counters.

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

### Data page

| Parameter        | Default     | Description                                                     |
| ---------------- | ----------- | --------------------------------------------------------------- |
| Data Type        | `All`       | Selects the object family included in Live Data or Events.      |
| Output Mode      | `Live Data` | Selects live values, lifecycle events, or receiver diagnostics. |
| Include Tracking | `On`        | Includes tracking objects when Data Type is All.                |
| Include Cameras  | `On`        | Includes camera objects when Data Type is All.                  |
| Include Points   | `Off`       | Includes point data when Data Type is All.                      |
| Timeout ms       | `1000`      | Expires received data after this duration without packets.      |

#### Data Type

| Option   | Included data                                                               |
| -------- | --------------------------------------------------------------------------- |
| All      | Combines the families enabled by the Include parameters.                    |
| Points   | Points received through SPNet Point Data.                                   |
| Tracking | Tracking objects such as Movables, Rigid Bodies, and Tracked Points.        |
| Cameras  | Camera and Extended Camera objects using the available camera table fields. |

In Live Data mode, Points, Tracking, and Cameras each provide a compact table with relevant columns. All provides the combined column set.

Events mode uses the same event columns for every Data Type.

#### Include filters

The three Include parameters are available only when Data Type is All.

For a point-only table, select **Data Type → Points**. The Include Points setting is then ignored.

{% hint style="info" %}
With the default Data Type of All, points are excluded until Include Points is enabled.
{% endhint %}

#### Output Mode

**Live Data**

Shows one row per currently available object.

The table updates as positions, rotations, sizes, and other values change. Objects disappear from this table when they are absent from the received data or the packet timeout expires.

If no objects are available, only the column headers remain.

**Events**

Records changes in object membership:

| Event      | Meaning                                                                                |
| ---------- | -------------------------------------------------------------------------------------- |
| `active`   | An object has appeared in the selected data.                                           |
| `inactive` | A previously observed object has disappeared, timed out, or been excluded by a filter. |

Movement alone keeps the object active. Use Live Data or the SPNet Data CHOP for continuously changing properties.

Events remain in the table according to Event History.

**Diagnostics**

Shows receiver information as name/value rows.

These values describe the shared connection independently of the selected object-family filters.

#### Timeout ms

Controls expiry based on the time since the shared receiver last received a packet.

* `1000` expires data after one second without packets.
* `0` disables expiry based on packet age.
* The supported range is `0` to `60000` milliseconds.

After expiry:

* Live Data becomes empty apart from its headers.
* Events adds inactive transitions for previously observed objects, with reason `timeout`.

Fresh data can generate active events again.

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

### Events page

These parameters are available when Output Mode is Events.

| Parameter     | Default | Description                              |
| ------------- | ------- | ---------------------------------------- |
| Event History | `64`    | Requested number of retained event rows. |
| Clear Events  | Pulse   | Clears the retained event log.           |

#### Event History

The supported range is `1` to `10000`.

Older events are removed as the history fills. The newest batch of transitions is kept complete, even if that batch exceeds the configured limit.

Event History counts event rows, excluding the header.

#### Clear Events

Clears the displayed history while retaining the currently observed object membership.

Existing objects continue to be observed. They generate another active event after becoming inactive and appearing again.

Clearing the history also preserves event-ID progression.

### 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, use the same group and port in Grid Studio and TouchDesigner.

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

Interface Address refers to the receiving computer's local adapter address.

SPNet operators with identical Connection settings share one native receiver.

### Live Data columns

Live Data includes a header row followed by the current objects.

#### Common columns

| Columns          | Description                                                             |
| ---------------- | ----------------------------------------------------------------------- |
| `event`          | Contains `current`.                                                     |
| `key`            | Object identity composed of type and ID, such as `point:7`.             |
| `type`           | Object type.                                                            |
| `id`             | Numeric object ID, written as text to preserve its value.               |
| `name`           | Received object name or a generated fallback.                           |
| `tx`, `ty`, `tz` | Position in meters, converted to TouchDesigner coordinates.             |
| `rx`, `ry`, `rz` | Received Euler rotation values. Grid Studio sends these in radians.     |
| `timestamp`      | Source timestamp, preserved as transmitted.                             |
| `packet_age_ms`  | Time since the shared receiver last received a packet, in milliseconds. |

#### Additional columns by Data Type

| Data Type | Additional columns                              |
| --------- | ----------------------------------------------- |
| Points    | `sx`, `sy`, `sz`, `r`, `g`, `b`, `a`            |
| Tracking  | `qx`, `qy`, `qz`, `qw`, `sx`, `sy`, `sz`        |
| Cameras   | `qx`, `qy`, `qz`, `qw`, `fovx`, `focus`, `zoom` |
| All       | Combined set of the columns above.              |

Size columns contain XYZ dimensions. Color columns contain RGBA values.

Quaternion columns retain the received quaternion values. For cameras, `fovx` contains the horizontal field of view in degrees; focus and zoom contain received metadata.

#### Coordinates and rotations

Position conversion is applied automatically:

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

{% hint style="info" %}
The DAT preserves received Euler and quaternion rotations. Use the SPNet Data CHOP when you need rotations prepared for TouchDesigner XYZ degrees.
{% endhint %}

### Event columns

Events mode always uses these eight columns:

| Column      | Description                                                        |
| ----------- | ------------------------------------------------------------------ |
| `event_id`  | Unique identifier for the transition.                              |
| `event`     | `active` or `inactive`.                                            |
| `key`       | Object identity composed of type and ID.                           |
| `type`      | Object type.                                                       |
| `id`        | Numeric object ID, preserved as text.                              |
| `name`      | Object name or fallback.                                           |
| `timestamp` | Local time when the transition was observed, in Unix milliseconds. |
| `reason`    | Explanation of the transition.                                     |

#### Event reasons

| Reason     | Meaning                                                        |
| ---------- | -------------------------------------------------------------- |
| `appeared` | The object became available in the selected data.              |
| `removed`  | The object disappeared from the received data.                 |
| `timeout`  | The packet timeout expired.                                    |
| `filtered` | An Include filter excluded the object while Data Type was All. |

Event rows are retained in generation order, with the newest rows at the end.

{% hint style="info" %}
Event timestamps describe when this DAT observed the transition. Live Data timestamps come from the sender.
{% endhint %}

### Object identity and event identity

Use **key** to associate graphics or state with an object.

For example, `point:1` and `movable:1` identify different objects even though their numeric IDs match.

Use **event\_id** to identify a particular transition. Several events can share a timestamp, so event\_id is the appropriate value for preventing repeated actions.

A DAT Execute DAT can monitor the table and process each new event\_id once.

{% hint style="info" %}
Event history contains past transitions. Use Live Data for current membership, or maintain membership in your event handler.
{% endhint %}

Membership is based on received objects and timeout status. The sender's visibility flag is ignored.

### Changing the observation settings

Changing Data Type, switching between Live Data and Events, or changing Connection settings restarts observation and clears the event history.

When Events observation starts, currently available objects can generate fresh active events.

Use separate SPNet Events DAT nodes when you need Live Data and Events simultaneously.

### Diagnostics

Diagnostics mode provides the following name/value rows:

| Name                 | Description                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `state`              | Shared receiver state.                                                                        |
| `source`             | Address and source port of the last sender.                                                   |
| `packets`            | Received packet counter.                                                                      |
| `objects`            | Decoded-object counter.                                                                       |
| `decode_errors`      | Decode-error counter.                                                                         |
| `generic_values`     | Generic values in the receiver snapshot.                                                      |
| `events`             | Runtime events in the receiver snapshot, separate from this DAT's retained lifecycle history. |
| `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.                                          |
| `packets_per_second` | Incoming packet rate.                                                                         |
| `objects_per_second` | Decoded-object rate.                                                                          |

Assess packet counters and packet age together with the receiver state when checking a connection.