Thu demo đơn tay với UMI và chạy SLAM pipeline chính thức
Đây là bài 3 trong series UMI + VLA. Bài này giả sử bạn đã có 1 UMI handheld unit hoạt động (xem bài 2).
Mục tiêu: bạn sẽ thu được ít nhất 20 demo chất lượng và xuất ra file replay_buffer.zarr.zip — đầu vào cho bài train policy ở bài 4.
Cài đặt môi trường
# Clone repo nếu chưa có
git clone https://github.com/real-stanford/universal_manipulation_interface.git
cd universal_manipulation_interface
# Tạo conda environment
conda create -n umi python=3.10 -y
conda activate umi
# Cài dependencies (theo README chính thức)
pip install -e .
Nếu repo có environment.yml hoặc requirements.txt riêng, dùng file đó thay cho pip install -e .. Kiểm tra README để xem version dependencies hiện tại.
Thiết lập workspace trước khi thu demo
1. Chọn task rõ ràng
Bắt đầu với task đơn giản, có kết quả quan sát được rõ ràng. Ví dụ tốt:
- Nhặt một khối hình vuông (20 cm x 20 cm) từ vị trí A đặt vào vị trí B
- Mở nắp hộp đơn giản
- Xếp vật thể vào khay
Tránh task mà success/failure khó đánh giá tự động.
2. Chuẩn bị workspace
[ ] Bàn phẳng, đủ diện tích (~60cm x 60cm workspace)
[ ] Ánh sáng đồng đều — tránh bóng mạnh từ 1 phía
[ ] Không có vật chuyển động trong background
[ ] Object được đặt trong vùng mà robot arm có thể reach
[ ] Calibration board (ChArUco/AprilTag) đặt cạnh workspace
3. Calibration trước khi thu
Chạy calibration một lần cho mỗi setup mới:
# Kiểm tra gripper range (min/max width)
python scripts/calibrate_gripper_range.py --help
# Kiểm tra latency giữa video và IMU
python scripts/calibrate_uvc_camera_latency.py --help
# Hand-eye calibration (UMI gripper trong world frame)
python scripts/calibrate_slam_tag.py --help
Đọc --help cho từng script để biết đối số cần thiết. Mỗi script có output file riêng (JSON calibration data). Lưu vào calib/ folder và không xóa.
Thu demo: quy trình chuẩn
Bước 1: Thiết lập GoPro
- Bật GoPro, chọn mode: Video, 4K hoặc 1080p, 60fps, Linear hoặc Fisheye mode
- Kiểm tra battery đầy hoặc cắm nguồn
- Kiểm tra SD card còn đủ dung lượng (~1-2 GB per 10 phút video)
- Bật GoPro trước khi bắt đầu demo — để IMU warm up
Bước 2: Đặt ArUco calibration board
Đặt calibration board trong góc workspace, visible từ camera GoPro trong ít nhất 10 giây đầu và 10 giây cuối mỗi demo. SLAM cần board này để khởi tạo coordinate frame.
Bước 3: Thu demo
Cầm UMI gripper, đứng trước workspace:
- Hướng camera về calibration board ~2 giây (để SLAM khởi tạo)
- Thực hiện task chậm và có chủ ý — tốc độ vừa phải, không nhanh hay giật cục
- Mở/đóng gripper rõ ràng tại điểm grasp và release
- Giữ trong 1-2 giây ở điểm grasp/release để encoder data ổn định
- Sau task, đưa camera về board thêm 1-2 giây
- Dừng recording
Số lượng demo tối thiểu:
| Mục đích | Số demo |
|---|---|
| Smoke test pipeline | 5 demos |
| Kiểm tra policy có học được không | 20 demos |
| Baseline đáng tin cậy | 50 demos |
| Production quality | 100-200 demos |
Bước 4: Tổ chức file
mkdir -p data/raw/task_pick_cube/session_001
# Copy video files từ GoPro vào thư mục này
# Đặt tên theo convention: demo_001.MP4, demo_002.MP4, ...
Chạy SLAM pipeline: 8 bước chính thức
Đây là core của toàn bộ quá trình xử lý. Pipeline gồm 8 script chính thức, chạy theo thứ tự:
Script 00: Process videos
python scripts_slam_pipeline/00_process_videos.py --help
Bước này xử lý raw GoPro video: chuyển đổi format, extract frames, chuẩn bị cho SLAM.
Script 01: Extract GoPro IMU
python scripts_slam_pipeline/01_extract_gopro_imu.py --help
Trích xuất dữ liệu IMU (accelerometer + gyroscope) từ metadata của file GoPro .MP4. IMU này là thứ làm UMI khác biệt với systems chỉ dùng visual odometry.
Script 02: Create map
python scripts_slam_pipeline/02_create_map.py --help
Dùng calibration board và ORB-SLAM3 để tạo sparse map của workspace. Bước này thường cần 1-2 "mapping clip" — clip chạy chậm xung quanh workspace mà không thu demo.
Nếu bước này fail: kiểm tra calibration board có visible rõ không, ánh sáng đủ không, và GoPro fisheye mode đang bật.
Script 03: Batch SLAM
python scripts_slam_pipeline/03_batch_slam.py --help
Chạy SLAM trên tất cả demo videos để tính trajectory 6DoF của gripper. Đây là bước tốn thời gian nhất (~1-5 phút per demo tùy độ phức tạp).
Expected output: file trajectory cho mỗi demo, dạng pose_left.csv hoặc tương tự.
Kiểm tra sau khi chạy:
# Trajectory phải smooth, không có jumps lớn
# Nếu có nhiều NaN hoặc pose jump > 5cm/frame → demo đó có thể bị loại
Script 04: Detect ArUco
python scripts_slam_pipeline/04_detect_aruco.py --help
Detect ArUco marker trên jaw của gripper trong mỗi frame → tính gripper width theo thời gian.
Nếu detection rate thấp (<70%): tag có thể bị blur (tốc độ quá cao), ánh sáng không đủ, hoặc tag quá nhỏ. Giải pháp: in tag lớn hơn, thu lại với tốc độ chậm hơn.
Script 05: Run calibrations
python scripts_slam_pipeline/05_run_calibrations.py --help
Kết hợp calibration data (camera intrinsics, extrinsics, timing offset) với trajectory data. Output là calibrated poses.
Script 06: Generate dataset plan
python scripts_slam_pipeline/06_generate_dataset_plan.py --help
Tạo plan file xác định: demo nào được dùng, timing window, action representation convention. Đây là nơi bạn có thể loại bỏ demo chất lượng thấp.
Review output file của bước này — nó list ra tất cả demos và validity flags. Loại bỏ demos có:
- Trajectory không smooth (drift > threshold)
- Gripper width detection rate thấp
- Duration quá ngắn (<2 giây)
- Robot IK infeasible (nếu bạn đã setup IK filter)
Script 07: Generate replay buffer
python scripts_slam_pipeline/07_generate_replay_buffer.py --help
Script cuối cùng: tổng hợp tất cả data thành replay_buffer.zarr.zip. Đây là file bạn sẽ dùng để train Diffusion Policy ở bài 4.
Verify output:
python -c "
import zarr
z = zarr.open('replay_buffer.zarr.zip', 'r')
print(z.tree())
print('Total demos:', len(z['meta']['episode_ends']))
"
Output phải có các keys: robot0_eef_pos, robot0_eef_rot_axis_angle, robot0_gripper_width, camera0_rgb.
Kiểm tra chất lượng data
Đừng train trên raw output. Kiểm tra trước:
1. Visualize trajectory của 3-5 demo ngẫu nhiên
python scripts/slam_pose_replay.py --help
Trajectory phải smooth. Nếu thấy teleport hay drift lớn → demo đó không nên dùng.
2. Check gripper width
Width signal phải:
- Không bị stuck ở 0 hoặc max trong suốt demo (trừ lúc grasp/release)
- Smooth, không noisy đột ngột
- Khớp với timing bạn nhớ khi thực hiện demo
3. Check frame count
Mỗi demo phải có frame count hợp lý cho duration. Nếu FPS thực tế thấp hơn expected → video processing có vấn đề.
Cấu trúc file sau khi xử lý
data/
├── raw/
│ └── task_pick_cube/
│ └── session_001/
│ ├── demo_001.MP4
│ ├── demo_002.MP4
│ └── ...
├── processed/
│ └── task_pick_cube/
│ ├── trajectories/
│ ├── gripper_width/
│ └── dataset_plan.json
└── replay_buffer.zarr.zip ← output cho bài 4
Lỗi thường gặp
| Lỗi | Nguyên nhân | Fix |
|---|---|---|
| SLAM tracking fail | Không đủ features trong background | Thêm texture vào workspace (dán sticker pattern) |
| ArUco detection rate thấp | Motion blur hoặc ánh sáng | Thu chậm hơn, đèn tốt hơn, tag lớn hơn |
| Replay buffer thiếu key | Pipeline bị interrupt | Chạy lại từ script 06-07 |
| Demo bị reject hàng loạt | Workspace quá nhỏ | Mở rộng workspace, tránh IK limits |
| IMU data missing | GoPro model không support | Dùng GoPro Hero 7 Black trở lên |
Definition of done — trước khi sang bài 4
[ ] Ít nhất 20 demo chất lượng đã collect
[ ] Tất cả 8 SLAM scripts đã chạy thành công
[ ] replay_buffer.zarr.zip có đầy đủ keys
[ ] Visualize 3-5 trajectories → smooth
[ ] Gripper width signal hợp lý
[ ] Dataset plan không có too many rejected demos
Nếu checklist OK — tiếp tục bài 4: train Diffusion Policy.
