接口参考：参数与数据格式

from pathlib import Path
from stereo_camera_python import Camera, StereoRuntimeError, list_devices

APP = Path(r"F:\ZhiMuStereo\apps\ZhiMuStereo-0.2.6\apps\windows\Camera")
OUTPUT = Path(r"F:\ZhiMuStereo\data\python-captures")
# Linux 改为实际安装根；sdk-python 已绑定本程序目录。
for device in list_devices(installation_root=APP):
    print(device.serial, device.vid, device.pid, device.friendly_name)

try:
    with Camera.open("YOUR_CAMERA_SERIAL", installation_root=APP,
                     calibration="this-camera.yaml", backend="auto", profile="quarter") as camera:
        result = camera.capture(with_depth=True, timeout_ms=5000)
        print("左右图：", result.left.shape, result.right.shape)
        print("视差：", None if result.disparity is None else result.disparity.shape)
        print("深度：", None if result.depth_m is None else result.depth_m.shape)
        print("会话：", result.metadata.get("inference_session"))
        print("保存到：", result.save(OUTPUT))
except StereoRuntimeError as exc:
    print("错误码：", exc.code, "原因：", str(exc))
    raise

BUNDLE="$HOME/ZhiMuStereo/apps/ZhiMuStereo-0.2.6"
bash "$BUNDLE/camera.sh" record --serial ACTUAL_HARDWARE_SN --duration 10 --output "$HOME/ZhiMuStereo/recordings"
# 仅拼接视频可加 --source-views off

from stereo_camera_python import Camera
# application 路线：安装资源根为 Camera 或 Camera-headless。
APP = "/actual/path/to/Camera"
with Camera.open("ACTUAL_HARDWARE_SN", installation_root=APP, config_root=APP + "/config") as camera:
    recorded = camera.record("/path/to/recordings", duration_s=10)
    print(recorded.status, recorded.output_path)

# 长时间业务中也可用 start_recording() / stop_recording()
# 录像期间 capture() 仍获取触发后的新帧。

from stereo_camera_python import Camera

with Camera.open("YOUR_CAMERA_SERIAL", installation_root=r"F:\ZhiMuStereo\apps\ZhiMuStereo-0.2.6\apps\windows\Camera") as camera:
    controls = camera.controls()
    for control in controls:
        print(control.to_dict())
    # 正式业务使用查询到的 ID，不假设固定 ID 跨驱动一致。
    sharpness = next((c for c in controls if "sharpness" in c.name.lower()), None)
    if sharpness is not None and sharpness.writable and sharpness.supports_manual:
        print(camera.set_control(sharpness.id, sharpness.default, automatic=False))

python3 python_stereo_camera/examples/v4l2_controls.py --device /dev/video0
# 示例数值来自实测 2UK2，其他相机先检查范围。
python3 python_stereo_camera/examples/v4l2_controls.py --device /dev/video0 \
  --flicker 50 --exposure 100 --sharpness 3 --restore

import json
from pathlib import Path
import numpy as np

capture_dir = Path(r"F:\ZhiMuStereo\data\captures\SERIAL\CAPTURE_ID")
manifest = json.loads((capture_dir / "capture_manifest.json").read_text(encoding="utf-8"))
print(manifest["status"], manifest.get("metric_depth_available"))
files = manifest["files"]
if "disparity" in files:
    disparity = np.load(capture_dir / files["disparity"], allow_pickle=False)
    print(disparity.dtype, disparity.shape)
if "depth_m" in files:
    depth = np.load(capture_dir / files["depth_m"], allow_pickle=False)
    usable = np.isfinite(depth) & (depth > 0)
    # 业务过滤只对副本生效；不改 SDK 的原始数组或保存文件。
    filtered = np.where(usable, depth, np.nan)
    print("有限正深度比例：", float(usable.mean()))

cmake_minimum_required(VERSION 3.24)
project(CameraConsumer LANGUAGES CXX)
find_package(StereoCameraCpp CONFIG REQUIRED)
add_executable(camera_consumer camera_consumer.cpp)
target_compile_features(camera_consumer PRIVATE cxx_std_17)
target_link_libraries(camera_consumer PRIVATE StereoCamera::runtime)

#include <iostream>
#include <memory>
#include <stdexcept>
#include <opencv2/imgcodecs.hpp>
#include <stereo/calibration.hpp>
#include <stereo/pipeline.hpp>

int main(int argc, char** argv) {
    if (argc != 4) {
        std::cerr << "usage: camera_consumer APP_ROOT RAW_SBS CALIBRATION\n";
        return 2;
    }
    try {
        auto calibration = std::make_shared<stereo::Calibration>(
            stereo::Calibration::load(argv[3]));
        auto sbs = cv::imread(argv[2], cv::IMREAD_COLOR);
        if (sbs.empty()) throw std::runtime_error("cannot read input");
        stereo::PipelineOptions options;
        options.ai.applicationRoot = argv[1];
        options.ai.backend = "auto";
        options.ai.profile = "quarter";
        options.snapshotUsage = "offline";
        options.snapshotScale = 0.25;
        stereo::ProcessingPipeline pipeline(calibration, options);
        auto result = pipeline.processSnapshot(sbs, 1, true);
        if (!result.match) throw std::runtime_error("no disparity result");
        std::cout << "disparity: " << result.match->disparity.size() << '\n';
        std::cout << "metric depth: " << !result.match->depthMetres.empty() << '\n';
        return 0;
    } catch (const std::exception& error) {
        std::cerr << error.what() << '\n';
        return 1;
    }
}

# 当前目录包含下载的 CMakeLists.txt 和 camera_consumer.cpp。
PREFIX="$HOME/zhimu-stereo/apps/camera"
cmake -S . -B "$HOME/zhimu-stereo/build/consumer" -DCMAKE_PREFIX_PATH="$PREFIX"
cmake --build "$HOME/zhimu-stereo/build/consumer" --parallel 2
"$HOME/zhimu-stereo/build/consumer/camera_consumer" "$PREFIX" \
  "$HOME/input/raw_sbs.png" "$HOME/input/calibration.yaml"

PREFIX="$HOME/zhimu-stereo/apps/ros-sdk"
# 先按客户构建流程构建 --headless SDK，准备该平台推理资源。
bash scripts/linux/build_ros.sh "$PREFIX" jazzy
source "$PREFIX/ros/jazzy/install/local_setup.bash"
export LD_LIBRARY_PATH="$PREFIX/lib:$PREFIX/deps/lib:$PREFIX/deps/lib64:${LD_LIBRARY_PATH:-}"
ros2 launch zhimu_stereo_ros stereo.launch.py \
  application_root:="$PREFIX" config_root:="$HOME/zhimu-stereo/data/config" \
  output_root:="$HOME/zhimu-stereo/data/ros-captures" serial:=YOUR_CAMERA_SERIAL \
  subtype:=MJPG backend:=auto namespace:=stereo \
  require_calibration:=true depth_stream:=false snapshot_profile:=quarter
# 另一终端激活同环境、source 同 overlay 后调用。
ros2 service call /stereo/capture zhimu_stereo_ros/srv/Capture \
  "{with_depth: true, profile: quarter, save: true}"

ros2 launch zhimu_stereo_ros visualize.launch.py \
  application_root:="$PREFIX" config_root:="$HOME/zhimu-stereo/data/config" \
  output_root:="$HOME/zhimu-stereo/data/ros-captures" serial:=YOUR_CAMERA_SERIAL \
  backend:=auto require_calibration:=true stream_profile:=quarter \
  depth_stream:=true point_cloud:=true depth_visualization:=true
# 已在运行相机节点：只启动显示，namespace 要与相机节点一致。
ros2 launch zhimu_stereo_ros visualize.launch.py start_camera:=false namespace:=stereo
# ROS 1 相同参数，使用：
# roslaunch zhimu_stereo_ros visualize.launch ...

BUNDLE="$HOME/ZhiMuStereo/apps/ZhiMuStereo-0.2.6"
APP="$BUNDLE/apps/linux/Camera-headless"
if [[ ! -d "$APP" ]]; then APP="$BUNDLE/apps/linux/Camera"; fi
SDK="$HOME/ZhiMuStereo/envs/sdk-0.2.6-py312"
"$SDK/sdk-python.sh" -m stereo_camera_python.management_cli sync-customer --username CUSTOMER_ACCOUNT \
  --asset-id ACTUAL_ASSET_UUID --asset-code ACTUAL_LEDGER_CODE \
  --vid 15AA --pid 1555 --serial ACTUAL_HARDWARE_SN --mi 00 \
  --config "$APP/config" --directory "$HOME/ZhiMuStereo/data/calibration-cache"

from stereo_camera_python import Camera, CameraIdentity
from stereo_camera_python.management import ManagementClient
from pathlib import Path
import getpass
bundle = Path.home() / "ZhiMuStereo/apps/ZhiMuStereo-0.2.6"
app = bundle / "apps/linux/Camera-headless"
if not app.is_dir():
    app = bundle / "apps/linux/Camera"
config = app / "config"
identity = CameraIdentity("15AA", "1555", "ACTUAL_HARDWARE_SN", "00")
with ManagementClient() as cloud:
    cloud.login("CUSTOMER_ACCOUNT", getpass.getpass("Password: "))
    synced = cloud.sync_customer_calibration(
        "ACTUAL_ASSET_UUID", "ACTUAL_LEDGER_CODE", identity,
        config_root=config, directory=Path.home() / "ZhiMuStereo/data/calibration-cache")
with Camera.open(identity, installation_root=app, config_root=config) as camera:
    camera.capture(with_depth=True, profile="quarter").save(Path.home() / "ZhiMuStereo/data/captures")