> 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/parameter-control/generic-chop.md).

# Generic CHOP

Receive named numeric controls through SPNet and configure value types, name filters, retention, timeouts, and output channels.

The SPNet Generic CHOP receives named numeric values from Grid Studio and makes them available as channels for parameter control.

Values can be sent through Workflow Actions or Modifier nodes.

Each scalar produces one channel with one sample. Vectors and colors produce separate channels for their components.

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

### Data page

| Parameter   | Default     | Description                                                                                 |
| ----------- | ----------- | ------------------------------------------------------------------------------------------- |
| Output Mode | `Live Data` | Selects received control values or receiver diagnostics.                                    |
| Data Type   | `All`       | Filters values by their received type.                                                      |
| Name Filter | `*`         | Selects values by their original SPNet names.                                               |
| Timeout ms  | `0`         | Defines how long each value remains available without another update. Zero disables expiry. |

#### Output Mode

**Live Data**

Outputs the latest matching numeric values as channels.

For example:

| Received name | Value | Output channel |
| ------------- | ----- | -------------- |
| `brightness`  | `0.5` | `brightness`   |
| `speed`       | `1.2` | `speed`        |
| `enabled`     | `1`   | `enabled`      |

The output represents the latest received state. Each new value replaces the previous value with the same name.

**Diagnostics**

Outputs receiver and cache statistics instead of control values.

Data Type, Name Filter, and Timeout remain relevant to the diagnostic selection counts described below.

#### Data Type

| Option  | Included values              |
| ------- | ---------------------------- |
| All     | All supported numeric types. |
| Integer | Integer values.              |
| Float   | Floating-point values.       |
| Vector3 | Three-component vectors.     |
| Vector4 | Four-component vectors.      |
| Color   | Four-component RGBA colors.  |

Choose a specific type when your network expects a particular kind of value.

For text and point lists, use the **SPNet Generic DAT**.

#### Name Filter

Matches the original name sent by Grid Studio.

Matching is case-sensitive.

| Filter       | Matches                                                               |
| ------------ | --------------------------------------------------------------------- |
| `*`          | Every name.                                                           |
| Empty        | Every name.                                                           |
| `brightness` | Exactly `brightness`.                                                 |
| `light*`     | Names beginning with `light`.                                         |
| `*speed`     | Names ending with `speed`.                                            |
| `control?`   | `control` followed by one byte, such as `control1` for an ASCII name. |

Spaces are treated literally. A filter containing spaces matches a name containing those spaces.

{% hint style="info" %}
Name Filter matches the source name before channel-name encoding and component suffixes are applied. For a vector named position, filter for position to receive its position\_x, position\_y, and position\_z channels.
{% endhint %}

#### Timeout ms

Timeout is measured separately for each named value, starting when that value was last received.

| Value  | Behavior                                                           |
| ------ | ------------------------------------------------------------------ |
| `0`    | Keeps the latest value available until replaced.                   |
| `1000` | Hides the value after one second without an update to that name.   |
| `5000` | Hides the value after five seconds without an update to that name. |

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

Receiving another value, a camera packet, or other SPNet traffic does not refresh this value's age.

When a value expires, its channels are removed from the output.

{% hint style="info" %}
Use Timeout = 0 for controls sent only when a Workflow Action executes. The value then remains available between actions.
{% endhint %}

Expiry filters the output while the value remains in the receiver cache. Changing Timeout back to zero can make an older cached value available again.

### 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 the receiving computer's local adapter address.

SPNet operators with identical Connection settings share one receiver. Generic values are retained in its shared cache, while each operator applies its own filters and timeout.

### Output channels

#### Scalars

Integer and Float values produce one channel using the encoded source name.

For example, a Float named `brightness` produces:

```
brightness
```

#### Vectors

Vectors add component suffixes to the encoded name.

| Received value           | Output channels                                |
| ------------------------ | ---------------------------------------------- |
| Vector3 named `position` | `position_x`, `position_y`, `position_z`       |
| Vector4 named `values`   | `values_x`, `values_y`, `values_z`, `values_w` |

#### Colors

Colors use RGBA suffixes.

A Color named `tint` produces:

```
tint_r
tint_g
tint_b
tint_a
```

#### Channel-name encoding

Letters and digits are preserved. Other characters are encoded to create distinct channel names.

| Original name | Scalar output channel |
| ------------- | --------------------- |
| `brightness`  | `brightness`          |
| `light_level` | `light__level`        |
| `light level` | `light_20level`       |
| `light/level` | `light_2Flevel`       |
| `1value`      | `_n1value`            |
| Empty name    | `_empty`              |

An existing underscore is doubled. Other characters are represented by an underscore followed by their hexadecimal byte value.

Component suffixes are added after this encoding.

For example:

| Source                                  | Result        |
| --------------------------------------- | ------------- |
| Float named `position_x`                | `position__x` |
| X component of Vector3 named `position` | `position_x`  |

This keeps the scalar and vector component distinct.

### Value retention

The receiver keeps the latest value for each exact name.

* Updating one name replaces that name's previous value.
* Other names retain their existing values and receive times.
* A new value can replace an older value of a different type with the same name.
* Independent controls should use distinct names.

Names are shared within the receiver connection. If multiple senders update the same name on that connection, the latest received value wins.

The cache is held in memory by the receiver.

### Units and numeric values

Generic values are passed through without coordinate or unit conversion.

For example, a Vector3 can represent a position, a color-related control, or any three values defined by your project. Your TouchDesigner network determines its meaning.

CHOP channels use 32-bit floating-point storage. Large Integer values may therefore be rounded. Use the Generic DAT when an exact integer representation is required.

Non-finite values or values outside the supported floating-point range are replaced with zero and produce a node warning.

### Empty output

If no supported numeric values match the selected type, name, and timeout, the CHOP outputs no channels.

Check that:

* The sender has sent a value.
* Its type matches Data Type.
* Its original name matches Name Filter.
* It has not expired.

### Diagnostic channels

Diagnostics mode provides one sample per channel.

| Channel          | Description                                                             |
| ---------------- | ----------------------------------------------------------------------- |
| `cached_values`  | Number of named values retained by the shared receiver.                 |
| `active_values`  | Number of cached values passing this node's timeout setting.            |
| `matched_values` | Number of active values matching Data Type and Name Filter.             |
| `packets`        | Shared receiver packet counter.                                         |
| `packet_age_ms`  | Time since the shared receiver last received a packet, in milliseconds. |
| `decode_errors`  | Shared receiver decode-error counter.                                   |

These counts refer to named values. A vector counts as one value while producing several channels.

With Data Type set to All, the cache counts can also include Strings and Point Lists, which are available through the Generic DAT.

{% hint style="info" %}
Packet age describes the shared connection. Timeout uses each named value's own receive age, so continuing SPNet traffic can coexist with an expired control value.
{% endhint %}