MetDetPy 及 ClipToolkit 从配置文件中加载运行参数。大多数情况下，预设的配置文件能够较好的工作，但有时也可以调整参数可以取得更好的效果。该文档解释了上述两个工具使用的各项参数的含义，用户可以根据需要修改自己的视频读取配置，流星检测的参数，过滤流星的边界条件，图像降噪等能力的参数。
检测配置文件是JSON格式的文本，主要包含4个部分：描述文本(description)， 视频加载器(loader)， 检测器(detector) 和收集器(Collector)。作为参考，预设的配置文件储存在config文件夹下。可以结合默认使用的配置文件阅读本文档以更清晰了解配置文件的格式。
检测配置文件各部分的参数配置以及互相关系如下：
classDiagram
class LoaderCfg {
name: str
wrapper: str
resize: Union[list[int], int, str]
exp_time: Union[float, str]
merge_func: str
grayscale: bool
upper_bound: Optional[float]
continue_on_err: bool
}
class ModelCfg {
name: str
weight_path: str
dtype: str
input_color_order: str
nms: bool
warmup: bool
pos_thre: float
nms_thre: float
multiscale_pred: int
multiscale_partition: int
providers_key: Optional[str]
}
class BinaryCoreCfg {
adaptive_bi_thre: bool
init_value: int
sensitivity: str
area: float
interval: int
}
class HoughLineCfg {
threshold: int
min_len: int
max_gap: int
}
class DynamicCfg {
dy_mask: bool
window_sec: float
}
class BinaryCfg {
binary: BinaryCoreCfg
hough_line: HoughLineCfg
dynamic: DynamicCfg
}
class DLCfg {
model: ModelCfg
}
class DetectorCfg {
name: str
window_sec: float
cfg: Union[BinaryCfg, DLCfg]
}
class MeteorCfg {
min_len: float
max_interval: float
time_range: list[float]
speed_range: list[float]
drct_range: list[float]
det_thre: float
merge_dist_sqr: Optional[int]
clip_merge_interval: Optional[float]
recheck_threshold: Optional[float]
}
class RecheckCfg {
switch: bool
model: ModelCfg
}
class CollectorCfg {
meteor_cfg: MeteorCfg
recheck_cfg: RecheckCfg
positive_cfg: dict[str, Any]
}
class MainDetectCfg {
description: dict[str,str]
loader: LoaderCfg
detector: DetectorCfg
collector: CollectorCfg
}
MainDetectCfg --> LoaderCfg : loader
MainDetectCfg --> DetectorCfg : detector
MainDetectCfg --> CollectorCfg : collector
DetectorCfg --> BinaryCfg : cfg
DetectorCfg --> DLCfg : cfg
BinaryCfg --> BinaryCoreCfg : binary
BinaryCfg --> HoughLineCfg : hough_line
BinaryCfg --> DynamicCfg : dynamic
DLCfg --> ModelCfg : model
RecheckCfg --> ModelCfg : model
CollectorCfg --> MeteorCfg : meteor_cfg
CollectorCfg --> RecheckCfg : recheck_cfg
可用于描述配置文件的主要使用场景和说明。前端应用（如Meteor Master>=3.6.0）将可以展示这些信息。检测中不会实际使用该项。
描述文本段的示例如下：
"description": {
"preset_name": "配置名称",
"intro": "一段配置简介",
}如果希望在中文/英文页面有不同的显示，也可以使用如下方式配置：
"description": {
"preset_name_cn": "M3Det-通用",
"preset_name_en": "M3Det-general",
"intro_cn": "自适应检测器，适用于多数检测场景。",
"intro_en": "Adaptive meteor detector. Suitable for most detection scenarios."
}loader主要管理与视频读入和预处理相关的参数。示例配置如下：
"loader": {
"name": "ThreadVideoLoader",
"wrapper": "OpenCVVideoWrapper",
"resize": 960,
"exp_time": "auto",
"upper_bound": 0.34,
"merge_func": "max",
"grayscale": true
}视频加载器的各项参数说明如下：
| 参数名 | 可选类型 | 说明 | 推荐设置 |
|---|---|---|---|
| name | str | 所使用的loader的名称。目前可选"VanillaVideoLoader"和"ThreadVideoLoader"。一般情况下，推荐使用稳定且运行速度较快的"ThreadVideoLoader"。 |
"ThreadVideoLoader" |
| wrapper | str | 底层加载视频使用的wrapper。目前支持基于OpenCV的"OpenCVVideoWrapper" 及基于PyAV的 "PyAVVideoWrapper"。 |
"OpenCVVideoWrapper" |
| resize | int, array, str | 指定检测使用的分辨率。较低的分辨率下程序运行更快，较高的分辨率则有助于检测到更暗弱和短的流星。可以设置一个整数以仅指定长边长度（如960），程序会自适应不同长宽比的视频（推荐）；该设置也支持同时指定宽高（使用以:或者x分隔两个数字的字符串，如"960:540"，"960x540"；或直接使用列表，如[960,540]） |
960 |
| exp_time | float, str("auto", "slow", "real-time") |
指定单帧的曝光时间。使用传统检测器时，推荐使用"auto"，程序会根据片段估算实际曝光时间（会在启动前花费一小段时间）。如果确定视频帧率与曝光时间匹配，则可以使用"real-time"。如果希望指定具体数值，可以填入单位为s的浮点数（小数）。 |
"auto"（直线检测器）/0.5（深度学习检测器） |
| upper_bound | float (可选) | 指定使用自动估算曝光时间时的最长曝光时间。这是一个可选参数，当没有必要时可以不指定。 | 0.34 |
| merge_func | str | 描述多帧图像如何合并为一帧。仅当实际曝光时间长于视频的单帧时长时生效。可选"max","m3func","mix_max_median_stacker"。因为流星检测的视觉特性，推荐使用"max"。 |
"max" |
| grayscale | bool | 描述是否将视频转换为灰度图像进行加载。对于基于直线检测的检测器，该项必须为true；对于基于深度学习的检测器，目前必须选择false。 |
true（直线检测器）/false（深度学习检测器） |
- Q: 为什么要填写曝光时间？ A: 存在实际曝光时间与帧率不匹配的情况（例如，部分相机可以输出曝光时间为1/20s的4k60p的视频，视频每3帧变化一次，而非每帧间均有差异）。在这种情况下，使用实际的曝光时间可以改善运行速度和识别的准确率。
detector中主要设置使用的检测器，检测窗时长及检测时使用的参数（如二值化阈值，直线检测的相关设置）。
基于直线检测器的示例配置：
"detector": {
"name": "M3Detector",
"window_sec": 1,
"cfg": {
"binary": {
"adaptive_bi_thre": true,
"init_value": 7,
"sensitivity": "normal",
"area": 0.1,
"interval": 2
},
"hough_line": {
"threshold": 10,
"min_len": 10,
"max_gap": 10
},
"dynamic": {
"dy_mask": true,
"window_sec": 5
}
}
}基于深度学习检测器的示例配置：
"detector": {
"name": "MLDetector",
"window_sec": 1,
"cfg": {
"model": {
"name":"YOLOModel",
"weight_path": "./weights/yolov5s.onnx",
"dtype": "float32",
"input_color_order": "rgb",
"nms": true,
"warmup": true,
"pos_thre": 0.10,
"nms_thre": 0.45
}
}
}检测器的各项参数说明如下：
| 参数名 | 可选类型 | 说明 | 推荐设置 |
|---|---|---|---|
| name | str | 描述使用的检测器。目前可选"ClassicDetector", "M3Detector"与 "MLDetector"。其中， "ClassicDetector" 和"M3Detector"是基于直线检测的传统检测器，"MLDetector"则是基于深度学习的检测器。基本上，传统检测器更加灵敏，运行更快，但也更容易产生误报（可通过配置重校验改善）；深度学习检测器则更加稳健，但计算开销更大。二者在参数配置上有差异。 |
"M3Detector"(传统检测器)/"MLDetector"(深度学习检测器) |
| windows_sec | int,float | 描述滑动时间窗长度。运行时算法将逐帧在该窗口长度内检测可能的流星。通常来说，设置在1s附近可以取得比较好的结果。 | 1 |
| cfg | - | 描述具体的参数设置。 | （见下） |
当使用基于直线检测的检测器时，需要在detector下的"cfg"中配置"binary"(二值化阈值相关参数)， "hough_line"(直线检测相关参数)， "dynamic"(动态机制相关参数)；当使用基于深度学习的检测器时，需要在detector下的"cfg"中配置"model"项（深度学习模型相关参数）。这些参数的具体形式如下：
| 所属项 | 参数名 | 可选类型 | 说明 | 推荐设置 |
binary (二值化阈值相关参数) |
adaptive_bi_thre | bool | 是否启用自适应二值化阈值算法。该算法可以根据采样区域的视频信噪比估算最佳二值化阈值，进而将变亮区域分割出来。 | true |
| init_value | int | 初始的二值化阈值。当不启用自适应二值化阈值算法时，直接使用该值作为二值化阈值。 | 5 | |
| sensitivity | str | 描述自适应二值化阈值算法的灵敏度。灵敏度对应的函数会将信噪比值映射到对应的二值化阈值。当不启用自适应二值化阈值算法时，该项不生效。 | normal | |
| area | float | 描述自适应二值化阈值算法的采样区域大小。取值范围[0,1]，代表采样区域与全图面积的比值。设置合适的大小能够在获取近似准确的估计值的同时加速估算。推荐区域设置在0.05-0.2。设置为非法值（小于0或者大于1）时将使用全图采样估算。 | 0.1 | |
| interval | int | 设置阈值估算间隔。过于频繁的阈值估算会增大计算量，降低程序运行性能；过低的计算频率则可能无法及时根据信噪比变化变。 | 2 | |
hough_line (Hough直线检测相关参数。参数具体含义参考OpenCV官方文档) |
threshold | int | hough直线检测的阈值。 | 10 |
| min_len | int | 描述构成直线的最小长度。 | 10 | |
| max_gap | int | 描述直线间允许的最大间隔。 | 10 | |
dynamic (动态机制相关参数) |
dy_mask | bool | 是否启用动态掩模机制。动态掩模对持续产生响应的区域施加掩模，能够降低在亮星点和持续干扰附近区域的响应。 | true |
| window_sec | float | 动态掩模的时间窗口长度（单位：秒）。用于控制动态掩模的持续时间。 | 5 | |
model (模型相关参数) |
- | - | 参考模型部分。 | 0.6 |
收集器中设置流星的过滤和收集条件，以及重校验相关的配置。
"collector": {
"meteor_cfg": {
"min_len": 20,
"max_interval": 5,
"time_range": [
0,
8
],
"speed_range": [
3,
12
],
"drct_range": [
0,
0.6
],
"det_thre": 0.5,
"merge_dist_sqr": 2048,
"recheck_threshold": 0.25
},
"recheck_cfg": {
"switch": true,
"model": {
"name":"YOLOModel",
"weight_path": "./weights/yolov5s_v2.onnx",
"dtype": "float32",
"input_color_order": "rgb",
"nms": true,
"warmup": true,
"pos_thre": 0.10,
"nms_thre": 0.45,
"multiscale_pred":2,
"multiscale_partition":2
}
},
"positive_cfg": {
"positive_cates": [
"METEOR",
"RED_SPRITE"
]
}
}其中主要包含三部分设置：流星的筛选配置"meteor_cfg"、重校验配置"recheck_cfg"和正样本配置"positive_cfg"。
流星筛选配置中，可以设置流星的速度，持续时间，允许间隔，直线程度，得分阈值等过滤条件。其各项参数说明如下：
| 参数名 | 可选类型 | 说明 | 推荐设置 |
|---|---|---|---|
| min_len | int | 开始记录流星所需要的最小长度(px)。 | 20 |
| max_interval | int | 流星间的最长间隔时间（经过该时间长度没有额外响应，这一个/组流星将被认为已经结束）。单位：s。 | 5 |
| time_range | array | 描述流星的持续时间范围。超过或者没有到达阈值的响应将会被排除。单位：s。 | [0,8] |
| speed_range | array | 描述流星的允许速度范围。超过或者没有到达阈值的响应将会被排除。该数值的计算方式为：(流星的移动距离(px)/流星的运动时间(s))/(视频长边长度(px)) * 100。可以将该数值理解为流星每秒在画面中移动的距离比例(%)，如[3,12]代表预期捕获每秒在画面中移动距离为3%-12%的目标。单位：$s^{-1}$。 | [3, 12] |
| drct_range | array | 描述流星的直线程度范围。越接近0，该流星越接近理想直线。该值通过计算所有响应的方向向量集合的方差得到。 | [0,0.6] |
| det_thre | float | 描述正样本流星的阈值，超过该得分的流星被认为是正样本流星。取值为[0,1]。 | 0.5 |
| merge_dist_sqr | int | 描述若干响应之间允许的最长距离平方。如果轨迹存在多个离散响应，可以尝试增大该值。该值以运行时分辨率为基准，分辨率差异过大时可能影响效果。 | 2048 |
| recheck_threshold | float，可选 | 序列送入模型重校验所需的最低前置得分。省略时使用 det_thre 的一半。 |
0.25 |
| clip_merge_interval | float，可选 | 将已确认目标合并到同一导出片段所允许的最大时间间隔，单位为秒。省略时使用 max_interval。 |
与 max_interval 相同 |
旧字段 thre2 仍可作为兼容兜底读取，但已经弃用；新配置应使用 merge_dist_sqr。
重校验是v2.0.0中新增的机制，允许在主程序给出时间范围和流星位置后再次校验图像中是否存在需要捕获的目标（如流星，红色精灵等）。其各项参数说明如下：
| 参数名 | 可选类型 | 说明 | 推荐设置 |
|---|---|---|---|
| switch | str | 是否默认启用重校验。 | true |
| model | - | 参考模型部分。 | - |
| save_path | str | 保存重校验图像的路径。置空时，不保存重校验的图像。 | "" |
正样本是v2.2.0中新增的机制，支持配置预期输出的正负样本类型。其各项参数说明如下：
| 参数名 | 可选类型 | 说明 | 推荐设置 |
|---|---|---|---|
| positive_cates | list | 接受为正样本的类别集合。 | ["METEOR","RED_SPRITE"] |
可以在检测器中和收集器的重校验部分配置深度学习模型。 当尝试使用模型时，按照以下格式配置：
"model": {
"name":"YOLOModel",
"weight_path": "./weights/yolov5s.onnx",
"dtype": "float32",
"input_color_order": "rgb",
"nms": true,
"warmup": true,
"pos_thre": 0.10,
"nms_thre": 0.45,
"multiscale_pred":2,
"multiscale_partition":2
}| 参数名 | 可选类型 | 说明 | 推荐设置 |
|---|---|---|---|
| name | str | 使用的深度学习模型类型，这将决定程序如何处理输入输出。目前仅实现了YOLO格式的模型"YOLOModel"。 |
"YOLOModel" |
| weight_path | str | 网络权重的路径。可以是相对MetDetPy的路径，也可以是绝对路径。默认提供了已训练完成的YOLOv5s。网络输出的标签应当参考class_name文件配置。目前支持.onnx的网络权重格式。 |
"./weights/yolov5s.onnx" |
| dtype | str | 描述网络的输入数据格式。当使用量化模型时，需在此处配置格式，否则程序可能无法正常运行。目前支持全精度（"float32"），半精度（"float16"）。 |
"float32" |
| input_color_order | str | 模型权重所期望的通道顺序。传给 forward 的图像固定为 BGR；配置为 "rgb" 时模型会自动转换。 |
"rgb" |
| nms | bool | 是否需要执行非最大值抑制NMS。如果构建的网络已附带NMS，则选择false以提升运行速度。 |
true |
| warmup | bool | 是否需要在使用前预热。设置为true可以提升网络的运行速度。 |
true |
| pos_thre | float | 正样本阈值，超过该得分的会被认为是正样本。取值为[0,1]。 | 0.1 |
| nms_thre | float | 去重时使用的阈值。 | 0.45 |
| multiscale_pred | int | 多尺度检测时使用的尺度。取0时，不进行任何处理；取N>0的整数代表会进行必要的旋转处理，并在N个尺度上进行检测。需要注意：过深的尺度会显著增加计算量和误报样本，因此通常取1或2即可。 | 1（低分辨率）/2（高分辨率） |
| multiscale_partition" | int | 多尺度检测时，子图像在长/宽方向的分片数。需要取大于1的整数，建议值为2。过大的分片数会显著增加计算量和误报样本， | 2 |
ClipToolkit（切片工具）支持定义截取和保存视频时的视频读写参数，其默认配置文件为./global/clip_cfg.json中。该配置文件的结构定义如下（或参考 metstruct.py）：
| 参数名 | 可选类型 | 说明 | 推荐设置 |
|---|---|---|---|
| loader | str | 视频加载器 | "ThreadVideoLoader" |
| wrapper | str | 加载视频使用的后端wrapper |
|
| writer | str | 视频写入器，可选 OpenCVVideoWriter、PyAVVideoWriter 和 FFMpegVideoWriter。 | "FFMpegVideoWriter" |
| image_denoise | DenoiseOption | 图像降噪配置 | 见图像降噪配置 |
| export | ExportOption | 导出配置 | 见导出配置 |
| raw_img_load_config | Optional[RawImgLoadCfg] | 原始图像加载配置（可选） | 见原始图像加载配置 |
剪切配置文件各部分的参数配置以及互相关系如下：
classDiagram
class ExportOption {
positive_category_list: list[str]
bbox_color_mapping: Optional[dict[str, list[int]]]
filter_rules: FilterRules
jpg_quality: int
png_compressing: int
with_bbox: bool
with_annotation: bool
bbox_color: list[int]
bbox_thickness: int
clip_padding: ClipPaddingOption
ffmpeg_config: FFMpegConfig
}
class ClipPaddingOption {
before: float
after: float
}
class ConnectParam {
switch: bool
ksize_multiplier: float
gamma: float
threshold: int
}
class SimpleDenoiseParam {
ds_radius: int
ds_threshold: int
bi_d: int
bi_sigma_color: int
bi_sigma_space: int
}
class MFNRDenoiseParam {
bg_algorithm: str
sigma_high: float
sigma_low: float
bg_fix_factor: float
}
class DenoiseOption {
switch: bool
highlight_preserve: float
algorithm: str
blur_ksize: int
connect_lines: ConnectParam
simple_param: SimpleDenoiseParam
mfnr_param: MFNRDenoiseParam
}
class ClipCfg {
loader: str
wrapper: str
writer: str
image_denoise: DenoiseOption
export: ExportOption
raw_img_load_config: Optional[RawImgLoadCfg]
}
ClipCfg --> DenoiseOption : image_denoise
ClipCfg --> ExportOption : export
DenoiseOption --> ConnectParam : connect_lines
DenoiseOption --> SimpleDenoiseParam : simple_param
DenoiseOption --> MFNRDenoiseParam : mfnr_param
ExportOption --> ClipPaddingOption : clip_padding
ClipToolkit 通过配置文件中的 writer 字段指定视频写入器（VideoWriter）。不同的视频写入器支持不同的视频格式和功能：
| VideoWriter | 支持导出格式 | 音频复制 | 参数配置 |
|---|---|---|---|
| OpenCVVideoWriter | 仅支持 .avi 格式 |
不支持 | 不支持 |
| PyAVVideoWriter（发行版本） | 只能导出 .avi 格式 |
不支持 | 不支持 |
| PyAVVideoWriter（自行构建） | 支持 PyAV 支持的所有格式 | 部分支持 | 有限支持 |
| FFMpegVideoWriter（推荐） | 支持 FFMpeg 支持的所有格式（mp4, mkv, avi 等） | 完整支持音频复制和转码 | 完整支持所有导出配置 |
当使用 FFMpegVideoWriter 时，需要在配置文件的 export.ffmpeg_config 部分配置 FFMpeg 相关参数。
详见 ffmpeg配置
支持在导出图像时对导出图像进行后处理，降低图像噪点，连接可能存在的断线等。具体配置如下：
| 所属项 | 参数名 | 可选类型 | 说明 | 推荐设置 |
| switch | - | bool | 是否默认启用图像降噪。注意，即使配置为false, 仍可以通过在命令行的--denoise参数在单次任务中启用降噪。 | true |
| highlight_preserve | - | float | 高光保护阈值，控制高光部分不受到降噪影响，保护流星周围图像的细节。设置过高可能导致高光同样被降噪算法影响，过低则可能导致降噪效果不明显。 | 0.9 |
| algorithm | - | str | 默认使用的降噪算法。可选 "simple"（简单降噪算法） 以及 "mfnr-mix"（多帧混合降噪）。 | "simple" |
| blur_ksize | - | int | 使用的高斯模糊核尺寸。该参数用于估算流星蒙版。 | 31 |
| connect_lines | switch | bool | 是否在降噪过程中尝试连接断线。 | true |
| ksize_multiplier | float | 连接断线使用的高斯核尺寸系数。该系数与 "blur_ksize" 乘算以确定最终在降噪中使用的核尺寸。 | 1.5 | |
| gamma | float | 断线蒙版gamma亮度变换时使用的gamma系数。 | 1.0 | |
| threshold | int | 断线蒙版阈值。高于阈值的蒙版部分被视为需要连接的断线。 | 30 | |
simple_param （简单降噪相关参数） |
ds_radius | int | 蒙尘与划痕算法使用的中值滤波半径。 | 10 |
| ds_threshold | int | 蒙尘与划痕算法使用的亮度差阈值。 | 20 | |
| bi_d | int | 双边滤波算法使用的像素邻域的直径。 | 10 | |
| bi_sigma_color | float | 颜色空间滤波器的sigma值。值越大，则半相等颜色区域更大。 | 15 | |
| bi_sigma_space | float | 坐标空间中滤波器的sigma值。值越大，更大的区域内相似的颜色会参与降噪计算。 | 6 | |
mfnr_param （多帧降噪相关参数） |
bg_algorithm | str | 多帧降噪时估算背景的算法。可选 "median" （中值）, "med-of-med" （中值中值，快速的中值估算方法）, "sigma-clipping"（sigma裁剪均值）, "mean"（简单均值）。 | "mean" |
| sigma_high | float | 使用sigma裁剪均值时，sigma的拒绝上界比值。 | 3.0 | |
| sigma_low | float | 使用sigma裁剪均值时，sigma的拒绝上界比值。 | 3.0 | |
| bg_fix_factor | float | 背景估算时使用的修正系数。 | 1.5 |
| 参数名 | 可选类型 | 说明 | 推荐设置 |
|---|---|---|---|
| positive_category_list | list | 需要导出的正样本类别 | ["METEOR","RED_SPRITE"] |
| bbox_color_mapping | Optional[dict[str, list[int]]] | 按类别映射的标注框颜色（BGR顺序）。如果指定，将覆盖 bbox_color 设置。 |
None |
| filter_rules | FilterRules | 过滤规则配置 | 见过滤规则配置 |
| jpg_quality | int | 导出JPEG图像时的质量（1-100） | 95 |
| png_compressing | int | 导出PNG图像时的压缩级别（0-9） | 3 |
| with_bbox | bool | 导出时是否默认需要带上标注框 | false |
| with_annotation | bool | 导出时是否默认需要带上标注文件 | false |
| bbox_color | list | 默认标注框颜色(BGR顺序) | [255,0,0] |
| bbox_thickness | int | 标注框粗细 | 2 |
| clip_padding | ClipPaddingOption | 视频片段前后额外补偿的时间配置 | 见时间补偿配置 |
| ffmpeg_config | FFMpegConfig | FFMpeg视频编码配置（仅在启用 FFMpegVideoWriter 时生效） | 见FFMpeg配置 |
过滤规则用于在导出时过滤检测结果，会同时作用于图像导出和视频导出流程。其各项参数说明如下：
| 参数名 | 可选类型 | 说明 | 推荐设置 |
|---|---|---|---|
| switch | bool | 是否启用过滤规则 | true |
| threshold | float | 置信度阈值，低于该值的检测结果将被过滤 | 0.0 |
| min_length_ratio | float | 最小长度比例阈值，低于该值的检测结果将被过滤（相对于图像长边） | 0.0 |
| exclude_category_list | list[str] | 需要排除的类别列表 | [] |
说明：
- 若通过
ClipToolkit命令行显式使用--enable-filter-rules或--disable-filter-rules，将覆盖此处switch的配置值。 - 若过滤后无有效目标，当前导出任务会被跳过。
时间补偿配置用于在每个视频片段的起始和结束时间前后额外补偿指定的时间长度。其各项参数说明如下：
| 参数名 | 可选类型 | 说明 | 推荐设置 |
|---|---|---|---|
| before | float | 开始时间前补偿的时间长度（秒）。正数表示向前扩展，负数表示向后收缩。 | 0.0 |
| after | float | 结束时间后补偿的时间长度（秒）。正数表示向后扩展，负数表示向前收缩。 | 0.0 |
注意事项：
- 当补偿后的时间戳超出视频边界时，程序会自动裁剪到视频的有效范围，并输出警告日志
- 文件名使用裁剪后的时间戳生成，确保时间戳的合法性
- 该配置对所有导出模式（图像/视频）均生效
FFMpeg视频编码配置用于控制使用 FFMpegVideoWriter 时的视频编码参数。其各项参数说明如下：
| 参数名 | 可选类型 | 说明 | 推荐设置 |
|---|---|---|---|
| path | Optional[str] | FFMpeg可执行文件路径。如果为None，将使用系统PATH中的FFMpeg | None |
| preset | str | FFMpeg编码预设，可选值如 "slow", "medium", "fast" 等 | "slow" |
| crf | int | 恒定速率因子（Constant Rate Factor），控制视频质量（0-51，值越小质量越高） | 18 |
| video_encoder | str | 视频编码器，如 "libx264", "libx265" 等 | "libx264" |
| pix_fmt | str | 像素格式，如 "yuv420p", "yuv422p" 等 | "yuv420p" |
启用FFMpegVideoWriter时，会按照如下路径顺序查找FFMpeg工具：
- 如果
path字段指定了路径，将在该路径下查找ffmpeg和ffprobe - 在 MetDetPy 项目根目录下查找
- 在系统 PATH 环境变量中查找
如果未找到 FFMpeg，程序将报错。
原始图像加载配置用于控制加载RAW格式图像时的处理参数。其各项参数说明如下：
| 参数名 | 可选类型 | 说明 | 推荐设置 |
|---|---|---|---|
| power | float | 伽马校正的幂值 | 2.222 |
| target_nl_mean | float | 目标归一化亮度均值 | 0.3 |
| contrast_alpha | float | 对比度增强系数 | 1.2 |
| output_bps | int | 输出图像的位深度（位数） | 8 |