Spotlight 效果在图像处理中用来模拟舞台追光灯把视觉焦点集中到画面某个主体上。很多视频剪辑工具都有类似滤镜但如果需要批量处理、精细控制灯光位置或者把灯光和运动轨迹绑定到程序里手动操作就很难满足要求。这篇文章会从零实现一个基于 Python 和 OpenCV 的 spotlight 效果工具支持任意图像、多个光源、可调强度和羽化还能把效果应用到视频帧上。之所以强调“改编版”和“完整版”是因为很多公开示例只实现了一个固定圆心的聚光灯缺少羽化、多光源、动态轨迹、视频支持这些生产环境常用的能力。这篇文章会把这些能力补全用函数式结构组织代码方便你直接放在自己的图像或视频处理流水线里。学完后你可以把它用于商品图高亮、舞台背景模拟、演示视频制作、直播推流前的测试画面处理等场景。1. 先理解 Spotlight 效果的本质再开始写代码1.1 聚光灯效果在图像处理里是什么从图像处理角度看聚光灯效果就是通过一个掩膜mask控制“亮的区域”和“暗的区域”让画面只有一个局部是明亮的其他区域变暗。这个局部通常是一个圆形或者椭圆中心最亮边缘逐渐衰减。衰减的过程称为羽化feathering羽化做得越柔和灯光过渡越自然。实现时并不需要复杂的深度学习模型只需要两步生成一张与输入图像同尺寸的灰度掩膜掩膜中灯光中心像素值为 255边缘为 0中间按距离渐变。用掩膜对原图做权重合成中心区域保留原图亮度边缘以外的区域压暗。这里的核心变量是“距离”。离灯光中心越近的像素保留的亮度越多离中心越远的像素亮度被压得越低。因此生成掩膜本质上就是计算每个像素到灯光中心的距离再映射到 0 到 255 的灰度范围。1.2 为什么不用现成滤镜而要用代码实现视频剪辑软件和图像编辑器里都有类似“径向模糊”“灯光效果”的滤镜但那些方案的问题在于不能批量处理大量图片。灯光位置和半径很难用参数精确控制。无法在视频序列中让灯光按坐标轨迹移动。无法把灯光效果嵌入到自己的程序、服务或者自动化流程中。用 Python 和 OpenCV 实现之后你可以把灯光坐标、半径、羽化量、强度都变成函数参数甚至从文件中读取每一帧的灯光坐标生成动态追光视频。这个能力适合做一些自动化渲染、商品展示、舞台背景模拟等工作。1.3 技术路线选择OpenCV NumPyOpenCV 负责图像读取、图像缩放、颜色空间转换、视频读写NumPy 负责矩阵运算和掩膜计算。两者是目前最成熟、最稳定的组合。本文的代码不需要 GPU普通 CPU 就能运行对于 1080p 的单帧图片单光源处理时间通常在几十毫秒级别。注意如果你只需要处理单张静态图片也可以用 Pillow 完成但后续做视频、实时摄像头处理时OpenCV 的VideoCapture和VideoWriter会方便得多。因此本文统一使用 OpenCV。2. 环境准备和依赖安装先跑通最小环境2.1 版本和平台要求本文示例代码基于 Python 3.9、OpenCV 4.x、NumPy 1.21。这三个版本组合在 Windows、macOS、Linux 上都能正常工作。如果你使用的是较新版本代码依然兼容如果使用的是 Python 2.7 或者 OpenCV 3.x建议先升级因为后面用到的cv2.imread、cv2.VideoWriter在旧版本中的行为略有差异。安装命令如下python -m venv venv source venv/bin/activate # Windows 使用 venv\Scripts\activate pip install opencv-python numpy如果你的网络环境比较慢可以使用国内镜像源安装pip install opencv-python numpy -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后运行下面的命令验证版本import cv2 import numpy as np print(OpenCV version:, cv2.__version__) print(NumPy version:, np.__version__)预期输出类似OpenCV version: 4.9.0 NumPy version: 1.26.42.2 准备测试图片为了看到明显效果准备一张背景比较亮的图片会更好。你可以在当前目录下放一张input.jpg尺寸随意代码里会自动处理缩放。如果没有现成图片可以用 OpenCV 生成一张纯色测试图import numpy as np import cv2 # 生成一张 640x480 的灰色测试图 img np.full((480, 640, 3), 200, dtypenp.uint8) cv2.imwrite(input.jpg, img)这张图整幅都是浅灰色方便观察聚光灯效果中心区域保持 200 亮度边缘区域变暗。后面处理真实照片时效果会更直观。2.3 环境检查清单写代码之前建议按下面清单快速检查环境避免后面被低级问题卡住检查项验证命令正常结果Python 版本python --version3.9 以上OpenCV 是否安装python -c import cv2; print(cv2.__version__)打印 4.x 版本号NumPy 是否安装python -c import numpy; print(numpy.__version__)打印 1.21 以上版本号测试图片是否存在ls -l input.jpg文件存在且可读视频编解码是否正常运行后面视频示例能生成输出文件且可播放3. 实现最小版 spotlight理解掩膜合成原理3.1 核心思路圆形渐变掩膜假设图片宽高为W和H灯光中心在(cx, cy)灯光半径为radius。那么每个像素(x, y)到中心的欧氏距离为distance sqrt((x - cx)^2 (y - cy)^2)把distance映射到 0 到 255 的灰度值距离为 0灰度值为 255即灯光中心最亮。距离大于等于radius灰度值为 0即灯光外完全变暗。距离在0到radius之间灰度值线性衰减。最简单的映射是alpha 1 - distance / radius alpha clip(alpha, 0, 1) gray alpha * 255这种线性衰减会让灯光边缘有点生硬。更自然的效果是把线性值做一次幂运算比如alpha (1 - distance / radius) ** 2这样中心更亮边缘衰减更快。这个参数后面会称为“柔光强度”。3.2 用 NumPy 生成掩膜NumPy 的优势是可以用矩阵操作批量计算所有像素的距离不用写双重 for 循环。先生成坐标网格import numpy as np import cv2 def create_spotlight_mask(height, width, center, radius, softness2.0): 生成聚光灯掩膜。 Args: height: 图像高度 width: 图像宽度 center: (cx, cy) 灯光中心坐标 radius: 灯光半径单位为像素 softness: 羽化强度大于 1 的边缘过渡更柔和 Returns: uint8 类型的掩膜灯光中心为 255外部为 0 y_indices, x_indices np.indices((height, width)) cx, cy center distance np.sqrt((x_indices - cx) ** 2 (y_indices - cy) ** 2) # 距离归一化到 0~1大于 1 的截断为 1 normalized np.clip(distance / radius, 0, 1) # 用幂函数控制羽化softness 越大边缘过渡越柔和 alpha (1 - normalized) ** softness mask (alpha * 255).astype(np.uint8) return mask这里有一个容易误解的地方softness并不是“模糊半径”而是控制衰减曲线的形状。softness1时是线性衰减softness2时中心附近更亮边缘迅速变暗softness越大灯光范围看起来越小但边界更自然。3.3 将掩膜应用到图像有了掩膜之后合成公式如下result image * (mask / 255) image * (1 - mask / 255) * dark_ratio也可以拆成两步mask_float mask.astype(np.float32) / 255.0 inverse_mask 1.0 - mask_float # 灯光区域内保留原图灯光外部区域压暗到 dark_ratio result cv2.multiply(image, mask_float[:, :, None]) \ cv2.multiply(image, (inverse_mask * dark_ratio)[:, :, None])说明mask_float[:, :, None]是为了把形状从(H, W)扩展到(H, W, 1)方便和(H, W, 3)的彩色图相乘。dark_ratio是外部暗区保留的亮度比例取值范围 0 到 1。dark_ratio0.3表示灯光外区域只保留原图 30% 的亮度。cv2.multiply会自动处理溢出和类型转换比直接用*更稳妥。完整的最小代码如下import cv2 import numpy as np def create_spotlight_mask(height, width, center, radius, softness2.0): y_indices, x_indices np.indices((height, width)) cx, cy center distance np.sqrt((x_indices - cx) ** 2 (y_indices - cy) ** 2) normalized np.clip(distance / radius, 0, 1) alpha (1 - normalized) ** softness mask (alpha * 255).astype(np.uint8) return mask def apply_spotlight(image, center, radius, dark_ratio0.2, softness2.0): h, w image.shape[:2] mask create_spotlight_mask(h, w, center, radius, softness) mask_float mask.astype(np.float32) / 255.0 mask_3d mask_float[:, :, None] inv_3d 1.0 - mask_3d bright_part cv2.multiply(image, mask_3d) dark_part cv2.multiply(image, (inv_3d * dark_ratio).astype(np.float32)) result cv2.add(bright_part, dark_part) return result if __name__ __main__: image cv2.imread(input.jpg) if image is None: raise FileNotFoundError(input.jpg 不存在请检查图片路径) h, w image.shape[:2] center (w // 2, h // 2) radius min(w, h) // 3 result apply_spotlight(image, center, radius) cv2.imwrite(output_spotlight.jpg, result)运行python spotlight_minimal.py运行结束后打开output_spotlight.jpg正常情况下图片中心区域保持原图亮度四周明显变暗且过渡平滑。3.4 两个关键参数dark_ratio 和 softness这两个参数决定了最终视觉效果先记住它们的作用参数含义推荐范围调大效果调小效果dark_ratio灯光外区域保留的亮度比例0.1 到 0.4外部变亮灯光对比度降低外部变暗主体更突出softness衰减曲线指数1.0 到 3.0边缘过渡更柔和灯光范围更集中灯光衰减更接近线性边缘生硬如果发现灯光边缘有肉眼可见的圆形断裂线说明softness太小或者radius设置得太大。通常softness2.0在大多数图片上都有不错的表现。4. 扩展成完整版多光源、羽化控制和视频处理4.1 多光源叠加真实舞台灯光往往不止一个光源。多光源的处理方式是为每个光源分别生成掩膜然后把多个掩膜合并成一张总掩膜。合并方式不是求平均值而是取最大值因为只要有任意一个光源照到该区域该区域就应该亮。实现代码如下def merge_masks(mask_list): 将多个掩膜合并为一张。 合并方式每个像素取所有掩膜中的最大值。 if not mask_list: raise ValueError(mask_list 不能为空) merged np.maximum.reduce(mask_list) return merged def apply_multi_spotlight(image, light_points, dark_ratio0.2, softness2.0): h, w image.shape[:2] masks [] for center, radius in light_points: mask create_spotlight_mask(h, w, center, radius, softness) masks.append(mask) merged merge_masks(masks) mask_float merged.astype(np.float32) / 255.0 mask_3d mask_float[:, :, None] inv_3d 1.0 - mask_3d bright_part cv2.multiply(image, mask_3d) dark_part cv2.multiply(image, (inv_3d * dark_ratio).astype(np.float32)) return cv2.add(bright_part, dark_part)调用示例light_points [ ((200, 200), 150), ((600, 350), 180), ] result apply_multi_spotlight(image, light_points, dark_ratio0.15, softness2.5) cv2.imwrite(output_multi_spotlight.jpg, result)这里使用np.maximum.reduce而不是np.mean是因为均值会让重叠区域变亮但也会让非重叠区域变暗不够真实。取最大值能保证每个光源覆盖范围内都有足够的亮度。4.2 支持羽化半径独立控制有些场景希望中心区域非常亮但边缘衰减范围很大因此可以给每个光源分别配置softness。改造数据结构把原来的(center, radius)扩展为(center, radius, softness)def apply_multi_spotlight_flexible(image, light_specs, dark_ratio0.2): h, w image.shape[:2] masks [] for center, radius, softness in light_specs: mask create_spotlight_mask(h, w, center, radius, softness) masks.append(mask) merged merge_masks(masks) mask_float merged.astype(np.float32) / 255.0 mask_3d mask_float[:, :, None] inv_3d 1.0 - mask_3d bright_part cv2.multiply(image, mask_3d) dark_part cv2.multiply(image, (inv_3d * dark_ratio).astype(np.float32)) return cv2.add(bright_part, dark_part)调用示例light_specs [ ((200, 200), 150, 2.0), ((600, 350), 180, 1.5), ] result apply_multi_spotlight_flexible(image, light_specs, dark_ratio0.15)这样每个灯光的边缘过渡可以独立调节不再受全局参数限制。4.3 灯光遮罩支持椭圆形状圆形灯光在人物脸部特写或商品展示中不太自然因为真实光束常被天花板或舞台设备遮挡成椭圆。改成椭圆只需要在距离计算时除以横向和纵向各自的半径def create_ellipse_spotlight_mask(height, width, center, rx, ry, softness2.0): y_indices, x_indices np.indices((height, width)) cx, cy center distance np.sqrt(((x_indices - cx) / rx) ** 2 ((y_indices - cy) / ry) ** 2) normalized np.clip(distance, 0, 1) alpha (1 - normalized) ** softness mask (alpha * 255).astype(np.uint8) return mask这里rx是椭圆横向半径ry是纵向半径。距离计算时分别除以自身半径让标准距离为 1 的时候正好落在椭圆边界上。其余合成逻辑不变。4.4 应用到视频让灯光跟随轨迹移动视频处理的本质是逐帧处理。你可以从外部文件读取灯光中心坐标也可以根据时间函数生成运动轨迹。下面用一个简单例子演示灯光中心先从左向右移动再从上向下移动形成一个 L 形扫动路径。import cv2 import numpy as np def process_video(input_video, output_video, dark_ratio0.2, softness2.0): cap cv2.VideoCapture(input_video) fps cap.get(cv2.CAP_PROP_FPS) width int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) height int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) frame_count int(cap.get(cv2.CAP_PROP_FRAME_COUNT)) fourcc cv2.VideoWriter_fourcc(*mp4v) writer cv2.VideoWriter(output_video, fourcc, fps, (width, height)) if not writer.isOpened(): raise RuntimeError(VideoWriter 打开失败请检查编码器和输出路径) frame_index 0 radius min(width, height) // 3 while True: ret, frame cap.read() if not ret: break # 根据帧序号计算灯光位置形成从左到右的移动轨迹 progress frame_index / max(frame_count - 1, 1) cx int(radius progress * (width - 2 * radius)) cy height // 2 result apply_spotlight(frame, (cx, cy), radius, dark_ratio, softness) writer.write(result) frame_index 1 if frame_index % 30 0: print(f已处理 {frame_index}/{frame_count} 帧) cap.release() writer.release() if __name__ __main__: process_video(input_video.mp4, output_spotlight_video.mp4)运行后视频中的灯光会从左向右平滑移动。如果你想做更复杂的轨迹可以在外部准备一份trajectory.csv里面记录每一帧的light_x和light_y程序读取后应用到对应帧。注意OpenCV 的VideoWriter输出格式是固定的默认写成mp4v编码的 MP4 文件。如果输出文件无法在播放器中打开可以换成XVID或MJPG或者用 FFmpeg 做一次转封装。5. 参数详解和调参建议5.1 灯光中心坐标(cx, cy)中心坐标决定高亮区域的位置。单位是像素左上角为原点。设置时要避免中心太靠近图像边缘否则一半灯光会被切掉。如果灯光超出图像边界可以在生成掩膜前把center限制在有效范围内cx int(np.clip(cx, 0, width - 1)) cy int(np.clip(cy, 0, height - 1))5.2 灯光半径radiusradius是灯光覆盖区域的基础半径。取值太小高光只出现在很小区域主体无法完全照亮取值太大整张图都是亮的失去聚光灯对比效果。一般建议让灯光覆盖主体区域外接圆直径的 60% 到 80%。5.3 暗部保留比例dark_ratio这个参数控制场景暗到多少。dark_ratio0灯光外部全黑。dark_ratio0.3外部保留 30% 亮度观感柔和。dark_ratio0.6暗部不明显适合只需要轻微对比的场景。如果处理后主体与暗部边界不清晰适当调低dark_ratio。如果暗部出现明显偏色检查输入图像是否为 RGB 或 BGR 格式不要直接处理灰度图后想保留彩色。5.4 羽化指数softnesssoftness影响过渡曲线的形状。数值越大中心越亮、边缘越暗灯光范围看起来越小数值越小过渡越线性灯光范围看起来越大。参见下表softness视觉特征适合场景1.0线性衰减边界明显强调规则圆形光斑2.0中心亮边缘柔和大多数照片和视频3.0中心极亮迅速变暗舞台追光效果5.5 多光源之间的间距多光源布局时各光源间距不要太大否则两灯之间会出现明显的暗区。如果想让重叠区域更亮可以把合并方式从np.maximum改为加权求和但注意最终结果不能超过 255需要做截断。weighted np.zeros_like(masks[0], dtypenp.float32) for mask in masks: weighted mask.astype(np.float32) * 0.6 merged np.clip(weighted, 0, 255).astype(np.uint8)这种加权方式适合模拟多个灯光叠加后的整体照明但重叠区域可能接近 255导致高光溢出需要自行控制权重。6. 运行验证怎么看效果是否正常6.1 静态图片验证对input.jpg执行处理命令后检查输出文件python spotlight_multi.py python -c import cv2; imgcv2.imread(output_multi_spotlight.jpg); print(img.shape)正常情况下输出图片的尺寸应该与输入图片完全一致颜色通道数为 3。然后用图片查看器检查四个要素灯光中心是否位于指定坐标。灯光半径是否覆盖预期主体。灯光外区域是否明显变暗。明暗过渡处是否有生硬边缘。如果发现过渡边缘有分层或者轮廓线优先调高softness。6.2 视频验证视频处理完成后用 OpenCV 读取输出视频的帧数确认帧率没有丢失cap cv2.VideoCapture(output_spotlight_video.mp4) print(总帧数:, cap.get(cv2.CAP_PROP_FRAME_COUNT)) print(帧率:, cap.get(cv2.CAP_PROP_FPS))如果帧数与输入视频不符说明处理过程中有跳帧或者VideoWriter写入失败。可以在循环里检查ret值必要的时候记录错误帧序号。6.3 用像素值量化验证确定灯光中心亮度是否保留可以打印中心像素的 RGB 值import cv2 image cv2.imread(output_spotlight.jpg) h, w image.shape[:2] center_pixel image[h // 2, w // 2] corner_pixel image[5, 5] print(中心像素 BGR:, center_pixel) print(角落像素 BGR:, corner_pixel)如果输入图是纯灰色 200中心像素的 BGR 应该是[200, 200, 200]左右角落像素应该接近[40, 40, 40]假设dark_ratio0.2。如果中心像素变暗了说明掩膜中心没有对齐到目标位置或者center传参时坐标写法错误。7. 常见问题排查7.1 图片读取失败cv2.imread返回None现象运行脚本时出现FileNotFoundError: input.jpg 不存在或者cv2.imread返回None但图片文件明明在目录里。可能原因文件路径写错相对路径没有指向当前工作目录。文件名包含中文或特殊字符OpenCV 在某些系统上无法读取。图片权限不足。检查方式ls -l input.jpg python -c import os; print(os.path.abspath(input.jpg))处理建议改用绝对路径读取。如果文件路径包含中文可以用cv2.imdecode方式读取import numpy as np import cv2 with open(测试图片.jpg, rb) as f: data np.frombuffer(f.read(), dtypenp.uint8) image cv2.imdecode(data, cv2.IMREAD_COLOR)7.2 灯光边缘有明显圆形截断线现象效果图上能看到一圈明显的圆形边界内部亮外部暗过渡非常生硬。可能原因softness太小或者radius设置过大导致衰减曲线在边界处斜率突变。检查方式打印掩膜中边界位置的像素值确认从 255 到 0 的跳变距离。处理建议把softness增大到 2.0 或 2.5。如果仍然生硬可以把radius减小让灯光覆盖范围小于主体区域。7.3 视频处理速度慢每秒只有几帧现象处理 1080p 视频时程序运行很慢甚至出现卡顿。可能原因每帧都重新生成完整掩膜且没有做任何优化。1080p 图像需要遍历约 200 万个像素点坐标生成掩膜本身有一定开销。处理建议如果灯光静止只需要生成一次掩膜然后循环复用。如果灯光移动可以减少掩膜生成频率比如每 10 帧计算一次掩膜中间帧插值。对所有帧统一缩小处理尺寸处理完成后再放大回原尺寸。scale 0.5 small_frame cv2.resize(frame, None, fxscale, fyscale) small_result apply_spotlight(small_frame, (small_cx, small_cy), small_radius) result cv2.resize(small_result, (width, height))7.4 输出视频没有声音现象生成的视频画面正确但音频丢失。原因OpenCV 的VideoWriter只负责写视频流不处理音频。处理建议用 OpenCV 生成无声视频后再用 FFmpeg 从原视频中抽取音轨合并ffmpeg -i output_spotlight_video.mp4 -i input_video.mp4 -c:v copy -c:a aac -map 0:v:0 -map 1:a:0 final_video.mp4这条命令将output_spotlight_video.mp4的视频流和input_video.mp4的音频流合并到final_video.mp4。7.5 多光源重叠区域过曝现象多个灯光重叠处出现白色色块细节丢失。原因np.maximum合并后的掩膜在重叠区域可能达到 255原图亮度本来就高相乘后接近 255。处理建议把合并方式改为除以光源数量merged np.mean(masks, axis0).astype(np.uint8)或者使用加权求和并设置上限merged np.clip(sum(masks) / len(masks), 0, 255).astype(np.uint8)8. 最佳实践和扩展方向8.1 可复用的处理函数设计建议不要把灯光参数写死在主流程里而是定义配置字典方便批量测试不同参数spotlight_config { dark_ratio: 0.2, softness: 2.0, light_points: [ ((200, 200), 150, 2.0), ((600, 350), 180, 1.5), ], }这样你可以把配置放到 JSON 文件里对多张图片复用同一套灯光参数import json with open(spotlight_config.json, r, encodingutf-8) as f: config json.load(f) result apply_multi_spotlight_flexible(image, config[light_points], config[dark_ratio])8.2 性能优化清单优化手段适用场景效果提前生成掩膜灯光位置不变避免每帧重复计算距离矩阵降低处理分辨率视频预览处理速度提升数倍使用np.float32计算需要高精度比float64节省内存只计算灯光外接矩形区域灯光范围小避免全图距离计算多线程并行处理多段视频每段视频分配线程8.3 生产环境还需要注意什么这篇文章里的代码更偏向学习原型如果要放到生产环境或者自动化服务中还需要补齐以下能力输入参数校验例如检查radius必须大于 0dark_ratio必须落在 0 到 1 之间。日志记录记录每张图片的处理耗时、输出路径、参数快照。失败重试机制处理视频时如果中途崩溃需要支持断点续传。资源释放使用完VideoCapture和VideoWriter后要确保release()被调用。安全限制如果服务开放给外部调用需要限制上传文件大小、处理超时时间和输出文件数量。8.4 扩展方向这个 spotlight 工具可以继续扩展的方向包括按椭圆或任意多边形生成灯光区域。用摄像头实时追踪人脸让灯光自动跟随人脸移动。把灯光效果嵌入到直播推流软件作为 OBS 滤镜的替代实现。结合目标检测模型检测到商品后自动把灯光对准商品位置。如果从学习角度继续深入建议下一步研究cv2.filter2D做高斯模糊羽化以及cv2.remap做灯光形变。这些能力组合起来能做出更接近影视级光照的视觉效果。从工程角度看这个项目最重要的收获不是学会调一个聚光灯效果而是理解“图像处理中的遮罩合成”这个基本模型。无论是抠图、局部增强、水印合成还是背景替换底层都在做类似的掩膜权重计算。掌握了这一点后续再接触其他图像算法就会轻松很多。