originplot

originplot 技能

0. 技能身份

技能名称： originplot
别名： originpro-external-plotting
中文名称： OriginPro 外部 Python 自动绘图 Skill
主要目标： 希望使用外部 Python 控制 Origin / OriginPro，进行科学、工程、实验或出版级绘图的任何人。
核心理念： 将 OriginPro 视为由 Python 控制的出版级渲染引擎，而非主要的数值计算引擎。

典型工作流：

Numerical computation / experiment
    -> standardized data file
    -> Python data adapter
    -> originpro automation layer
    -> Origin workbook / worksheet / matrix
    -> Origin graph template
    -> exported figure and saved OPJU project

---

1. 何时使用此技能

当用户希望进行以下操作时，使用此技能：

• 在外部 Python 环境中使用 originpro。
• 通过 Python 以编程方式控制 Origin / OriginPro。
• 将 CSV、DAT、TXT、Excel 或 NumPy 数据自动导入 Origin。
• 根据多个数据文件批量生成 Origin 图形。
• 自动应用 Origin 图形模板。
• 从 Origin 导出 PNG、TIFF、PDF、EPS、SVG 或其他出版级图形。
• 自动保存 Origin 项目 .opju。
• 将手动 Origin 绘图工作流转换为可重复使用的脚本。
• 调试外部 Python 与 OriginPro 自动化问题。
• 围绕 OriginPro 设计可重复使用的绘图工作流。
• 通过 OriginPro 制作 Nature 风格或面向高影响力期刊的科学图形。
• 围绕 GraphPage / GraphLayer / Plot 设计通用的“任意图形”控制架构。
• 通过 FigureSpec 等声明式配置驱动绘图。

---

2. 适用范围与非适用范围

此技能可以做什么

• 设计外部 Python + OriginPro 绘图架构。
• 提供可重复使用的 Origin 自动化 Python 代码框架。
• 帮助选择 Worksheet、Matrix、GraphPage、GraphLayer 和基于模板的绘图方式。
• 生成折线图、散点图、分组图、热图、矩阵图、等高线图和批量图。
• 将 Origin 模板作为首选的样式机制。
• 对 Nature 风格、适合论文的图形或面向高影响力期刊的图形，要求使用内置的调色板 / 样式规则。
• 帮助导出图形并保存 .opju 项目。
• 帮助用户清晰分离计算、数据准备、绘图和导出。
• 帮助调试常见的 originpro 自动化错误。
• 为任意图形定义通用的层级控制模型。
• 定义声明式 FigureSpec / LayerSpec / PlotSpec 协议，以便 Agent 一致地生成图形。

此技能不做什么

• 不将 Origin 用作大规模数值模拟的主要引擎。
• 不替代用于繁重计算的 Fortran / C++ / Python / MATLAB / HPC 工作流。
• 不鼓励 WSL/Linux 在官方外部软件包要求 Windows 和本地安装 Origin 的情况下直接调用 originpro。
• 当 Origin 模板是更好的抽象方式时，不要在 Python 中硬编码所有视觉样式。
• 不把 originpro 当作 matplotlib 的替代品。它是连接 Origin 的自动化桥接工具。

---

3. 需要记住的外部信息

稳定原则：

• originpro 是用于与 Origin 软件交互的高级 Python API。
• 外部 originpro 通过 Origin Automation Server / COM 控制 Origin。
• 它可以读取、写入和修改 Origin 数据对象，创建图形并导出图形。
• 外部 originpro 面向通过 Windows Python 控制本地 Origin 安装的场景。
• 应将 Origin 视为渲染和模板引擎；Python 则作为编排层。

适用时应包含的官方参考链接：

https://www.originlab.com/doc/ExternalPython
https://www.originlab.com/doc/ExternalPython/External-Python-Code-Samples
https://www.originlab.com/doc/python
https://www.originlab.com/doc/python/Examples/Graphing
https://www.originlab.com/doc/python/Examples/Origin-Python-Data-Exchange
https://pypi.org/project/originpro/

API 限制： 不要猜测未知的 originpro API。如果 API 不明确，请先查阅官方文档或检查已安装的软件包源代码，然后再编写代码；否则应说明不确定之处，并采用基于模板的替代方案。

---

4. 顶层架构

使用以下层级设计每个 OriginPro 自动化工作流：

1. Computation / acquisition layer
   Fortran, C++, Python, MATLAB, lab instruments, simulation, experiment

2. File/data layer
   CSV, DAT, TXT, XLSX, NPY, NPZ, HDF5, raw instrument output

3. Python data adapter layer
   pandas, numpy, unit conversion, column naming, reshaping, validation

4. Origin data object layer
   Workbook, Worksheet, Matrixbook, Matrixsheet

5. Origin graph object layer
   GraphPage, GraphLayer, Plot, Axis, Legend, Colormap

6. Template and styling layer
   .otpu, .otp, custom graph themes, journal styles

7. Export and archive layer
   PNG, TIFF, PDF, EPS, SVG, OPJU, logs

架构原则：

Computation belongs outside Origin.
Data normalization belongs in Python.
Visual style belongs mostly in Origin templates.
Automation and batching belong in Python.
Final figure quality belongs to Origin.

---

5. 通用图形层级控制模型

对于任意图形控制，本节为必需内容。任何图形都应分解为以下控制层：

L0 Runtime / Session
L1 Data
L2 Origin Data Object
L3 GraphPage
L4 GraphLayer
L5 Plot / Primitive
L6 Axis / Scale / Tick
L7 Legend / Label / Annotation
L8 Theme / Template / Style
L9 Export / Archive / QA

L0 运行时 / 会话

控制内容：

• 是否启动 Origin。
• 可见或隐藏模式。
• 新建项目或附加到现有项目。
• 异常安全关机。
• 输出、模板和日志目录。
• Windows Python 与 WSL 到 Windows 桥接。

L1 数据

控制内容：

• 数据源、架构、单位和语义。
• 缺失值 / 无效值。
• 排序、分组、规范化、重塑、透视。
• 语义角色，例如 x、y、group、size、error、z。

L2 Origin 数据对象

控制内容：

• 用于 XY、多 Y、分组表格、柱状图 / 散点图数据、原始 XYZ 数据的 Worksheet。
• 用于规则网格热图、等高线图和类图像数据的 Matrix。
• 当数据不规则或需要三角剖分式等高线绘制时，使用 Worksheet-XYZ。

决策规则：

Regular 2D field -> Matrix preferred
Tabular XY / grouped data -> Worksheet preferred
Irregular XYZ -> Worksheet XYZ

L3 GraphPage

控制内容：

• 整个图形画布。
• 单面板或多面板布局。
• 页面大小、边距、面板间距。
• 共享图例或共享色标策略。

L4 GraphLayer

控制内容：

• 每个面板 / 坐标系。
• 图层位置和大小。
• 图层中包含哪些绘图。
• 图层专属的轴标题、范围、面板标签和共享轴行为。

L5 绘图 / 基本图元

控制内容：

• 折线图、散点图、柱状图、误差线、热图、等高线图、面积图、曲面图、箱线图、小提琴图、气泡图。
• 数据字段到视觉通道的映射：

x, y, z, color, size, group, error, text

L6 轴 / 刻度 / 刻度线

控制内容：

• 轴标题和单位。
• 线性 / 对数刻度。
• 范围、留白、刻度、次刻度、刻度标签格式。
• 共享轴。
• 顶部 / 右侧边框的可见性。

L7 图例 / 标签 / 注释

控制内容：

• 图例。
• 面板标签 (a)、(b)、(c)。
• 标注框、箭头、文本注释、拟合方程、统计标记。
• 色标标签。

L8 主题 / 模板 / 样式

控制内容：

• 全局字体和线宽。
• 语义配色方案。
• 柱形填充、标记形状、色图、边框样式。
• Nature 或 PRL 等期刊样式。
• 最终样式优先使用 Origin 模板。

L9 导出 / 归档 / 质量检查

控制内容：

• 导出 PNG/PDF/SVG/TIFF/EPS。
• 保存 OPJU。
• 归档清理后的数据。
• 视觉质量检查和文件存在性检查。

通用控制顺序

对于任何图形，按以下顺序操作：

Data -> Object -> Layout -> Plot -> Axis -> Annotation -> Style -> Export

或展开为：

1. Define data semantics.
2. Choose the Origin data object.
3. Decide page layout.
4. Decide each layer's role.
5. Map data to plot primitives.
6. Configure axes.
7. Add legend/labels/annotations.
8. Apply theme/template.
9. Export and run QA.

---

6. 适用于任意图形的控制平面

当用户询问如何控制任意图形时，使用以下四个平面作答：

6.1 结构控制

回答的问题：

• 有多少个面板？
• 页面如何布局？
• 使用哪些 Origin 对象？
• 使用单页还是多页？

映射到：L2 + L3 + L4

6.2 语义控制

回答的问题：

• 各列代表什么？
• 哪些内容映射到 x/y/颜色/大小/误差？
• 哪个变量是比较维度？

映射到：L1 + L5

6.3 视觉控制

回答的问题：

• 字体、线宽、颜色、边框、图例样式、色图。

映射到：L6 + L7 + L8

6.4 交付控制

回答的问题：

• 导出哪些内容？
• 是否保存 OPJU？
• 是否归档清理后的数据？
• 是否执行质量检查？

映射到：L9

---

7. FigureSpec 协议概述

为了让 Agent 友好地生成任意图形，请使用声明式配置协议。

FigureSpec
    |- RuntimeSpec
    |- DataSpec[]
    |- PageSpec
    |- LayerSpec[]
    |- PlotSpec[]
    |- StyleSpec
    |- ExportSpec

设计原则：

FigureSpec describes WHAT to build.
Python/originpro executor decides HOW to build it.

完整协议请参阅配套文档 FIGURESPEC_PROTOCOL.md。

---

8. 建议的项目结构

originplot_project/
├── data/
│   ├── raw/
│   ├── processed/
│   └── README.md
├── specs/
│   ├── figure_2x2_nature.yaml
│   └── figure_single_heatmap.yaml
├── templates/
│   ├── line_basic.otpu
│   ├── line_multi_component.otpu
│   ├── scatter_basic.otpu
│   ├── heatmap_diverging.otpu
│   ├── contour_basic.otpu
│   ├── journal_style.otpu
│   └── nature_style.otpu
├── scripts/
│   ├── origin_session.py
│   ├── data_loader.py
│   ├── data_validator.py
│   ├── style_nature.py
│   ├── plot_line.py
│   ├── plot_scatter.py
│   ├── plot_heatmap.py
│   ├── plot_multipanel.py
│   ├── figurespec_executor.py
│   ├── batch_export.py
│   └── config.py
├── output/
│   ├── figures/
│   ├── opju/
│   ├── data/
│   └── logs/
└── README.md

---

9. 数据类型决策树

9.1 XY 或多 Y 曲线

使用 Worksheet。

9.2 XYZ 数据

如果是规则网格，则转换为 Matrix；否则使用 Worksheet XYZ。

9.3 矩阵数据

使用 Matrixsheet。

9.4 批量绘图

使用文件循环 + 一个通用模板 + 每次运行归档一个 OPJU。

---

10. 模板策略

优先采用以下最终工作流：

1. Manually create one ideal graph in Origin.
2. Save it as .otpu.
3. Let Python inject data and export.

保持以下内容相互分离：

Origin template controls:
    fonts, line widths, colors, legends, axis style, page size
Python controls:
    data, mapping, graph names, variable labels, output paths, batching

---

11. Nature 风格的强制规则

除非用户明确另有要求，否则 Nature 风格输出使用以下语义色板：

NATURE_PALETTE = {
    "blue_main":      "#0F4D92",
    "blue_secondary": "#3775BA",
    "green_1": "#DDF3DE",
    "green_2": "#AADCA9",
    "green_3": "#8BCF8B",
    "red_1":   "#F6CFCB",
    "red_2":   "#E9A6A1",
    "red_strong": "#B64342",
    "neutral_light": "#CFCECE",
    "neutral_mid":   "#767676",
    "neutral_dark":  "#4D4D4D",
    "neutral_black": "#272727",
    "gold":   "#FFD700",
    "teal":   "#42949E",
    "violet": "#9A4D8E",
    "magenta":"#EA84DD",
}

核心规则：

• 优先使用 Arial 或 Helvetica。
• 保持面板边框可见。
• 使用无边框图例。
• 始终一致地使用语义颜色。
• 默认使用稀疏刻度，不显示网格。
• 根据数据设置坐标轴范围。
• 保存 OPJU，并至少导出一个矢量格式文件。
• 仅在布局最终确定后添加 (a)、(b)、(c) 样式的面板标签。

---

12. 安装指南

pip install originpro pandas numpy pyyaml

外部模式必须在 Windows Python 中运行。

---

13. 标准会话封装

import sys
import originpro as op


def setup_origin(show=True, new_project=True):
    def origin_shutdown_exception_hook(exctype, value, traceback):
        try:
            op.exit()
        finally:
            sys.__excepthook__(exctype, value, traceback)

    if op and getattr(op, "oext", False):
        sys.excepthook = origin_shutdown_exception_hook
        op.set_show(show)

    if new_project:
        op.new()
    return op


def close_origin(save_path=None):
    if save_path:
        op.save(save_path)
    if getattr(op, "oext", False):
        op.exit()

---

14. 此技能的响应模式

回答任何绘图请求时，请按以下结构组织响应：

1. Data semantics
2. Origin data object choice
3. GraphPage / GraphLayer structure
4. Plot mappings
5. Axis strategy
6. Annotation strategy
7. Style / template strategy
8. Export / OPJU / QA strategy
9. Minimal working code or FigureSpec

---

15. 提供代码前的检查清单

确定：

1. Windows Python or WSL/Linux bridge?
2. Local Origin installed?
3. Data format?
4. Data type: XY, multi-Y, XYZ, matrix, batch?
5. Desired output: PNG, PDF, SVG, TIFF, OPJU?
6. Built-in template or custom .otpu?
7. Single figure or batch?
8. Needs Nature style or not?
9. For arbitrary figures: what are page, layer, plot, and annotation responsibilities?
10. Would FigureSpec be more reusable than hard-coded Python?

---

16. 最终设计原则

Use Python to automate.
Use OriginPro to render.
Use templates to standardize.
Use FigureSpec to formalize arbitrary figures.
Use OPJU to preserve editability.