企业官网建设流程全解析

MapMap OSC 协议深度指南：用 /mapmap 指令+正则批量控制全部映射图层

【免费下载链接】mapmapOpen source video mapping software项目地址: https://gitcode.com/gh_mirrors/ma/mapmap

MapMap 是一款开源视频映射（video mapping）软件，它内置完整的OSC（Open Sound Control）接口：默认监听 UDP12345端口，所有指令地址均以/mapmap开头。无论用整数编号还是通配符模式，你都可以一条指令批量控制全部映射图层（opacity、solo、visible 等属性），让序列器、MIDI 控制器或另一台电脑在演出中实时驱动 MapMap。

一、快速上手：MapMap 默认监听 UDP 12345，3 步发出第一条指令

1. 打开 MapMap 并加载你的映射项目；
2. 用任意 OSC 客户端向127.0.0.1:12345发送一条消息，例如/mapmap/play；
3. 看到画布开始播放，说明 OSC 通道已打通。🎬

💡 端口可按需修改：在偏好设置对话框中更改，或用启动参数mapmap --osc-port <端口号>（默认值 12345 定义在 src/core/MM.h）。完整的地址方案见项目根目录的 OSC 说明文件。

二、全局传输控制：/mapmap/play 等 4 条指令速查

这 4 条全局指令不需要任何参数，作用于所有素材，是现场演出最常用的"急停/启动"手段：

三、核心技巧：用编号或通配符模式批量选择映射图层

这是 MapMap OSC 协议最强大的部分。所有针对**素材（source）或图层（layer）**的指令，第一个参数都是"目标选择器"，支持两种方式：

• 整数：按 id 选中单个元素（编号从 1 开始）；
• 字符串：按名称匹配shell 风格通配符模式（即正则式的轻量写法），命中所有符合的元素——这就是"批量控制"的关键。

例如你有一批命名为clip01～clip12的视频素材，发送一条/mapmap/source/rewind "clip*"，12 个素材会同时倒回起点。

小知识：layer（图层）和mapping（映射）是同义词，两种写法都可以，图层本身就是映射。

四、图层属性指令清单：opacity、solo、visible 一键设置

4.1 常用属性

写法统一为/mapmap/layer/<属性> <目标> <值>，例如把所有mesh-开头的图层设为 50% 不透明：

/mapmap/layer/opacity "mesh-*" 0.5

4.2 几何指令：移动、平移与顶点

演出中调整映射范围时，几何指令同样支持通配符批量：

/mapmap/layer/move/xy <目标> <x> <y> 把图层中心移到 (x, y) /mapmap/layer/translate/xy <目标> <dx> <dy> 相对平移 /mapmap/layer/vertex/xy <目标> <顶点序号> <x> <y> 设置目标形顶点 /mapmap/layer/vertex/source/xy <目标> <顶点序号> <x> <y> 设置源形顶点

坐标使用 MapMap 内部坐标系（画布左上角为原点），具体数值可打开已保存的.mmp项目文件直接读取。

五、实战示例：3 条指令"指挥"整场秀

下图这类网格纹理常作为映射校准的测试图案，配合 OSC 指令可以快速做切换与调校：

一场演出的典型调度，只需要 3 条消息：

/mapmap/rewind 全部素材倒回起点，准备开场 /mapmap/layer/solo "mesh-1" 1 只显示 1 号墙面的映射 /mapmap/play 启动演出

结束前再补一条/mapmap/source/opacity "clip*" 0.1，所有视频素材瞬间淡出到 10%——整个过程不碰鼠标。✨

六、零依赖工具：用 mapmap-osc.py 快速发送测试

项目自带一个无需安装任何第三方库的 Python 命令行 OSC 客户端：scripts/mapmap-osc.py，它会自动识别参数类型（整数/浮点/字符串），也可以加i:、f:、s:前缀强制指定类型。

python3 scripts/mapmap-osc.py /mapmap/play python3 scripts/mapmap-osc.py /mapmap/layer/opacity 0 0.5 python3 scripts/mapmap-osc.py /mapmap/source/color 3 '#ff0000' python3 scripts/mapmap-osc.py --host 192.168.1.20 --port 9000 /mapmap/pause

想深入原理？指令的解析逻辑集中在 src/control/OscAction.cpp（地址 + 参数 → 动作的纯函数解析），消息接收与执行在 src/control/OscInterface.cpp，配套单元测试见 tests/TestOsc.cpp。

七、安全提醒：OSC 端口没有认证

OSC 端口不做身份验证——任何能访问该端口的设备都能控制你的 MapMap。正式演出时如果不想接收外部消息，请直接在防火墙封掉 12345 端口，或把 MapMap 运行在独立网络中。这也是官方刻意不通过 OSC 暴露项目文件读/写功能的原因。

掌握/mapmap地址体系后，配合编号与通配符模式，MapMap 就能被序列器、硬件控制器或脚本完全接管——这正是开源视频映射软件用于现场演出时的核心玩法。

【免费下载链接】mapmapOpen source video mapping software项目地址: https://gitcode.com/gh_mirrors/ma/mapmap