three.js SVGLoader 深入解析从 SVG 字符串到 3D 几何体的完整管线【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.jsSVGLoader 是 three.js 提供的 SVG可缩放矢量图形格式加载器它把 XML 格式的二维矢量图解析为ShapePath数组再借助ShapeGeometry或描边几何生成算法将其渲染为真实的 3D 网格。本文基于仓库中的官方 API 文档 docs/pages/SVGLoader.html.md 与核心实现 examples/jsm/loaders/SVGLoader.js 展开读完后你将掌握SVG 数据经load/parse后的结果结构、defaultDPI与defaultUnit两个关键配置项如何影响坐标换算、各静态方法填充/描边材质、描边几何生成的参数语义与默认值以及从 SVG 描边样式到三角化几何的底层原理。SVGLoader 是什么SVGLoader 继承自Loader是 three.js 的一个 addon附加组件用于加载 Scalable Vector Graphics 格式的矢量图像。SVG 是基于 XML 的二维图形格式支持交互与动画描述SVGLoader 的职责是把它转译成 three.js 世界中的曲线与多边形每个 SVG 图形元素path、rect、circle等被解析为一个ShapePathShapePath中的子路径由直线段、贝塞尔曲线、椭圆弧构成可直接用toShapes()转成可填充的Shape描边stroke部分则由SVGLoader.pointsToStroke()之类的静态方法转成带法线与 UV 的BufferGeometry。SVGLoader 属于 addon必须显式导入参见官方手册 manual/index.html 中的 Installation#Addons 说明import { SVGLoader } from three/addons/loaders/SVGLoader.js;基础用法从文件到网格官方文档给出的最小完整示例如下——加载 SVG 文件遍历其中的路径为每条路径生成填充材质与ShapeGeometryconst loader new SVGLoader(); const data await loader.loadAsync( data/svgSample.svg ); const paths data.paths; const group new THREE.Group(); for ( let i 0; i paths.length; i ) { const path paths[ i ]; const material new THREE.MeshBasicMaterial( { color: path.color, side: THREE.DoubleSide, depthWrite: false } ); const shapes SVGLoader.createShapes( path ); for ( let j 0; j shapes.length; j ) { const shape shapes[ j ]; const geometry new THREE.ShapeGeometry( shape ); const mesh new THREE.Mesh( geometry, material ); group.add( mesh ); } } scene.add( group );需要注意一点版本相关的事实SVGLoader.createShapes( shapePath )自 r185 起已被标记为弃用见 SVGLoader.js#L2244-L2250源码中会打印警告并直接委托给shapePath.toShapes()。因此在新代码中推荐直接调用const shapes path.toShapes();仓库中的官方示例 examples/webgl_loader_svg.html 展示了更完整的填充 描边双通道渲染流程值得参考const loader new SVGLoader(); loader.load( url, function ( data ) { const group new THREE.Group(); group.scale.multiplyScalar( 0.25 ); group.position.x - 70; group.position.y 70; group.scale.y * - 1; // SVG 的 Y 轴向下翻转以匹配屏幕方向 let renderOrder 0; for ( const path of data.paths ) { // 通道一填充形状 const fillMaterial SVGLoader.createFillMaterial( path ); if ( fillMaterial ) { const shapes path.toShapes(); for ( const shape of shapes ) { const geometry new THREE.ShapeGeometry( shape ); const mesh new THREE.Mesh( geometry, fillMaterial ); mesh.renderOrder renderOrder ; group.add( mesh ); } } // 通道二描边几何 const strokeMaterial SVGLoader.createStrokeMaterial( path ); if ( strokeMaterial ) { for ( const subPath of path.subPaths ) { const geometry SVGLoader.pointsToStroke( subPath.getPoints(), path.userData.style ); if ( geometry ) { const mesh new THREE.Mesh( geometry, strokeMaterial ); mesh.renderOrder renderOrder ; group.add( mesh ); } } } } scene.add( group ); } );该示例还通过 GUI 切换了数十个测试用例 SVG 文件如models/svg/tiger.svg、models/svg/lineJoinsAndCaps.svg、models/svg/tests/units.svg等可用于验证各种路径、描边连接样式与单位换算行为。构造与实例属性new SVGLoader( manager )构造函数接收一个可选的LoadingManager用于统一管理多个资源的加载进度与错误上报const manager new THREE.LoadingManager(); const loader new SVGLoader( manager );.defaultDPI : number默认“每英寸点数”dots per inch默认值为90见 SVGLoader.js#L83。它只在 SVG 属性值带有物理单位mm/cm/in/pt/pc且需要换算到像素时才会参与计算。.defaultUnit : mm | cm | in | pt | pc | px默认目标单位默认值为px见 SVGLoader.js#L91。这两个属性共同决定了内部函数parseFloatWithUnits()的换算行为。从源码SVGLoader.js#L1527-L1624可以看出其换算规则内置一个unitConversion二维表覆盖mm/cm/in/pt/pc之间的换算系数其中到px的换算系数标记为-1表示“依赖 DPI”若源单位是px而defaultUnit不是px按“像素 → 英寸 → 默认单位”换算即scale unitConversion[in][defaultUnit] / defaultDPI若源单位带物理单位且defaultUnit是px则scale unitConversion[sourceUnit][in] * defaultDPI。举例说明SVG 中写width1in在默认配置defaultDPI 90defaultUnit px下将得到90个场景单位如果把loader.defaultDPI改成72同样1in就得到72。仓库示例中的models/svg/tests/units.svg测试用例见 webgl_loader_svg.html#L109 中的 “Units” 选项就是专门用于验证这一行为的。.load( url, onLoad, onProgress, onError )从给定 URL 开始加载加载完成后把解析结果传给onLoad()回调。覆写了基类Loader#load。url文件的路径/URL也可以是 data URIonLoad加载完成后执行参数为parse()的返回值onProgress加载过程中执行onError出错时执行。从源码实现SVGLoader.js#L104-L136可以看到内部细节load()实际创建一个FileLoader即按文本读取并透传path、requestHeader、withCredentials等Loader基类的配置文本读取成功后在try/catch中调用scope.parse( text )解析抛错时会调用onError(e)未提供则console.error并向LoadingManager上报itemError( url )。这也意味着加载失败与解析失败都会进入错误通道编写健壮代码时应当同时处理二者。异步偏好者可以直接使用Loader基类提供的loadAsync( url )它返回 Promise即前文示例中await loader.loadAsync( ... )的写法。.parse( text ) : Object解析原始的 SVG 字符串并返回结果对象。覆写了Loader#parse。text原始 SVG 数据字符串。返回值一个对象包含形状路径数组与 SVG XML 文档即{ paths: ArrayShapePath, xml }当前源码实现中还包含gradients渐变定义表见 SVGLoader.js#L2158。parse()是整个加载器中工作量最大的部分源码约 2000 行。其流程为用DOMParser().parseFromString( text, image/svgxml )把字符串变成 XML 文档parseGradients( xml )预扫描所有linearGradient/radialGradient节点建立以id为键的渐变表含 stops、gradientUnits、gradientTransform等支持通过xlink:href的渐变继承以一套默认样式为起点做深度优先遍历parseNode()fill: #000、fillOpacity: 1、strokeOpacity: 1、strokeWidth: 1、strokeLineJoin: miter、strokeLineCap: butt、strokeMiterLimit: 4见 SVGLoader.js#L2148-L2156。从源码结构看节点处理覆盖了这些 SVG 元素path、rect圆角用贝塞尔近似、circle、ellipse、line、polygon、polyline以及容器元素g、svg、style内嵌 CSS 样式表按 class/id 选择器解析和defs/useuse通过xlink:href递归引用已有节点引用不存在的 id 会打印警告。几个值得了解的行为细节样式继承parseStyle()沿 DOM 树逐层克隆并叠加样式支持内联属性、style样式表含多 class 选择器与style属性三种来源数值统一经过parseFloatWithUnits()做单位换算SVGLoader.js#L1202-L1269fill 颜色只有当fill不是none且不是渐变引用url(...)时才会直接把颜色写入path.color渐变则由createFillMaterial()在材质阶段烘焙成纹理变换矩阵每个节点经transform属性translate/rotate/scale/skewX/skewY/matrix解析出的Matrix3会被压入变换栈并对路径的每个曲线做“烘焙”——直线与贝塞尔点直接变换椭圆则按是否含倾斜skew走快速路径或基于特征值分解的通用路径eigenDecompositionSVGLoader.js#L2058-L2125strokeWidth也会乘以变换的缩放比例路径d命令parsePathNode()用正则把d拆成命令序列支持全部 22 种命令M/H/V/L/C/S/Q/T/A及其小写相对形式Z通过autoClose true标记闭合。其中S/T命令通过getReflection()计算控制点反射A椭圆弧命令按 W3C 规范把“端点参数”转换为“中心参数”再调用absellipse()SVGLoader.js#L790-L849半径不足时按规范等比放大。最终每条路径的path.userData会被填充为{ node, style, transform, gradients }这就是后文静态方法所依赖的数据来源。静态方法.createFillMaterial( shapePath ) : MeshBasicMaterial | null为给定路径创建填充材质。从shapePath.userData.style读取样式若fill未定义或为none返回null若fill是url(#gradientId)形式的渐变引用则通过buildGradientTexture()把渐变烘焙成CanvasTexture赋给material.map线性渐变用 1×N 条状纹理 投影矩阵径向渐变用方形纹理 归一化 UV 矩阵并按spreadMethod设置pad/reflect/repeat对应的纹理环绕模式见 SVGLoader.js#L3129-L3273否则把path.color赋给材质材质固定为MeshBasicMaterialopacity fillOpacity * opacity、transparent: true、side: DoubleSide、depthWrite: falseSVGLoader.js#L2171-L2207。.createStrokeMaterial( shapePath ) : MeshBasicMaterial | null为给定路径创建描边材质若stroke未定义或为none返回null若stroke是渐变引用仅打印 “Gradient strokes are not supported” 警告从源码看渐变描边目前不受支持返回的MeshBasicMaterial颜色取style.strokeopacity strokeOpacity * opacity同样transparent: true、DoubleSide、depthWrite: falseSVGLoader.js#L2215-L2235。.createShapes( shapePath ) : Array.由给定的 shape path 创建形状数组。Deprecated自 r185 起弃用请使用shapePath.toShapes()代替。源码中该方法已退化为带警告的转发函数。.getStrokeStyle( width, color, lineJoin, lineCap, miterLimit ) : Object由参数构造一个描边样式对象。各参数及默认值参数说明默认值width描边宽度1color描边颜色格式同Color#getStyle()#000lineJoin连接样式round|bevel|miter|miter-limitmiterlineCap端帽样式round|square|buttbuttmiterLimit最大连接长度以width的倍数计超出则被截断4返回对象为{ strokeColor: color, strokeWidth: width, strokeLineJoin: lineJoin, strokeLineCap: lineCap, strokeMiterLimit: miterLimit }SVGLoader.js#L2262-L2278。该对象可以直接作为pointsToStroke()的style参数用于不经过 SVG 文件、仅凭点列生成描边的场景。.pointsToStroke( points, style, arcDivisions, minDistance ) : BufferGeometry | null从二维点数组创建描边几何。points二维点Vector2数组至少 2 个点路径可以是开放的也可以是闭合的最后一个点等于第一个点styleSVG 样式对象可来自SVGLoader.getStrokeStyle()也可来自SVGLoader.parse()结果中path.userData.stylearcDivisions圆角连接round join与圆端帽round endcap所用的圆弧分段数默认12minDistance距离小于该值的相邻点将被合并默认0.001。返回带position、normal、uv三个属性的BufferGeometry。UV 的生成规则为u沿路径方向v沿路径法线方向从左到右。若没有生成任何几何则返回nullSVGLoader.js#L2290-L2309。其内部实现pointsToStrokeWithBuffers()是一套完整的描边三角化算法约 800 行要点包括先通过removeDuplicatedPoints()按minDistance去除相邻重复点点列少于 2 个直接返回 0以strokeWidth / 2为半宽沿每段法线偏移出左右两条边线逐段生成四边形拆成两个三角形转角处按strokeLineJoin分派bevel直接补一个斜面三角形round调用makeCircularSector()按arcDivisions分段生成扇形miter计算斜接长度超出strokeMiterLimit * width时自动退化为 bevelmiter-clip则按比例截断斜接尖角端点处按strokeLineCap生成端帽round用半圆扇形、square修正已有顶点外延半个线宽、butt不额外生成收尾阶段扫描所有三角形把因尖角折叠而翻转成顺时针的三角形退化为退化三角形避免视觉破洞对应源码注释 “Second fix for #25326”SVGLoader.js#L2763-L2787。.pointsToStrokeWithBuffers( points, style, arcDivisions, minDistance, vertices, normals, uvs, vertexOffset ) : numberpointsToStroke()的底层缓冲区版本前四个参数语义相同arcDivisions默认12minDistance默认0.001另加vertices / normals / uvs调用方预先持有的浮点数组算法直接写入其中vertexOffset写入偏移默认0。返回写入的顶点数量。该方法的两个实用特性见源码注释SVGLoader.js#L2324-L2329可以把vertices传为undefined先“干跑”一次仅返回顶点计数用于预分配精确大小的缓冲区支持带vertexOffset的追加写入因此可以把多条路径的描边合并进同一个 BufferGeometry减少 draw call——这是它相对pointsToStroke()的核心价值。坐标方向与缩放注意事项SVG 的坐标系是 Y 轴向下、原点左上角而 three.js 场景是 Y 轴向上。官方示例的处理方式是webgl_loader_svg.html#L173-L177group.scale.multiplyScalar( 0.25 ); // 缩小整体尺寸 group.position.x - 70; // 手动居中 group.position.y 70; group.scale.y * - 1; // 翻转 Y 轴由于加载结果没有自动居中/归一化实际项目中通常还需要根据path.userData中的路径点自行计算包围盒来居中与缩放defaultDPI/defaultUnit决定了 SVG 单位到场景单位的换算基准跨文件统一配置即可保证不同 SVG 之间的相对尺寸一致。源码与相关资源核心实现examples/jsm/loaders/SVGLoader.js约 3300 行含路径命令解析、单位换算、变换烘焙、描边三角化与渐变纹理烘焙官方示例页面examples/webgl_loader_svg.html内置 30 个测试 SVG老虎、连接样式、单位、defs 继承、CSS 样式表等可切换填充/描边开关与线框模式对比效果API 文档源文件docs/pages/SVGLoader.html.md 与渲染页 docs/pages/SVGLoader.html。小结SVGLoader 把 SVG 加载拆成两个清晰的层次parse()负责“忠实转译”——把 XML、样式表、变换、渐变全部解析为带userData的ShapePath集合静态方法负责“按需生成”——createFillMaterial()/createStrokeMaterial()生成与 SVG 样式对齐的材质toShapes()ShapeGeometry或pointsToStroke() 描边几何则决定最终的三角化方式。理解了defaultDPI/defaultUnit的换算规则、userData.style的数据结构以及描边算法对 join/cap 的处理就能把任意来源的 SVG 资源稳定地接入 three.js 场景。【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考