Block a user
11962cdc34
配置没写的滤波键等于"关"，不再回落到会滤波的默认值 - What: DEFAULT_FORCE_MEDIAN_WINDOW 3 -> 1、DEFAULT_FLOW_EMA_ALPHA 0.5 -> 1.0（DEFAULT_FORCE_LOWPASS_HZ 本就是 0.0），并把注释改成"配置文件没写的键就是关，而不是我们觉得合理的那一档"——原因写在注释里：否则设备会去滤一个没人要求滤的测量，而文件里没有任何线索；实测的延迟/降噪数据保留在注释中，作为 balanced/low_noise 预设的依据。docs/filters.md 第 2 节增加"缺省 = 关"这一条并说明没有 filters 段的配置什么都不滤，预设表里 balanced 的用途由"默认建议"改为"建议起步档"（它不再是默认值）。examples/filters/README.md 补一句"整段删掉等价于 off"。tests/test_filter_presets.py 新增 test_a_config_with_no_filters_block_filters_nothing：把 box bundle 的 filters 段整段删掉后构造真实 Sensor，断言 filters_state() 报 ema 1.0 / median 1 / cutoff 0.0 且 any_stage_applied 为 False。 - Why: 上一版只把"非法值"改成回落到关，但"键根本不写"仍会走 DEFAULT_* 从而把 EMA 0.5 + 中值 3 打开——这与"配置自描述、文件说什么就跑什么、出厂默认全关"矛盾，且现实里存在大量没有 filters 段的手写配置（例如 _perf/cfg_res_280x300.json），它们会在无人察觉的情况下继续滤波。缺省开是这条链上最后一个隐藏默认值。 - Verification: 删掉 filters 段后实测 filters_state() = (1.0, 1, 0.0) 且 any_stage_applied=False，出厂 box/mini/finger 三份同样为全关；pytest tests/test_filter_presets.py + tests/test_calibration.py → 33 passed；SDK 全量 336 passed / 15 skipped（唯一失败仍是需要 1200 帧而样例只有 577 帧的 longrun 测试）；app 侧 studio 85 项与 shared 142 项测试、ui_check 554 项检查在升级后的 0.5.2 下全绿。 - Not in this change: 出厂 bundle 的三个显式值未动（本来就全关）；_perf 的两个校验脚本不在仓库内，已就地补上显式 filters 段（balanced）以保持"开 vs 关"对照仍有意义；app 侧 wrapper/齿轮/CSV 17 列未动。
ae5bf0c208
断开连接不再因无头 OpenCV 抛错 - What: Sensor.disconnect() 里的 cv2.destroyAllWindows() 包上 try/except cv2.error：无头构建（opencv-python-headless）没有 highgui，destroyAllWindows 会抛 "The function is not implemented"，此前会让 finally 里 disconnect() 的调用方（测试、采集退出路径）拿到一个与传感器无关的异常。 - Why: 跑 SDK 测试时发现 tests/test_calibration.py::test_sensor_cal_path_v2_applies_to_read_info 与 test_set_calibration_swaps_curve 在本机（cv2 4.14.0 headless）稳定失败，断言本身都过了，报错在 finally 的 disconnect() 第 1098 行；这不是滤波改动引入的，但会一直污染每次验证，且 SDK 明确支持无头/CI 使用（backend="cpu"、external-frame 模式）。 - Verification: 修前该模块 7 failed / 13 passed（含上述两个既有测试），修后 20 passed；SDK 全量 335 passed / 15 skipped（唯一失败为需要 1200 帧而 data/sample/s1_480p.mp4 只有 577 帧的 longrun 测试）。 - Not in this change: 未改 disconnect() 的其他分支；未引入 highgui 依赖探测，只在真正调用失败时忽略。
7f8e5d0975
四个滤波预设落成机器可读的配置文件，并加上防漂移测试 - What: 新增 examples/filters/filters_{off,low_latency,balanced,low_noise}.json —— 每个都是完整可整块替换的 filters 段（五键齐全：flow_ema_alpha / force_median_window / force_lowpass_cutoff_hz / force_lowpass_order / force_lowpass_sample_rate_hz），数值即 FILTER_PRESETS 展开后的结果；examples/filters/README.md 说明这四份副本的存在与用途；新增 tests/test_filter_presets.py（12 项）：预设名恰为四个、每个示例文件 == 默认块叠加该预设（改预设或改文件都会红）、每份都是含三个开关键的真实 filters 段、三个出厂 bundle（box/mini/finger）的 filters 段仍为全关、且用 external-frame 模式构造真实 Sensor 核对 filters_state() 报的也是全关（文件与设备必须一致）。 - Why: 之前的实现计划里写的是"四个 sensor_<preset>.json 整机配置"，但整机配置要按传感器各复制一份、且必然随 bundle 漂移；README 里内嵌的 JSON 又无法被测试覆盖，等于把"建议用哪档滤波"这句话留在了一处会过时的散文里。改成"filters 片段 + 断言与 FILTER_PRESETS 逐值一致的测试"，既不谎称是完整配置，也不会静默过时。 - Verification: pytest tests/test_filter_presets.py → 12 passed；SDK 全量 335 passed / 15 skipped（唯一失败仍是需要 1200 帧而样例只有 577 帧的 longrun 测试）。 - Not in this change: 未生成按传感器复制的整机配置；docs/filters.md 的预设表未纳入测试（只有这四个文件与代码常量对齐）；app 侧未动。
35190562e5
标定指纹改读生效值并按测量/读数分组 - What: calibration.py 新增 FILTER_MEASUREMENT_KEYS（flow_ema_alpha）与 FILTER_READOUT_KEYS（中值窗口、低通截止/阶数/采样率/rate_auto）、filters_fingerprint()（把 Sensor.filters_state() 归一化成 {measurement, readout, preset, source}：非法值丢弃、来源没写的键不出现而不是补默认、空映射返回 {} 表示"无记录"）、filter_mismatches()（按组判读差异）与 _filters_from_config / _flat_filters_from（扁平旧格式与 preset 展开的兼容解析，显式键优先）；pipeline_from_sensor_json() 新增 filters_state= 关键字——传了生效值就用生效值，否则读文件的 filters 段并标注 source="sensor.json.filters"，返回结构化 filters 键，删除原先会凭空补出 0.5/3/10 的扁平键与 enabled 覆盖逻辑；Calibration.to_dict() 写 meta.filters（同时保留扁平键供旧读者按名取用）；parse() 把 filters 读回 pipeline（此前 to_dict 写进 meta 的滤波键在读回时被整段丢弃，指纹实际是"只写不读"）；check() 改用 filter_mismatches 分开报告——measurement 组差异进 warnings 且措辞含 not comparable，readout 组差异进新增字段 CheckResult.notes（只记录、不拦截）；build(extra_meta=…) 把 filters 与扁平滤波键折进结构化组。tests/test_calibration.py 新增 11 项测试（分组、preset 展开与显式键优先、enabled:false 全关、非法值为空而非默认、写入-读回往返、旧扁平文档读回、生效值压过文件、四个预设逐档核对）。docs/filters.md 新增第 7 节。 - Why: 用户决策 B 要求"Sensor.filters_state() 作为唯一生效值出口，calibration.py 指纹与 session.json 都读它、不读配置文件，指纹分 measurement/readout 两组"；动手时确认旧实现三个问题叠加：来源错（读文件、被 filters.enabled 覆盖、文件没写就补默认 0.5/3/10），写进 meta 的指纹在读回时被丢弃，check() 因此永远比不出滤波差异——审计链是断的，不是不精确。 - Verification: SDK 全量 pytest 335 passed / 15 skipped，唯一失败 test_vnormal_longrun_no_outlier_jumps 需要 1200 帧而 data/sample/s1_480p.mp4 只有 577 帧（环境/数据，与本改动无关）；external-frame 模式逐预设构造真实 Sensor，filters_fingerprint(filters_state()) 得 off(1.0,1,0.0) / low_latency(1.0,3,0.0) / balanced(0.5,3,0.0) / low_noise(0.3,3,10.0)；写入→读回往返后 measurement/readout/preset 完整保留且 to_dict 幂等；旧扁平 meta 文档仍读回同一指纹；.repro/verify_cal_filters.py 50 项全绿。 - Not in this change: 未动 app（app 的 meta_from_sensor_json 只取 4 个键，不受影响）；未升级 venv 内 SDK；examples/filters 的四个机器可读预设片段与 app 侧 wrapper/齿轮/CSV 17 列未动。
zhangyijian
created branch feature/studio_adapt in orisys-tech/orisys-sdk
2026-09-14 13:56:48 +08:00
4a482e579f
按"硬件问题、配置不变"收尾：记录里写下实测帧率，探针加逐颗验收模式 - What: worker 把本会话实测到的采集速率记进 self._measured_capture_fps（box 与 finger 两条循环都算：finger 的帧率也从"1 秒窗口内计数"改成 (n-1)/span 的速率，两条视图对 fps 的含义必须一致），capture_status() 因此多出 measured_fps —— session.json 的 capture 块现在同时有 requested / negotiated / measured_fps / dropped_frames，一颗摄像头到底交付了多少 fps 由记录自证。status.capture_slow 的中英文案改写：删掉已被实测否证的"降低分辨率/换格式"建议，改成"这是采集端（摄像头/驱动）的问题、软件改不了，换一颗真能交付 30 fps 的（并先确认线材/端口没把它降速）再测"。tools/camera_probe.py 新增 --check 验收模式：只测 bundle 用的那一个格式（MJPG 1920x1080@30，120 帧），按**实测**速率打印一行 PASS/FAIL 并给出退出码，用于逐颗过检；无摄像头时报 "No camera answered on index N (is the app closed?)" 并返回 1。tests：假设备用上 capture_status() 的 measured_fps（0.05 s 粒度等它出现，断言 20–35 fps）、探针 --check 的无摄像头路径。 - Why: 用户判定这是驱动/硬件问题（同型号产品此前能跑 30 fps），决定**配置不变**、以后用能到 30 fps 的产品，并在之后逐颗检测。配置不变意味着应用继续按 30 fps 申请（这是对的：申请 15 只会把问题上移），但由此产生两件必须收尾的事：(1) 提示语里"降低分辨率/换格式"是错的建议——探针已经证明 720p MJPG 一样是 15 fps、YUYV 只有 1 fps；(2) 既然要逐颗检测，就必须有一个能回答"这一颗交付了多少"的权威数字，而驱动自报值不可信（DSHOW 回读），所以把实测值写进记录并给探针一个单行验收模式。 - Verification: shared 全量 161 passed；studio 91 passed；ui_check 554 项检查 0 失败；locale_check 中英键集一致；探针 --check 在无摄像头时打印指定文案并返回 1，--help 列出该选项。 - Not in this change: 未改任何采集配置（resolution_raw/fps/fourcc 都不动）；未做自动降级；frames.csv 仍未记录 process_ms/capture_fps（留到加未滤波 17 列、记录格式升版时一起）。
30ef50814f
探针增加尺寸扫描：区分链路带宽不够与摄像头本身就是 15 fps - What: tools/camera_probe.py 新增 SWEEP_SIZES 与 size_sweep()，在帧率扫描之后对 MJPG@30 依次申请 1920x1080/1280x720/960x540/848x480/640x480 并打印实测速率，提示语写明判断方式：帧越小越快 ⇒ 链路带宽是瓶颈；每个尺寸都一样 ⇒ 是摄像头本身的速率上限。 - Why: 用户实测 MJPG 在 1080p 与 720p 都是 15 fps、YUYV 两档都是 1 fps，两种解释仍然都成立（链路只能扛约 3-4 MB/s，或这颗摄像头在这些格式上就是 15 fps 设备），而处置完全不同；帧率扫描只能区分"申请被砍半"与"固定上限"，尺寸扫描才能区分"带宽"与"设备"。 - Verification: compileall 通过；无摄像头时仍返回 1 并给出解释；studio 全量 91 passed（探针的无摄像头用例覆盖 main() 的降级路径）。 - Not in this change: 未改 SDK 采集参数；未做自动降级。
a44eb2d65d
达不到帧率的判据改用实测速率（DSHOW 回读值会说谎），探针加帧率扫描 - What: short_capture_fallacy() 改为以**实测**速率为准（新增 measured_fps 关键字参数），消息改成"it delivers about 15 fps while the config asks for 30 (1920x1080 reported 30, MJPG/DSHOW)"——把驱动自报值降级为"矛盾的一部分"而不是判据；app_window 的 _check_capture_negotiation() 相应改为用 packet 的 capture_fps（实测）判据、实测为 0 时不下结论（等窗口填满）。tools/camera_probe.py 重写：probe() 返回结构体、format_row() 把 reported 与 measured 分列并在达不到 90% 时标 "<-- misses the request"；新增 --samples 与**帧率扫描**（同一格式依次申请 60/30/20/15/10 fps，逐行给实测值与"跟随申请 / 只有申请的 x 倍"的判断，最后给"本次看到的ceiling"）。tests/test_worker_frame_rate.py 的归因测试同步更新，并显式覆盖"驱动自报 30 而实测 15 必须判为不达标"与"没有实测值时不说话"。 - Why: 用户跑探针的结果推翻了我上一轮的判据：MJPG 1920x1080@30 -> MJPG 1920x1080 @ 30.0 measured 15.0。DSHOW 后端下 CAP_PROP_FPS 只是回读你设的值，所以 SDK 的 status.fps 同样不可信 —— 我原来比较"申请 vs 协商"等于拿申请跟自己比，那个提示永远不会出现（用户实际看到的只有轨道上的实测 16.7）。这也解释了为什么这件事必须靠实测：真实速率只能测出来。另外探针显示 1280x720 MJPG 实测也是 15、YUYV 只有 1 fps，说明换分辨率不解决问题，需要区分"摄像头本身的上限"与"我们申请多少就被砍半"。 - Verification: shared 全量 161 passed（含新增/更新的 3 项断言）；studio 91 passed；ui_check 554 项检查 0 失败；探针在本机（无摄像头）仍返回 1 并给出解释，format_row/_decode 单测通过（"reported 30.0 measured 15.0 ... <-- misses the request"）。 - Not in this change: 未改 SDK 采集申请顺序/后端；未做自动降级；frames.csv 仍未记录 process_ms/capture_fps。
3db55b2077
新增摄像头能力探针 tools/camera_probe.py，用来把 16.7 fps 归因到格式协商 - What: 新脚本对每个摄像头索引 × 两种后端（DSHOW/MSMF）× 五组请求（MJPG 1920x1080@30、MJPG 1920x1080@auto、MJPG 1280x720@30、YUYV 1920x1080@30、YUYV 1280x720@30）实际打开并连续抓 60 帧，逐行打印"申请 → 驱动协商到的 fourcc/尺寸/帧率 + 实测帧率"，这样\"协商到 30\"与\"真的给到 30\"是两个分开的事实；没有摄像头时给出明确说明（含"要关掉 app，两个进程不能同时占用同一个摄像头"）并返回 1；--help/--index/--max-index 可用。tests/test_ui_smoke.py 增加 test_the_camera_probe_is_usable_without_a_camera：无摄像头时返回 1 且输出解释、fourcc 编解码往返正确（'MJPG' → 'MJPG'、0 → '-'）。 - Why: 用户按上一轮读数确认"还是摄像头 16.7"，即摄像头自身只发布 16.7。配置申请的是 resolution_raw=1920x1080、fps=30、fourcc 走 CaptureConfig 默认 MJPG、backend=auto；SDK 已在 open 里做了 width/height → fourcc → fps → fourcc 再设一次 + warmup 后校验并在 fourcc 不符时重试一次，但仍存在两种可能：这颗摄像头在 1080p 下就只有 16.67（UVC 常见），或者它在 MJPG 之外落到了别的格式/后端。这两种的处置完全不同（前者要改分辨率/换摄像头，而 1920x1080 是 5x3 瓦片网格的结构参数，改它要重做拼接标定；后者是申请顺序/格式的问题，可以在 SDK 侧修），而在应用里看不出来。因此需要一个不经过应用的独立探针，把驱动真正提供的东西列出来。 - Verification: 本机（无摄像头）运行 --index 9 → 输出 "No camera answered on indices 9..9." 与关闭 app 的提示、退出码 1；--help 正常；_decode(_fourcc_code('MJPG')) == 'MJPG'。studio 全量 91 passed（新增 1 项）；ui_check 554 项检查 0 失败。 - Not in this change: 未改 SDK 的采集申请顺序或后端选择（等探针结果：若显示 MJPG+1080p 下驱动只给 16.67，则是硬件边界；若显示申请 MJPG 却协商成 YUYV，再改 SDK）；未做分辨率自动降级。
zhangyijian
deleted branch feature/cal_json_v2 from orisys-tech/orisys-sdk
2026-09-10 21:49:07 +08:00
Feature/cal json v2
Feature/cal json v2