# nuxyz

**Repository Path**: osr-tech/nuxyz

## Basic Information

- **Project Name**: nuxyz
- **Description**: 电动三轴平台精准定位工具，用于控制三轴平台的 Python 包，支持 USB HID 通信和 JupyterLab 交互式 GUI 界面。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-03
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎯 nuxyz: OSR电动三轴平台精准定位工具

> **版权声明**
> 本项目仅用于学习科研使用，如果您需要将本项目代码用于商业产品，请联系我们(sales@osr-tech.com)获取商业许可证。
> 如果本项目对您的研究和实验有帮助，可在工作中引用本工程，并推荐给其他人，我们不胜感激！

<p align="center">
<img src="images/xyz-1.png" width="400" alt="OSR电动三轴平台">
</p>

用于控制OSR电动三轴平台的 Python 包，支持 USB HID 通信和 JupyterLab 交互式 GUI 界面。

## 🌟 功能特性

- **⚡ 精确三轴控制** - 支持 X、Y、Z 三轴高精度位移控制
- **🔄 双坐标系统** - 支持绝对坐标（硬件原点）和软件坐标（用户自定义原点）
- **🖥️ 交互式 GUI** - 基于 JupyterLab 的图形化控制界面
- **📐 扫描区域规划** - 通过左上角和右下角定义扫描区域，自动生成扫描点网格
- **📊 坐标可视化** - 使用 plotly 显示扫描点和记录点，支持背景图片叠加
- **🕹️ 连续移动** - 支持操纵杆式连续移动操作
- **⌨️ 键盘控制** - 支持方向键和 PageUp/PageDown 控制移动

## 📦 安装

下载whl 安装包，使用 pip 进行安装。

```bash
pip install nuxyz-*.whl
```

## 🚀 快速开始

### 基本使用

```python
import nuxyz

# 初始化三轴平台（自动连接第一个找到的设备）
t = nuxyz.XYZGUI()

# 或指定序列号连接
t = nuxyz.XYZGUI(serial_number='315B36633033')

# 显示控制面板
t.pannel

# 获取当前坐标
t.get_xyz()

# 移动到指定坐标点
t.move_xyz(20516, -3885, 8734)
```

### 🎮 控制面板功能

`t.pannel` 面板提供以下功能：

- 📍 移动到指定坐标点
- 🔄 刷新当前坐标点
- 🎯 设置当前坐标点为相对坐标系原点 (0, 0, 0)
- 🏠 自动校准，回到绝对坐标原点

控制方式：
- 🖱️ 鼠标点击界面箭头图标
- ⌨️ 键盘快捷键：`↑` `↓` `←` `→` 控制 X/Y 轴，`PageUp` `PageDown` 控制 Z 轴

### 📐 扫描工作流程

```python
# 1. 设置软件原点（可选）
t.set_soft_origin()

# 2. 移动到扫描区域左上角并记录
t.set_top_left_corner()

# 3. 移动到扫描区域右下角并记录
t.set_bottom_right_corner()

# 4. 计算扫描点列表（5行 x 5列 = 25个点）
scan_points = t.compute_scan_point_list(5, 5)

# 5. 查看扫描点可视化
t.view_records()

# 6. 执行扫描
import time
for pos in scan_points:
    t.move_xyz(*pos)
    time.sleep(0.05)
    # 在此执行测量操作
```

### 👁️ 坐标记录可视化

```python
# 显示坐标记录界面
t.view_records()
```

`view_records()` 界面支持：
- 🖼️ 加载芯片表面图片作为背景
- 📍 直观查看扫描点相对于芯片的位置
- 🖱️ 点击坐标点更新 X、Y、Z 坐标值

## 📖 使用示例

详见 examples 中的 notebook。