# xv_xense

**Repository Path**: blouce/xv_xense

## Basic Information

- **Project Name**: xv_xense
- **Description**: 实现了 xv 和 xense 代码的 ros 采集，并对数据进行了处理
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-17
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xv_xense

> 机器人遥操作数据管道 —— 从 rosbag 解析、坐标系对齐、轨迹可视化，到基于触觉反馈的位姿预测网络。

## 项目概览

本项目提供一套完整的机器人遥操作数据处理与学习工具链，涵盖以下核心能力：

- **数据解析** — 将 rosbag 转换为结构化 JSON 和可视化 MP4
- **坐标系转换** — XV ↔ X2Robot 坐标系对齐，支持单臂/双臂模式
- **轨迹回放与可视化** — 数据回放、3D 轨迹对比、参考系切换
- **Delta 预测网络** — 基于触觉反馈和从端位姿，预测主端位置偏移

## 目录结构

```
xv_xense/
├── x2robot-rosbag-to-mp4/   # rosbag → JSON + MP4 转换与触觉数据注入
├── xv_x2robot/              # 坐标系旋转/对齐 + 数据回放 + 轨迹可视化
├── train_xense/             # Delta Predictor 神经网络训练与推理
├── data_process/            # 辅助数据处理工具
├── bash_scripts/            # 自动化脚本
├── data/                    # 数据目录
└── LICENSE                  # MIT License
```

## 环境要求

- Python 3.10+
- PyTorch ≥ 2.0（仅 `train_xense` 需要）
- 依赖详见各子模块 `requirements.txt`

## 各模块说明

### 1. x2robot-rosbag-to-mp4 — 数据解析

将 rosbag 文件解析为结构化 JSON 并生成可视化 MP4 视频，同时支持注入触觉传感器数据。

```bash
# 步骤一：解析 rosbag，生成 mp4 和 json
python batch_process.py source_dir output_dir

# 步骤二：注入触觉数据到 json
python batch_process_xense.py source_dir output_dir

# 步骤三：为 json 生成触觉可视化图片
python visualize_position_tactile.py input_dir [--ext .json]
```

详细说明见 [x2robot-rosbag-to-mp4/README.md](x2robot-rosbag-to-mp4/README.md)

### 2. xv_x2robot — 坐标系对齐 & 轨迹可视化

将 XV 坐标系数据旋转对齐到 X2Robot 法兰坐标系，支持单臂/双臂模式，并提供数据回放与 3D 轨迹可视化。

**坐标系对齐：**

```bash
# 单臂批量转换（支持 --arm left|right，默认 right）
python rotate_json_xv_x2robot.py -i xv_data_dir/ -o output_dir/ [--arm left|right] [--ref-first]

# 双臂对齐
python rotate_json_xv_x2robot.py --arm dual --left-arm xv_left.json --right-arm xv_right.json -o output.json
```

**数据回放：**

```bash
# 自变量数据回放
python replay_json_x2robot.py -i x2robot_data.json

# 无本体 → 自变量回放
python replay_json_x2robot.py -i x2robot_data.json --chunk-pause 0.1 --right-arm
```

**轨迹可视化：**

| 场景 | 命令 |
|------|------|
| 双臂 | `python vis_json_x2robot.py -i data.json -o dual.mp4 --mode dual` |
| 单臂 + 第一帧参考 | `python vis_json_x2robot.py -i data.json -o left.mp4 --mode single --ref first_frame` |
| 单臂 + 世界坐标 | `python vis_json_x2robot.py -i data.json -o left.mp4 --mode single --ref world` |
| XV 世界坐标 | `python vis_json.py -i data.json -o world.mp4 --ref world` |

详细说明见 [xv_x2robot/README.md](xv_x2robot/README.md)

### 3. train_xense — Delta Predictor

基于时序窗口的神经网络，在遥操作场景中利用从端（Follower）位姿和触觉反馈，预测主端（Master）相对于从端的位置偏移（delta）。

**核心思路：**

- **残差学习** — 网络预测 `delta = master_position - follow_position`
- **多尺度时序窗口** — 短窗口（~12 帧）捕获局部动态，长窗口（~40 帧）捕获全局轨迹
- **1D-CNN + Attention Pooling** — 替代传统 RNN/LSTM 的时序特征提取

**架构：**

```
Input (T, 48)
  ├─ Short Encoder: Conv1D(128) × 4 + AttentionPool → (128,)
  ├─ Long Encoder:  Conv1D(192) × 6 + AttentionPool → (192,)
  └─ Fusion: Concat → MLP(512) × 3 → Output(3)
```

**快速开始：**

```bash
# 安装依赖
pip install -r requirements.txt

# 训练
python train_from_json.py \
    --train-root /path/to/train_data \
    --test-root /path/to/test_data \
    --model-version 2 \
    --epochs 400

# 推理
python infer_and_fill_only_grasp.py \
    -i /path/to/input_json_dir \
    -o /path/to/output_json_dir \
    --checkpoint ./checkpoints/multiscale_predictor_best.pt

# 评估
python compute_delta_correlation.py \
    -i /path/to/test_data \
    --checkpoint ./checkpoints/multiscale_predictor_best.pt
```

详细说明见 [train_xense/README.md](train_xense/README.md)

### 4. data_process — 辅助工具

提供 rosbag 转 MP4（含/不含触觉可视化）和 JSON 排序等数据处理工具。

## 许可证

本项目基于 [MIT License](LICENSE) 开源。