点类型组

30 秒版本：

Type-groups 可以理解为 points 的“标签/分组”（例如 MARKER 组）。
在 Python easy 层，设置 View.type_groups 就能作为额外的 AND-filter 来筛选 points。
缺失元数据时的行为是可配置的；strict 模式可以直接抛错。

形象化：像给一张表加了“分类”列，然后按分类筛选。

一些 C3D 文件会包含描述 point “type groups”（例如 marker group）的元数据。

sqzc3d 会将这类元数据从 chunk 中暴露为：

type_group_names：组名列表
type_group_starts：prefix-sum offsets
type_group_indices：扁平化的 point index 列表

所有 indices 都在 chunk-local point index space 中。

Python Easy

推荐：大多数用户直接用这层即可。

Easy 层通过 View.type_groups 支持 type-groups。

effective selection 是 AND：

point_labels 的选择（如果被设置）
type-groups 的选择（如果非空）

import sqzc3d as sq

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

Python Core：从 type-groups 映射到 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)

默认语义：

缺失 TYPE_GROUPS 元数据：视作 no-op（ALL points）。
元数据存在但 group name 缺失：返回空集。
strict=True 会在缺失/无效时抛错。

Python helper 也暴露了 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++：从 chunk 消费 type-group 元数据

当 chunk 含有 type-group 元数据时，会暴露为：

chunk->type_group_names（长度 chunk->n_type_groups）
chunk->type_group_starts（长度 chunk->n_type_groups + 1）
chunk->type_group_indices（flattened chunk-local point indices）

示例（C 风格）：

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)
}