图形学前端【免费下载链接】two.jsA renderer agnostic two-dimensional drawing api for the web项目地址https://gitcode.com/gh_mirrors/tw/two.js点击查看免费下载Two.js 是一个渲染器无关的二维绘图 API而Two.Path正是其构建所有可绘制形状的基础原语类——矩形、椭圆、多边形乃至文本等一切图形本质上都是一条或多条Two.Path。本文将基于仓库内的官方文档与源码系统讲解Two.Path的构造方式、全部属性与方法、渲染更新机制并结合可运行示例与测试用例帮助你直接掌握如何用Two.Path绘制、变换、命中检测和动画任何形状。Two.Path 在 Two.js 中的定位Two.Path继承自Two.Shape见 wiki/docs/shape/README.md而Two.Shape是 Two.js 场景图中承载平移、旋转、缩放等变换的基础对象。从 src/path.js 可以看到其类声明export class Path extends Shape { ... }官方文档对它的定义是This is the primary primitive class for creating all drawable shapes in Two.js即所有可绘制形状的第一原语。这意味着Two.Rectangle、Two.Ellipse、Two.Polygon、Two.Line等内置形状类都建立在Two.Path之上凡是文档中声明返回Two.Path的方法默认都会返回实例自身以支持链式调用例如path.noFill().center()一条Two.Path由有序的Two.Anchor锚点顶点序列定义其形态取决于这些顶点的坐标、控制点手柄handle与命令类型。构造与基础用法构造函数签名与参数含义如下对应 src/path.js 与类型声明 src/path.d.ts参数类型默认值说明verticesTwo.Anchor[]空集合一组Two.Anchor其顺序与坐标决定了渲染出的形状closedBooleanfalse形状是否闭合curvedBooleanfalse是否让 Two.js 自动为每个顶点计算贝塞尔手柄manualBooleanfalse是否由开发者手动控制顶点排布为false时 Two.js 依据closed/curved自动排布坐标最基本的用法是传入一组锚点构造一条折线var path new Two.Path([ new Two.Anchor(0, 0), new Two.Anchor(100, 100), new Two.Anchor(200, 0) ]); path.closed true; // 让首尾相连 path.curved true; // 自动生成平滑贝塞尔曲线构造时 Two.js 会在 src/path.js 初始化一批默认属性closed !!closed、curved !!curved、beginning 0、ending 1、fill #fff、stroke #000、linewidth 1、opacity 1、cap butt、join miter、miter 4并通过this.automatic !manual决定是否自动绘制。测试套件 tests/suite/core.js 给出了贴合实际的构造示例var path new Two.Path([new Two.Anchor(0, 0), new Two.Anchor(100, 100)]); path.fill #ff0000; path.stroke #00ff00; path.linewidth 5; path.opacity 0.5;核心属性详解Two.Path的属性可划分为几何形态、样式外观、渲染控制与蒙版四大类。Path.Propertiessrc/path.js列出了每个 Path 都具备的字符串化属性集合fill、stroke、linewidth、opacity、visible、cap、join、miter、closed、curved、automatic、beginning、ending、dashes、strokeAttenuation。几何与形态closed、curved、automatic、vertices、lengthclosed布尔值决定是否在vertices数组的最后一个点与第一个点之间绘制闭合线src/path.js。将closed置为true会把首尾焊接起来同时把_flagVertices与_flagLength标记为待更新。curved布尔值当automatic true时决定相邻点之间是直线还是平滑曲线src/path.js。automatic布尔值决定 Two.js 是否替开发者自动计算曲线、直线与绘图命令。置为false后开发者可以完全手工控制每个锚点的位置与手柄src/path.js。vertices有序的锚点列表用于渲染路径。虽然看起来是普通数组但它实际是一个Two.Collection实例见 wiki/docs/collection/README.md。从源码看src/path.js该属性在 setter 中会将Collection的insert/remove事件分别绑定到bindVertices与unbindVertices从而在增删顶点时自动通知渲染器更新。length只读所有顶点之间距离的总和src/path.js。它并非预先算好而是在读取时通过_updateLength()惰性求值该值也是getPointAt、beginning/ending截取路径的度量基准。样式属性fill、stroke、linewidth、opacity、cap、join、miterfill/stroke路径的填充与描边内容。既可以是 CSS 颜色字符串如#ff0000、rgba(255,0,0,.5)也可以是Two.Gradient或Two.Texture实例。官方文档提示可参考 CSScolor_value规范了解字符串颜色写法。源码中 settersrc/path.js会为 Gradient/Texture 类型绑定change事件一旦渐变或纹理内容变化便触发重绘。linewidth描边的像素粗细默认1src/path.js。opacity路径的整体不透明度默认1可与带 alpha 通道的 CSS 颜色叠加使用src/path.js。cap线帽样式合法值为butt、round、square见 src/path.d.ts默认butt。join线段连接样式合法值为miter、round、bevel默认miter。miter斜接限制miter limit默认4。以上三种描边属性的取值与语义对应 SVG 的stroke-linecap、stroke-linejoin、stroke-miterlimit规范。渲染控制beginning、ending、visible、className、dashesbeginning/ending均为 0 到 1 之间的小数表示渲染器从路径的百分之多少处开始 / 停止绘制src/path.js。官方文档特别提示这一对属性非常适合配合使用用来让描边路径画进画出身地动画进出。源码在_update()src/path.js中会取beginning与ending的 min/max通过getIdByLength找到截取区间并仅在beginning 0 ending 1时才真正按闭合路径绘制避免截取部分时渲染器用一条直线弦偷懒闭合见 src/path.js。visible是否显示路径。官方文档特别说明在 Canvas 与 WebGL 渲染器下当visible false时所有更新都会被禁用场景中大量对象时性能提升显著src/path.js。className应用于元素的 CSS 类名仅在 SVG 渲染器中真正输出到 DOMsrc/path.js。dashes数字数组奇数下标表示虚线长度、偶数下标表示虚线间隔对应 SVGstroke-dasharray语义dashes.offset为像素单位的虚线显示偏移量对应stroke-dashoffsetsrc/path.js。path.stroke #333; path.linewidth 2; path.dashes [10, 5]; // 10px 实线 5px 空白循环重复 path.dashes.offset 2; // 虚线整体偏移 2px path.beginning 0; path.ending 1;蒙版与描边衰减mask、clip、strokeAttenuationmask其 alpha 属性会成为该路径裁剪区域的形状src/path.js。注意官方文档标注该属性当前因 SVG 规范问题Chromium issue #370951暂不工作。从源码可见给mask赋值对象时若该对象还没有clip会自动把clip置为true。clip布尔值告诉 Two.js 渲染器此对象是否代表另一个对象的蒙版src/path.js。strokeAttenuation布尔值默认true。为true时描边宽度随变换缩放默认行为为false时描边宽度保持屏幕空间恒定——Two.js 会依据对象的世界变换缩放自动补偿描边宽度无论缩放级别如何视觉上的线条粗细保持一致src/path.js。这在缩放画布或相机时非常实用。path.strokeAttenuation false; // 缩放时线条粗细不变对应测试见 tests/suite/core.js它验证了strokeAttenuation属性在true/false两种取值下均能正确读写。序列化fromObject 与 toObjectTwo.Path.fromObject(obj)静态方法从一个描述Two.Path的普通对象创建新实例src/path.js。实现中若fill/stroke是对象而非字符串会调用getEffectFromObject还原为 Gradient/Texture 效果若对象含id则会保留。toObject()实例方法返回一个 JSON 兼容的普通对象来表示该路径包含renderer.type path、vertices以及Path.Properties中所有已定义的属性src/path.js。两者配合即可实现路径 → 对象 → 路径的完整往返。var obj path.toObject(); var restored Two.Path.fromObject(obj); // 得到等价的新路径测试 tests/suite/core.js 验证了这一往返过程toObject保留vertices、fill、id等字段fromObject与copy均能还原出与原始路径一致的实例。实例方法逐一解析copy 与 clonecopy(path)把另一个Two.Path的属性整体复制到当前实例上先复制顶点每个顶点通过clone()深拷贝再遍历Path.Properties复制全部属性src/path.js。clone(parent)创建一份属性完全相同的新Two.Path可选择传入父级Two.Group将克隆体直接加入场景src/path.js。克隆还保留了translation、rotation、scale、skewX、skewY以及手动矩阵。var clone path.clone(); // 独立副本 var cloneInScene path.clone(two.scene); // 克隆并加入场景disposedispose()释放路径的渲染器资源并解绑所有事件src/path.js。从源码看它会解绑 vertices 集合事件、逐顶点解绑顶点与左右控制点事件、并调用 fill/stroke 上 Gradient/Texture 的dispose()或unbind()做彻底清理同时保留渲染器类型以便未来重新挂载到新渲染器。noFill 与 noStroke两个链式速记方法noFill()将fill设为nonenoStroke()将stroke设为none并把linewidth置为0src/path.js。corner 与 centercorner()把形状顶点对齐到路径外接矩形的左上角src/path.js。center()把形状顶点对齐到路径外接矩形的中心src/path.js。两者都通过getBoundingClientRect(true)求局部外接框然后平移所有顶点若存在mask也会同步平移其 translation。getBoundingClientRectgetBoundingClientRect(shallow)返回包含top、left、right、bottom、width、height的对象src/path.js。关键实现细节shallow为true时基于本地矩阵计算否则基于世界矩阵src/path.js计算边界时会考虑linewidth / 2的描边扩展且当存在曲线段时会调用getCurveBoundingBox精确求贝塞尔曲线包围盒src/path.js顶点数为 0 时返回宽高均为 0 的对象。contains命中检测contains(x, y, options)判断某坐标点是否落在Two.Path的边界内返回布尔值src/path.js。参数含义参数说明x,y待检测的坐标options.ignoreVisibility为true时也检测visible false的形状options.tolerance命中检测的像素容差padding官方文档特别强调contains期望的是世界空间坐标——即从渲染器获取的像素空间坐标例如将鼠标clientX/clientY减去 canvas 偏移并换算像素比后得到的值。从源码看src/path.js检测流程为先检查可见性与透明度visible false或opacity 0直接返回false再用getBoundingClientRect()做外接框快速排除随后用worldMatrix的逆矩阵把世界坐标变换为局部坐标借助 src/utils/hit-test.js 中导出的hasVisibleFill、hasVisibleStroke、buildPathHitParts、pointInPolygons、distanceToSegments等工具分别进行填充多边形与描边线段两种精细命中测试填充命中判断点在多边形内描边命中判断点到线段的距离不超过linewidth / 2 tolerance。// 鼠标点击命中检测 var rect canvas.getBoundingClientRect(); var x (event.clientX - rect.left) * two.width / rect.width; var y (event.clientY - rect.top) * two.height / rect.height; if (path.contains(x, y, { tolerance: 2 })) { console.log(命中路径); }getPointAtgetPointAt(t, obj)接收 0 到 1 之间的浮点t返回该路径曲线上对应百分比处的点若传入obj则把计算出的坐标写入该对象否则返回新的Anchorsrc/path.js。它是沿线取点、做描边动画与引导移动的基础工具。源码先按t * this.length在预计算的_lengths分段中定位所在线段再用getComponentOnCubicBezier做三次贝塞尔插值同时用lerp计算出切向控制点src/path.js。var point path.getPointAt(0.5); // 路径中点 path.getPointAt(0.25, someVector); // 写入已有对象plotplot()依据closed/curved与顶点排序计算所有点的位置及各自手柄的位置src/path.js。它虽然是公开方法但官方文档明确说明当automatic true时它由_update()在内部调用开发者通常无需手动触发。从实现看curved true时调用getCurveFromPoints(this._collection, this.closed)生成贝塞尔手柄否则把第一个顶点标为move、其余标为line。smoothsmooth(options)在不切换automatic的情况下调整顶点手柄以生成平滑曲线src/path.js。参数参数说明options.type平滑算法类型options.from开始平滑的顶点下标options.to结束平滑的顶点下标类型声明src/path.d.ts给出的默认值为type continuous、from 0、to 1实际实现src/utils/path.js支持四种算法continuous、asymmetric全局样条以及catmull-rom、geometric局部插值可额外传options.factor调节张力。传入不支持的算法会抛出明确报错Path.smooth does not support type ...src/path.js。执行后会自动把automatic置为false并标记顶点/长度需要更新。path.smooth({ type: catmull-rom, factor: 0.5 });subdividesubdivide(limit)在vertices的每两个相邻锚点之间插入中点锚点src/path.js。limit表示递归细分次数。实现会先调用_update()随后对每段按isSegmentCurved区分曲线段用splitSubdivisionSegment精确切分贝塞尔与直线段线性取中点最后把automatic与curved置为false、写入新的顶点集合。细分后曲线被离散为更多控制点便于做逐点形变或物理仿真。从源码看 Two.Path 的更新机制理解Two.Path的渲染更新机制有助于写出高性能代码。核心是脏标记flag系统与_update()流程每个公开属性如closed、curved、beginning、ending、fill、linewidth等都通过Object.defineProperty定义了 getter/settersrc/path.js 起的proto对象。setter 在赋值时把对应的_flagXxx置为true从而精确追踪哪些属性变了。渲染器在每一帧渲染前调用_update()src/path.js若_flagVertices为真且automatic为真先plot()计算命令与手柄随后_updateLength()重新计算分段长度再依据beginning/ending裁剪出需要渲染的顶点子集写入_renderer.vertices。flagReset()src/path.js在更新完成后把全部标记复位保证只更新变化的部分避免每帧做重复计算。官方文档建议_update一帧内尽量只调用一次。顶点集合是Two.Collection其insert/remove事件驱动BindVertices/UnbindVerticessrc/path.js为每个锚点绑定change监听也就是说直接改动某个Anchor的坐标也会自动触发路径重绘。length属性的惰性求值读取时才_updateLength与闭合方式的两种实现closed属性隐式闭合 vs. SVGZ命令显式闭合都体现在 src/path.js 的分段长度计算中getPointAt与截取渲染共享同一套长度分段数据保证沿线取值与渲染结果一致。测试与验证仓库在 tests/suite/core.js 中提供了大量针对Two.Path的 QUnit 测试可作为学习与回归验证的样例Two.Path Object Conversiontests/suite/core.js验证toObject/fromObject/copy的属性保真Two.Path strokeAttenuationtests/suite/core.js验证描边衰减属性读写大量new Two.Path([...])构造与contains、clone相关用例散布于 tests/suite/core.js、tests/suite/core.js、tests/suite/shapes.js 等位置。运行测试的方式可参考 tests/index.html浏览器运行 QUnit 测试入口与 package.json 中定义的测试脚本。小结Two.Path是 Two.js 所有可绘制形状的地基通过Two.Anchor顶点序列定义几何通过closed/curved/automatic三枚开关控制自动绘图策略通过一整套样式与渲染属性fill、stroke、linewidth、beginning/ending、dashes、strokeAttenuation等控制外观并通过contains、getPointAt、smooth、subdivide、getBoundingClientRect等方法支撑命中检测、沿线动画与网格变形等进阶能力。理解它的构造语义与脏标记更新机制是高效使用 Two.js 绘制、动画与交互图形的前提。更多相关概念可继续阅读 wiki/docs/anchor/README.md锚点、wiki/docs/collection/README.md顶点集合与 wiki/docs/shapes/README.md基于 Path 的内置形状。赞分享图形学前端【免费下载链接】two.jsA renderer agnostic two-dimensional drawing api for the web项目地址https://gitcode.com/gh_mirrors/tw/two.js点击查看免费下载相关推荐Rich Console API 完全指南掌握 Python 终端渲染的核心控制台类Rich Console API 完全指南掌握 Python 终端渲染的核心控制台类 本篇技术指南围绕 Rich 库的核心类 rich.console.Contwo.js 文本绘制完全指南Two.Text 原语类属性、样式与渲染器深入解析two.js 文本绘制完全指南Two.Text 原语类属性、样式与渲染器深入解析 Two.Text 是 two.js一个与渲染器无关的 Web 二维绘图 A图形学前端SFML 2D图形渲染入门用RenderWindow绘制你的第一个图形掌握核心渲染流程SFML 2D图形渲染入门用RenderWindow绘制你的第一个图形掌握核心渲染流程 SFMLSimple and Fast Multimedia Li图形学音视频游戏开发上一篇解锁KaTeX宏系统自定义数学命令的终极指南下一篇Vendure 仓库开发工作流指南从源码构建、E2E 测试到提交分支规范创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考