darktable AI 任务详解：Object Mask、Raw Denoise、Denoise 与 Upscale 的模型规范与集成指南

darktable AI 任务详解Object Mask、Raw Denoise、Denoise 与 Upscale 的模型规范与集成指南【免费下载链接】darktabledarktable is an open source photography workflow application and raw developer项目地址: https://gitcode.com/GitHub_Trending/da/darktabledarktable 的 AI 子系统基于 ONNX Runtime为摄影工作流提供四类神经网络任务交互式对象抠图Object Mask、传感器级原始降噪Raw Denoise、成片降噪Denoise与超分辨率放大Upscale。本文以 dev-doc/AI_Tasks.md 为主线逐项拆解每个任务的任务键task key、模型 I/O 规格、预处理/后处理流程、分块tiling策略、config.json清单格式与 ONNX 导出要求并结合 src/common/ai 目录下的实际实现segmentation、restore、restore_rgb、restore_raw_bayer、restore_raw_linear与消费端 src/libs/neural_restore.c 给出源码级佐证。读完本文你将能够判断一个 ONNX 模型能否接入 darktable、如何为每个任务编写正确的config.json、如何导出符合规范的模型以及每个任务在运行时实际经历了哪些处理环节。系统的整体架构、构建开关USE_AI、执行提供方provider选择与如何新增一个 AI 任务的完整指南参见 dev-doc/AI.md。一、任务总览darktable 的 AI 任务由config.json中的task字段标识运行时通过模型注册表model registry按任务键查找当前激活模型再由对应模块加载执行。四类任务及其对应关系如下任务任务键task核心 API消费端对象抠图 Object Maskmasksrc/common/ai/segmentation.hsrc/develop/masks/object.c原始降噪 Raw DenoiseBayerrawdenoisesrc/common/ai/restore_raw_bayer.hsrc/libs/neural_restore.c原始降噪 Raw DenoiseLinearrawdenoisesrc/common/ai/restore_raw_linear.hsrc/libs/neural_restore.c成片降噪 Denoisedenoisesrc/common/ai/restore_rgb.hsrc/libs/neural_restore.c超分辨率 Upscaleupscalesrc/common/ai/restore_rgb.hsrc/libs/neural_restore.c模型清单 data/ai_models.json 中登记了各任务的默认模型mask-object-sam21-smallmask、denoise-ninddenoise、rawdenoise-nindrawdenoise、upscale-realplksrupscale并通过default: true指定默认启用项、min_version声明模型包的最低版本要求。二、Object Mask基于 SAM/SAM2/SegNext 的交互式抠图2.1 任务定位Object Mask 提供交互式对象抠图能力模型基于 SAMSegment Anything、SAM 2.1 或 SegNext 系列。任务键为maskAPI 位于 src/common/ai/segmentation.h由暗房darkroom的蒙版管理器消费入口为 src/develop/masks/object.c。2.2 工作流程从用户交互到最终蒙版的完整流程如下用户在蒙版管理器中选择对象蒙版工具图像被导出为 sRGB uint8 格式交给 SAM 编码器encoder编码编码每张图像只运行一次并缓存结果用户点击放置前景/背景点point prompt每次点击运行轻量级解码器decoder生成一张蒙版迭代精化上一次的低分辨率蒙版被回馈给解码器逐步改善精度蒙版被缩放到图像原始尺寸作为 darktable 蒙版形状mask shape应用。2.3 支持的模型架构架构config.json中的arch编码器输出张量数蒙版候选数支持 Box 提示SAM 2.1sam23 个3多蒙版 multi-mask是SegNextsegnext2 个1单蒙版 single-mask否源码中 segmentation.c 通过读取模型注册表中的arch字段来区分模型类型sam或sam2归入 SAM 类segnext归入 SegNext 类未知 arch 直接返回 NULL 并打印[segmentation] unknown arch日志。dt_seg_supports_box()用于向 UI 报告当前模型是否支持框选提示。2.4 编码器Encoder规格编码器输入固定为[1, 3, 1024, 1024]的 float32 张量即预处理后的图像。预处理由segmentation.c完成顺序如下最长边缩放至 1024 px双线性插值保持宽高比短边补零zero-pad至 1024×1024归一化SAM 使用 ImageNet 均值/方差SegNext 缩放到 [0, 1]HWC 布局转 CHW。编码器典型输出输出Shape说明0[1, 256, 64, 64]图像嵌入image embeddings1[1, 32, 256, 256]高分辨率特征2仅 SAM2[1, 64, 128, 128]中分辨率特征2.5 解码器Decoder规格解码器输入按索引排列前 E 个输入是编码器输出的透传E 为编码器输出张量数SAM2 为 3、SegNext 为 2其后依次为索引名称Shape说明0..E-1encoder outputs随架构变化编码器输出透传Epoint_coords[1, N1, 2]提示点坐标N 个真实提示 1 个 SAM 填充点E1point_labels[1, N1]1前景0背景-1填充E2mask_input[1, 1, 256, 256]上一轮低分辨率蒙版E3has_mask_input[1]首次点击为 0.0精化时为 1.0解码器输出索引名称Shape说明0masks[1, M, 1024, 1024]蒙版 logitssigmoid 之前的值1iou_predictions[1, M]每个蒙版的预测 IoU2low_res_masks[1, M, 256, 256]供迭代精化使用其中 M 为蒙版候选数SAM2 为 3SegNext 为 1。提示点结构在dt_seg_point_t中定义x/y为原始图像空间像素坐标label取值 0背景、1前景、2框左上角、3框右下角框提示仅 SAM 支持需先用dt_seg_supports_box()确认。2.6 蒙版后处理解码器输出到最终蒙版的转换步骤选取预测 IoU 分数最高的蒙版裁掉补零区域zero-padded region双线性缩放到原始图像尺寸应用 sigmoidmask 1 / (1 exp(-logits))输出值域为 [0, 1]。dt_seg_compute_mask()返回的正是这个 [0,1] 浮点蒙版缓冲宽度×高度调用方用g_free()释放。在 segmentation.c 的采样实现中可以看到蒙版从编码图像坐标映射到原图时采用基于亮度的引导重采样guide-based upsampling并对 sigmoid 前的 logits 值应用apply_sigmoid分支与文档描述的后处理链一致。2.7 迭代精化首次解码has_mask_input 0.0解码器忽略mask_input后续解码上一轮low_res_masks回馈为mask_inputhas_mask_input 1.0dt_seg_reset_prev_mask()仅清除缓存的上一轮蒙版保留图像嵌入使下一次计算从头开始dt_seg_reset_encoding()清除全部缓存包括图像嵌入图像切换时必须调用。从 segmentation.h 的注释可以看到dt_seg_encode_image/dt_seg_compute_mask/dt_seg_reset_*之间必须由调用方串行化context 内部不做线程同步编码器通常在后台线程执行解码器在 UI 线程的用户点击回调中运行二者会共同改写prev_mask状态。此外解码器加载时被强制固定到 CPU 执行提供方并禁用图优化DT_AI_OPT_DISABLED注释给出的原因是解码器轻量、硬件加速收益有限且可规避 SegNext 解码图如Concat-Reshape在 ORT 图优化下的问题。为缓解首次点击的卡顿dt_seg_warmup_decoder()会在dt_seg_load()之后于后台线程运行一次哑推理把 ONNX Runtime 首次Run()的惰性编译与显存分配成本移出用户交互路径。分割模块还支持编码器嵌入的磁盘缓存dt_seg_disk_cache_save/load以图像 ID 为键、以畸变模块参数哈希distort_hash做失效判断命中缓存时可直接跳过重新编码。2.8 config.json 示例与目录布局{ id: mask-object-sam21-small, name: mask sam2.1 hiera small, description: Segment Anything 2.1 (Hiera Small) for interactive masking, task: mask, arch: sam2, backend: onnx }目录布局要求编码器与解码器作为两个独立的 ONNX 文件同目录存放mask-object-sam21-small/ config.json encoder.onnx decoder.onnx模型 ID 遵循task-subtask-model[-size]命名规范详见 dev-doc/AI.md例如mask-object-sam21-small、mask-object-segnext-b2hq。2.9 ONNX 导出约束解码器导出脚本维护在 darktable-ai 模型仓库中。导出必须满足以下硬性约束不得包含orig_im_size输入masks输出必须固定在 1024×1024将F.interpolate编入计算图而不是依赖外部缩放low_res_masks输出为 256×256所有空间维度必须是具体值禁止num_labels之类的符号维度只允许num_points保持动态。三、Raw Denoise传感器级原始降噪3.1 任务定位Raw Denoise 在 darktable 主处理管线之前、直接在 raw CFA 马赛克层面做降噪输出为 DNG 文件重新导入后按普通 raw 走完整管线调色。任务键为rawdenoise共享 API 为 src/common/ai/restore.h消费端同样是 src/libs/neural_restore.c。两个管线变体共享同一任务键按传感器类型路由变体API适用传感器输出Bayersrc/common/ai/restore_raw_bayer.hRGGB / BGGR / GRBG / GBRG统一强制裁剪到 RGGB 原点CFA Bayer DNGuint16保持原 CFA 模式Linearsrc/common/ai/restore_raw_linear.hX-Trans、Foveon、带 CFA 模式的单色传感器等无法打包为 4 通道 Bayer 的类型LinearRaw DNG3 通道 float 去马赛克传感器分类由dt_restore_classify_sensor()完成它依据图像标志与 rawspeed 填充的buf_dsc.filters将 raw 归类为BAYER、XTRANS、LINEAR或UNSUPPORTED非 raw、纯单色等无法路由的输入并据此选择对应的 loaderdt_restore_load_rawdenoise_bayer/dt_restore_load_rawdenoise_xtrans/dt_restore_load_rawdenoise_linear。当前 X-Trans loader 会回退到 Linear 变体保留独立的 loader 入口是为了未来可以通过仅修改 manifest 的方式接入专用的 X-Trans 模型。3.2 工作原理Bayer 变体RGGB 家族直接从 rawspeed 加载 raw CFA 马赛克不经过去马赛克除 rawprepare 外不做 darktable 预处理预处理逐通道黑电平扣除、逐通道白平衡归一化默认使用由adobe_XYZ_to_CAM推导的日光白平衡、按像素位点site范围归一化将 2T×2T 的 CFA 块打包为 T×T 的 4 通道张量RGGB 顺序为 R、G1、G2、B非 RGGB 传感器被强制裁剪到 RGGB 原点分块推理模型内部通过 PixelShuffle 完成去马赛克返回 3 通道 2T×2T 的 camRGB 块后处理反转归一化与白平衡可选标量均值匹配match_gain以保持各块增益一致重新马赛克回原 CFA 布局通过dt_imageio_dng_write_cfa_bayer写入 uint16 马赛克到 CFA Bayer DNG。Linear 变体X-Trans、Foveon 等运行最小 darktable 管线rawprepare → highlights → demosaic关闭色温在完整传感器分辨率下得到 camRGB raw-ADC 单位的 3 通道 float 缓冲——复用 darktable 自带的传感器感知去马赛克AMaZE / VNG / Markesteijn / …而非自研应用日光白平衡与camRGB → lin_rec2020矩阵可选的标量曝光提升至target_mean训练分布默认 0.30分块推理逐块match_gain反转曝光提升、矩阵与白平衡恢复 camRGB raw通过dt_imageio_dng_write_linear写入 LinearRaw DNG。两个变体完成后都会自动导入图库、与源图像分组并继承用户标签与 denoise/upscale 共用同一_import_image路径见 src/libs/neural_restore.c。3.3 模型输入输出契约Bayerinput_kind: bayer_v1张量名称Shape类型说明输入 0input[1, 4, T, T]float32打包后的半分辨率 CFA 块通道序 R G1 G2 B值为(raw - black) / range * wb_norm输出 0output[1, 3, 2T, 2T]float32去马赛克后的 camRGB与输入同 WB/曝光框架Linearinput_kind: linear_v1张量名称Shape类型说明输入 0input[1, 3, T, T]float323 通道平面块默认色彩空间lin_rec2020输出 0output[1, 3, T, T]float32同输入空间的去噪块契约标签input_kind是硬性约束声明了但实际不匹配的input_kind属于加载硬错误不静默回退loader 拒绝打开打包错误的 ONNX并通过dt_control_log反馈早于该契约标签的 manifest 按bayer_v1兼容处理。以 src/common/ai/restore.h 的实现注释为准bayer_v1的详细约定包括通道提取从 CFA 的 R 原点开始因此 BGGR/GRBG/GBRG 传感器也会按 RGGB 方式打包与 RawNIND 训练时先把非 RGGB 传感器物理裁剪到 RGGB 原点再分块的做法一致bayer_orientation可取force_rggb默认或nativewb_norm可取daylight默认由相机adobe_XYZ_to_CAM推导 D65、as_shot或noneedge_pad默认mirror_cropped即在有效 RGGB 裁剪矩形内部做镜像填充使角落块看到与训练一致的反射。输出端除非声明output_scale: absolute否则 loader 默认在重新马赛克前应用match_gain标量均值匹配。3.4 分块策略块尺寸按顺序尝试Bayer 路径为半分辨率512、384、256、192重叠每边 16 个打包像素 32 个传感器像素Bayer 路径的角落块在有效 RGGB 裁剪矩形内部做镜像填充variants.bayer.edge_pad: mirror_cropped与 RawNIND 训练一致。由于静态 ONNX 导出声明了固定的输入 H×Wdt_restore_get_tile_size()返回模型内置的块尺寸Bayer 为打包空间即半传感器单位调用方必须精确按此尺寸分块没有推理失败的兜底。3.5 config.json 示例与目录布局{ id: rawdenoise-nind, name: raw denoise NIND, description: RawNIND raw-domain denoise (Bayer Linear), task: rawdenoise, github_asset: rawdenoise-nind.dtmodel, default: true, variants: { bayer: { input_kind: bayer_v1, onnx: model_bayer.onnx, bayer_orientation: force_rggb, wb_norm: daylight, edge_pad: mirror_cropped }, linear: { input_kind: linear_v1, onnx: model_linear.onnx, input_colorspace: lin_rec2020, wb_norm: as_shot, target_mean: 0.30 } } }rawdenoise-nind/ config.json model_bayer.onnx model_linear.onnxvariants结构让一个模型包同时携带 Bayer 与 Linear 两个 ONNX 文件由调用方根据传感器分类选择加载哪个变体github_asset指向.dtmodel发布资产zip 归档内含 config.json 与 ONNX 文件。四、Denoise成片神经网络降噪4.1 任务定位Denoise 对已显影developed图像做神经网络推理降噪。任务键为denoise加载器dt_restore_load_denoise与推理函数dt_restore_process_tiled分别位于 src/common/ai/restore.h 与 src/common/ai/restore_rgb.h消费端为 src/libs/neural_restore.c。4.2 工作流程darktable 将图像通过完整处理管线导出白平衡、曝光、镜头校正等得到线性 Rec.709 的 float4 RGBA 像素restore 模块将线性 RGB 转为 sRGB带重叠地分块逐块送入 ONNX 模型输出块重新拼接后转回线性 RGB可选地基于 DWT离散小波变换的细节恢复把原图中的精细纹理融合回降噪结果结果写为带 ICC 配置文件与 EXIF 的 TIFFTIFF 自动导入图库、与源图像分组并继承源图的用户标签内部darktable|*自动标签跳过使输出仍能出现在基于标签的收藏中。导入逻辑在 src/libs/neural_restore.c 的_import_image()中实现除标签外还会从源图复制星级评分、颜色标签、地理位置与标题描述等数据库元数据并把新图加入源图所在分组若源图当时是分组代表图还会将输出提升为新的分组代表。4.3 模型规格单输入模型NAFNet、UNet、NIND张量名称Shape类型说明输入 0input[1, 3, H, W]float32sRGB 图像NCHW 平面布局值域 [0,1]输出 0output[1, 3, H, W]float32去噪后的 sRGB 图像同布局H 与 W 是动态维度运行时由块尺寸决定输入与输出空间尺寸必须一致scale 1x。多输入模型FFDNet张量名称Shape类型说明输入 0input[1, 3, H, W]float32sRGB 图像输入 1sigma[1, 1, H, W]float32噪声水平图值 sigma / 255.0输出 0output[1, 3, H, W]float32去噪图像多输入模型需在config.json中设置num_inputs: 2。4.4 色彩空间约定模型工作在 sRGB 空间色彩转换由 restore 模块负责推理前线性 Rec.709 → sRGBIEC 61966-2-1推理后sRGB → 线性 Rec.709。4.5 分块策略块尺寸按顺序尝试2048、1536、1024、768、512、384、256每边重叠 64 像素内存预算为 darktable 可用内存的 1/4边界处理镜像填充mirror padding。从 restore_rgb.c 的dt_restore_process_tiled()实现可以看到具体分块几何step T - 2*OT 为块尺寸O 为重叠输出步长为step*scale按cols × rows网格平铺并对块输入、块输出与行缓冲做失败可恢复的内存分配g_try_malloc。块尺寸的解析与 OOM 重试tile ladder 降级在 src/common/ai/restore.c 的_resolve_tile_size()中完成。推理失败时还提供dt_restore_reload_session_cpu()作为兜底——在 GPU 推理失败不支持的算子、显存不足、EP 崩溃时卸载原会话并在 CPU 提供方上重建同一次任务最多尝试一次 CPU 回退。4.6 细节恢复DWT基于离散小波变换的亮度细节恢复流程提取亮度残差原始 - 降噪用 5 波段小波分解滤波高频细波段噪声被激进阈值化低频粗波段纹理被保留滤波后的残差以用户可控强度混合回结果。在实现中细节恢复强度通过 darktablerc 键plugins/lighttable/neural_restore/detail_recovery_bands调节逗号分隔的各波段阈值乘数实际小波处理调用dwt_denoise()声明于 restore_rgb.c 顶部对应src/common/dwt.c。此外对于具备阴影提升shadow boost能力的模型dt_restore_process_tiled()会在分块前对整图做一次深阴影占比分析_image_has_deep_shadows一次性决定是否启用阴影提升曲线保证所有块采用同一标志、避免逐块接缝。4.7 config.json 示例与 ONNX 导出{ id: denoise-nind, name: denoise nind, description: UNet denoiser trained on NIND dataset, task: denoise, backend: onnx, num_inputs: 1 }推荐的 PyTorch 导出方式H/W 保持动态以便运行时自由选块torch.onnx.export(model, dummy_input, model.onnx, input_names[input], output_names[output], dynamic_axes{ input: {2: height, 3: width}, output: {2: height, 3: width} })五、Upscale超分辨率放大5.1 任务定位Upscale 对已显影图像做 2 倍或 4 倍超分辨率放大。任务键为upscale加载器dt_restore_load_upscale_x2/dt_restore_load_upscale_x4位于 src/common/ai/restore.h推理与 Denoise 共用 src/common/ai/restore_rgb.h 的dt_restore_process_tiled消费端同为 src/libs/neural_restore.c。5.2 工作原理处理管线与 Denoise 相同区别仅在于输出尺寸被放大2x输出为[1, 3, H*2, W*2]4x输出为[1, 3, H*4, W*4]。单个模型可通过两个独立 ONNX 文件同时提供两种倍率model_x2.onnx提供 2x 放大model_x4.onnx提供 4x 放大。5.3 模型规格张量名称Shape类型说明输入 0input[1, 3, H, W]float32sRGB 图像NCHW 布局输出 0output[1, 3, H*S, W*S]float32放大后的 sRGB 图像S 缩放倍数5.4 分块与流式写出块尺寸按顺序尝试512、384、256、192比 Denoise 小因为存在 scale² 的内存放大系数每边重叠 16 像素TIFF 流式写出扫描线直接写出、不缓冲完整放大结果——这对大图至关重要60MP 图像做 4x 放大需要约 3.6GB 内存。dt_restore_process_tiled()通过行写出器dt_restore_row_writer_t逐行落盘正是为满足这一内存约束而设计的接口。5.5 config.json 示例与目录布局{ id: upscale-bsrgan, name: upscale bsrgan, description: BSRGAN 2x and 4x blind super-resolution, task: upscale, github_asset: upscale-bsrgan.dtmodel, default: true }upscale-bsrgan/ config.json model_x2.onnx model_x4.onnx六、任务清单规范与通用约束综合四类任务config.json的核心字段约定如下完整字段表见 dev-doc/AI.md字段必填默认值说明id是--全局唯一标识name是--UI 中显示的模型名description否简短描述task否general任务类型denoise、upscale、mask、rawdenoise等backend否onnx后端类型目前仅onnxarch否模型架构如sam2、segnextnum_inputs否1模型输入数量模型发现机制为扫描模型目录自定义路径或user_data_dir/darktable/models/Linux/macOS 为~/.local/share/darktable/models/Windows 为%APPDATA%\darktable\models\下各子目录中的config.json先发现者优先重复 ID 跳过。下载的模型也解压到同一路径因此下载后立即可被发现。用户可在偏好设置中开启 AI 功能并下载模型相关实现见 src/common/ai_models.c 与 src/gui/preferences_ai.c。对任何新接入的任务可遵循 dev-doc/AI.md 的新增 AI 功能四步流程在 src/common/ai 下创建处理模块不透明类型 包装dt_ai_*调用→ 在 src/CMakeLists.txt 的USE_AI段登记源文件 → 在 data/ai_models.json 添加模型条目 → 创建 UI 消费模块lighttable 模块放src/libs/、darkroom IOP 放src/iop/UI 层只允许包含src/common/ai/的头文件不得直接包含ai/backend.h或common/ai_models.h。七、小结darktable 的 AI 任务体系围绕统一的 ONNX Runtime 后端与模型注册表展开四类任务各有清晰的输入输出契约Object Maskmask编码器 解码器两段式编码结果缓存、解码结果迭代精化SAM2 支持多蒙版与框提示、SegNext 仅单蒙版点提示解码器强制 CPU 执行Raw Denoiserawdenoise在 CFA 域工作Bayer 变体bayer_v14 通道打包、模型内 PixelShuffle 去马赛克、输出 CFA Bayer DNG与 Linear 变体linear_v1复用 darktable 去马赛克、输出 LinearRaw DNG共享任务键并按传感器路由input_kind契约不匹配即为硬错误DenoisedenoisesRGB 域推理Rec.709 ↔ sRGB 双向转换支持单/双输入模型FFDNet 的 sigma 图配套 DWT 细节恢复与可选阴影提升Upscaleupscale与 Denoise 同管线输出按 scale 放大采用更小的分块与 TIFF 流式写出控制内存峰值。每个任务的config.json都是模型可被 darktable 识别与正确执行的关键task决定路由arch决定分割模型的加载分支variants/num_inputs等字段进一步细化加载行为。遵循本文给出的张量规格、预处理顺序与导出约束即可为 darktable 制作符合规范的 ONNX 模型包.dtmodel并借助源码级文档 dev-doc/AI.md 将其完整接入现有工作流。【免费下载链接】darktabledarktable is an open source photography workflow application and raw developer项目地址: https://gitcode.com/GitHub_Trending/da/darktable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考