OpenCV 图像调色优化实录：基于图像金字塔的 RAW / HEIC 文件加载与调色实践

一、引言：为什么调色“看似简单，实则复杂”

在大多数图像编辑软件中，调色功能往往以滑块形式呈现，用户只需拖动滑杆，就能快速调整曝光、色温、饱和度、对比度等参数。这似乎只是一些简单的数值微调，背后逻辑也无非是对像素值做加减乘除。然而，真正开发一个高质量的调色模块，却远非表面那样轻松。

在实际应用中，调色模块需要同时满足以下几个严苛的目标：

• 输出图像质量高，不引入瑕疵（如色带、噪声放大）；

• 调色行为可预测，用户操作后应有“直觉的一致性”反馈；

• 性能高效，适用于大图、RAW 图、批量处理等使用场景。

这些目标往往互相制约。例如，为了避免颜色断层（banding），可能需要引入 LUT 插值或 gamma 空间调整，而这些操作又会增加计算开销，或引发不同色域下的数值偏差。

我在做图像编辑器 Monica(https://github.com/fengzhizi715/Monica) 时，早期的调色模块仅实现了 HSV 调整和简单的对比度控制，虽然逻辑清晰，但在高分辨率图像和连续处理操作中，逐渐暴露出性能瓶颈，且难以精确控制局部区域。仅靠 naive 的像素遍历方式，难以支撑专业用户对质量与效率的双重要求。

二、初始方案回顾：C++ 从 forEach 到并行 + LUT

在 Monica 的调色模块开发初期，使用了最直接的方式实现图像调整逻辑 —— OpenCV 的 Mat::forEach 方法。每一个像素的调色操作（如色温调整、饱和度增强、高光阴影处理等）都以函数形式在 forEach 中完成。这种写法直观易懂，代码结构清晰，尤其适合快速验证算法的正确性。然而，在实际使用中，forEach 带来的性能瓶颈逐渐暴露出来：在面对超分辨率的大图时，即便只是简单的色温微调，依然会带来明显的延迟感。尤其是在桌面端同步预览调色效果时，用户对交互性能的要求远高于移动端，传统逐像素计算方式已无法满足流畅性的基本要求。

为此，我开始对调色流程进行重构：

• 预计算 LUT 表

• 使用cv::LUT替代 forEach 操作

• 引入cv::parallel_for_加速非线性模块

具体的方案可以看我之前的文章(OpenCV 图像调色优化实录：从 forEach 到并行 + LUT 提速之路)。

三、图像金字塔：高性能调色的关键结构

在调色模块开发中，性能与精度始终是一对难以调和的矛盾。特别是当开始支持大尺寸 RAW 与 HEIC 文件时，这个问题更加突出。一个典型的 RAW 文件往往高达 20MB 以上，解码后的分辨率轻松达到 6000×4000 或更高，直接在原始分辨率上做任何图像处理，性能瓶颈随即显现。

3.1 为什么需要图像金字塔？

在实际用户交互中，调色是一种“即时反馈”的过程。用户拖动滑块，希望看到颜色立刻发生变化。在这个过程中，真正要求“精度”的操作只有最终保存输出，而非每一次预览调整。为此，我们引入了图像金字塔（Image Pyramid）机制，将原始大图处理与预览小图展示逻辑有效分离，达到了如下几方面优化目标：

• 加速预览处理速度 用户拖动滑块调整参数时，只对金字塔中第一级（通常是原图尺寸的 1/2）进行调色与渲染。图像尺寸缩小至原来的 1/2，计算量减少近 4 倍，极大提升了预览响应速度。

• 保证最终图像精度 当用户点击“保存”时，我们再将调色参数应用到原始图像（图像金字塔中的底层），完成真正意义上的精细调色处理与输出，兼顾交互体验与结果质量。

• 统一图像处理入口 金字塔结构本质上是对一张图像在不同分辨率下的封装。无论是预览、最终保存，还是导出缩略图，都可以基于 PyramidImage 对象统一处理逻辑，降低模块耦合度。

3.2 图像金字塔结构与实现方式

图像金字塔由若干级别的图像组成，每一级都是上一级的 1/2 尺寸（通过高斯降采样等方式生成）。在 Monica 的实现中，我设计了如下 PyramidImage 类：

#pragma once

#include <opencv2/opencv.hpp>
#include <vector>
#include <memory>
#include <mutex>
#include <future>
#include <atomic>

class PyramidImage {
public:
    // 从解码后的图像构造（可用原图或预览图）
    explicit PyramidImage(const cv::Mat& image, int levels = 4);

    void waitForPyramid() const;

    bool isPyramidReady() const;

    // 更新原图（如解码完成后替换预览）
    void updateImage(const cv::Mat& newImage);

    // 获取原图
    cv::Mat getOriginal() const;

    // 获取指定层级（0 表示原图，levels-1 为最小图）
    cv::Mat getLevel(int level) const;

    // 获取预览图（默认返回第一层，非最后一层）
    cv::Mat getPreview() const;

    // 获取 pyramid 层级总数
    int getLevelCount() const;

private:
    void buildPyramidAsync();
    int computeValidLevels(const cv::Mat& image, int maxLevel) const;
    cv::Mat downsample(const cv::Mat& input);

    cv::Mat originalImage;
    std::vector<cv::Mat> pyramid;
    int numLevels;

    mutablestd::mutex pyramidMutex;
    mutablestd::shared_future<void> pyramidReadyFuture;
    mutablestd::shared_ptr<std::promise<void>> pyramidReadyPromise;

    std::atomic<bool> isBuilding{false};
};

#include "../../include/pyramid/PyramidImage.h"
#include <thread>
#include <algorithm>
#include <iostream>  // 可用于调试日志

PyramidImage::PyramidImage(const cv::Mat& image, int levels)
        : originalImage(image.clone()), numLevels(std::max(1, levels)) {
    buildPyramidAsync();
}

void PyramidImage::updateImage(const cv::Mat& newImage) {
    {
        std::lock_guard<std::mutex> lock(pyramidMutex);
        originalImage = newImage.clone();
    }
    buildPyramidAsync();
}

void PyramidImage::waitForPyramid() const {
    if (pyramidReadyFuture.valid()) {
        pyramidReadyFuture.wait();
    }
}

bool PyramidImage::isPyramidReady() const {
    return pyramidReadyFuture.valid() &&
           pyramidReadyFuture.wait_for(std::chrono::seconds(0)) == std::future_status::ready;
}

cv::Mat PyramidImage::getOriginal() const {
    std::lock_guard<std::mutex> lock(pyramidMutex);
    return originalImage.clone();
}

cv::Mat PyramidImage::getLevel(int level) const {
    waitForPyramid();