AddVignette 视频暗角光晕与镜头边缘衰减节点

节点核心功能 (What is it?)

AddVignette 节点为视频流添加高精度的镜头暗角（Vignette）或反向亮角光晕效果。它通过在画面四周由内向外模拟光学镜头的自然渐进式光线衰减（Natural Light Falloff），使画面视觉焦点自然汇聚至中央主体，赋予视频深邃的电影胶片质感与专业影调层次。

典型适用场景 (When would I use it?)

在以下情况下使用 AddVignette 节点：

• 强有力地将观者的视觉注意力吸引并引导至画面中心或特定主体；
• 为数字视频注入电影级镜头暗角与氛围感；
• 模拟大光圈物理镜头、复古相机或老式望远镜的光学边缘衰减；
• 赋予画面更强烈的明暗反差与情绪张力；
• 使用反向暗角（白光晕）营造梦幻、回忆或圣洁高调的视觉意境。

使用指南 (How to use it)

基础配置流程 (Basic Setup)

1. 在工作流画布中添加 AddVignette 节点。
2. 将输入视频连接至 video 输入插槽。
3. 调整暗角镜头发散角度（angle）、中心坐标偏移（center_x, center_y）及宽高比（aspect）。
4. 选择正向暗角（forward 压暗四周）或反向暗角（backward 提亮四周）。
5. 执行工作流，合成暗角特效的视频即刻生成。

参数输入插槽 (Parameters)

• video：待添加暗角的目标视频流（原生支持 VideoArtifact 与 VideoUrlArtifact）。
• angle：镜头暗角扩散发散角弧度（取值范围：0.1–3.14，默认值：0.628）：
  • 数值越小暗角越微弱收敛；
  • 0.1：极微弱细腻暗角；
  • 0.628：经典适中的标准电影暗角（默认）；
  • 3.14：极限重度暗角，压暗绝大部分边缘。
• center_x：暗角中心点水平偏移量（-1.0 至 1.0，默认值：0.0 正中心）：
  • -1.0：极左；0.0：水平居中；1.0：极右。
• center_y：暗角中心点垂直偏移量（-1.0 至 1.0，默认值：0.0 正中心）：
  • -1.0：顶部；0.0：垂直居中；1.0：底部。
• aspect：暗角渐变几何形状的宽高比（取值范围：0.1–10.0，默认值：1.0）：
  • 0.1：极扁平横向椭圆；
  • 1.0：正圆形暗角（默认）；
  • 10.0：极狭长竖向椭圆。
• mode：暗角模式下拉菜单（默认值："forward"）：
  • forward：经典暗角（四周渐变压暗）；
  • backward：反向暗角（四周渐变提亮白晕）。
• processing_speed：转码编码与画质平衡（fast / balanced / quality）。

输出引脚 (Outputs)

• video：完成镜头暗角渲染后的全新视频工件。

典型示例 (Example)

为人物肖像特写视频添加柔和电影暗角：

1. 将 LoadVideo 的输出连接至 AddVignette 的 video 输入插槽。
2. 将 angle 设为 0.5（适度温和的边缘压暗）。
3. 保持 center_x: 0.0 与 center_y: 0.0（正中对齐面部）。
4. 将 aspect 设为 1.0 形成正圆光晕衰减。
5. 选择 "forward" 经典暗角模式。
6. 运行工作流，导出的工件将带有平滑优雅的电影光晕，文件命名为 {original_filename}_vignette_a0.50_x0.00_y0.00_r1.00_forward.{format}。

关键技术特性 (Important Notes)

• 底层使用基于高次样条平滑过渡的 FFmpeg vignette 高保真算法，绝不产生生硬的阶梯感色阶断层；
• 原视频所有音轨与伴奏 100% 完整保留并精准对齐；
• 中心坐标支持偏移，特别适合主体处于三分法黄金分割线或偏离中心的人物构图。

参数调优专家建议 (Parameter Recommendations)

• 人物肖像 (Portraits)：angle: 0.4–0.6，中心居中 (0, 0)，aspect: 1.0；
• 风光宽幅大片 (Landscapes)：angle: 0.3–0.5，aspect: 1.5–2.0（拉宽暗角适配 16:9 宽屏）；
• 偏心构图主体：根据主体在画面中的实际重心，调节 center_x 与 center_y，使光晕正中精准套在主体头上；
• 戏剧感与悬疑张力：选用 angle: 1.5–2.5，压暗周围大面积无关背景。