ykcheungab
68edb0dc4c
本文件 L184-265 重复了 examples/README.md 已有的内容：示例清单、各产品入口、全部命令与参数、3dview 说明。删掉重复段落改为指向该文件，只保留首次运行所需的最短路径，并把 Windows/Ubuntu 的取 ID 步骤与运行结果合并，不再各写一遍。 验证：doc_count 1439/1775，doc_lint changed 与 --all 均干净。
202 lines
7.6 KiB
Markdown
202 lines
7.6 KiB
Markdown
---
|
||
title: 快速开始
|
||
description: 安装并运行 Orisys SDK 的基础步骤
|
||
---
|
||
|
||
# 快速开始
|
||
|
||
## 简介
|
||
本文件介绍如何上手和运行叠动视触觉传感器配套的SDK，进行图像处理，计算形变、力以及接触信息，接受从摄像头或视频文件中读取图像，处理后打印和展示处理后信息。
|
||
支持操作系统：Windows、Ubuntu
|
||
建议Python 版本: 3.10, 3.11, 3.12
|
||
|
||
项目链接：
|
||
|
||
- PyPI 安装页：[https://pypi.org/project/orisys/](https://pypi.org/project/orisys/)
|
||
- 项目文档/代码：[https://github.com/Orisys-Tech/orisys-sdk](https://github.com/Orisys-Tech/orisys-sdk)
|
||
|
||
## 基础环境设置
|
||
### 安装 Python 与 Anaconda
|
||
1. 访问 [Anaconda 官网](https://www.anaconda.com/download) 下载适合您操作系统的安装包（Windows、Linux）。
|
||
2. 按照提示完成安装。
|
||
3. 安装完成后，打开命令行终端（Windows 用户可在 “Anaconda Navigator” 打开 “Anaconda Prompt”），输入 `conda info`，若能显示 conda 的信息，则说明安装成功。
|
||
|
||
### 创建 conda 虚拟环境
|
||
虚拟环境相当于一个独立的 Python 工作空间，可以避免不同项目所需的库版本冲突。
|
||
打开命令行终端（或 Anaconda Prompt），依次输入以下命令（以 Python 3.10 为例）：
|
||
```bash
|
||
conda create -n orisys python=3.10
|
||
conda activate orisys
|
||
```
|
||
|
||
激活后，命令行提示符前会出现 `(orisys)` 字样，表示当前已进入虚拟环境。
|
||
|
||
### 创建工作区文件夹
|
||
“Anaconda Prompt” 启动后的默认工作路径在用户根文件夹中，建议创建工作区文件夹方便管理。可以手动创建文件夹，也可以运行 `mkdir <path>` 命令。例如：
|
||
|
||
```bash
|
||
mkdir orisys_ws
|
||
```
|
||
|
||
创建后如果要更换工作区，使用 `cd <path>` 命令，例如：
|
||
|
||
```bash
|
||
cd "C:\Users\orisys\orisys_ws"
|
||
```
|
||
### 安装 CUDA（可选）
|
||
如果您拥有 NVIDIA 显卡，并希望利用 GPU 加速计算，则需要安装 CUDA 工具包和 cuDNN。
|
||
|
||
1. 方法一（官网下载）：
|
||
访问 [NVIDIA CUDA Toolkit 官网](https://developer.nvidia.com/cuda/toolkit) 下载对应系统的 CUDA Toolkit 安装包，并按照提示安装。注意 12.x 和 13.x 的版本对应不同的 CuPy 库版本。
|
||
|
||
2. 方法二（使用 Anaconda 安装，推荐）：
|
||
在已激活的 orisys 环境中直接运行以下命令（以 CUDA 12.9 为例）：
|
||
|
||
```bash
|
||
conda install nvidia/label/cuda-12.9.0::cuda-toolkit nvidia::cudnn
|
||
```
|
||
|
||
该方法会自动配置好 CUDA，无需手动下载。
|
||
|
||
注意：如果您的计算机没有 NVIDIA 显卡，或者不想使用 GPU 加速，可以跳过此步骤。套件也支持纯 CPU 运行（但速度可能较慢）。
|
||
|
||
## 安装 orisys SDK
|
||
|
||
推荐优先从 PyPI 安装。PyPI 会自动选择适合当前 Python 版本和操作系统的安装包，适合大多数用户。
|
||
|
||
### 使用 PyPI 安装（推荐）
|
||
确认已经激活 `orisys` 虚拟环境后，运行：
|
||
|
||
```bash
|
||
pip install orisys
|
||
```
|
||
|
||
如果需要升级到最新版本，运行：
|
||
|
||
```bash
|
||
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` 命令切换到该文件夹，然后运行：
|
||
|
||
```bash
|
||
# 请将文件名替换为您实际下载的文件名
|
||
pip install orisys-<版本>-cp310-cp310-win_amd64.whl
|
||
```
|
||
|
||
### 安装 CuPy（可选）
|
||
注意：如果您没有安装 CUDA，或者使用 CPU 运行，可以跳过这一步。
|
||
|
||
CuPy 是一个与 NumPy 类似但支持 GPU 加速的库，您需要根据您安装的 CUDA 版本选择对应的 CuPy 版本。
|
||
|
||
方法一（使用 extras 参数，推荐）：
|
||
在安装 orisys 时，可以直接指定 CUDA 版本，pip 会自动安装配套的 CuPy：
|
||
|
||
```bash
|
||
# 如果您的 CUDA 版本是 12.x
|
||
pip install "orisys[cuda12]"
|
||
|
||
# 如果您的 CUDA 版本是 13.x
|
||
pip install "orisys[cuda13]"
|
||
```
|
||
如果之前已经安装了 orisys，可以单独安装 CuPy：
|
||
|
||
方法二（手动安装）：
|
||
|
||
```bash
|
||
# CUDA 12.x
|
||
pip install "cupy-cuda12x>=12.3.0"
|
||
|
||
# CUDA 13.x
|
||
pip install "cupy-cuda13x>=13.0.0"
|
||
```
|
||
|
||
### 测试安装
|
||
安装完成后，在命令行输入 `python` 命令进入 Python 环境，并导入 `orisys` 库查看版本号，验证是否成功：
|
||
```bash
|
||
python
|
||
```
|
||
|
||
进入 Python 后继续输入：
|
||
|
||
```python
|
||
import orisys
|
||
print(orisys.__version__)
|
||
```
|
||
如果打印出版本号，则说明安装成功。
|
||
|
||
## 使用方法
|
||
## 使用设备专属的力标定参数
|
||
|
||
摄像头编号与设备 ID 是两个独立参数。命令中的 `-v 0` 或 `--camera_id 0` 只表示选择第 0 个视频源；`device_id` 才是传感器的设备编号（SN），目前需要人工确认并填写。
|
||
|
||
将**这台设备实际测得**的标定 JSON 放在自行选择的目录中，不要放进 SDK 的 `config/`，也不要覆盖 `sensors/<产品>/force_calibration.json`。目录结构如下，路径可由用户更改：
|
||
|
||
```te
|
||
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`：
|
||
|
||
```python
|
||
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()
|
||
```
|
||
或者使用命令：
|
||
```bash
|
||
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`](../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` 即 ID `0`）。
|
||
|
||
然后运行（假设 ID 为 `0`）：
|
||
|
||
```bash
|
||
python examples/basic_pipeline.py -v 0 -c box
|
||
```
|
||
|
||
窗口打开后按 `q` 停止，按 `r` 重设数据。若本地没有示例文件（例如通过 PyPI 安装），从项目链接下载。
|
||
|
||
### 开发套件使用方法
|
||
参考开发套件附带的开发文档。 |