Type-groups

Quick summary:

  • Type-groups are like “tags” for points (for example, a marker group).

  • In Python Easy, set View.type_groups to apply an extra AND-filter.

  • Missing-metadata behavior is configurable; strict mode can raise.

Mental model: filtering a spreadsheet by a “category” column.

Some C3D files include metadata describing point “type groups” (for example, a marker group).

sqzc3d exposes this metadata from a chunk as:

  • type_group_names: group names

  • type_group_starts: prefix-sum offsets

  • type_group_indices: flattened point index list

All indices are in the chunk-local point index space.

Python Easy

Recommended for most users.

The easy layer supports type-groups via View.type_groups.

The effective selection is an AND:

  • point_labels selection (if set)

  • type-groups selection (if non-empty)

import sqzc3d as sq

v = sq.read("trial.c3d")
v.type_groups = ["MARKER"]
pts = v.points

Python Core: map type-groups to indices

import sqzc3d

dec = sqzc3d.Decoder("trial.c3d")
chunk = dec.read(frame_count=1)
dec.close()

idx = sqzc3d.type_group_indices(chunk, "MARKER", strict=False)
pts, valid = chunk.points(idx, copy=True)

Default semantics:

  • Missing TYPE_GROUPS metadata means no-op (ALL points).

  • Metadata exists but the group name is missing means empty set.

  • strict=True makes missing/invalid cases error out.

The Python helper also exposes the missing-meta policy:

import sqzc3d

dec = sqzc3d.Decoder("trial.c3d")
chunk = dec.read(frame_count=1)
dec.close()

# If TYPE_GROUPS metadata is missing:
# - missing_meta="all" yields ALL points (default)
# - missing_meta="empty" yields empty
idx = sqzc3d.type_group_indices(chunk, ["MARKER"], strict=False, missing_meta="all")

C/C++: consume type-group metadata from a chunk

When a chunk contains type-group metadata, it is exposed as:

  • chunk->type_group_names (length chunk->n_type_groups)

  • chunk->type_group_starts (length chunk->n_type_groups + 1)

  • chunk->type_group_indices (flattened chunk-local point indices)

Example (C-style):

for (int gi = 0; gi < chunk->n_type_groups; ++gi) {
  const char* name = chunk->type_group_names[gi];
  const int s = chunk->type_group_starts[gi];
  const int e = chunk->type_group_starts[gi + 1];
  // indices are chunk-local point indices: chunk->type_group_indices[s..e)
}