当前位置：首页 > news >正文

（6）JS-Clipper2之ClipperOffset

news 2026/2/8 18:40:00

1. 描述

ClipperOffset类封装了对打开路径和关闭路径进行偏移(膨胀/收缩)的过程。
这个类取代了现在已弃用的OffsetPaths函数，该函数不太灵活。可以使用不同的偏移量(增量)多次调用Execute方法，而不必重新分配路径。现在可以在一次操作中对开放和封闭路径的混合进行偏移。此外，OffsetPaths的Limit参数的双重功能不仅让一些用户感到困惑，而且当EndType是etRound和Jo时，它也阻止了自定义RoundPrecision被分配。

当偏移闭合路径(多边形)时，重要的是:

它们的方向是一致的，即外多边形具有相同的方向，而孔具有相反的方向，
它们不自相交。

2.属性

2.1 ClipperLib.ClipperOffset.ArcTolerance

ArcTolerance只有在JoinType是jtRound或者当EndType是开放式轮廓（JoinType = jtRound and/or EndType = etRound）的时候才有效；

ArcTolerance属性（圆弧精度）指定了近似处理弧线时可接受的最大不精确性(“公差”)。

ArcTolerance 默认值为0.25，说明qd（倒角偏离真实圆弧的最大距离）不超过0.25。我们可以发现，qd越小，整个近似圆弧越光滑，代价就是我们需要插入更多的顶点。

将公差降低到0.25以下不会改善平滑度，因为顶点坐标仍将四舍五入为整数值。实现子整数精度的唯一方法是在偏移之前和之后进行坐标缩放（参见下面的示例）。

将ArcTolerance设置为偏移量delta（弧半径）的合理分数是很重要的。相对于偏移delta的较大公差将产生较差的弧近似值，但同样重要的是，非常小的公差将大大降低偏移性能，同时提供不必要的精度。当偏移坐标已被缩放以保持浮点精度的多边形时，这很可能是一个问题。

例如：设想一组多边形（在浮点坐标中定义）将使用圆连接偏移10个单位，解决方案是将浮点精度保持到至少小数点后6位。

为了保持这种程度的浮点精度，并且考虑到Clipper和ClipperOffset都对整数坐标进行操作，在偏移之前，多边形坐标将被缩放108（并四舍五入为整数）。偏移delta和ArcTolerance也需要按相同的因子进行缩放。如果ArcTolerance保持默认的0.25个单位不变，那么解决方案中的每个弧线将包含44000个顶点的一小部分，而最终的弧线不精度将是0.25 × 10-8个单位（即缩放逆转后）。然而，如果在最终未缩放的解决方案中0.1个单位是可接受的不精度，那么ArcTolerance应该设置为0.1 × scaling_factor （0.1 × 108）。现在，如果缩放同样应用于ArcTolerance和Delta Offset，那么在这个例子中，定义每个弧的顶点数（步骤）将是23的一小部分。

Number ArcTolerancevar co = new ClipperLib.ClipperOffset();
co.ArcTolerance = 1.23;

2.2 ClipperLib.ClipperOffset.MiterLimit

该属性包含了一个比例系数(=最大容忍距离/偏置距离)，当大于最大容忍距离时，则会使用1*delta距离来进行；

默认的MiterLimit值大小是2，这也是允许的最小MiterLimit大小，如果没有规定合理的MiterLimit，在部分尖锐的拐角处就会形成长的突起，如下图：

3. 方法

3.1 ClipperLib.ClipperOffset()

构造函数

ClipperOffset ClipperOffset(Number miterLimit = 2.0, Number roundPrecision = 0.25);var co = new ClipperLib.ClipperOffset(2.0, 0.25);

构造函数包含了两个可选参数，MiterLimit和ArcTolerance，这两个参数和其同名的属性的含义是相同的。

MiterLimit只是在JoinType是jtMiter的时候才启用，

ArcTolerance只有在JoinType是jtRound或者当EndType是开放式轮廓的时候才有效；

3.2 ClipperLib.ClipperOffset.AddPath()

void AddPath(Path path, JoinType jointype, EndType endtype);var path = [{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}];
var co = new ClipperLib.ClipperOffset(2, 0.25);
co.AddPath(path, ClipperLib.JoinType.jtMiter, ClipperLib.EndType.etClosedPolygon);

向ClipperOffset对象添加一个路径用来准备偏置；

其中开放式路径只能被偏移一个正值；

这个方法可以被多次调用。

3.3 ClipperLib.ClipperOffset.AddPaths()

向ClipperOffset对象添加路径，为偏移做准备。这个方法可以被多次调用。

void AddPaths(Paths paths, JoinType jointype, EndType endtype);var paths = [[{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}],[{X:20,Y:20},{X:20,Y:100},{X:100,Y:100},{X:100,Y:20}]]; 
var co = new ClipperLib.ClipperOffset(2, 0.25);
co.AddPaths(paths, ClipperLib.JoinType.jtMiter, ClipperLib.EndType.etClosedPolygon);

3.4 ClipperLib.ClipperOffset.Clear()

清空所有多边形对象

去除了Clipper对象中所有存在的被裁剪对象和裁剪对象，使得该Clipper对象可以重用

void Clear();var path = [{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}];
var co = new ClipperLib.ClipperOffset();
co.AddPath(path, ClipperLib.JoinType.jtRound, ClipperLib.EndType.etClosedPolygon);
co.Clear();

3.5 ClipperLib.ClipperOffset.Execute()

void Execute(Paths solution, Number delta);
void Execute(PolyTree polytree, Number delta);var subj = new ClipperLib.Paths();
var solution = new ClipperLib.Paths();
subj[0] = [{"X":348,"Y":257},{"X":364,"Y":148},{"X":362,"Y":148},{"X":326,"Y":241},{"X":295,"Y":219},{"X":258,"Y":88},{"X":440,"Y":129},{"X":370,"Y":196},{"X":372,"Y":275}];
var scale = 100;
ClipperLib.JS.ScaleUpPaths(subj, scale);
var co = new ClipperLib.ClipperOffset(2, 0.25);
co.AddPaths(subj, ClipperLib.JoinType.jtRound, ClipperLib.EndType.etClosedPolygon);
co.Execute(solution, -7.0);
ClipperLib.JS.ScaleDownPaths(subj, scale);
//draw solution with your own drawing function...
DrawPolygons(solution, 0x4000FF00, 0xFF009900);

该方法有两个参数，

第一个是接受结果的结构(可以是PolyTree或Paths中的一种)，

第二个参数是指偏移量的大小–负值会收缩多边形，正值会膨胀扩边多边形。

该方法可以被调用多次，来实现对相同路径实现不同程度的偏置

关于缩放的注意事项：
因为ClipperOffset使用整数坐标，所以你必须缩放坐标以保持精度并使弧线平滑——在整数输入的情况下也是如此。
Javascript Clipper为此提供了四个函数：ScaleUpPath、scaleupppaths、ScaleDownPath和ScaleDownPaths。
如果JoinType为jtRound或EndType为etRound，强烈建议进行缩放