SCARA Robot Writing

项目状态	用途	入口	验证命令	下一步
archived（机器人学课程大作业）	保存 SCARA 轨迹书写的源码、报告、答辩与演示证据	trajectory_control_demo.m、deliverables/final/	matlab -batch "startup; runtests('tests');"	仅在需要复现或展示时恢复依赖

中文说明在前，English version below.

---

中文说明

项目目标

这是一个 MATLAB 机器人课程项目仓库。当前任务是搭建一个 R-R-R-P SCARA 机械臂演示系统，让它能够根据笔迹轨迹完成书写动作，并围绕这个任务完成：

• 轨迹处理
• 运动控制
• 仿真验证
• 演示视频
• 报告与展示材料

当前仓库的重点不是单纯的建模，而是把“轨迹输入 -> 控制计算 -> 动画演示”这条链路跑通。

当前已经完成的内容

• 可复用的 SCARA 机器人模型
• 原始轨迹的统一配置入口与 JSON/容错双路径解析
• 轨迹归一化、重采样、处理后 JSON 导出
• 带 anti-windup 的单点关节速度 PI 控制 demo
• 轨迹仿真与动画渲染解耦的整条笔画跟踪动画
• 全轨迹定量指标与 JSON 日志输出
• Windows 一键启动脚本与 PowerShell 桌面启动脚本
• MATLAB 基础回归测试

队友如何快速上手

最常用入口

• 集成演示：trajectory_control_demo.m
• 旧版场景演示：modeling.m
• Windows 启动脚本：scripts/run_trajectory_control_demo.cmd
• PowerShell 桌面启动脚本：scripts/open_trajectory_control_demo.ps1

在 MATLAB 中运行

先打开仓库根目录，再运行：

startup
trajectory_control_demo

如果要运行旧版场景演示：

startup
run('modeling.m')

命令行运行

在仓库根目录执行：

matlab -batch "startup; trajectory_control_demo;"

Windows 一键启动

直接运行：

scripts\run_trajectory_control_demo.cmd

如果需要从 PowerShell 中稳定拉起 MATLAB 桌面动画窗口，运行：

powershell -ExecutionPolicy Bypass -File .\scripts\open_trajectory_control_demo.ps1

目录说明

代码目录

• src/robot/：机器人结构、正逆运动学、笔头建模
• src/planning/：轨迹加载、归一化、重采样、跟踪计划生成
• src/control/：单点控制、轨迹仿真、动画渲染、指标计算
• src/config/：项目路径、规划、控制、场景统一配置
• src/utils/：JSON 写出等通用工具
• scripts/：启动脚本和辅助入口

数据目录

• data/trajectories/raw/：原始轨迹输入，新的轨迹文件放这里
• data/trajectories/processed/：处理后的标准轨迹输出

输出目录

• outputs/figures/：生成的预览图、误差图、动画快照
• outputs/videos/：演示视频
• outputs/logs/：日志文件

文档目录

• docs/assignment_requirements.md：作业要求摘要
• docs/project_status.md：当前完成度与后续待办

轨迹文件约定

新增轨迹文件时，建议按下面流程：

1. 把原始文件放到 data/trajectories/raw/
2. 运行 trajectory_control_demo
3. 检查轨迹预览和动画是否正常
4. 如有需要，再修改轨迹适配逻辑

不要直接手改 processed 目录里的输出文件，把它们当作程序生成结果看待。

当前主入口会展示什么

trajectory_control_demo 当前会展示四部分：

1. 原始轨迹预览
2. 处理后的纸面轨迹预览
3. 单点控制误差与电机速度命令
4. 单 3D 视角的 SCARA 写字动画场景

主动画场景始终保留这些元素：

• 机械臂本体
• 笔架
• 纸面
• 已写轨迹
• 当前目标点与笔尖位置

桌面模式下，轨迹动画窗口支持：

• 鼠标旋转 rotate3d
• 缩放 zoom
• 平移 pan
• 预设机位切换：Overview / Top / Rack / Paper

批处理模式下，动画窗口保留固定默认机位用于稳定导出。

当前典型输出

• data/trajectories/processed/trajectory_ordered_processed.json
• outputs/figures/trajectory_preview.png
• outputs/figures/single_point_control_demo.png
• outputs/figures/trajectory_tracking_animation.png
• outputs/logs/single_point_control_metrics.json
• outputs/logs/trajectory_tracking_metrics.json

当前验证结果

在当前默认参数下，主入口验证得到：

• 单点最终位置误差约 3.0 mm
• 全轨迹 RMS 误差约 6.0 mm
• 落笔阶段 RMS 误差约 2.5 mm

最终交付状态

课程报告、英文答辩 PPT、演示视频与本地 MATLAB 实现均已完成并归档。最终交付物集中在 deliverables/final/，过程性演示视频保存在 outputs/videos/。

协作约定

• 原始轨迹统一放 data/trajectories/raw/
• 生成图片、日志、视频不要留在仓库根目录
• 功能改动后至少跑一次测试或主入口 demo
• commit message 用英文，简短描述意图

归档阅读路径

• 项目过程与关键决策：docs/PROJECT_STORY.md
• 最终交付与验证边界：docs/ACCEPTANCE.md

---

English Overview

Project Goal

This repository is a MATLAB robotics course project. The current task is to build an R-R-R-P SCARA robot demo that can follow handwriting trajectories and demonstrate:

• trajectory processing
• motion control
• simulation validation
• demo generation
• report and presentation support

The main value of this repo is the full pipeline from trajectory input to control behavior to animation output.

What Is Already Implemented

• reusable SCARA robot model
• unified raw-trajectory entry with JSON-first parsing and malformed-input fallback
• trajectory normalization, resampling, and processed JSON export
• single-point joint-speed PI control demo with anti-windup
• full-stroke trajectory simulation decoupled from animation rendering
• quantitative metrics logging for both set-point and full-stroke tracking
• Windows one-click launcher and PowerShell desktop launcher
• basic MATLAB regression tests

Quick Start

Main integrated demo

From the repo root in MATLAB:

startup
trajectory_control_demo

Legacy scene demo

startup
run('modeling.m')

Command line

From the repo root:

matlab -batch "startup; trajectory_control_demo;"

Windows launcher

scripts\run_trajectory_control_demo.cmd

PowerShell desktop launcher

powershell -ExecutionPolicy Bypass -File .\scripts\open_trajectory_control_demo.ps1

Repository Structure

Source

• src/robot/: robot geometry, kinematics, brush rendering
• src/planning/: trajectory loading, normalization, resampling, planning
• src/control/: control demos, tracking simulation, animation rendering, metrics
• src/config/: centralized project configuration
• src/utils/: shared helper utilities
• scripts/: launchers and helper entry points

Data

• data/trajectories/raw/: incoming raw trajectory files
• data/trajectories/processed/: normalized outputs

Outputs

• outputs/figures/: generated figures and animation snapshots
• outputs/videos/: demo videos
• outputs/logs/: runtime logs

Docs

• docs/assignment_requirements.md
• docs/project_status.md

Team Workflow Suggestion

When a teammate contributes a new trajectory:

1. place the raw file under data/trajectories/raw/
2. run trajectory_control_demo
3. check both the preview and the animation
4. adjust parsing or normalization only if needed

Treat files under processed as generated outputs, not hand-edited sources.

What the Main Demo Shows

The current integrated demo includes:

1. raw trajectory preview
2. processed paper-space trajectory preview
3. single target-point controller behavior
4. a single 3D SCARA scene for writing animation

The main animation scene always keeps these objects visible:

• the robot arm
• the brush rack
• the writing paper
• the written stroke trace
• the current target point and brush tip

In MATLAB desktop mode, the animation window supports:

• rotate3d
• zoom
• pan
• preset view buttons: Overview, Top, Rack, Paper

In batch mode, the same scene uses a fixed default camera for stable export.

Current Outputs

• data/trajectories/processed/trajectory_ordered_processed.json
• outputs/figures/trajectory_preview.png
• outputs/figures/single_point_control_demo.png
• outputs/figures/trajectory_tracking_animation.png
• outputs/logs/single_point_control_metrics.json
• outputs/logs/trajectory_tracking_metrics.json

Current Verification Snapshot

With the current default configuration, the integrated demo reports:

• single-point final position error: about 3.0 mm
• full-trajectory RMS tracking error: about 6.0 mm
• pen-down RMS tracking error: about 2.5 mm

What Still Needs Work

The repo is already demo-ready, but still needs:

• final video packaging
• report and presentation preparation

Collaboration Notes

• keep raw trajectories in data/trajectories/raw/
• do not leave generated files in the repo root
• run at least one test or the main demo after a meaningful change
• use short English commit messages