[QML] Qt5/6图像色彩空间处理

一、概述

Qt5Compat.GraphicalEffects 模块提供了一系列图像效果控件，用于对图片进行各种视觉处理。这些控件都继承自 QML 的 Item 类型，可以通过数据绑定与用户界面交互，实现实时预览效果。

---

二、基础用法

所有图像效果控件都遵循相同的使用模式：

1. 准备一个 Image 控件作为数据源（通常设置 visible: false）
2. 创建效果控件，指定 source 属性为 Image 的 id
3. 将效果控件通过 anchors.fill 覆盖到容器 Item 上
4. 使用 Slider 等控件，通过 onValueChanged 事件绑定到效果属性上

基础代码示例

// 1. 准备图片源（设置为隐藏）
Image {
    id: img1
    visible: false  // 只让效果控件显示处理后的结果
    source: "qrc:///resource/green_apple.png"
}

// 2. 容器Item
Item {
    id: item
    width: 400
    height: 400
    anchors.centerIn: parent
}

// 3. 效果控件
BrightnessContrast {
    id: bc
    anchors.fill: item  // 填充到容器
    source: img1         // 指定数据源
    brightness: 0.5     // 初始值
    contrast: 0.5
}

// 4. Slider绑定
Slider {
    id: sliderBrightness
    from: 0
    to: 1
    onValueChanged: {
        bc.brightness = value  // 数据绑定
    }
}

---

三、控件分类详解

---

3.1 BrightnessContrast（亮度/对比度）

最常用的图像调整控件，同时控制亮度和对比度。

属性说明：

BrightnessContrast {
    source: img1           // 数据源
    brightness: 0.0       // 亮度，范围 -1.0 到 1.0
                          //   -1.0 = 全黑
                          //    0.0 = 原图
                          //    1.0 = 全白
    contrast: 0.0         // 对比度，范围 -1.0 到 1.0
                          //   -1.0 = 灰度
                          //    0.0 = 原图
                          //    1.0 = 最大对比
}

完整示例：亮度/对比度调整

Window {
    width: 640
    height: 480
    visible: true
    color: "gray"

    Image {
        id: img1
        scale: 0.5
        visible: false
        source: "qrc:///resource/green_apple.png"
    }

    Item {
        id: item
        width: 400
        height: 400
        anchors.centerIn: parent
    }

    BrightnessContrast {
        id: bc
        anchors.fill: item
        source: img1
        brightness: 0.5
        contrast: 0.5
    }

    // 亮度滑块
    Text {
        anchors.right: sliderBrightness.left
        anchors.verticalCenter: sliderBrightness.verticalCenter
        text: "亮度"
        color: "red"
    }
    Slider {
        id: sliderBrightness
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.bottom: sliderContrast.top
        anchors.bottomMargin: 10
        width: 400
        from: 0
        to: 1
        onValueChanged: {
            bc.brightness = value - 0.5  // 转换为 -0.5 到 0.5
        }
    }

    // 对比度滑块
    Text {
        anchors.right: sliderContrast.left
        anchors.verticalCenter: sliderContrast.verticalCenter
        text: "对比度"
        color: "red"
    }
    Slider {
        id: sliderContrast
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.bottom: parent.bottom
        anchors.bottomMargin: 20
        width: 400
        from: 0
        to: 1
        onValueChanged: {
            bc.contrast = value - 0.5
        }
    }
}

---

3.2 Colorize（HSL色彩调整）

在 HSL 色彩空间中进行色调、饱和度、亮度的独立调整。

属性说明：

Colorize {
    source: img1           // 数据源
    hue: 0.0               // 色调，范围 0.0 到 1.0
                          //   0.0 = 红色
                          //   0.33 = 绿色
                          //   0.66 = 蓝色
    saturation: 0.0        // 饱和度，范围 0.0 到 1.0
                          //   0.0 = 灰度
                          //   1.0 = 最大饱和度
    lightness: 0.0        // 亮度，范围 -1.0 到 1.0
                          //   -1.0 = 全黑
                          //    0.0 = 原图
                          //    1.0 = 全白
}

完整示例：HSL色彩调整

Window {
    width: 640
    height: 600
    visible: true
    color: "gray"

    Image {
        id: img1
        scale: 0.5
        visible: false
        source: "qrc:///resource/green_apple.png"
    }

    Item {
        id: item
        width: 400
        height: 400
        anchors.centerIn: parent
        anchors.verticalCenterOffset: -50
    }

    Colorize {
        id: colorize
        anchors.fill: item
        source: img1
        hue: 0.0
        saturation: 0.0
        lightness: 0.0
    }

    // 色调滑块
    Text {
        id: name
        text: "色调"
        anchors.right: sediao.left
        anchors.verticalCenter: sediao.verticalCenter
    }
    Slider {
        id: sediao
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.bottom: baohedu.top
        anchors.bottomMargin: 10
        width: 400
        from: 0
        to: 1
        onValueChanged: {
            colorize.hue = value
        }
    }

    // 饱和度滑块
    Text {
        text: "饱和度"
        anchors.right: baohedu.left
        anchors.verticalCenter: baohedu.verticalCenter
    }
    Slider {
        id: baohedu
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.bottom: liangdu.top
        anchors.bottomMargin: 10
        width: 400
        from: 0
        to: 1
        onValueChanged: {
            colorize.saturation = value
        }
    }

    // 亮度滑块
    Text {
        text: "亮度"
        anchors.right: liangdu.left
        anchors.verticalCenter: liangdu.verticalCenter
    }
    Slider {
        id: liangdu
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.bottom: parent.bottom
        anchors.bottomMargin: 20
        width: 400
        from: -1
        to: 1
        onValueChanged: {
            colorize.lightness = value
        }
    }
}

---

3.3 Desaturate（饱和度调整）

专门用于调整图像饱和度的控件，只有一个参数。

属性说明：

Desaturate {
    source: img1           // 数据源
    desaturation: 0.0      // 饱和度，范围 0.0 到 1.0
                          //   0.0 = 保持原样
                          //   1.0 = 完全灰度化
}

完整示例：单独饱和度调整

Text {
    text: "饱和度"
}

Slider {
    id: baohedu
    anchors.horizontalCenter: parent.horizontalCenter
    width: 400
    height: 30
    from: 0
    to: 1
    onValueChanged: {
        desaturation.desaturation = value
    }
}

Desaturate {
    id: desaturation
    anchors.fill: item
    source: img1
    desaturation: 0  // 初始值
}

---

3.4 GammaAdjust（伽马调整）

通过伽马曲线调整图像亮度，是一种非线性调整方式。

伽马校正是一种非线性操作，常用于控制图像的亮度。通过调整伽马值，您可以改变图像中暗部和亮部的相对亮度，从而实现更自然的视觉效果或特定的艺术风格。

通常，值 1.0 表示没有调整（原始图像）。

值 <1.0 会使图像变亮（尤其是在中间调）。

值 >1.0 会使图像变暗（尤其是在中间调）。

属性说明：

GammaAdjust {
    source: img1           // 数据源
    gamma: 1.0            // 伽马值，范围 0.0 到 +∞
                          //   1.0 = 原图
                          //   < 1.0 = 提亮暗部
                          //   > 1.0 = 压暗亮部
}

完整示例：伽马调整

Slider {
    id: gama
    anchors.horizontalCenter: parent.horizontalCenter
    width: 400
    height: 30
    from: 0
    to: 1
    onValueChanged: {
        gamaAdjust.gamma = value
    }
}

GammaAdjust {
    id: gamaAdjust
    anchors.fill: item
    source: img1
    gamma: 0  // 初始值
}

---

3.5 HueSaturation（色调/饱和度/亮度综合调整）

与 Colorize 类似，但在 HSL 空间中使用不同的参数范围。

属性说明：

HueSaturation {
    source: img1           // 数据源
    hue: 0.0               // 色调，范围 -1.0 到 1.0
                          //   -1.0/1.0 = 不改变
                          //   正值 = 正向偏移
    saturation: -0.3       // 饱和度，范围 -1.0 到 1.0
                          //   -1.0 = 完全灰度
                          //    0.0 = 不改变
                          //    1.0 = 最大饱和度
    lightness: -0.4        // 亮度，范围 -1.0 到 1.0
                          //   -1.0 = 最暗
                          //    0.0 = 不改变
                          //    1.0 = 最亮
}

完整示例：HueSaturation 综合调整

Slider {
    id: gama
    anchors.horizontalCenter: parent.horizontalCenter
    width: 400
    height: 30
    from: 0
    to: 1
    onValueChanged: {
        hue.hue = value
    }
}

HueSaturation {
    id: hue
    anchors.fill: item
    source: img1
    hue: -0.3
    saturation: -0.3
    lightness: -0.4
}

---

四、控件对比速查

控件	属性1	属性2	属性3	典型用途
BrightnessContrast	brightness -1.0~1.0	contrast -1.0~1.0	-	基础曝光调整
Colorize	hue 0.0~1.0	saturation 0.0~1.0	lightness -1.0~1.0	色彩着色
Desaturate	desaturation 0.0~1.0	-	-	灰度化处理
GammaAdjust	gamma 0.0~1.0	-	-	暗部/亮部微调
HueSaturation	hue -1.0~1.0	saturation -1.0~1.0	lightness -1.0~1.0	综合色彩调整

---

五、使用注意事项

5.1 性能优化

• 效果控件会实时渲染，建议对源图片进行缩放处理后再应用效果
• 避免同时使用多个效果控件叠加，可以考虑使用 GLSL 自定义着色器
• 在移动设备上使用时，注意控制效果复杂度

5.2 数据绑定

• Slider 的 from/to 属性决定值的范围，需要根据效果控件的取值范围调整
• 可以在 onValueChanged 中进行值转换，如 value - 0.5 将 0~1 转换为 -0.5~0.5
• 使用 Connections 也可以实现更复杂的绑定逻辑

5.3 常见问题

• 图片不显示：检查 Image 控件的 source 路径是否正确
• 效果不生效：确认效果控件的 source 属性已正确绑定到 Image 的 id
• 值范围不对：参考本文档中的取值范围说明进行调整

---

六、扩展学习

Qt5Compat.GraphicalEffects 模块还包含其他效果控件：

模糊效果： GaussianBlur、Blur、MaskedBlur、RecursiveBlur、FastBlur、DirectionalBlur、RadialBlur、ZoomBlur

颜色调整： ColorOverlay、Threshold、LevelAdjust、DiscreteTransfer

渐变效果： LinearGradient、RadialGradient

投影/发光： DropShadow、InnerShadow、Glow

遮罩效果： OpacityMask、ThresholdMask

其他效果： Convolve、Displacement