deck.gl SolidPolygonLayer 完全指南填充与挤出多边形渲染、属性配置与二进制数据优化【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.glSolidPolygonLayer 是 deck.gl 中负责渲染填充filled和/或挤出extruded多边形的原始primitive图层也是高层 PolygonLayer 内部渲染填充部分的底层实现。本文以仓库中的官方文档 solid-polygon-layer.md 为骨架结合 solid-polygon-layer.ts、polygon.ts 与 polygon-tesselator.ts 等源码系统讲解其安装方式、全部渲染选项与数据访问器、多边形几何格式、二进制属性直通优化以及 WebGL2/WebGPU 双后端下的底层原理与性能注意事项。读完本文你将能独立构建从简单区块着色到带孔洞、带海拔的三维挤出多边形场景并能针对大规模数据做性能优化。一、图层概览与定位SolidPolygonLayer的核心职责是把多边形几何数据三角化tessellation后渲染为填充的面并且可选地沿高度方向挤出形成三维体块。它只负责面的渲染不渲染轮廓线——如果需要渲染多边形描边应使用 PathLayer。从源码结构看该图层的定位非常清晰它本身是一个原始图层继承自Layer见 solid-polygon-layer.tslayerName为SolidPolygonLayer高层复合图层PolygonLayer在渲染时用getSubLayerClass(fill, SolidPolygonLayer)创建它作为fill子图层同时用PathLayer作为stroke子图层见 polygon-layer.ts。因此PolygonLayer中所有和填充面相关的行为最终都落到本图层上测试中GeoJsonLayer内部也会创建SolidPolygonLayer子图层来完成面要素渲染见 arc-layer.spec.ts 与 solid-polygon-layer.spec.ts。最小可用示例官方文档给出一个基于旧金山邮编区划sf-zipcodes数据的最小示例同时覆盖 JavaScript、TypeScript 与 React 三种用法。以 JavaScript 为例import {Deck} from deck.gl/core; import {SolidPolygonLayer} from deck.gl/layers; const layer new SolidPolygonLayer({ id: SolidPolygonLayer, data: https://raw.githubusercontent.com/visgl/deck.gl-data/master/website/sf-zipcodes.json, extruded: true, wireframe: true, getPolygon: d d.contour, getElevation: d d.population / d.area / 10, getFillColor: d [d.population / d.area / 60, 140, 0], getLineColor: [80, 80, 80], pickable: true }); new Deck({ initialViewState: { longitude: -122.4, latitude: 37.74, zoom: 11 }, controller: true, getTooltip: ({object}) object ${object.zipcode}\nPopulation: ${object.population}, layers: [layer] });TypeScript 版本的关键差异在于泛型与类型标注import {Deck, PickingInfo} from deck.gl/core; import {SolidPolygonLayer} from deck.gl/layers; type ZipCode { zipcode: number; population: number; area: number; contour: [longitude: number, latitude: number][]; }; const layer new SolidPolygonLayerZipCode({ id: SolidPolygonLayer, data: https://raw.githubusercontent.com/visgl/deck.gl-data/master/website/sf-zipcodes.json, extruded: true, wireframe: true, getPolygon: (d: ZipCode) d.contour, getElevation: (d: ZipCode) d.population / d.area / 10, getFillColor: (d: ZipCode) [d.population / d.area / 60, 140, 0], getLineColor: [80, 80, 80], pickable: true });React 版本则使用deck.gl/react提供的DeckGL组件挂载图层import React from react; import {DeckGL} from deck.gl/react; import {SolidPolygonLayer} from deck.gl/layers; import type {PickingInfo} from deck.gl/core; function App() { const layer new SolidPolygonLayerZipCode({ id: SolidPolygonLayer, data: https://raw.githubusercontent.com/visgl/deck.gl-data/master/website/sf-zipcodes.json, extruded: true, wireframe: true, getPolygon: (d: ZipCode) d.contour, getElevation: (d: ZipCode) d.population / d.area / 10, getFillColor: (d: ZipCode) [d.population / d.area / 60, 140, 0], getLineColor: [80, 80, 80], pickable: true }); return DeckGL initialViewState{{longitude: -122.4, latitude: 37.74, zoom: 11}} controller getTooltip{({object}: PickingInfoZipCode) object ${object.zipcode}\nPopulation: ${object.population}} layers{[layer]} /; }示例中getElevation使用人口密度population / area推算挤出高度、getFillColor用人口密度映射绿色通道直观演示了一个 accessor 驱动三维视觉变量的典型数据可视化模式。二、安装与导入方式官方文档提供了两种安装路径# 方式一安装聚合包 npm install deck.gl # 方式二按需安装模块 npm install deck.gl/core deck.gl/layers推荐按需安装方式二只引入deck.gl/coreDeck 实例、视图、属性管理器等与deck.gl/layers包含本图层的全部基础图层。代码中通过类型导入获取完整类型提示import {SolidPolygonLayer} from deck.gl/layers; import type {SolidPolygonLayerProps} from deck.gl/layers; new SolidPolygonLayerDataT(...props: SolidPolygonLayerPropsDataT[]);SolidPolygonLayerPropsDataT类型定义在 solid-polygon-layer.ts 中等于_SolidPolygonLayerPropsDataT LayerProps——也就是说所有基础 Layer 属性id、data、pickable、opacity、visible、updateTriggers等均自动继承。如果使用预打包脚本pre-bundled scripts通过 CDN 引入后在全局命名空间deck下使用script srchttps://unpkg.com/deck.gl^9.0.0/dist.min.js/script !-- 或分别引入 core 与 layers -- script srchttps://unpkg.com/deck.gl/core^9.0.0/dist.min.js/script script srchttps://unpkg.com/deck.gl/layers^9.0.0/dist.min.js/scriptnew deck.SolidPolygonLayer({});三、渲染选项Render Options本小节所有属性在源码的_SolidPolygonLayerProps类型与defaultProps中均有对应声明见 solid-polygon-layer.ts下表汇总默认值与作用属性类型默认值作用filledbooleantrue是否按getFillColor填充多边形面extrudedbooleanfalse是否按getElevation挤出多边形三维wireframebooleanfalse是否生成多边形的线框轮廓elevationScalenumber1海拔倍率最终海拔 elevationScale * getElevation(d)materialMaterialtrue挤出面的光照材质配置_normalizebooleantrue实验性是否规范化getPolygon返回的坐标_windingOrderCW \| CCWCW实验性环的绕序仅在_normalize: false时生效_full3dbooleanfalse实验性是否在面积最大的平面上执行三角化3.1 filled / extruded / wireframe三种渲染形态filled默认true决定是否绘制多边形表面。关闭后不生成面可与其他图层叠加使用。extruded默认false决定是否沿getElevation给出的高度挤出。文档特别强调如果不需要三维效果应保持extruded: false而不是把getElevation返回 0——扁平渲染生成的几何体更少、速度更快。源码中getElevation的默认值为1000但仅在extruded: true时生效。wireframe默认false生成多边形的线框包含封闭顶部/底部的水平线条以及每个顶点处的一条垂直支柱strut。需要注意的两个官方提醒线框使用GL.LINE绘制因此线宽恒为 1 像素线框与实体挤出互斥若想同时看到实体与线框效果需要用相同数据创建两个图层叠加。从渲染实现看这一互斥关系体现得非常直观。在 draw() 方法中存在wireframeModel且wireframe: true时先绘制triangle-strip拓扑的线框模型存在sideModel且filled: true时绘制侧面侧面模型是 instanced 的triangle-strip四边形见 solid-polygon-layer.ts存在topModel且filled: true时绘制顶部面非 instanced、使用索引的triangle-list见 solid-polygon-layer.ts。也就是说图层内部实际上维护了顶面、侧面、线框三个独立 Modelfilled/extruded/wireframe三个开关共同决定哪些 Model 被创建和绘制。此外updateState中当filled或extruded变化时模型会被重建regenerateModels见 solid-polygon-layer.ts。3.2 elevationScale不改数据也能缩放海拔elevationScale的最终海拔计算公式为最终海拔 elevationScale * getElevation(d)它是一个纯数字倍率源码中类型为{type: number, min: 0, value: 1}即不允许负值见 solid-polygon-layer.ts作用是在不更新数据的前提下整体缩放海拔。典型应用场景是数据本身是真实海拔米而展示时需要统一放大若干倍以获得视觉层次。从 WGSL 着色器代码可以确认该属性在 GPU 端的实际应用pos.z attributes.elevations * solidPolygon.elevationScale见 solid-polygon-layer.wgsl.ts。3.3 material挤出面的光照材质material默认值为true是一个包含材质属性的对象用于 LightingEffect 对挤出多边形的光照计算。可配置项如ambient、diffuse、shininess、specularColor等详见 光照材质指南。实现上图层着色器模块栈中集成了gouraudMaterial模块见 solid-polygon-layer.ts这正是 Gouraud 光照材质在 WebGL 后端的入口若不需要光照可显式传material: false获得更快的渲染性能。3.4 实验性渲染选项_normalize / _windingOrder / _full3d这三个属性以下划线开头属于实验性 API仅在确有性能或特殊渲染需求时使用_normalize默认true是否规范化getPolygon返回的坐标。设为false可跳过规范化流程提升数据更新时的性能但要求数据本身格式正确、闭合且绕序一致否则容易出错。官方建议仅在已预处理好的静态数据或后端已做校验的场景使用。当关闭规范化后多边形必须以扁平数组或{positions, holeIndices}形式提供且环必须闭合首尾顶点相同绕序必须与_windingOrder一致。_windingOrder默认CW仅在_normalize: false时生效指定环的绕序CW外环顺时针孔洞逆时针CCW外环逆时针孔洞顺时针。具体取值取决于数据来源——大多数几何格式强制规定了绕序。绕序设置错误会导致挤出多边形的面朝向翻转进而影响背面剔除culling和光照效果。源码中该属性通过RING_WINDING_ORDER_CW着色器 define 传入见 solid-polygon-layer.ts而在内部规范化路径中多边形统一被改写为外环顺时针、孔洞逆时针OUTER_POLYGON_WINDING WINDING.CLOCKWISE、HOLE_POLYGON_WINDING WINDING.COUNTER_CLOCKWISE见 polygon.ts。_full3d默认false仅对XYZ三维坐标数据生效。设为true时多边形三角化在面积最大的平面上执行而不是默认的 xy 平面。适用于几何特征只沿 z 轴变化而需要正确渲染的场景。源码中getSurfaceIndices会分别计算 xy/xz/yz 三个平面的面积选择最大者必要时对坐标做置换permute后再交给 earcut 三角化见 polygon.ts。四、数据访问器Data Accessors本小节四个 accessor 均支持传常量值作用于所有对象或传函数对每个对象调用并且都标注了 transition-enabled支持属性过渡动画。访问器默认值说明getPolygonobject object.polygon返回每个数据对象对应的多边形几何getFillColor[0, 0, 0, 255]填充色 RGBAgetLineColor[0, 0, 0, 255]描边色 RGBA仅extruded: true时生效getElevation1000挤出高度仅extruded: true时生效4.1 getPolygon四种多边形几何格式getPolygon默认返回object.polygon其返回值PolygonGeometry在 polygon.ts 中被定义为以下四种格式的联合格式一点数组单个环// [x, y, z] 数组 const polygon [[-122.4, 37.7], [-122.4, 37.8], [-122.5, 37.8]];格式二环的数组首环为外边界后续环为孔洞// 兼容 GeoJSON Polygon 规范RFC 7946 const polygon [ [[-122.4, 37.7], [-122.4, 37.8], [-122.5, 37.8], [-122.5, 37.7], [-122.4, 37.7]], // 外环 [[-122.45, 37.75], [-122.45, 37.77], [-122.47, 37.77], [-122.47, 37.75], [-122.45, 37.75]] // 孔洞 ];格式三扁平数组或 TypedArray// 等价于单个环[x0, y0, z0, x1, y1, z1, ...] const polygon [-122.4, 37.7, 0, -122.4, 37.8, 0, -122.5, 37.8, 0];默认每个坐标占 3 个连续数字若每个坐标只有 2 个数字x, y需将图层的positionFormat设为XY。格式四{positions, holeIndices}对象const polygon { positions: [-122.4, 37.7, 0, -122.4, 37.8, 0, -122.5, 37.8, 0, /* ... */], // 扁平坐标数组 holeIndices: [9] // 每个孔洞在 positions 中的起始索引首环为外边界 };其中positions为扁平坐标数组同样默认 3 个数字一组holeIndices记录每个孔洞的起始索引。源码中polygon.ts的normalize()函数会把上述四种格式统一规范化成扁平复数多边形positions holeIndices或扁平简单多边形并自动① 检测环是否闭合未闭合时自动补上首顶点完成闭合copyNestedRing/copyFlatRing② 按外环顺时针、孔洞逆时针修正绕序通过modifyPolygonWindingDirection。这就是为什么多边形即使首尾顶点不重复也会被自动视为闭合。4.2 颜色与海拔访问器getFillColorRGBA 颜色格式[r, g, b, [a]]每通道 0-255a缺省时为 255。传数组则全体使用该颜色传函数则逐对象求值。getLineColor同上格式仅extruded: true时生效作用于线框/侧面线条。getElevation挤出高度。使用地理投影模式时按米解释例如lnglat坐标系下即米制否则按单位坐标解释仅extruded: true时生效。传数字或函数均可。源码层面这三个访问器分别映射到elevations、fillColors、lineColors三个缓冲区其中fillColors/lineColors使用unorm8类型、尺寸跟随colorFormat见 solid-polygon-layer.ts并且都支持属性过渡transition: ATTRIBUTE_TRANSITION。五、多边形三角化与几何规范化源码原理为了让上面的配置讲解落到实处这里补充文档未展开的底层机制。5.1 三角化流水线SolidPolygonLayer的几何生成完全由PolygonTesselator继承自 deck.gl 的Tesselator管理核心流水线为规范化normalizeGeometry调用Polygon.normalize()把四种输入格式统一为扁平形式见 polygon-tesselator.ts可选切割当设置了resolution经纬度网格切割或wrapLongitude墨卡托边界切割时多边形会被cutPolygonByGrid/cutPolygonByMercatorBounds切割成多个子多边形用于处理跨 180° 经线等场景三角化getSurfaceIndices使用earcut库对规范化后的多边形执行耳切法三角化见 polygon.ts同时生成顶点位置、索引和vertexValid三个属性见 polygon-tesselator.ts。在initializeState中如果数据是lnglat坐标系还会传入preproject预投影函数因为经纬度坐标通常是非线性投影会影响三角化结果见 solid-polygon-layer.ts。5.2 vertexValid区分真实边界与相邻复用顶点的掩码由于侧面/线框渲染会把相邻顶点的缓冲区通过偏移一个顶点的方式复用nextVertexPositions属性见 solid-polygon-layer.ts每个环的最后一个顶点会与下一环的第一个顶点重叠。vertexValid掩码用于标记这些不应绘制连线的位置positions A0 A1 A2 A3 A4 B0 B1 B2 C0 ... nextPositions A1 A2 A3 A4 B0 B1 B2 C0 C1 ... vertexValid 1 1 1 1 0 1 1 0 1 ...示例来自 polygon-tesselator.ts 的注释。每环最后一个顶点标记为 0从而避免跨环的伪线段。六、使用二进制属性Use binary attributes这是面向大规模数据的核心优化手段。常规路径下图层需要为每个顶点展开属性、执行三角化而直接以二进制缓冲区喂给图层可以跳过大部分 CPU 侧的数据处理显著降低数据更新开销。官方文档将这种方式与 性能指南-直接提供属性 关联。6.1 必须提供的布局信息因为每个多边形的顶点数不同当直接提供data.attributes.getPolygon时图层还必须提供data.startIndices——它描述每个多边形起始顶点在缓冲区中的索引。例如有 3 个多边形、顶点数分别为 5、6、7均包含与首顶点重合的闭合末顶点则startIndices应为[0, 5, 13, 20]。当多边形数据包含孔洞时还需要额外提供data.attributes.vertexValid掩码所有顶点为1但每个环最后一个顶点的索引为0。官方文档给出的例子是第二个多边形含一个 3 顶点的外环加一个 3 顶点的内环此时vertexValid为[1, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 0, 1, 1, 1, 1, 1, 1, 1, 0]关于vertexValid如何从原始要素批量推导可参考 GeoJSON 图层中的参考实现 geojson-layer-props.ts它对顶点总数生成全 1 掩码然后把每个多边形末顶点索引处index - 1置 0再以instanceVertexValid属性传入。6.2 其他属性的对齐要求所有其他属性getFillColor、getElevation等若以二进制提供必须与getPolygon缓冲区保持相同的顶点数量布局——即每个顶点对应一份颜色/海拔值。6.3 关闭规范化以真正获益要真正拿到二进制数据的性能红利应用应尽可能跳过图层内全部数据处理设置_normalize: false。源码中当_normalize: false且未提供索引缓冲区时getGeometryFromBuffer直接返回null即无需读取位置数据做规范化/三角化见 polygon-tesselator.ts。此时数据由外部二进制直接透传。6.4 完整对照示例普通 JSON 数组写法const POLYGON_DATA [ { contour: [[-122.4, 37.7], [-122.4, 37.8], [-122.5, 37.8], [-122.5, 37.7], [-122.4, 37.7]], population: 26599 }, // ... ]; new SolidPolygonLayer({ data: POLYGON_DATA, getPolygon: d d.contour, getElevation: d d.population, getFillColor: [0, 100, 60, 160] })等价的二进制属性写法// 展平多边形顶点 // [-122.4, 37.7, -122.4, 37.8, -122.5, 37.8, -122.5, 37.7, -122.4, 37.7, ...] const positions new Float64Array(POLYGON_DATA.map(d d.contour).flat(2)); // 颜色/海拔属性必须为每个顶点提供一个值 // [255, 0, 0, 255, 0, 0, 255, 0, 0, ...] const elevations new Uint8Array(POLYGON_DATA.map(d d.contour.map(_ d.population)).flat()); // startIndices 描述每个多边形在缓冲区中的起始顶点索引 const startIndices new Uint16Array(POLYGON_DATA.reduce((acc, d) { const lastIndex acc[acc.length - 1]; acc.push(lastIndex d.contour.length); return acc; }, [0])); new SolidPolygonLayer({ data: { length: POLYGON_DATA.length, startIndices: startIndices, // 必需否则无法正确渲染各多边形 attributes: { getPolygon: {value: positions, size: 2}, getElevation: {value: elevations, size: 1} } }, _normalize: false, // 指示图层跳过规范化直接使用二进制数据 getFillColor: [0, 100, 60, 160] })要点提示data.length为多边形数量getPolygon的size: 2表示每坐标 2 个数字x, y因此也无需再设置positionFormat常量访问器如getFillColor数组不需要展开成顶点级缓冲区图层会自动补齐_normalize: false时数据必须已经闭合、绕序正确且格式为扁平或{positions, holeIndices}见上文 3.4 节。仓库测试 solid-polygon-layer.spec.ts 中WebGPU binary extruded polygons 用例使用geojsonToBinary把 GeoJSON 转为二进制后喂给GeoJsonLayer并断言SolidPolygonLayer子图层能正常初始化渲染可作为二进制路径的端到端参考。七、备注与使用要点Remarks官方文档在结尾给出三条经验性结论只渲染填充面需要多边形轮廓时使用 PathLayer多边形总是闭合即使首尾顶点不相同图层也会在两者之间隐式补一条线段复杂多边形的规范遵循 GeoJSON 约定首环为外边界、后续环为孔洞与 RFC 7946 的 Polygon 结构保持一致这一点在 4.1 节的格式二中有完整体现。另外补充两点从源码可确认的工程细节该图层关闭了经度环绕wrapLongitude返回false见 solid-polygon-layer.ts因此跨 180° 经线的多边形需要自行处理切割getBounds()基于vertexPositions属性计算图层包围盒见 solid-polygon-layer.ts可用于视口适配等场景。八、WebGL2 与 WebGPU 双后端说明文档开头标注了 WebGPU 支持。源码中图层对两个后端做了明确的差异化适配着色器WebGL2 使用 GLSL 顶点/片元着色器solid-polygon-layer-vertex-top.glsl、solid-polygon-layer-vertex-side.glsl、solid-polygon-layer-fragment.glslWebGPU 使用 WGSLgetSolidPolygonShaderWGSL见 solid-polygon-layer.ts属性布局WebGPU 无法表达 WebGL 的单顶点偏移视图因此额外生成独立的nextVertexPositions缓冲区见 solid-polygon-layer.ts并在二进制输入时按 stride/offset 手动展平位置calculatePositions见 solid-polygon-layer.ts顶点有效掩码WebGPU 使用vertexValidfloat32与独立indices布局WebGL 使用实例化的instanceVertexValiduint16且顶面模型在 WebGPU 下会过滤掉侧面专用属性见 solid-polygon-layer.ts裁剪扩展clipExtension仅在 WebGPU 后端被挂载见 solid-polygon-layer.ts。对于绝大多数应用无需感知这些差异deck.gl 会自动选择后端只有当你在 WebGPU 路径上排查二进制渲染问题时上述布局差异才成为关键线索。九、相关资源官方 API 文档solid-polygon-layer.md底层源码目录modules/layers/src/solid-polygon-layer图层实现solid-polygon-layer.ts几何规范化与三角化polygon.ts三角化器polygon-tesselator.ts复合图层PolygonLayerpolygon-layer.ts高层 GeoJSON 图层中vertexValid的参考实现geojson-layer-props.ts二进制数据性能指南performance.md光照材质设置using-effects.md基础图层属性layer.md相关测试solid-polygon-layer.spec.ts【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考