ykcheungab
68edb0dc4c
本文件 L184-265 重复了 examples/README.md 已有的内容：示例清单、各产品入口、全部命令与参数、3dview 说明。删掉重复段落改为指向该文件，只保留首次运行所需的最短路径，并把 Windows/Ubuntu 的取 ID 步骤与运行结果合并，不再各写一遍。 验证：doc_count 1439/1775，doc_lint changed 与 --all 均干净。
7.6 KiB
title, description
| title | description |
|---|---|
| 快速开始 | 安装并运行 Orisys SDK 的基础步骤 |
快速开始
简介
本文件介绍如何上手和运行叠动视触觉传感器配套的SDK，进行图像处理，计算形变、力以及接触信息，接受从摄像头或视频文件中读取图像，处理后打印和展示处理后信息。
支持操作系统：Windows、Ubuntu
建议Python 版本: 3.10, 3.11, 3.12
项目链接：
基础环境设置
安装 Python 与 Anaconda
- 访问 Anaconda 官网 下载适合您操作系统的安装包（Windows、Linux）。
- 按照提示完成安装。
- 安装完成后，打开命令行终端（Windows 用户可在 “Anaconda Navigator” 打开 “Anaconda Prompt”），输入
conda info，若能显示 conda 的信息，则说明安装成功。
创建 conda 虚拟环境
虚拟环境相当于一个独立的 Python 工作空间，可以避免不同项目所需的库版本冲突。 打开命令行终端（或 Anaconda Prompt），依次输入以下命令（以 Python 3.10 为例）：
conda create -n orisys python=3.10
conda activate orisys
激活后，命令行提示符前会出现 (orisys) 字样，表示当前已进入虚拟环境。
创建工作区文件夹
“Anaconda Prompt” 启动后的默认工作路径在用户根文件夹中，建议创建工作区文件夹方便管理。可以手动创建文件夹，也可以运行 mkdir <path> 命令。例如：
mkdir orisys_ws
创建后如果要更换工作区，使用 cd <path> 命令，例如：
cd "C:\Users\orisys\orisys_ws"
安装 CUDA（可选）
如果您拥有 NVIDIA 显卡，并希望利用 GPU 加速计算，则需要安装 CUDA 工具包和 cuDNN。
-
方法一（官网下载）： 访问 NVIDIA CUDA Toolkit 官网 下载对应系统的 CUDA Toolkit 安装包，并按照提示安装。注意 12.x 和 13.x 的版本对应不同的 CuPy 库版本。
-
方法二（使用 Anaconda 安装，推荐）： 在已激活的 orisys 环境中直接运行以下命令（以 CUDA 12.9 为例）：
conda install nvidia/label/cuda-12.9.0::cuda-toolkit nvidia::cudnn
该方法会自动配置好 CUDA，无需手动下载。
注意：如果您的计算机没有 NVIDIA 显卡，或者不想使用 GPU 加速，可以跳过此步骤。套件也支持纯 CPU 运行（但速度可能较慢）。
安装 orisys SDK
推荐优先从 PyPI 安装。PyPI 会自动选择适合当前 Python 版本和操作系统的安装包，适合大多数用户。
使用 PyPI 安装（推荐）
确认已经激活 orisys 虚拟环境后，运行：
pip install orisys
如果需要升级到最新版本，运行：
pip install --upgrade orisys
如果当前网络无法访问 PyPI，或需要安装客服提供的指定版本，可以使用下方 .whl 文件安装方式。
使用 .whl 文件安装（离线或指定版本）
从官方渠道获取 .whl 文件，文件名格式通常为：
orisys-{版本}-{Python版本}-{Python版本}-{操作系统}_{硬件架构}.whl
例如 orisys-<版本>-cp310-cp310-win_amd64.whl 表示：
版本：<版本>（以实际下载的文件名为准，可用 python -c "import orisys; print(orisys.__version__)" 确认）
Python 版本：3.10（cp310）
操作系统：Windows（win）
硬件架构：64位（amd64）
请根据您的系统选择对应的文件，或者咨询客服索取。
将下载好的 .whl 文件放在一个文件夹中（如上述 orisys_ws 文件夹），打开命令行（确保已激活 orisys 环境或使用 “Anaconda Prompt”），使用 cd 命令切换到该文件夹，然后运行：
# 请将文件名替换为您实际下载的文件名
pip install orisys-<版本>-cp310-cp310-win_amd64.whl
安装 CuPy（可选）
注意：如果您没有安装 CUDA，或者使用 CPU 运行，可以跳过这一步。
CuPy 是一个与 NumPy 类似但支持 GPU 加速的库，您需要根据您安装的 CUDA 版本选择对应的 CuPy 版本。
方法一（使用 extras 参数，推荐）： 在安装 orisys 时，可以直接指定 CUDA 版本，pip 会自动安装配套的 CuPy：
# 如果您的 CUDA 版本是 12.x
pip install "orisys[cuda12]"
# 如果您的 CUDA 版本是 13.x
pip install "orisys[cuda13]"
如果之前已经安装了 orisys，可以单独安装 CuPy：
方法二（手动安装）：
# CUDA 12.x
pip install "cupy-cuda12x>=12.3.0"
# CUDA 13.x
pip install "cupy-cuda13x>=13.0.0"
测试安装
安装完成后，在命令行输入 python 命令进入 Python 环境，并导入 orisys 库查看版本号，验证是否成功：
python
进入 Python 后继续输入：
import orisys
print(orisys.__version__)
如果打印出版本号，则说明安装成功。
使用方法
使用设备专属的力标定参数
摄像头编号与设备 ID 是两个独立参数。命令中的 -v 0 或 --camera_id 0 只表示选择第 0 个视频源；device_id 才是传感器的设备编号（SN），目前需要人工确认并填写。
将这台设备实际测得的标定 JSON 放在自行选择的目录中，不要放进 SDK 的 config/，也不要覆盖 sensors/<产品>/force_calibration.json。目录结构如下，路径可由用户更改：
D:/orisys_data/calibrations/
├── box/
│ └── BOX-001.json
├── mini/
│ └── MINI-001.json
└── finger/
└── FINGER-001.json
例如，使用 BOX-001 时，calibration_dir 指向上图的 calibrations 目录，device_id 填 BOX-001：
import orisys
sensor = orisys.Sensor(
0, # 摄像头编号，不是设备 ID
config_name="box",
calibration_dir="D:/orisys_data/calibrations",
device_id="BOX-001",
verbose=True,
)
try:
print(sensor.calibration.source_path if sensor.calibration else "未加载标定")
print(sensor.force_units) # 依次为 FN、FX、FY 的单位
finally:
sensor.disconnect()
或者使用命令：
python examples/basic_pipeline.py -v 0 -c box --calibration-dir data/calibrations --device-id BOX-001
若该设备的标定文件不存在，SDK 不应用标定，力值保持 raw，也不会回退到产品默认标定。若文件存在，但其中的设备 ID、产品类型或测量设置与当前设备不匹配，SDK 会报错。FingerRuntime.open() 支持这两个参数，但 finger_pipeline.py 目前还没有对应的命令行参数。
运行示例程序
示例的完整清单、每个产品对应的入口、全部命令与参数，见 examples/README.md。这里只给第一次运行的最短路径。
先在仓库根目录（即 config/、examples/、assets/ 同级）确认传感器 ID：
- Windows：在 PowerShell 运行
Get-PnpDevice -PresentOnly | Where-Object { $_.Class -match '^Camera' }。若插上传感器后多出一行，ID 为1，否则为0。 - Ubuntu：运行
v4l2 --list-devices，从新增的设备名取编号（/dev/video0即 ID0）。
然后运行（假设 ID 为 0）：
python examples/basic_pipeline.py -v 0 -c box
窗口打开后按 q 停止，按 r 重设数据。若本地没有示例文件（例如通过 PyPI 安装），从项目链接下载。
开发套件使用方法
参考开发套件附带的开发文档。