TiXL 中 Cos 运算符实战：用余弦波驱动实时运动图形-开发者社区

音视频
图形学
桌面应用

【免费下载链接】t3

TiXL is an open source software to create realtime motion graphics.

项目地址：https://gitcode.com/GitHub_Trending/t3/t3

导读

Cos 是 TiXL 运算符库Lib.numbers.float.trigonometry中生成余弦波（cosine wave，又称 cosinusoidal wave / cosinusoid）的核心运算符。在实时运动图形（realtime motion graphics）制作中，它最常见的用途是把 Time 运算符的时间信号转换成周期性的往返运动——例如让图层平滑地上下浮动、左右摆动，或者驱动颜色、旋转、不透明度做有节奏的循环变化。阅读完本文，你将掌握 Cos 的输入输出结构、底层求值实现、与 Sin 及 AnimValue 等替代方案的选型思路，并能在 TiXL 图形编辑器中直接搭建可运行的余弦波动画。

Cos 运算符速览

Cos 属于 Lib.numbers.float.trigonometry 系列（该系列共三个运算符：Atan2、Cos、Sin）。其官方文档定义如下：

功能：Creates a cosine wave（生成余弦波）；
推荐组合：以 Time 作为输入；
替代方案：Sin（提供更多参数选项）；
相关参考：AnimValue、SampleCurve。

输入与输出

名称	类型	说明
Input	System.Single	输入值，典型用法为接入 Time 的输出
Result（输出）	System.Single	输入角度对应的余弦值，取值范围`[-1, 1]`

从节点的符号定义文件 Cos.t3 可以看到，Input 的默认值为0.0，即节点在无连接输入时输出Math.Cos(0) = 1。

底层实现：一次求值的完整链路

Cos 的 C# 实现位于 Cos.cs，核心逻辑极为简洁：

[Output(Guid = "4480F970-9E51-456A-8D66-D501FCA2C15B")] public readonly Slot<float> Result = new(); public Cos() { Result.UpdateAction += Update; } private void Update(EvaluationContext context) { Result.Value = (float)Math.Cos(Input.GetValue(context)); }

理解这段代码需要注意三点：

惰性求值：Result.UpdateAction += Update将Update注册为输出槽的更新动作。只有当下游节点真正请求Result的值时，Update才会被调用，这是 TiXL 求值框架（EvaluationContext）典型的按需求值机制，避免在每一帧无谓地计算未被消费的数值。
单输入单输出：Cos 只有一个InputSlot<float>与一个Slot<float>，不做任何周期、相位、幅值处理，直接调用Math.Cos得到结果。
返回值域：Math.Cos对任意输入返回[-1, 1]的值。也就是说，直接驱动位移时运动幅度固定在 ±1，如需更大行程，需要级联 Float 一类的算术节点进行缩放，或者改用参数更丰富的 Sin。

实战一：让图层随时间做往返运动

官方文档明确推荐“以 Time 作为输入”这一组合。TiXL 中的 Time 运算符输出随时间增长的时间值（可选择以小节/秒为单位，并支持SpeedFactor调速），把它接入 Cos 的 Input：

在节点图中放置 Time 与 Cos 两个节点；
将 Time 的Timefloat输出连接到 Cos 的Input输入；
将 Cos 的Result输出连接到目标图层的位移（Position）或旋转（Rotation）输入；
运行工程，观察图层以余弦规律往返摆动。

由于余弦函数的周期性，时间每增加2π（约 6.283 秒），波形完成一个完整周期。如果你希望波形的往返速度更快或更慢，可以在 Time 与 Cos 之间插入一个乘法节点对时间进行缩放，例如乘以2π / 期望周期秒数；Time 运算符自身的SpeedFactor输入也能直接调整时间流速。

实战二：通过复制 Sin 节点获得周期、相位、幅值控制

当需求超出“±1 范围内纯余弦摆动”时，官方文档给出的替代方案是 Sin。之所以说它“feature more options”，从 Sin.cs 的实现可以看得一清二楚：

Result.Value = (float)Math.Sin(Input.GetValue(context) / Period.GetValue(context) + Phase.GetValue(context)) * Amplitude.GetValue(context) + Offset.GetValue(context);

Sin 在余弦/正弦函数之外，还提供了四个可调节参数：

参数	类型	作用
Period	Single	控制波形在高点与低点之间波动的快慢（周期）
Phase	Single	将波形整体向前/向后平移（相位偏移）
Amplitude	Single	定义波形的最高与最低值（幅度）
Offset	Single	在输出上叠加/减去一个常数值（直流偏置）

因此当你需要精确控制动画的幅度与中心位置时，直接复制（Duplicate）一个 Sin 节点并接入相同的时间输入，即可得到带完整参数面板的波形输出；Cos 与 Sin 波形之间只相差 π/2 的相位，视觉上表现为“从最高点开始下降”与“从零点开始上升”的区别。

更多替代方案：AnimValue 与 SampleCurve

除 Sin 外，官方文档还列出了两个可参考的替代节点：

AnimValue：生成与当前 BPM 速率同步的 LFO 式周期信号，支持多种波形形状（Shape）、速率（Rate）、相位、幅度、偏置与 Bias 等参数，且可直接在图形编辑器中按住CTRL + 左键拖动实时调整速率与形状。它更偏“音乐节拍驱动”的动画场景，是 VJ 现场演出常用的节奏化工具。
SampleCurve：在 Lib.numbers.curve 系列中按时间采样自定义曲线，适合需要完全自定义、非正弦形状的动画需求。

选择建议：需要最纯粹的三角函数运算用 Cos；需要周期/相位/幅度控制用 Sin；需要与音乐 BPM 同步的 LFO 波形用 AnimValue；需要任意自定义波形用 SampleCurve。

节点在仓库中的位置与扩展方式

Cos 运算符在仓库中的完整文件三件套如下：

Cos.cs——C# 实现（求值逻辑与输入输出槽定义）；
Cos.t3——符号定义（输入默认值、连接关系）；
Cos.t3ui——编辑器 UI 布局（节点在画布上的位置与描述文本）。

其中Cos.t3ui中记录了输入槽的说明“Input value / Example: [Time]”，与官方文档“Useful combinations: [Time]”互相印证。如果你需要自定义一个“带周期、相位、幅度、偏移控制的余弦节点”，完全可以仿照 Sin.cs 的结构，把Math.Sin换成Math.Cos并保留四个输入槽即可——这正是 TiXL 运算符库“符号定义 + 自动生成文档”模式的直接体现（trigonometry README 注明文档由运算符库自动生成）。

小结

Cos 是 TiXL 中生成周期性余弦波的最小单元：一个输入、一个输出，底层即Math.Cos的一次调用。将它接入 Time 即可快速获得平滑的往返运动，配合缩放节点或直接改用 Sin/AnimValue/SampleCurve 则能进一步控制速度、相位、幅度与波形形状。对实时运动图形创作者而言，掌握 Cos 及其兄弟节点的求值机制，等于掌握了最基础的“周期性运动生成器”，足以支撑从简单摆动到复杂节拍动画的绝大部分需求。