视频黑边检测与裁剪--AI 数据湖服务-火山引擎

文档中心

立即注册

AI 数据湖服务

视频处理

视频黑边检测与裁剪

算子ID：daft.las.functions.video.video_blackborder_crop.VideoBlackBorderCrop

算子介绍

描述

视频黑边检测与裁剪

核心功能

多算法支持：支持3种黑边检测算法，适配不同场景：
行列占比法（threshold_ratio）：适配黑边内有水印/零星噪声的场景。
边缘检测法（edge_detection）：适配渐变黑边/轻微噪声的场景。
直方图分析法（histogram）：适配像素分布不均的黑边场景。
自动边界计算：自动计算有效画面边界。
无损裁剪：基于FFmpeg实现视频裁剪，保持原始编码特性。
音画同步：保留原始音频且音视频精准对齐。

适用场景

视频预处理
去除视频黑边
视频标准化

格式支持

MP4 (.mp4)
AVI (.avi)
MOV (.mov)
MKV (.mkv)
其他常见视频格式

注意与前提

细分项	注意与前提
费用	调用算子前，您需先了解使用算子时的模型调用费用，详情请参见大模型调用计费。
鉴权（API Key）	调用算子前，您需要先生成算子调用的API Key，并建议将API Key配置为环境变量，便于更安全地调用算子，详情请参见获取 API Key 并配置。
BaseURL	调用算子前，您需要先根据您当前使用的LAS服务所在地域，了解算子调用的BaseURL，用于配置算子调用路径参数取值。详情请参见获取 Base URL，下文中的调用示例仅作为参考，实际调用时需替换为您对应地域的路径取值。

Daft 调用

算子参数

输入

输入列名	说明
input_col	包含输入视频路径的数组（支持本地路径、HTTP/HTTPS URL、TOS/S3 URL）。
output_col	包含输出裁剪后文件路径的数组。

输出

包含裁剪结果路径的数组（字符串类型）。成功返回输出路径，失败返回None。

参数

如参数没有默认值，则为必填参数

参数名称	类型	默认值	描述
detection_method	str	threshold_ratio	黑边检测算法。可选值：["threshold_ratio", "edge_detection", "histogram"] threshold_ratio: 适配水印+黑边场景 edge_detection: 适配渐变黑边/轻微噪声场景 histogram: 适配像素分布不均场景默认值: "threshold_ratio"
black_threshold	int	10	黑边判定阈值，像素值<该值视为黑边（0-255）。默认值: 10
valid_pixel_ratio	float	0.1	有效行列的非黑像素占比阈值（0-1）。默认值: 0.1
sample_frames	int	20	黑边识别采样帧数，采样越多识别越准确。默认值: 20
is_keep_audio	bool	true	是否保留音频。默认值: True
timeout	int	None	单个视频处理超时时间（秒），为None时不限制。默认值: None
core_region_ratio	float	0.5	核心区域比例，用于辅助判断。默认值: 0.5
continuous_black_rows	int	3	连续黑边行数判定阈值。默认值: 3
continuous_black_cols	int	3	连续黑边列数判定阈值。默认值: 3
dark_region_brightness	int	50	暗区亮度阈值。默认值: 50
edge_sensitivity	float	1.0	边缘检测敏感度。默认值: 1.0

调用示例

下面的代码展示了如何使用 Daft（适用于分布式）运行算子对视频进行黑边检测与裁剪

from __future__ import annotations

import os

import daft
from daft import col
from daft.las.functions.udf import las_udf
from daft.las.functions.video import VideoBlackBorderCrop

if __name__ == "__main__":
    # 内容会保存到指定的TOS路径下，因此，需要设置好环境变量以保证有权限写入TOS，包括：ACCESS_KEY,SECRET_KEY,TOS_ENDPOINT,TOS_REGION,TOS_TEST_DIR
    TOS_DIR = os.getenv("TOS_TEST_DIR", "tos_bucket")
    output_tos_dir = f"tos://{TOS_DIR}/video/video_blackborder_crop"
    if os.getenv("DAFT_RUNNER", "native") == "ray":
        import logging

        import ray

        def configure_logging():
            logging.basicConfig(
                level=logging.INFO,
                format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
                datefmt="%Y-%m-%d %H:%M:%S.%s".format(),
            )
            logging.getLogger("tracing.span").setLevel(logging.WARNING)
            logging.getLogger("daft_io.stats").setLevel(logging.WARNING)
            logging.getLogger("DaftStatisticsManager").setLevel(logging.WARNING)
            logging.getLogger("DaftFlotillaScheduler").setLevel(logging.WARNING)
            logging.getLogger("DaftFlotillaDispatcher").setLevel(logging.WARNING)

        ray.init(dashboard_host="0.0.0.0", runtime_env={"worker_process_setup_hook": configure_logging})
        daft.set_runner_ray()

    daft.set_execution_config(actor_udf_ready_timeout=600)
    daft.set_execution_config(min_cpu_per_task=0)

    tos_dir_url = os.getenv("TOS_DIR_URL", "las-cn-beijing-public-online.tos-cn-beijing.volces.com")
    samples = {
        "input_path": [f"https://{tos_dir_url}/public/shared_video_dataset/sample.mp4"],
        "output_path": [f"{output_tos_dir}/test_blackborder_video_cropped_histogram.mp4"],
    }
    ds = daft.from_pydict(samples)

    constructor_kwargs = {
        "detection_method": "histogram",
        "black_threshold": 50,
        "sample_frames": 10,
        "is_keep_audio": True,
        "core_region_ratio": 0.5,
        "continuous_black_rows": 3,
        "continuous_black_cols": 3,
        "dark_region_brightness": 50,
    }

    ds = ds.with_column(
        "crop_result",
        las_udf(VideoBlackBorderCrop, construct_args=constructor_kwargs)(col("input_path"), col("output_path")),
    )

    ds.show()

# ╭────────────────────────────────┬────────────────────────────────┬────────────────────────────────╮
# │ input_path                     ┆ output_path                    ┆ crop_result                    │
# │ ---                            ┆ ---                            ┆ ---                            │
# │ String                         ┆ String                         ┆ String                         │
# ╞════════════════════════════════╪════════════════════════════════╪════════════════════════════════╡
# │ https://las-ai-qa-online.tos-… ┆ https://las-ai-qa-online.tos-… ┆ https://las-ai-qa-online.tos-… │
# ╰────────────────────────────────┴────────────────────────────────┴────────────────────────────────╯

最近更新时间：2026.02.10 15:51:19

这个页面对您有帮助吗？

有用

无用

AI 数据湖服务

描述 #

核心功能 #

适用场景 #

格式支持 #

算子参数 #

输入 #

输出 #

参数 #

调用示例 #

描述

核心功能

适用场景

格式支持

算子参数

输入

输出

参数

调用示例