CSV_stage 插件使用说明

一、插件作用

CSV_stage 用来把 CSV 表格里的灯具位置和旋转信息写入 grandMA2 的 Stage/3D 位置。

它读取固定文件名：

Stage-xyz.csv

插件会按照 CSV 里的 Fixture ID 去匹配 MA2 show 里已经配接好的灯具，然后把对应灯具的 X、Y、Z 位置和 Rotation X、Rotation Y、Rotation Z 写入 MA2。

注意：这个插件是做 Stage 位置，不是做 Layout Pool 排版。如果要根据 Stage 位置生成 Layout，需要用 Layout 相关插件。


二、使用前准备

1. 先在 MA2 show 里完成灯具配接。

2. 确认 CSV 里的 Fixture ID 和 MA2 show 里的 Fixture ID 一致。
   例如 CSV 里第一列是 101，show 里也必须有 Fixture 101。

3. 准备好 CSV 文件，文件名必须是：

   Stage-xyz.csv

4. CSV 建议使用 UTF-8 或普通 CSV 格式保存，不要保存成 xlsx。


三、CSV 文件格式

CSV 第一行表头建议保持下面这个格式：

Fixture ID,Name,Manufacturer,Mode,Patch,X/m,Y/m,Z/m,Rotation X/deg,Rotation Y/deg,Rotation Z/deg

每一列含义：

Fixture ID
MA2 里的灯具编号。这个是插件匹配灯具的关键字段，必须正确。

Name
灯具名称，只作记录或检查用。

Manufacturer
厂家名称，只作记录或检查用。

Mode
灯具模式，只作记录或检查用。

Patch
DMX 地址，只作记录或检查用。

X/m
灯具在 Stage 里的 X 位置，单位是米。

Y/m
灯具在 Stage 里的 Y 位置，单位是米。

Z/m
灯具在 Stage 里的 Z 高度，单位是米。

Rotation X/deg
X 轴旋转角度，单位是度。

Rotation Y/deg
Y 轴旋转角度，单位是度。

Rotation Z/deg
Z 轴旋转角度，单位是度。

示例：

Fixture ID,Name,Manufacturer,Mode,Patch,X/m,Y/m,Z/m,Rotation X/deg,Rotation Y/deg,Rotation Z/deg
1,Beam 1,ACME,17ch,1.1,-5,0,6,0,0,0
2,Beam 2,ACME,17ch,1.18,-4,0,6,0,0,0
101,Strobe 1,ACME,10ch,3.1,0,2,4.5,0,0,90


四、文件放置位置

如果从 U 盘读取：

把 Stage-xyz.csv 放到 U 盘的：

gma2/importexport/

完整结构应该类似：

U盘/gma2/importexport/Stage-xyz.csv

如果从电脑读取：

把 Stage-xyz.csv 放到当前 MA2 show 文件夹的：

gma2/importexport/

在 macOS / MA2 onPC 里，一般就是当前 show 对应的 importexport 文件夹。


五、插件安装

1. 把 CSV_stage.xml 和 CSV_stage.lua 放到：

   gma2/plugins/

2. 在 MA2 里打开 Plugin Pool。

3. 选择一个空的 Plugin 格子。

4. Import 导入 CSV_stage.xml。

5. 导入后，Plugin Pool 里会出现 CSV_stage 插件。


六、运行方法

1. 运行 CSV_stage 插件。

2. 插件会询问读取位置：

   输入 1 = 从 U 盘读取
   输入 2 = 从电脑 / 当前 show 文件夹读取

3. 输入对应数字后确认。

4. 插件会读取 Stage-xyz.csv。

5. 插件会按 Fixture ID 匹配灯具，并写入位置和旋转。

6. 执行完成后，打开 Stage/3D 视图检查灯具位置是否正确。


七、运行结果

正常情况下：

匹配到的 Fixture 会被移动到 CSV 指定的位置。

如果 CSV 里有旋转数据，对应 Fixture 的 Rotation 也会被写入。

CSV 里有但 show 里不存在的 Fixture ID 会被跳过。

show 里有但 CSV 里没有的 Fixture 不会被修改。


八、常见问题

1. 运行插件后没变化

检查 Stage-xyz.csv 是否放在正确目录。
检查文件名是否完全正确，必须是 Stage-xyz.csv。
检查 CSV 里的 Fixture ID 是否和 show 里的 Fixture ID 一致。
检查是否输入了正确来源：1 是 U 盘，2 是电脑。

2. 只改了一部分灯

通常是部分 Fixture ID 在 show 里不存在，或者 CSV 的 Fixture ID 写错。

3. 位置方向不对

检查 CSV 里的 X/m、Y/m、Z/m 是否来自同一个坐标系统。
如果是从 Vectorworks、SketchUp 或其他软件导出的坐标，需要确认前后、左右、高度轴向是否和 MA2 Stage 一致。

4. 高度不对

重点检查 Z/m 列。MA2 Stage 里的 Z 一般代表高度。

5. 旋转不对

检查 Rotation X/deg、Rotation Y/deg、Rotation Z/deg 是否是角度制，不要填弧度。
如果外部软件导出的是弧度，需要先转换成角度。

6. CSV 打开后乱码

尽量用 UTF-8 保存 CSV。
如果只是 Name 乱码，一般不影响位置写入；Fixture ID 和数值列正确就可以。

7. CSV 用 Excel 保存后出问题

确认保存的是 CSV，不是 xlsx。
确认表头没有被改名。
确认数值列里不要带单位，比如不要写 5m、90deg，只写 5、90。


九、建议工作流程

1. 先备份 show 文件。

2. 在外部软件或表格里整理好 Stage-xyz.csv。

3. 把 CSV 放进 gma2/importexport 文件夹。

4. 运行 CSV_stage 插件。

5. 打开 Stage/3D 检查位置。

6. 没问题后保存 show。


十、注意事项

CSV_stage 会修改 show 里灯具的 Stage 位置信息。正式项目运行前建议先保存一个备份。

如果 show 里原本已经有 Stage 位置，运行插件后，CSV 里匹配到的灯具位置会被新数据覆盖。

如果只是想根据 Stage 位置排 Layout Pool，不要用这个插件，应该用 StageLayoutBuilder / Layout 生成类插件。