一、基础定位、头文件、继承关系1. 引入头文件#includeqgssinglebandpseudocolorrenderer.h2. 继承链QgsRasterRenderer ↳ QgsSingleBandRenderer ↳ QgsSingleBandPseudoColorRendererQgsRasterRenderer栅格渲染器顶层抽象基类所有栅格渲染器统一父类定义block()、clone()、XML读写、透明度等通用接口QgsSingleBandRenderer单波段渲染器公共父类封装「渲染波段号」基础逻辑QgsSingleBandPseudoColorRenderer单波段伪彩色渲染器专门实现单波段数值→渐变色/分级上色DEM、NDVI、温度热力图底层渲染器。3. 完整渲染链路总览QgsRasterLayer ↓ QgsSingleBandPseudoColorRenderer 当前讲解对象控制渲染波段、透明度、持有QgsRasterShader ↓ QgsRasterShader scale/offset、拉伸min/max、Nodata透明、亮度对比度 ↓ QgsColorRampShader 分段色标、插值渐变/离散/精确匹配逻辑4. 核心职责指定要渲染的目标波段1起始持有唯一QgsRasterShader着色器实例所有数值转颜色逻辑由shader提供实现栅格像素块渲染入口block()从provider读取像素、调用shader上色、输出RGBA画布统一管理图层透明度、灰度转换、图层混合模式提供克隆、序列化XML保存到qgs工程。二、构造函数// 空构造无数据源、无shader仅用于反序列化加载工程QgsSingleBandPseudoColorRenderer();// 标准业务构造最常用// provider栅格数据源bandNo渲染波段shader着色器传入后renderer接管内存QgsSingleBandPseudoColorRenderer(QgsRasterDataProvider*provider,intbandNo,QgsRasterShader*shadernullptr);三、核心属性读写API1. 渲染波段继承自 QgsSingleBandRenderer// 获取当前渲染波段intband()const;// 修改渲染波段切换后需要重新统计极值、刷新shader拉伸区间voidsetBand(intbandNo);注意波段号从1开始传0会渲染失效。2. 着色器 QgsRasterShader 管理核心// 获取内部着色器可修改min/max、scale/offset、shaderFunctionQgsRasterShader*rasterShader()const;// 设置新着色器renderer 获得 shader 所有权自动释放旧shadervoidsetRasterShader(QgsRasterShader*shader);内存规则setRasterShader()传入的shader由渲染器托管外部禁止手动delete替换shader时旧着色器会自动销毁无内存泄漏。3. 图层全局透明度继承 QgsRasterRenderer// 透明度 0~1000完全不透明100完全透明intopacity()const;voidsetOpacity(intopacity);4. 图层混合模式叠加、正片叠底等QPainter::CompositionModecompositionMode()const;voidsetCompositionMode(QPainter::CompositionMode mode);5. Nodata全局透明开关兼容层实际优先走shader透明配置boolusesTransparentNodata()const;voidsetUsesTransparentNodata(booltransparent);四、核心渲染入口函数 block()函数签名重写父类虚函数QgsRasterBlock*block(constQgsRectangleextent,intwidth,intheight,QgsRasterBlockFeedback*feedbacknullptr)override;功能生成RGBA彩色像素块供画布绘制内部完整执行步骤调用provider-readBlock(band(), extent, width, height)读取原始单波段浮点像素块创建RGBA 4通道输出像素块Byte类型0~255遍历每一行每一列像素判断是否Nodata若shader开启透明Nodata直接填充Alpha0取出原始rawVal交给rasterShader()-shade()计算RGBA应用图层全局透明度opacity衰减Alpha通道返回彩色RGBA像素块上层绘图组件渲染进度反馈feedback用于大影像渲染时进度条、取消渲染。五、克隆、序列化工程保存/加载必备1. 深度克隆 clone()QgsRasterRenderer*clone()constoverride;完整复制波段号、透明度、混合模式、内部完整QgsRasterShader连带内部QgsColorRampShader色标列表深度拷贝返回全新渲染器对象使用完成必须手动delete。2. XML读写 writeXml / readXmlvoidwriteXml(QDomDocumentdoc,QDomElementparentElem)constoverride;voidreadXml(constQDomElementrendererElem)override;存储内容渲染波段、透明度、混合模式完整序列化QgsRasterShadermin/max、scale/offset、亮度对比度、transparentNodata嵌套序列化QgsColorRampShader全部色标、插值模式clip开关等。QGIS工程保存、样式文件(.qml)读写底层依赖这两个接口。六、自动生成拉伸区间工具函数高频业务接口// 根据栅格波段统计自动填充shader的min/max原始像素值scaleoffset0场景voidsetShaderMinMaxToNone();voidsetShaderMinMaxToFullExtent();voidsetShaderMinMaxToCurrentExtent(constQgsRectanglecurrentExtent);常用场景// 自动用整幅栅格的波段极值填充shader拉伸窗口renderer-setShaderMinMaxToFullExtent();内部逻辑调用provider-bandStatistics()获取min/max赋值给shader的minimumValue/maximumValue。七、完整分层协作示例代码DEM伪彩色渲染#includeqgsrasterdataprovider.h#includeqgsrasterbandstats.h#includeqgsrastershader.h#includeqgsrastercolorrampshader.h#includeqgssinglebandpseudocolorrenderer.h#includeqgsrasterlayer.h// DEM单波段伪彩色渲染封装函数voidsetupDemPseudoColorRender(QgsRasterLayer*demLayer){QgsRasterDataProvider*provdemLayer-dataProvider();if(!prov||!prov-isValid())return;intrenderBand1;// 1. 统计波段原始极值QgsRasterBandStats statsprov-bandStatistics(renderBand,QgsRasterBandStats::Min|QgsRasterBandStats::Max);if(!stats.isValid())return;// 2. 构建色标无scale/offsetdisplayValrawValQListQgsColorRampItemitems;items.append(QgsColorRampItem(stats.minVal,QColor(10,40,200),低海拔));items.append(QgsColorRampItem((stats.minValstats.maxVal)/2,QColor(30,190,50),中海拔));items.append(QgsColorRampItem(stats.maxVal,QColor(210,20,20),高海拔));// 3. 色带着色函数QgsColorRampShader*rampFuncnewQgsColorRampShader(items,QgsColorRampShader::Interpolated);rampFunc-setClipBelow(true);rampFunc-setClipAbove(true);// 4. 外层ShaderQgsRasterShader*shadernewQgsRasterShader();shader-setMinimumValue(stats.minVal);shader-setMaximumValue(stats.maxVal);shader-setTransparentNodata(true);shader-setRasterShaderFunction(rampFunc);// 5. 创建伪彩色渲染器核心类QgsSingleBandPseudoColorRenderer*rendernewQgsSingleBandPseudoColorRenderer(prov,renderBand,shader);render-setOpacity(90);// 图层透明度90%render-setCompositionMode(QPainter::CompositionMode_SourceOver);// 6. 绑定到栅格图层demLayer-setRenderer(render);demLayer-triggerRepaint();// 刷新画布}八、与其他栅格渲染器对比区分渲染器类用途是否依赖 QgsRasterShaderQgsSingleBandPseudoColorRenderer单波段渐变/分级伪彩色DEM、NDVI、热力图✅ 必须依赖QgsSingleBandGrayRenderer单波段黑白灰度拉伸✅ 依赖灰度shaderQgsMultiBandColorRendererRGB三波段真彩色遥感影像❌ 无shader直接合成三色QgsPalettedRasterRenderer索引色栅格自带色表❌关键区分QgsSingleBandGrayRenderer和QgsSingleBandPseudoColorRenderer同属单波段渲染器都持有QgsRasterShader灰度渲染器内部shaderFunction是灰度映射伪彩色渲染器搭配QgsColorRampShader实现多色渐变分级。九、开发高频踩坑点1. 内存所有权问题// 正确renderer接管shader无需手动delete shaderQgsRasterShader*shadernewQgsRasterShader();QgsSingleBandPseudoColorRenderer*rendernewQgsSingleBandPseudoColorRenderer(prov,1,shader);// 错误外部手动delete shader渲染器析构时二次释放崩溃deleteshader;2. scale/offset 存在时shader min/max 不能填原始波段极值QgsSingleBandPseudoColorRenderer只负责持有shader不会自动换算scale/offset后的区间需要手动计算displayMin (rawMin-offset)*scale赋值给shader。3. 切换波段后极值不刷新调用setBand(2)切换渲染波段后旧shader的min/max仍是波段1的区间必须重新统计并更新shader拉伸窗口。4. 浮点栅格使用 Exact 模式匹配失败Exact精确匹配仅适合整型分类栅格浮点存在精度误差渲染器会大面积透明。5. 渲染器替换后图层不刷新修改完renderer必须调用layer-triggerRepaint()触发画布重绘。6. 多线程渲染限制block()内部会读取providerGDAL驱动非线程安全多线程并行渲染同一图层需要加互斥锁。十、典型业务使用场景DEM数字高程模型渐变伪彩色渲染NDVI、NDWI植被指数热力分级气温、降雨量、污染物浓度热力图坡度、地形起伏度离散分级设色单波段灰度数据自定义渐变色展示。十一、类层级结构精简总结QgsRasterRenderer (顶层栅格渲染器) └── QgsSingleBandRenderer (单波段公共父类管理波段号) └── QgsSingleBandPseudoColorRenderer ├─ 成员QgsRasterShader* mShader ├─ 核心方法block() 输出RGBA彩色像素块 ├─ 辅助setShaderMinMaxToFullExtent() 自动拉伸 ├─ 生命周期clone()、writeXml/readXml 序列化 └─ 配置透明度、图层混合模式
