选择器与索引空间

本页定义 Python 与 C 中的选择器语义。

30 秒版本：

  • None 表示“全选”，[] 表示“空选”。

  • 按 labels 选择会保序（你传入什么顺序，就按什么顺序返回）。

  • indices 有“编号体系”的问题：先确认你用的是哪一种 index space。

形象化：labels 像“姓名”，indices 像“工号”；更重要的是别把不同部门的工号体系混着用。

Python easy 层

Easy surface 是 labels-only（不暴露 indices）。

import sqzc3d as sq

v = sq.read("trial.c3d", points=None)        # ALL points
v = sq.read("trial.c3d", points=["LANK"])    # label selection
v = sq.read("trial.c3d", points=[])          # empty selection

选择器语义：

  • None 表示默认（ALL）。

  • [] 表示空选择。

  • str 或 sequence[str] 表示按 label 选择。

Python core 层

Core surface 支持 indices 或 labels：

chunk.points(None)         # ALL
chunk.points([])           # empty
chunk.points([0, 1, 2])    # indices (chunk-local point indices)
chunk.points(["LANK"])     # labels (chunk-local label table)

备注：

  • 对非连续选择，必须 copy=True。

Label 归一化

label_norm 会在匹配前对 labels 做归一化（trim / 大小写折叠 / 空白统一）。

如果归一化导致“同名冲突”（多个源 labels 归一化后变成同一个），sqzc3d 会直接报错， 而不是悄悄选中其中一个。

此时建议：用 label_norm=EXACT 配合精确 label，或下探到 Core 用 indices 来消歧义。

C API

核心入口是 sqzc3d_build_opt_t。

C materialize API 会在构建 chunk 时对 points/analogs 做选择（也就是“在 materialize 阶段做过滤”）。

Point selection：

  • point_sel_mode = sqzc3d_POINT_SEL_ALL

  • point_sel_mode = sqzc3d_POINT_SEL_INDICES 且 point_sel 是 source-total point indices

  • point_sel_mode = sqzc3d_POINT_SEL_LABELS 且 point_labels 按 source labels 匹配

空选择：

  • *_sel_count == 0 是合法的空选择（不是错误）。

索引空间

这就是所谓的 index spaces：同一份数据有两套“编号体系”。

points 存在两个 index space：

  • Source-total：原始 C3D POINT:LABELS 表的索引。

  • Chunk-local：materialized chunk 的索引，范围 [0..chunk->n_points)。

在 C API 中：

  • sqzc3d_build_opt_t.point_sel 使用 source-total space。

  • sqzc3d_chunk_t.type_group_indices 是 chunk-local。

  • chunk 暴露出来的所有 point indices（views/type-groups）都是 chunk-local。