├── ChangeLog.txt
├── Documentation.md
├── README.md
├── bower.json
├── clipper.js
├── example
└── main_demo.html
└── package.json
/ChangeLog.txt:
--------------------------------------------------------------------------------
1 | ============================================================
2 | Javascript Clipper Change Log
3 | ============================================================
4 |
5 | v6.4.2.2 (8 September 2017)
6 | * Added ClipperLib.version, which returns "6.4.2.2".
7 | * Main Demo -updates:
8 | - Main Demo is made to support IntPoint and FPoint version of
9 | Javascript Clipper.
10 | - Benchmark is now more complete. Nearly all possible combinations
11 | of various properties are covered. A new Random Benchmark is added,
12 | which covers Random Rectangles, Random Polygons and Random Grid -
13 | polygon types.
14 | - Polygons in Preview-window are now hoverable and clickable.
15 | - Polygon explorer shows now the clicked polygon in red color.
16 |
17 | v6.4.2.1 (3 September 2017)
18 | * Speedup: Overloading techique is changed regarding functions IntPoint,
19 | DoublePoint and SlopesEqual. This reduced execution time of intersection
20 | operation from 101 ms to 69 ms in solutions with 10k+ vertices.
21 |
22 | * Several bugfixes:
23 | #12 Union of polygons with colinear edges (2)
24 | #16 horizontal end segment of an open path gets reversed.
25 | #17 ClipperLib.JS.Lighten always returns a Paths
26 | #18 TypeError: this.ParseFirstLeft is not a function
27 | #19 ir is not defined
28 | #20 Undesired zero width bridge when performing difference operation
29 |
30 | * Updates from C# Clipper v6.4.2 (27 February 2017) Rev 512:
31 | - Several minor bugfixes: #152 #160 #161 #162
32 |
33 | * Updates from C# Clipper v6.4 (2 July 2015) Rev 495:
34 | - Numerous generally minor bugfixes
35 |
36 | v6.2.1.2 (27 November 2016)
37 | * use_xyz directive changed to ClipperLib.use_xyz and use_lines
38 | directive changed to ClipperLib.use_lines, so they can be set
39 | runtime.
40 | * use_int32 removed, because in Javascript there is no such integer.
41 | * When copying IntPoints, Z-member was missing when use_xyz is true.
42 |
43 | v6.2.1.1 (19 November 2016)
44 | * Line 3282: Changed ZFillFunction to this.ZFillFunction.
45 |
46 | v6.2.1.0 (17 June 2016)
47 | * Updates from C# Clipper upto 6.2.1 Rev 482 (31 October 2014).
48 |
49 | * Updates from C# Clipper v6.2.1 (31 October 2014) Rev 482:
50 | - Bugfix in ClipperOffset.Execute where the Polytree.IsHole property
51 | was returning incorrect values with negative offsets
52 | - Very minor improvement to join rounding in ClipperOffset
53 |
54 | * Updates from C# Clipper v6.2.0 (17 October 2014) Rev 477:
55 | - Numerous minor bugfixes, too many to list.
56 | (See revisions 454-475 in Sourceforge Repository)
57 | - The ZFillFunction (custom callback function) has had its parameters
58 | changed.
59 | - Deprecated functions have been removed.
60 |
61 | * Updates from C# Clipper v6.1.5 (26 February 2014) Rev 460
62 | - Improved the joining of output polygons sharing a common edge
63 | when those common edges are horizontal.
64 | - Fixed a bug in ClipperOffset.AddPath() which would produce
65 | incorrect solutions when open paths were added before closed paths.
66 | - Minor code tidy and performance improvement
67 |
68 | * Updates from C# Clipper v6.1.4 (6 February 2014)
69 | - Fixed bugs in MinkowskiSum
70 | - Fixed minor bug when using Clipper.ForceSimplify.
71 | - Modified use_xyz callback so that all 4 vertices around an
72 | intersection point are now passed to the callback function.
73 |
74 | v6.1.3.2 (1 February 2014)
75 | * Update: Unnecessary closures removed around ref/out calls and major
76 | speedup and code cleanliness achieved. Intersection operation speedup
77 | in newest Chrome is 2.3x (from 2530 ms to 1107 ms) and in newest
78 | Firefox 1.7x (from 7186 ms to 4164 ms).
79 |
80 | v6.1.3.1 (21 January 2014)
81 | * Fixed potential endless loop condition when adding open
82 | paths to Clipper.
83 | * Added PointInPolygon function.
84 | * Overloaded MinkowskiSum function to accommodate multi-contour
85 | paths.
86 |
87 | v6.1.2.1 (15 December 2013)
88 | * Minor improvement to joining polygons.
89 |
90 | v6.1.1.1 (13 December 2013)
91 | * Fixed a couple of bugs affecting open paths that could
92 | raise unhandled exceptions.
93 | * Fixed Uncaught ReferenceError: DistanceFromLineSqrd is not defined when
94 | using CleanPolygon or CleanPolygons
95 | * Fixed SimplifyPolygon calls in Main Demo
96 |
97 | v6.1.0.1 (12 December 2013)
98 | * Added: Info and Examples page: http://jsclipper.sourceforge.net/6.1.0.1/
99 | * Added: Clipper 6 documentation in
100 | https://sourceforge.net/p/jsclipper/wiki/documentation/
101 | * Migration guide for Clipper 5 users in
102 | https://sourceforge.net/p/jsclipper/wiki/migration5to6/
103 | * Modified: To accommodate open paths, several functions have been renamed:
104 | Polygon -> Path
105 | Polygons -> Paths
106 | AddPolygon -> AddPath
107 | AddPolygons -> AddPaths
108 | PolyTreeToPolygons -> PolyTreeToPaths
109 | ReversePolygons -> ReversePaths
110 | * Modified: OffsetPolygons function is replaced by ClipperOffset
111 | class, which is much more flexible. There is also now deprecated
112 | OffsetPaths function, which may be removed in future update.
113 | * Update: ExPolygons has been replaced with the PolyTree &
114 | PolyNode classes to more fully represent the parent-child
115 | relationships of the polygons returned by Clipper. There is
116 | for backward compatibility ClipperLib.JS.PolyTreeToExPolygons.
117 | * Added: Open path (polyline) clipping.
118 | * Update: Major improvement in the merging of
119 | shared/collinear edges in clip solutions (see Execute).
120 | * Added: The IntPoint structure now has an optional 'Z' member.
121 | (See the precompiler directive use_xyz.)
122 | * Added: New CleanPolygon and CleanPolygons functions.
123 | * Added: MinkowskiSum and MinkowskiDiff functions added.
124 | * Added: Several other new functions have been added including
125 | PolyTreeToPaths, OpenPathsFromPolyTree and ClosedPathsFromPolyTree.
126 | * Added: ReverseSolution, PreserveCollinear and StrictlySimple properties to Clipper class
127 | * Added: The Clipper constructor now accepts an optional InitOptions
128 | parameter to simplify setting properties.
129 | * Modified: The Clipper class has a new ZFillFunction property.
130 | * Deprecated: Version 6 is a major upgrade from previous versions
131 | and quite a number of changes have been made to exposed structures
132 | and functions. To minimize inconvenience to existing library users,
133 | some code has been retained and some added to maintain backward
134 | compatibility. However, because this code will be removed in a
135 | future update, it has been marked as deprecated and a precompiler
136 | directive use_deprecated has been defined.
137 | * Changed: The behaviour of the 'miter' JoinType has been
138 | changed so that when squaring occurs, it's no longer
139 | extended up to the miter limit but is squared off at
140 | exactly 'delta' units. (This improves the look of mitering
141 | with larger limits at acute angles.)
142 | * Bugfixes: Several minor bugs have been fixed including
143 | occasionally an incorrect nesting within the PolyTree structure.
144 |
145 | 5.0.2.3 - 27 November 2013
146 | * Added: Node.js compatibility.
147 | * Bugfix: jQuery's "event.returnValue is deprecated." warning is stripped.
148 |
149 | 5.0.2.2 - 11 September 2013
150 | * Bugfix: SlopesEqual() uses now big integers only when needed and causes speed improvements in certain cases.
151 | * Bugfix: Fixed inconsistent use of DV in jsbn.js, in function bnpFromInt() DV replaced with this.DV.
152 | * BugFix: ExPolygons structure is now working as expected.
153 | * Added: Main Demo has now Ex-button in Polygon Explorer, which shows Solution as ExPolygons structure.
154 | * Added: ExPolygons is now explained in wiki in https://sourceforge.net/p/jsclipper/wiki/ExPolygons/
155 | * Added: Web Workers compatibility
156 | * Added: Web Workers support page is available in https://sourceforge.net/p/jsclipper/wiki/Web%20Workers/
157 |
158 | 5.0.2.1 - 12 January 2013
159 | * Update: Clipper library updated to version 5.0.2. The Area algorithm has been updated and is faster.
160 | 'CheckInputs' parameter of the OffsetPolygons function has been renamed 'AutoFix'.
161 | * Added: ClipperLib.Clean(), which removes too near vertices to avoid micro-self-intersection-artifacts when offsetting.
162 | * Added: ClipperLib.Lighten(), which reduces count of vertices using perpendicular distance reduction algorithm.
163 | * Added: ClipperLib.Clone(), which make true clone of polygons.
164 | Several updates to the Main Demo:
165 | * Added: Clean, Simplify, Lighten buttons
166 | * Change: Custom Polygons: input boxes to textareas to allow more data
167 | * Added: Polygon Output Formats (Clipper, Plain, SVG)
168 | * Update: Polygon Explorer: Also multipolygon is clickable (on Points column)
169 | * Added: Polygon Explorer: When numbers on Points or Points in subpolygons are clicked, the area of multipolygon or subpolygon is shown
170 | * Update: Several updates to wiki in https://sourceforge.net/p/jsclipper/wiki/Home/
171 |
172 | 4.9.7.2 - 1 January 2013
173 | * Update: Browser specific speedup for ClipperLib.Clipper.Round(), ClipperLib.Cast_Int32() and ClipperLib.Cast_Int64().
174 | * Update: Major enhancements for Main Demo. Including benchmark, custom polygons and polygon importer.
175 | * Update: Documentation is updated with new screenshots of Main Demo. Browser speedtest is published in Wiki.
176 |
177 | 4.9.7.1 - 12 December 2012
178 | * Initial release
--------------------------------------------------------------------------------
/Documentation.md:
--------------------------------------------------------------------------------
1 | # Clipper 6 Documentation
2 |
3 | This is Javascript Clipper 6 documentation. Unfortunately there is no documentation for Javascript Clipper 5. If you need Clipper 5 docs, please download C# Clipper 5 and check the documentation folder.
4 |
5 | If you are migrating from Javascript Clipper 5 to 6, please read the migration guide.
6 |
7 |
8 |
9 | ## Table of Contents
10 |
11 | [TOC]
12 |
13 |
14 |
15 | ## Overview
16 |
17 | The Javascript Clipper Library performs clipping and offsetting of both lines and polygons.
18 |
19 | A number of features set Clipper apart from other clipping libraries:
20 |
21 | * it accepts all types of polygons including self-intersecting ones
22 | * it supports multiple polygon filling rules (EvenOdd, NonZero, Positive, Negative)
23 | * it's very fast relative to other libraries
24 | * it also performs line and polygon offsetting
25 | * it's numerically robust
26 | * it's free to use in both freeware and commercial applications
27 |
28 | **Current Javascript Clipper version:** 6.1.3.2 (C# 6.1.3a)
29 |
30 | **Original C# version's Author & copyright:**
31 | Angus Johnson. Copyright © 2010-2014
32 | License, terms and conditions: Boost Software License
33 |
34 | **Javascript Clipper's Author & copyright:**
35 | Timo. Copyright © 2012-2014
36 | License, terms and conditions: Boost Software License
37 |
38 | Javascript Clipper uses implementation of Tom Wu's JSBN library, which has BSD license.
39 |
40 | Terminology:
41 |
42 | * **Clipping:** commonly refers to the process of removing (cutting away) from a set of 2-dimensional geometric shapes those parts that are outside a rectangular 'clipping' window. This can be achieved by intersecting subject paths (lines and polygons) with the clipping rectangle. In a more general sense, the clipping window need not be rectangular but can be any type of polygon, even multiple polygons. Also, while clipping typically refers to an intersection operation, in this documentation it will refer to any one of the four boolean operations (intersection, union, difference and exclusive-or).
43 | * **Path:** is an ordered sequence of vertices defining a single geometric contour that's either a line (an open path) or a polygon (a closed path).
44 | * **Contour:** synonymous with path.
45 | * **Line:** or polyline is an open path containing 2 or more vertices.
46 | * **Polygon:** in a general sense is a two-dimensional region that's bounded by an outer closed path and containing zero to many 'holes'. However in this documentation polygon refers to a Path that's known to be closed.
47 | * **Hole:** is a closed region within a polygon that's not part of the polygon. A polygon that forms the outer boundaries of a hole is called a hole polygon.
48 | * **Polygon Filling Rule:** together with a list of paths, the filling rule defines those regions bounded by paths that are inside polygons (ie 'filled' in a graphical display) and those which are outside.
49 |
50 | **Distribution package contents:**
51 |
52 | The ZIP package contains the Clipper library's source code as minified and unminified. The library was initially written in Delphi Pascal, but was then made available also in C++, C# and Python. The library's source code in each language is about 5000 lines. Javascript implementation is longer, about 6200 lines due to JSBN library and some helper functions.
53 |
54 | Demo applications and examples are not included in the distribution package. They can be accessed here. The sample applications show how Clipper can be used with **SVG** and **Canvas**.
55 |
56 | **Download Link:**
57 |
58 | SourceForge
59 |
60 | **References:**
61 |
62 | Read about references regarding clipping and offsetting algorithms.
63 |
64 | **See also:**
65 | OffsetPaths, ClipType, Path, PolyFillType
66 |
67 |
68 |
69 | ## Preprocessor defines
70 |
71 |
72 | Boolean use_int32
73 | Boolean use_xyz
74 | Boolean use_lines
75 | Boolean use_deprecated
76 |
77 | ####
78 |
79 | **use_int32:**
80 | Not implemented in Javascript.
81 |
82 | **use_xyz:**
83 | Adds a 'Z' member to IntPoint with only a minor cost to perfomance. For more details see Clipper's Clipper.ZFillFunction property. (Disabled by default)
84 |
85 | **use_lines:**
86 | Enables open path (line) clipping. If line clipping is disabled, there's generally a very small (ie ~5%) improvement in performance. (Enabled by default)
87 |
88 | **use_deprecated:**
89 | Enables code developed with versions of Clipper prior to version 6 to compile without changes. This exposes compatibility code that will be removed in a future update. (Enabled by default)
90 |
91 | **Usage:**
92 |
93 |
94 | var use_xyz = true;
95 | var use_lines = true;
96 | var use_deprecated = true;
97 |
98 | ####
99 |
100 | **See also:**
101 | Clipper.ZFillFunction, IntPoint
102 |
103 |
104 |
105 | ## ClipperBase
106 |
107 | ClipperBase is an abstract base class for Clipper. A ClipperBase object should not be instantiated directly.
108 |
109 |
110 |
111 | ### --- ClipperBase methods ---
112 |
113 |
114 |
115 | ### ClipperBase.AddPath()
116 |
117 |
118 | Boolean AddPath(Path pg, PolyType polyType, Boolean closed);
119 |
120 | ####
121 |
122 |
123 | Any number of subject and clip paths can be added to a clipping task, either individually via the AddPath() method, or as groups via the AddPaths() method, or even using both methods.
124 |
125 | 'Subject' paths may be either open (lines) or closed (polygons) or even a mixture of both, but 'clipping' paths must always be closed. Clipper allows polygons to clip both lines and other polygons, but doesn't allow lines to clip either lines or polygons.
126 |
127 | With closed paths, orientation should conform with the filling rule that will be passed via Clipper's Execute method.
128 |
129 | Path Coordinate range:
130 | Path coordinates must be between ± 4503599627370495 (sqrt(2^106 -1)/2), otherwise a range error will be thrown when attempting to add the path to the Clipper object. If coordinates can be kept between ± 47453132 (sqrt(2^53 -1)/2), an increase in performance (approx. 40-50%) over the larger range can be achieved by avoiding large integer math.
131 |
132 | Return Value:
133 | The function will return false if the path is empty or almost empty. A path is almost empty when:
134 |
135 | * it has less than 2 vertices.
136 | * it has 2 vertices but is not an open path
137 | * the vertices are all co-linear and it is not an open path
138 |
139 | **Usage:**
140 |
141 |
142 | var cpr = new ClipperLib.Clipper();
143 | var path = [{"X":10,"Y":10},{"X":110,"Y":10},{"X":110,"Y":110},{"X":10,"Y":110}];
144 | cpr.AddPath(path, ClipperLib.PolyType.ptSubject, true);
145 |
146 | ####
147 |
148 | **See also:**
149 | Example, Clipper.Execute, AddPaths, Orientation, Defines, Path, PolyFillType, PolyType
150 |
151 |
152 |
153 | ### ClipperBase.AddPaths()
154 |
155 |
156 | Boolean AddPaths(Paths ppg, PolyType polyType, Boolean closed);
157 |
158 | ####
159 |
160 | Same functionality as in AddPath(), but the parameter is Paths.
161 |
162 | **Usage:**
163 |
164 |
165 | var cpr = new ClipperLib.Clipper();
166 | var paths = [[{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}],
167 | [{X:20,Y:20},{X:20,Y:100},{X:100,Y:100},{X:100,Y:20}]];;
168 | cpr.AddPaths(paths, ClipperLib.PolyType.ptSubject, true);
169 |
170 | ####
171 |
172 | **See also:**
173 | Example, Clipper.Execute, AddPath, Orientation, Defines, Paths, PolyFillType, PolyType
174 |
175 |
176 |
177 | ### ClipperBase.Clear()
178 |
179 |
180 | void Clear();
181 |
182 | ####
183 |
184 | The Clear method removes any existing subject and clip polygons allowing the Clipper object to be reused for clipping operations on different polygon sets.
185 |
186 | **Usage:**
187 |
188 |
189 | cpr.Clear();
190 |
191 | ####
192 |
193 |
194 |
195 | ## Clipper
196 |
197 | The Clipper class encapsulates boolean operations on polygons (intersection, union, difference and XOR), which is also called polygon clipping.
198 |
199 | Input polygons, both subject and clip sets, are passed to a Clipper object by its AddPath and AddPaths methods, and the clipping operation is performed by calling its Execute method. Multiple boolean operations can be performed on the same input polygon sets by repeat calls to Execute.
200 |
201 | **See also:**
202 |
203 | Overview, ClipType
204 |
205 |
206 |
207 | ### --- Clipper methods ---
208 |
209 |
210 |
211 | ### ClipperLib.Clipper()
212 |
213 |
214 | Clipper Clipper(InitOptions initOptions = 0);
215 |
216 | ####
217 |
218 | The Clipper constructor creates an instance of the Clipper class. One or more InitOptions may be passed as a parameter to set the corresponding properties. (These properties can still be set or reset after construction.)
219 |
220 | **Usage:**
221 |
222 |
223 | var cpr = new ClipperLib.Clipper();
224 | // or
225 | var cpr = new ClipperLib.Clipper(ClipperLib.Clipper.ioStrictlySimple | ClipperLib.Clipper.ioPreserveCollinear);
226 | // or
227 | var cpr = new ClipperLib.Clipper(2 | 4);
228 |
229 | ####
230 |
231 | **See also:**
232 | PreserveCollinear, ReverseSolution, StrictlySimple, InitOptions
233 |
234 |
235 |
236 | ### ClipperLib.Clipper.Area()
237 |
238 |
239 | Number Area(Path poly)
240 |
241 | ####
242 |
243 | This function returns the area of the supplied polygon. (It's assumed that the path will be closed.) Depending on orientation, this value may be positive or negative. If Orientation is true, then the area will be positive and conversely, if Orientation is false, then the area will be negative.
244 |
245 | **Usage:**
246 |
247 |
248 | var area = ClipperLib.Clipper.Area(polygon);
249 |
250 | ####
251 |
252 | ** See also:**
253 | Orientation, Path
254 |
255 |
256 |
257 | ### ClipperLib.Clipper.CleanPolygon()
258 |
259 |
260 | Path CleanPolygon(Path path, Number distance)
261 |
262 | ####
263 |
264 | This function is needed to prevent distortion that is caused by too near vertices and/or micro-self-interserctions.
265 |
266 | Removes vertices:
267 |
268 | * that join co-linear edges, or join edges that are almost co-linear (such that if the vertex was moved no more than the specified distance the edges would be co-linear)
269 |
270 | * that are within the specified distance of an adjacent vertex
271 |
272 | * that are within the specified distance of a semi-adjacent vertex together with their out-lying vertices
273 |
274 | Vertices are semi-adjacent when they are separated by a single (out-lying) vertex.
275 |
276 | The distance parameter's default value is approximately √2 so that a vertex will be removed when adjacent or semi-adjacent vertices having their corresponding X and Y coordinates differing by no more than 1 unit. (If the egdes are semi-adjacent the out-lying vertex will be removed too.)
277 |
278 | Timo: According to tests, the most proper distance value to remove artifacts before offsetting is 0.1 * scale.
279 |
280 | 
281 |
282 | **Usage:**
283 |
284 |
285 | var path = [{"X":10,"Y":10},{"X":11,"Y":11},{"X":110,"Y":10},{"X":110,"Y":110},
286 | {"X":10,"Y":110}];
287 | var cleaned_path = ClipperLib.Clipper.CleanPolygon(path, 1.1);
288 | // point {"X":11,"Y":11} is now removed
289 |
290 | ####
291 |
292 | **See also:**
293 | CleanPolygons, SimplifyPolygon, Path
294 |
295 |
296 |
297 | ### ClipperLib.Clipper.CleanPolygons()
298 |
299 |
300 | Paths CleanPolygons(Paths polys, Number distance)
301 |
302 | ####
303 |
304 | Same functionality as in CleanPolygon, but the parameter is of type Paths.
305 |
306 | According to tests, the most proper distance value to remove artifacts before offsetting is 0.1 * scale
307 |
308 | Read more in CleanPolygon.
309 |
310 | **Usage:**
311 |
312 |
313 | var paths = [[{X:10,Y:10},{X:11,Y:11},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}],
314 | [{X:20,Y:20},{X:20,Y:100},{X:100,Y:100},{X:100,Y:20}]];
315 | var cleaned_paths = ClipperLib.Clipper.CleanPolygons(paths, 1.1);
316 | // point {"X":11,"Y":11} is removed
317 |
318 | ####
319 |
320 | **See also:**
321 | CleanPolygon, SimplifyPolygons
322 |
323 |
324 |
325 | ### ClipperLib.Clipper.ClosedPathsFromPolyTree()
326 |
327 |
328 | Paths ClosedPathsFromPolyTree(PolyTree polytree)
329 |
330 | ####
331 |
332 | This function filters out open paths from the PolyTree structure and returns only closed paths in a Paths structure.
333 |
334 | **Usage:**
335 |
336 |
337 | // ... polytree is populated automatically by Execute()
338 | var polygons = ClipperLib.Clipper.ClosedPathsFromPolyTree(polytree);
339 |
340 | ####
341 |
342 | **See also:**
343 | PolyTree, Paths
344 |
345 |
346 |
347 | ### ClipperLib.Clipper.Execute()
348 |
349 |
350 | Boolean Execute(ClipType clipType,
351 | Paths solution,
352 | PolyFillType subjFillType,
353 | PolyFillType clipFillType);
354 |
355 | Boolean Execute(ClipType clipType,
356 | PolyTree solution,
357 | PolyFillType subjFillType,
358 | PolyFillType clipFillType);
359 |
360 | ####
361 |
362 | Once subject and clip paths have been assigned (via AddPath and/or AddPaths), Execute can then perform the clipping operation (intersection, union, difference or XOR) specified by the clipType parameter.
363 |
364 | The solution parameter can be either a Paths or PolyTree structure. The Paths structure is simpler and faster (roughly 10%) than the PolyTree stucture. PolyTree holds information of parent-child relationchips of paths and also whether they are open or closed.
365 |
366 | When a PolyTree object is used in a clipping operation on open paths, two ancilliary functions have been provided to quickly separate out open and closed paths from the solution - OpenPathsFromPolyTree and ClosedPathsFromPolyTree. PolyTreeToPaths is also available to convert path data to a Paths structure (irrespective of whether they're open or closed).
367 |
368 | There are several things to note about the solution paths returned:
369 |
370 | * they aren't in any specific order
371 | * they should never overlap or be self-intersecting (but see notes on rounding)
372 | * holes will be oriented opposite outer polygons
373 | * the solution fill type can be considered either EvenOdd or NonZero since it will comply with either filling rule
374 | * polygons may rarely share a common edge (though this is now very rare as of version 6)
375 |
376 | The subjFillType and clipFillType parameters define the polygon fill rule to be applied to the polygons (ie closed paths) in the subject and clip paths respectively. (It's usual though obviously not essential that both sets of polygons use the same fill rule.)
377 |
378 | Execute can be called multiple times without reassigning subject and clip polygons (ie when different clipping operations are required on the same polygon sets).
379 |
380 | 
381 |
382 | **Usage:**
383 |
384 |
385 | function DrawPolygons(paths, color)
386 | {/* ... */}
387 |
388 | function Main(args)
389 | {
390 | var subj = [[{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}],
391 | [{X:20,Y:20},{X:20,Y:100},{X:100,Y:100},{X:100,Y:20}]];
392 | var clip = [[{X:50,Y:50},{X:150,Y:50},{X:150,Y:150},{X:50,Y:150}],
393 | [{X:60,Y:60},{X:60,Y:140},{X:140,Y:140},{X:140,Y:60}]];
394 | DrawPolygons(subj, 0x8033FFFF);
395 | DrawPolygons(clip, 0x80FFFF33);
396 |
397 | var solution = new ClipperLib.Paths();
398 | var c = new ClipperLib.Clipper();
399 | c.AddPaths(subj, ClipperLib.PolyType.ptSubject, true);
400 | c.AddPaths(clips, ClipperLib.PolyType.ptClip, true);
401 | c.Execute(ClipperLib.ClipType.ctIntersection, solution);
402 |
403 | DrawPolygons(solution, 0x40808080);
404 | }
405 | Main();
406 |
407 | ####
408 |
409 | **See also:**
410 | Rounding, ClipperBase.AddPath, ClipperBase.AddPaths, PolyNode.IsOpen, PolyTree, ClosedPathsFromPolyTree, OpenPathsFromPolyTree, PolyTreeToPaths, ClipType, Path, Paths, PolyFillType
411 |
412 |
413 |
414 | ### ClipperLib.Clipper.GetBounds()
415 |
416 |
417 | IntRect GetBounds(Paths paths);
418 |
419 | ####
420 |
421 | This method returns the axis-aligned bounding rectangle of paths.
422 |
423 | **Usage:**
424 |
425 |
426 | var paths = [[{"X":10,"Y":10},{"X":110,"Y":10},{"X":110,"Y":110},{"X":10,"Y":110}]];
427 | var bounds = ClipperLib.Clipper.GetBounds(paths);
428 | // bounds is {"left":10,"top":10,"right":110,"bottom":110}
429 |
430 | ####
431 |
432 | **See also:**
433 | Example, IntRect
434 |
435 |
436 |
437 | ### ClipperLib.Clipper.MinkowskiDiff()
438 |
439 |
440 | Paths MinkowskiDiff(Path poly, Path path, Boolean isClosed)
441 |
442 | ####
443 |
444 | Minkowski Difference is performed by subtracting each point in a polygon from the set of points in an open or closed path. A key feature of Minkowski Difference is that when it's applied to two polygons, the resulting polygon will contain the coordinate space origin whenever the two polygons touch or overlap. (This function is often used to determine when polygons collide.)
445 |
446 | **See also:**
447 | MinkowskiSum, Path, Paths
448 |
449 |
450 |
451 | ### ClipperLib.Clipper.MinkowskiSum()
452 |
453 |
454 | Paths MinkowskiSum(Path pattern, Path path, Boolean pathIsClosed)
455 | Paths MinkowskiSum(Path pattern, Paths paths, PolyFillType pathFillType, Boolean pathIsClosed)
456 |
457 | ####
458 |
459 | Minkowski Addition is performed by adding each point in a polygon 'pattern' to the set of points in an open or closed path. The resulting polygon (or polygons) defines the region that the 'pattern' would pass over in moving from the beginning to the end of the 'path'.
460 |
461 | **Usage:**
462 |
463 |
464 | // Star shape ...
465 | var path = [{"X":89.85,"Y":355.85},{"X":131.72,"Y":227.13},{"X":22.1,"Y":147.57},{"X":157.6,"Y":147.57},{"X":199.47,"Y":18.85},{"X":241.34,"Y":147.57},{"X":376.84,"Y":147.57},{"X":267.22,"Y":227.13},{"X":309.09,"Y":355.85},{"X":199.47,"Y":276.29}];
466 | // Diagonal brush shape ...
467 | var shape = [{"X":4,"Y":-6},{"X":6,"Y":-6},{"X":-4,"Y":6},{"X":-6,"Y":6}];
468 | var solution = ClipperLib.Clipper.MinkowskiSum(shape, path, true);
469 |
470 | ####
471 |
472 | **See also:**
473 | MinkowskiDiff, Path, Paths
474 |
475 |
476 |
477 | ### ClipperLib.Clipper.OffsetPaths()
478 |
479 |
480 | Paths OffsetPaths(Paths polys, Number delta, JoinType jointype = JoinType.jtSquare, EndType endtype = EndType.etClosed, Number limit)
481 |
482 | ####
483 |
484 | **Deprecated.** (See ClipperOffset.)
485 |
486 | This function offsets the 'polys' parameter by the 'delta' amount. 'polys' may be open or closed paths. With closed paths (polygons), positive delta values 'expand' outer contours and 'shrink' inner 'hole' contours. Negative deltas do the reverse. With open paths (lines), the sign of the delta value is ignored since it's not possible to 'shrink' open paths.
487 |
488 | Edge joins may be one of three jointypes - jtMiter, jtSquare or jtRound. (See the image below for examples.)
489 |
490 | 
491 |
492 | The meaning and use of the limit parameter depends on jointype:
493 |
494 | * jtMiter: limit sets the maximum distance in multiples of delta that vertices can be offset from their original positions before squaring is applied. **The default value is 2** (ie twice delta) which is also the smallest allowed value. If the angle is acute enough to require squaring, then squaring will occur at 1 times delta. If offsetting was allowed without any limits (ie without squaring), then offsetting at very acute angles would produce unacceptably long 'spikes'.
495 |
496 | * jtRound: limit sets the maximum distance that rounded joins can deviate from their true arcs (since it would require an infinite number of vertices to perfectly represent an arc). **The default limit is 0.25 units** though realistically precision can never be better than 0.5 since arc coordinates will still be rounded to integer values. When offsetting polygons with very large coordinate values (typically as a result of scaling), it's advisable to increase limit to maintain consistent precisions at all joins because the maximum number of vertices allowed in any arc is 222. (This hard coded upper limit has been chosen because the imprecision in a circle constructed with 222 vertices will be only 1/10000th its radius and, not only is creating very large numbers of arc vertices computationally expensive, it can cause out-of-memory problems.)
497 |
498 | * jtSquare: The limit parameter is ignored since squaring will be applied uniformally at 1 times delta.
499 |
500 | Self-intersections in closed paths must be removed before the paths are passed to OffsetPaths.
501 |
502 |
503 | **Usage:**
504 |
505 |
506 | var paths = [[{"X":224,"Y":146},{"X":224,"Y":213},{"X":201,"Y":191},{"X":179,"Y":235},{"X":134,"Y":191},{"X":179,"Y":168},{"X":157,"Y":146}]];
507 | var offset_paths = ClipperLib.Clipper.OffsetPaths(paths, 10, ClipperLib.JoinType.jtRound, ClipperLib.EndType.etClosed, 0.25);
508 |
509 | ####
510 |
511 | **See also:**
512 | ClipperOffset, ClipperOffset.JoinType, Path
513 |
514 |
515 |
516 | ### ClipperLib.Clipper.OpenPathsFromPolyTree()
517 |
518 |
519 | Paths OpenPathsFromPolyTree(PolyTree polytree)
520 |
521 | ####
522 |
523 | This function filters out closed paths from the PolyTree structure and returns only open paths in a Paths structure.
524 |
525 | **Usage:**
526 |
527 |
528 | // ... polytree is populated automatically by Execute()
529 | var lines = ClipperLib.Clipper.OpenPathsFromPolyTree(polytree);
530 |
531 | ####
532 |
533 | **See also:**
534 | PolyTree, Paths
535 |
536 |
537 |
538 | ### ClipperLib.Clipper.Orientation()
539 |
540 |
541 | Boolean Orientation(Path poly)
542 |
543 | ####
544 |
545 | Returns true, if polygon area is >=0.
546 |
547 | Orientation is only important to closed paths. Given that vertices are declared in a specific order, orientation refers to the direction (clockwise or counter-clockwise) that these vertices progress around a closed path.
548 |
549 | Orientation is also dependent on axis direction:
550 |
551 | * On Y-axis positive upward displays, Orientation will return true if the polygon's orientation is counter-clockwise.
552 |
553 | * On Y-axis positive downward displays, Orientation will return true if the polygon's orientation is clockwise.
554 |
555 | 
556 |
557 | **Notes:**
558 |
559 | * Self-intersecting polygons have indeterminate orientations in which case this function won't return a meaningful value.
560 | * The majority of 2D graphic display libraries (eg GDI, GDI+, XLib, Cairo, AGG, Graphics32) and even the SVG file format have their coordinate origins at the top-left corner of their respective viewports with their Y axes increasing downward. However, some display libraries (eg Quartz, OpenGL) have their coordinate origins undefined or in the classic bottom-left position with their Y axes increasing upward.
561 | * For Non-Zero filled polygons, the orientation of holes must be opposite that of outer polygons.
562 | * For closed paths (polygons) in the solution returned by Clipper's Execute method, their orientations will always be true for outer polygons and false for hole polygons (unless the ReverseSolution property has been enabled).
563 |
564 | **Usage:**
565 |
566 |
567 | var orientation = ClipperLib.Clipper.Orientation(polygon);
568 |
569 | ####
570 |
571 | **See also:**
572 | Area, Clipper.ReverseSolution, Path
573 |
574 |
575 |
576 | ### ClipperLib.Clipper.PointInPolygon()
577 |
578 |
579 | Number PointInPolygon(IntPoint pt, Path poly)
580 |
581 | ####
582 |
583 | Returns 0 if false, -1 if pt is **on** poly and +1 if pt is **in** poly.
584 |
585 | **Usage:**
586 |
587 |
588 | var poly = [{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}];
589 | var pt = new ClipperLib.IntPoint(50,50);
590 | var inpoly = ClipperLib.Clipper.PointInPolygon(pt, poly);
591 | // inpoly is 1, which means that pt is in polygon
592 |
593 | ####
594 |
595 | **See also:**
596 | IntPoint, Path
597 |
598 |
599 |
600 | ### ClipperLib.Clipper.PolyTreeToPaths()
601 |
602 |
603 | Paths PolyTreeToPaths(PolyTree polytree)
604 |
605 | ####
606 |
607 | This function converts a PolyTree structure into a Paths structure (whether they are open or closed). To differentiate open and closed paths, use OpenPathsFromPolyTree or ClosedPathsFromPolyTree.
608 |
609 | **Usage:**
610 |
611 |
612 | // ... polytree is populated automatically by Execute()
613 | var paths = ClipperLib.Clipper.PolyTreeToPaths(polytree);
614 |
615 | ####
616 |
617 | **See also:**
618 | PolyTree, Paths
619 |
620 |
621 |
622 | ### ClipperLib.Clipper.ReversePath()
623 |
624 |
625 | // Call Path.reverse().
626 |
627 | ####
628 |
629 | Reverses the vertex order (and hence orientation) in a path.
630 |
631 | **Usage:**
632 |
633 |
634 | var path = [{"X":10,"Y":10},{"X":110,"Y":10},{"X":110,"Y":110},{"X":10,"Y":110}];
635 | path.reverse();
636 | // path is now [[{"X":10,"Y":110},{"X":110,"Y":110},{"X":110,"Y":10},{"X":10,"Y":10}]]
637 |
638 |
639 |
640 |
641 | ### ClipperLib.Clipper.ReversePaths()
642 |
643 |
644 | void ReversePaths(Paths p)
645 |
646 | ####
647 |
648 | Reverses the vertex order (and hence orientation) in each contained path.
649 |
650 | **Usage:**
651 |
652 |
653 | var paths = [[{"X":10,"Y":10},{"X":110,"Y":10},{"X":110,"Y":110},{"X":10,"Y":110}]];
654 | ClipperLib.Clipper.ReversePaths(paths);
655 | // paths is now [[{"X":10,"Y":110},{"X":110,"Y":110},{"X":110,"Y":10},{"X":10,"Y":10}]]
656 |
657 | ####
658 |
659 |
660 |
661 | ### ClipperLib.Clipper.SimplifyPolygon()
662 |
663 |
664 | Paths SimplifyPolygon(Path poly, PolyFillType fillType = PolyFillType.pftEvenOdd)
665 |
666 | ####
667 |
668 | Removes self-intersections from the supplied polygon (by performing a boolean union operation using the nominated PolyFillType).
669 |
670 | Polygons with non-contiguous duplicate vertices (ie 'touching') will be split into two polygons.
671 |
672 | 
673 |
674 | **Usage:**
675 |
676 |
677 | // five-pointed star with self-intersections...
678 | var five_pointed_star = [{"X":147,"Y":313},{"X":247,"Y":34},{"X":338,"Y":312},{"X":86,"Y":123},{"X":404,"Y":124}];
679 | var ten_pointed_star = ClipperLib.Clipper.SimplifyPolygon(five_pointed_star, ClipperLib.PolyFillType.pftNonZero);
680 | // ten_pointed_star is a ten-pointed star with no self-intersections
681 | var fifteen_pointed_star = ClipperLib.Clipper.SimplifyPolygon(five_pointed_star, ClipperLib.PolyFillType.pftEvenOdd);
682 | // fifteen_pointed_star is a fifteen-pointed star with no self-intersections
683 |
684 | ####
685 |
686 | **See also:**
687 | Clipper.StrictlySimple, CleanPolygon, Path, PolyFillType
688 |
689 |
690 |
691 | ### ClipperLib.Clipper.SimplifyPolygons()
692 |
693 |
694 | Paths SimplifyPolygons(Paths polys, PolyFillType fillType = PolyFillType.pftEvenOdd)
695 |
696 | ####
697 |
698 | The same functionality as in SimplifyPolygon, but the parameter is of type Paths.
699 |
700 | **Usage:**
701 |
702 |
703 | // five-pointed star with self-intersections...
704 | var five_pointed_star = [[{"X":147,"Y":313},{"X":247,"Y":34},{"X":338,"Y":312},{"X":86,"Y":123},{"X":404,"Y":124}]];
705 | var ten_pointed_star = ClipperLib.Clipper.SimplifyPolygons(five_pointed_star, ClipperLib.PolyFillType.pftNonZero);
706 | // ten_pointed_star is a ten-pointed star with no self-intersections
707 | var fifteen_pointed_star = ClipperLib.Clipper.SimplifyPolygon(five_pointed_star, ClipperLib.PolyFillType.pftEvenOdd);
708 | // fifteen_pointed_star is a fifteen-pointed star with no self-intersections
709 |
710 | ####
711 |
712 | **See also:**
713 | Clipper.StrictlySimple, CleanPolygons, PolyFillType
714 |
715 |
716 |
717 | ### --- Clipper Properties ---
718 |
719 | ### ClipperLib.Clipper.PreserveCollinear
720 |
721 |
722 | Boolean PreserveCollinear;
723 |
724 | ####
725 |
726 | By default, when three or more vertices are collinear in input polygons (subject or clip), the Clipper object removes the 'inner' vertices before clipping. When enabled the PreserveCollinear property prevents this default behavior to allow these inner vertices to appear in the solution.
727 |
728 | **Usage:**
729 |
730 |
731 | var cpr = new ClipperLib.Clipper();
732 | cpr.PreserveCollinear = true;
733 |
734 | ####
735 |
736 | **See also:**
737 | ClipperLib.Clipper()
738 |
739 |
740 |
741 | ### ClipperLib.Clipper.ReverseSolution
742 |
743 |
744 | Boolean ReverseSolution;
745 |
746 | ####
747 |
748 | When this property is set to true, polygons returned in the solution parameter of the Execute() method will have orientations opposite to their normal orientations.
749 |
750 | **Usage:**
751 |
752 |
753 | var cpr = new ClipperLib.Clipper();
754 | cpr.ReverseSolution = true;
755 |
756 | ####
757 |
758 | **See also:**
759 | Execute, Orientation
760 |
761 |
762 |
763 | ### ClipperLib.Clipper.StrictlySimple
764 |
765 |
766 | Boolean StrictlySimple;
767 |
768 | ####
769 |
770 | Terminology:
771 | * A simple polygon is one that does not self-intersect.
772 | * A weakly simple polygon is a simple polygon that contains 'touching' vertices, or 'touching' edges.
773 | * A strictly simple polygon is a simple polygon that does not contain 'touching' vertices, or 'touching' edges.
774 |
775 | Vertices 'touch' if they share the same coordinates (and are not adjacent). An edge touches another if one of its end vertices touches another edge excluding its adjacent edges, or if they are co-linear and overlapping (including adjacent edges).
776 |
777 | Polygons returned by clipping operations (see Clipper.Execute()) should always be simple polygons. When the StrictlySimply property is enabled, polygons returned will be strictly simple, otherwise they may be weakly simple. It's computationally expensive ensuring polygons are strictly simple and so this property is disabled by default.
778 |
779 |
780 |
781 | In the image above, the two examples show weakly simple polygons being broken into two strictly simple polygons. (The outlines with arrows are intended to aid visualizing vertex order.)
782 |
783 | See also the article on Simple Polygon on Wikipedia.
784 |
785 | **Usage:**
786 |
787 |
788 | var cpr = new ClipperLib.Clipper();
789 | cpr.StrictlySimple = true;
790 |
791 | ####
792 |
793 | **See also:**
794 | Execute, SimplifyPolygons
795 |
796 |
797 |
798 | ### ClipperLib.Clipper.ZFillFunction
799 |
800 |
801 | void ZFillCallback ZFillFunction;
802 |
803 | ####
804 |
805 | This property is only exposed if the Preprocessor directive use_xyz has been defined. (If it is defined, a Z member will be added to the IntPoint structure.) When a custom callback function is assigned it will be called during clipping operations so custom Z values can be assigned intersection vertices.
806 |
807 | Vertices in the solution of clipping operations more often than not correspond to input (subject or clip) vertices, but those vertices created at edge intersections do not. While the X and Y coordinates for these 'intersection' vertices are obviously defined by the points of intersection, there's no obvious way to assign their Z values. It really depends on the needs of the library user. While there are 4 vertices directly influencing an intersection vertex (ie the vertices on each end of the 2 intersecting edges), in an attempt to keep things simple only the vertices bounding one edge will be passed to the callback function.
808 |
809 | The CurvesDemo application in the Curves directory in the distribution zip package shows how the Z member together with the callback function can be used to flatten curved paths (defined by control points) and after clipping, to 'de-flatten' or reconstruct curved paths in the clipping solution.
810 |
811 | **Usage:**
812 |
813 |
814 | var cpr = new ClipperLib.Clipper();
815 | cpr.ZFillFunction = function (vert1, vert2, intersectPt) { /* function body */ };
816 | // or
817 | var ClipCallback = function (vert1, vert2, intersectPt) { /* function body */ };
818 | cpr.ZFillFunction = ClipCallback;
819 |
820 | ####
821 |
822 | **See also:**
823 | Defines, IntPoint, ZFillCallback
824 |
825 |
826 |
827 | ## Types
828 |
829 | ### ClipperLib.ClipType()
830 |
831 |
832 | Number ClipType {ctIntersection: 0, ctUnion: 1, ctDifference: 2, ctXor: 3};
833 |
834 | ####
835 |
836 | There are four boolean operations - AND, OR, NOT & XOR.
837 |
838 | Given that subject and clip polygon brush 'filling' is defined both by their vertices and their respective filling rules, the four boolean operations can be applied to polygons to define new filling regions:
839 |
840 | * AND (intersection) - create regions where both subject and clip polygons are filled
841 | * OR (union) - create regions where either subject or clip polygons (or both) are filled
842 | * NOT (difference) - create regions where subject polygons are filled except where clip * polygons are filled
843 | * XOR (exclusive or) - create regions where either subject or clip polygons are filled but not where both are filled
844 |
845 | 
846 |
847 | 
848 |
849 | All polygon clipping is performed with a Clipper object with the specific boolean operation indicated by the ClipType parameter passed in its Execute method.
850 |
851 | With regard to open paths (polylines), clipping rules generally match those of closed paths (polygons).
852 |
853 | However, when there are both polyline and polygon subjects, the following clipping rules apply:
854 |
855 | * union operations - polylines will be clipped by any overlapping polygons so that non-overlapped portions will be returned in the solution together with the union-ed polygons
856 | * intersection, difference and xor operations - polylines will be clipped only by 'clip' polygons and there will be not interaction between polylines and subject polygons.
857 |
858 | Example of clipping behaviour when mixing polyline and polygon subjects:
859 |
860 | 
861 |
862 | **Usage:**
863 |
864 |
865 | var cliptype = ClipperLib.ClipType.ctIntersection;
866 | var cliptype = ClipperLib.ClipType.ctUnion;
867 | var cliptype = ClipperLib.ClipType.ctDifference;
868 | var cliptype = ClipperLib.ClipType.ctXor;
869 |
870 | ####
871 |
872 | **See also:**
873 | Clipper, Clipper.Execute, PolyFillType
874 |
875 |
876 |
877 | ### ClipperLib.EndType
878 |
879 |
880 | ClipperLib.EndType = {etOpenSquare: 0, etOpenRound: 1, etOpenButt: 2, etClosedLine: 3, etClosedPolygon: 4 };
881 |
882 | ####
883 |
884 | The EndType enumerator has 5 values:
885 |
886 | * **etOpenSquare:** Ends are squared off and extended delta units
887 | * **etOpenRound:** Ends are rounded off and extended delta units
888 | * **etOpenButt:** Ends are squared off with no extension.
889 | * **etClosedLine:** Ends are joined using the JoinType value and the path filled as a polyline
890 | * **etClosedPolygon:** Ends are joined using the JoinType value and the path filled as a polygon
891 | **etOpenSingle:** Offsets an open path in a single direction. Planned for a future update.
892 |
893 | Note: With etClosedPolygon and etClosedLine types, the path closure will be the same regardless of whether or not the first and last vertices in the path match.
894 |
895 | 
896 | 
897 |
898 | **Usage:**
899 |
900 |
901 | var endtype = ClipperLib.EndType.etOpenSquare;
902 | var endtype = ClipperLib.EndType.etOpenRound;
903 | var endtype = ClipperLib.EndType.etOpenButt;
904 | var endtype = ClipperLib.EndType.etClosedLine;
905 | var endtype = ClipperLib.EndType.etClosedPolygon;
906 |
907 | ####
908 |
909 | **See also:**
910 | ClipperOffset.AddPath, ClipperOffset.AddPaths
911 |
912 |
913 |
914 | ### ClipperLib.EndType_
915 |
916 |
917 | if (use_deprecated)
918 | ClipperLib.EndType_ = {etSquare: 0, etRound: 1, etButt: 2, etClosed: 3};
919 |
920 | ####
921 |
922 | **Deprecated.** See ClipperOffset and EndType.
923 |
924 | The EndType_ enumerator has 4 values:
925 |
926 | * etSquare: Ends are squared off at exactly delta units
927 | * etRound: Ends are rounded off at exactly delta units
928 | * etButt: Ends are squared off abruptly
929 | * etClosed: Ends are joined using the JoinType value and the path filled as a polygon.
930 |
931 | 
932 |
933 | **Usage:**
934 |
935 |
936 | var endtype = ClipperLib.EndType_.etSquare;
937 | var endtype = ClipperLib.EndType_.etRound;
938 | var endtype = ClipperLib.EndType_.etButt;
939 | var endtype = ClipperLib.EndType_.etClosed;
940 |
941 | ####
942 |
943 |
944 |
945 | ### ClipperLib.ExPolygon()
946 |
947 |
948 | ExPolygon ExPolygon();
949 |
950 | ####
951 |
952 | Creates an instance of ExPolygon object.
953 |
954 | This is not anymore in the original Clipper, but in JS version we provide it to ensure backward compatibility.
955 |
956 | **Usage:**
957 |
958 |
959 | var expolygon = new ClipperLib.ExPolygon();
960 |
961 | ####
962 |
963 | **See also:**
964 | PolyTreeToExPolygons, ExPolygonsToPaths
965 |
966 |
967 |
968 | ### ClipperLib.ExPolygons()
969 |
970 |
971 | ExPolygons ExPolygons();
972 |
973 | ####
974 |
975 | Creates an instance of ExPolygons object ie array.
976 |
977 | This is not anymore in the original Clipper, but in JS version we provide it to ensure backward compatibility.
978 |
979 | **Usage:**
980 |
981 |
982 | var expolygons = new ClipperLib.ExPolygons();
983 |
984 | ####
985 |
986 | **See also:**
987 | PolyTreeToExPolygons, ExPolygonsToPaths
988 |
989 |
990 |
991 | ### InitOptions
992 |
993 |
994 | Number ioReverseSolution = 1;
995 | Number ioStrictlySimple = 2;
996 | Number ioPreserveCollinear = 4;
997 |
998 | ####
999 |
1000 | **Usage:**
1001 |
1002 |
1003 | var cpr = new ClipperLib.Clipper(ClipperLib.Clipper.ioStrictlySimple | ClipperLib.Clipper.ioPreserveCollinear);
1004 | // or
1005 | var cpr = new ClipperLib.Clipper(2 | 4);
1006 |
1007 | ####
1008 |
1009 | **See also:**
1010 | Constructor, Clipper.PreserveCollinear, Clipper.ReverseSolution, Clipper.StrictlySimple
1011 |
1012 |
1013 |
1014 | ### ClipperLib.IntPoint()
1015 |
1016 |
1017 | IntPoint IntPoint(Number X, Number Y)
1018 | IntPoint IntPoint()
1019 | IntPoint IntPoint(IntPoint point)
1020 |
1021 | ####
1022 |
1023 | The IntPoint structure is used to represent all vertices in the Clipper Library. An "integer" storage type has been deliberately chosen to preserve numerical robustness. (Early versions of the library used floating point coordinates, but it became apparent that floating point imprecision would always cause occasional errors.)
1024 |
1025 | A sequence of IntPoints are contained within a Path structure to represent a single contour.
1026 |
1027 | As of version 6, IntPoint now has an optional third member 'Z'. This can be enabled by exposing (ie uncommenting) the PreProcessor define 'use_xyz'. When the Z member is used, its values will be copied to corresponding verticies in solutions to clipping operations. However, at points of intersection where there's no corresponding Z value, the value will be assigned zero unless a new value is provided by a user supplied callback function.
1028 |
1029 | Users wishing to clip or offset polygons containing floating point coordinates need to use appropriate scaling when converting these values to and from IntPoints.
1030 |
1031 | See also the notes on rounding.
1032 |
1033 | **Usage:**
1034 |
1035 |
1036 | var point = new ClipperLib.IntPoint(10,20); // Creates object {"X":10,"Y":20}
1037 | var point2 = new ClipperLib.IntPoint(); // Creates object {"X":0,"Y":0}
1038 | var point3 = new ClipperLib.IntPoint(point); // Creates clone of point
1039 |
1040 | ####
1041 |
1042 | **See also:**
1043 | Rounding, Clipper.ZFillFunction, Defines, Path, Paths
1044 |
1045 |
1046 |
1047 | ### ClipperLib.IntRect()
1048 |
1049 |
1050 | IntRect IntRect(Number left, Number top, Number right, Number bottom);
1051 | IntRect IntRect(IntRect intRect);
1052 | IntRect IntRect();
1053 |
1054 | ####
1055 |
1056 | Structure returned by Clipper's GetBounds method.
1057 |
1058 | **See also:**
1059 | GetBounds
1060 |
1061 |
1062 |
1063 | ### ClipperLib.JoinType
1064 |
1065 |
1066 | ClipperLib.JoinType = {jtSquare: 0, jtRound: 1, jtMiter: 2};
1067 |
1068 | ####
1069 |
1070 | When adding paths to a ClipperOffset object via the AddPaths method, the joinType parameter may be one of three types - jtMiter, jtSquare or jtRound.
1071 |
1072 | 
1073 |
1074 | * **jtMiter:** There's a necessary limit to mitered joins since offsetting edges that join at very acute angles will produce excessively long and narrow 'spikes'. To contain these potential spikes, the ClipperOffset object's MiterLimit property specifies a maximum distance that vertices will be offset (in multiples of delta). For any given edge join, when miter offsetting would exceed that maximum distance, 'square' joining is applied.
1075 | * **jtRound:** While flattened paths can never perfectly trace an arc, they are approximated by a series of arc chords (see ClipperObject's ArcTolerance property).
1076 | * **jtSquare:** Squaring is applied uniformally at all convex edge joins at 1 × delta.
1077 |
1078 | **Usage:**
1079 |
1080 |
1081 | var jointype = ClipperLib.JoinType.jtSquare;
1082 | var jointype = ClipperLib.JoinType.jtRound;
1083 | var jointype = ClipperLib.JoinType.jtMiter;
1084 |
1085 | ####
1086 |
1087 | **See also:**
1088 | ClipperOffset, AddPaths, ArcTolerance, MiterLimit
1089 |
1090 |
1091 |
1092 | ### ClipperLib.Path()
1093 |
1094 |
1095 | Path Path()
1096 |
1097 | ####
1098 |
1099 | This structure contains a sequence of IntPoint vertices defining a single contour (see also terminology). Paths may be open and represent line segments bounded by 2 or more vertices, or they may be closed and represent polygons.
1100 |
1101 | Multiple paths can be grouped into a Paths structure.
1102 |
1103 | **Usage:**
1104 |
1105 |
1106 | var path = new ClipperLib.Path(); // Creates an empty array []
1107 | // or
1108 | var path = new Array();
1109 | // or
1110 | var path = [];
1111 |
1112 | ####
1113 |
1114 | **See also:**
1115 | Overview, Example, ClipperBase.AddPath, PolyTree, Orientation, IntPoint, Paths
1116 |
1117 |
1118 |
1119 | ### ClipperLib.Paths()
1120 |
1121 |
1122 | Paths Paths()
1123 |
1124 | ####
1125 |
1126 | This structure is fundamental to the Clipper Library. It's an array of one or more Path structures. (The Path structure contains an ordered array of vertices that make a single contour.)
1127 |
1128 | Paths may open (lines), or they may closed (polygons).
1129 |
1130 | **Usage:**
1131 |
1132 |
1133 | var paths = new ClipperLib.Paths(); // Creates an empty array []
1134 | // or
1135 | var paths = new Array();
1136 | // or
1137 | var paths = [];
1138 |
1139 | ####
1140 |
1141 | **See also:**
1142 | Clipper.Execute, ClipperBase.AddPath, ClipperBase.AddPaths, OffsetPaths, IntPoint, Path
1143 |
1144 |
1145 |
1146 | ### ClipperLib.PolyFillType
1147 |
1148 |
1149 | ClipperLib.PolyFillType = {pftEvenOdd: 0, pftNonZero: 1, pftPositive: 2, pftNegative: 3};
1150 |
1151 | ####
1152 |
1153 | Filling indicates regions that are inside a polygon (ie 'filled' with a brush color or pattern in a graphical display), and non-filling indicates regions outside polygons. The Clipper Library supports 4 filling rules: Even-Odd, Non-Zero, Positive and Negative.
1154 |
1155 | The simplest filling rule is Even-Odd filling. Given a group of polygons and starting from a point outside, whenever a contour is crossed either filling starts if it had stopped or it stops if it had started. For example, given a single rectangular polygon, when its first (eg left) edge is crossed filling starts and we're inside the polygon. Filling stops again when the next (eg right) edge is crossed.
1156 |
1157 | With the exception of Even-Odd filling, all other filling rules rely on edge direction and winding numbers to determine filling. Edge direction is determined by the order in which vertices are declared when constructing a polygon. Edge direction is used to determine the winding numbers of polygon regions and subregions.
1158 |
1159 | 
The winding number for any given polygon sub-region can be derived by:
1160 |
1161 | 1. starting with a winding number of zero
1162 | 2. from a point (P1) that's outside all polygons, draw an imaginary line to a point that's inside a given sub-region (P2)
1163 | 3. while traversing the line from P1 to P2, for each polygon edge that crosses the line from right to left increment the winding number, and for each polygon edge that crosses the line from left to right decrement the winding number.
1164 | 4. Once you arrive at the given sub-region you have its winding number.
1165 |
1166 | 
1167 |
1168 | **Even-Odd (Alternate)**: Odd numbered sub-regions are filled, while even numbered sub-regions are not.
1169 | **Non-Zero (Winding)**: All non-zero sub-regions are filled.
1170 | **Positive**: All sub-regions with winding counts > 0 are filled.
1171 | **Negative**: All sub-regions with winding counts < 0 are filled.
1172 |
1173 | 
1174 |
1175 | By far the most widely used fill rules are Even-Odd (aka Alternate) and Non-Zero (aka Winding). Most graphics rendering libraries (AGG, Android Graphics, Cairo, GDI+, OpenGL, Quartz 2D etc) and vector graphics storage formats (SVG, Postscript, Photoshop etc) support both these rules. However some libraries (eg Java's Graphics2D) only support one fill rule. Android Graphics and OpenGL are the only libraries (that I'm aware of) that support multiple filling rules.
1176 |
1177 | It's useful to note that edge direction has no affect on a winding number's odd-ness or even-ness. (This is why orientation is ignored when the Even-Odd rule is employed.)
1178 |
1179 | The direction of the Y-axis does affect polygon orientation and edge direction. However, changing Y-axis orientation will only change the sign of winding numbers, not their magnitudes, and has no effect on either Even-Odd or Non-Zero filling.
1180 |
1181 | **Usage:**
1182 |
1183 |
1184 | var polyfilltype = ClipperLib.PolyFillType.pftEvenOdd;
1185 | var polyfilltype = ClipperLib.PolyFillType.pftNonZero;
1186 | var polyfilltype = ClipperLib.PolyFillType.pftPositive;
1187 | var polyfilltype = ClipperLib.PolyFillType.pftNegative;
1188 |
1189 | ####
1190 |
1191 | **See also:**
1192 | Clipper.Execute, Orientation
1193 |
1194 |
1195 |
1196 | ### ClipperLib.PolyType
1197 |
1198 |
1199 | Number ClipperLib.PolyType = {ptSubject: 0, ptClip: 1};
1200 |
1201 | ####
1202 |
1203 | Boolean (clipping) operations are mostly applied to two sets of Polygons, represented in this library as subject and clip polygons. Whenever Polygons are added to the Clipper object, they must be assigned to either subject or clip polygons.
1204 |
1205 | UNION operations can be performed on one set or both sets of polygons, but all other boolean operations require both sets of polygons to derive meaningful solutions.
1206 |
1207 | **Usage:**
1208 |
1209 |
1210 | var polytype = ClipperLib.PolyType.ptSubject;
1211 | var polytype = ClipperLib.PolyType.ptClip;
1212 |
1213 | ####
1214 |
1215 | **See also:**
1216 | ClipperBase.AddPath, ClipperBase.AddPaths, ClipType
1217 |
1218 |
1219 |
1220 | ### ClipperLib.Clipper.ZFillCallback()
1221 |
1222 |
1223 | void ZFillCallback(IntPoint Z1, IntPoint Z2, IntPoint pt);
1224 |
1225 | ####
1226 |
1227 |
1228 | **See also:**
1229 | Clipper.ZFillFunction
1230 |
1231 |
1232 |
1233 | ## PolyTree
1234 |
1235 | PolyTree is intended as a read-only data structure that should only be used to receive solutions from polygon clipping operations. It's an alternative data structure the Paths structure which can also receive clipping solutions. Its major advantages over the Paths structure is that it properly represents the parent-child relationships of the returned polygons, and that it also differentiates between open and closed paths. However, since a PolyTree is more complex than a Paths structure, and because it's more computationally expensive to process (the Execute method being roughly 5-10% slower), it should only be used when parent-child polygon relationships are needed, or when open paths are being 'clipped'.
1236 |
1237 | An empty PolyTree object can be passed as the solution parameter to a Clipper object's Execute method. Once the clipping operation is completed, this method returns with the PolyTree structure filled with data representing the solution.
1238 |
1239 | A PolyTree object is a container for any number of PolyNode children, with each contained PolyNode representing a single polygon contour (either an outer or hole polygon). PolyTree itself is a specialized PolyNode whose immediate children represent the top-level outer polygons of the solution. (Its own Contour property is always empty.) The contained top-level PolyNodes may contain their own PolyNode children representing hole polygons that may also contain children representing nested outer polygons etc. Children of outers will always be holes, and children of holes will always be outers.
1240 |
1241 | PolyTrees can also contain open paths. Open paths will always be represented by top level PolyNodes. Two functions are provided to quickly separate out open and closed paths from a polytree - ClosedPathsFromPolyTree and OpenPathsFromPolyTree.
1242 |
1243 |  |
1244 | polytree:
1245 | Contour = ()
1246 | ChildCount = 1
1247 | Childs[0]:
1248 | Contour = ((10,10),(100,10),(100,100),(10,100))
1249 | IsHole = False
1250 | ChildCount = 1
1251 | Childs[0]:
1252 | Contour = ((20,20),(20,90),(90,90),(90,20))
1253 | IsHole = True
1254 | ChildCount = 2
1255 | Childs[0]:
1256 | Contour = ((30,30),(50,30),(50,50),(30,50))
1257 | IsHole = False
1258 | ChildCount = 0
1259 | Childs[1]:
1260 | Contour = ((60,60),(80,60),(80,80),(60,80))
1261 | IsHole = False
1262 | ChildCount = 0
1263 |
1264 | |
1265 |
1266 | **See also:**
1267 | Overview, Clipper, Clipper.Execute, PolyNode, ClosedPathsFromPolyTree, OpenPathsFromPolyTree, Paths
1268 |
1269 |
1270 |
1271 | ### --- PolyTree methods ---
1272 |
1273 |
1274 |
1275 | ### ClipperLib.PolyTree()
1276 |
1277 |
1278 | PolyTree PolyTree()
1279 |
1280 | ####
1281 |
1282 | Returns new PolyTree object.
1283 |
1284 | **Usage:**
1285 |
1286 |
1287 | var polytree = new ClipperLib.PolyTree(); // creates PolyTree object
1288 | // cpr.Execute ...
1289 |
1290 | ####
1291 |
1292 | **See also:**
1293 | Clipper.Execute, PolyNode, ClosedPathsFromPolyTree, OpenPathsFromPolyTree, Paths
1294 |
1295 |
1296 |
1297 | ### ClipperLib.PolyTree.Clear()
1298 |
1299 |
1300 | void polytree.Clear()
1301 |
1302 | ####
1303 |
1304 | This method clears any PolyNode children contained by PolyTree the object.
1305 |
1306 | Clear does not need to be called explicitly. The Clipper.Execute method that accepts a PolyTree parameter will automatically clear the PolyTree object before propagating it with new PolyNodes. Likewise, PolyTree's destructor will also automatically clear any contained PolyNodes.
1307 |
1308 | **See also:**
1309 | Clipper.Execute
1310 |
1311 |
1312 |
1313 | ### ClipperLib.PolyTree.GetFirst()
1314 |
1315 |
1316 | PolyNode GetFirst()
1317 |
1318 | ####
1319 |
1320 | This method returns the first outer polygon contour if any, otherwise a null pointer.
1321 |
1322 | This function is almost equivalent to calling Childs\[0\] except that when a PolyTree object is empty (has no children), calling Childs\[0\] would raise an out of range exception.
1323 |
1324 | **Usage:**
1325 |
1326 |
1327 | var polynode = polytree.GetFirst();
1328 |
1329 | ####
1330 |
1331 | **See also:**
1332 | PolyNode.GetNext, PolyNode.ChildCount, PolyNode.Childs
1333 |
1334 |
1335 |
1336 | ### ClipperLib.PolyTree.Total()
1337 |
1338 |
1339 | Number Total() // read only
1340 |
1341 | ####
1342 |
1343 | Returns the total number of PolyNodes (polygons) contained within the PolyTree. This value is not to be confused with ChildCount which returns the number of immediate children only (Childs) contained by PolyTree.
1344 |
1345 |
1346 | var total = polytree.Total();
1347 |
1348 | ####
1349 |
1350 | **See also:**
1351 | PolyNode.ChildCount, PolyNode.Childs
1352 |
1353 |
1354 |
1355 | ## PolyNode
1356 |
1357 | PolyNodes are encapsulated within a PolyTree container, and together provide a data structure representing the parent-child relationships of polygon contours returned by Clipper's Execute method.
1358 |
1359 | A PolyNode object represents a single polygon. Its IsHole property indicates whether it's an outer or a hole. PolyNodes may own any number of PolyNode children (Childs), where children of outer polygons are holes, and children of holes are (nested) outer polygons.
1360 |
1361 | **See also:**
1362 | Overview, Clipper.Execute, PolyTree
1363 |
1364 |
1365 |
1366 | ### --- PolyNode methods ---
1367 |
1368 |
1369 |
1370 | ### ClipperLib.PolyNode()
1371 |
1372 |
1373 | PolyNode PolyNode() // read only
1374 |
1375 | ####
1376 |
1377 | Creates new PolyNode object.
1378 |
1379 | **Usage:**
1380 |
1381 |
1382 | var polynode = new ClipperLib.PolyNode();
1383 |
1384 | ####
1385 |
1386 | **See also:**
1387 | Clipper.Execute, PolyTree
1388 |
1389 |
1390 |
1391 | ### ClipperLib.PolyNode.ChildCount()
1392 |
1393 |
1394 | Number ChildCount() // read only
1395 |
1396 | ####
1397 |
1398 | Returns the number of PolyNode Childs directly owned by the PolyNode object.
1399 |
1400 | **Usage:**
1401 |
1402 |
1403 | var count = polynode.ChildCount();
1404 |
1405 | ####
1406 |
1407 | **See also:**
1408 | Childs
1409 |
1410 |
1411 |
1412 | ### ClipperLib.PolyNode.Childs()
1413 |
1414 |
1415 | Array < PolyNode > Childs() // read only
1416 |
1417 | ####
1418 |
1419 | Array of PolyNode. Outer PolyNode childs contain hole PolyNodes, and hole PolyNode childs contain nested outer PolyNodes.
1420 |
1421 | **Usage:**
1422 |
1423 |
1424 | var childs = polynode.Childs();
1425 |
1426 | ####
1427 |
1428 | **See also:**
1429 | ChildCount
1430 |
1431 |
1432 |
1433 | ### ClipperLib.PolyNode.Contour()
1434 |
1435 |
1436 | Path Contour() // read only
1437 |
1438 | ####
1439 |
1440 | Returns a path list which contains any number of vertices.
1441 |
1442 | **Usage:**
1443 |
1444 |
1445 | var contour = polynode.Contour();
1446 |
1447 | ####
1448 |
1449 |
1450 |
1451 | ### ClipperLib.PolyNode.GetNext()
1452 |
1453 |
1454 | PolyNode GetNext()
1455 |
1456 | ####
1457 |
1458 | The returned Polynode will be the first child if any, otherwise the next sibling, otherwise the next sibling of the Parent etc.
1459 |
1460 | A PolyTree can be traversed very easily by calling GetFirst() followed by GetNext() in a loop until the returned object is a null pointer ...
1461 |
1462 | **Usage:**
1463 |
1464 |
1465 | var polytree = new ClipperLib.PolyTree();
1466 | //call to Clipper.Execute method here which fills 'polytree'
1467 |
1468 | var polynode = polytree.GetFirst();
1469 | while (polynode)
1470 | {
1471 | //do stuff with polynode here
1472 |
1473 | polynode = polynode.GetNext();
1474 | }
1475 |
1476 | ####
1477 |
1478 | **See also:**
1479 | PolyTree.GetFirst
1480 |
1481 |
1482 |
1483 | ### ClipperLib.PolyNode.IsHole()
1484 |
1485 |
1486 | Boolean IsHole() // read only
1487 |
1488 | ####
1489 |
1490 | Returns true when the PolyNode's polygon (Contour) is a hole.
1491 |
1492 | Children of outer polygons are always holes, and children of holes are always (nested) outer polygons.
1493 |
1494 | The IsHole property of a PolyTree object is undefined but its children are always top-level outer polygons.
1495 |
1496 | **Usage:**
1497 |
1498 |
1499 | var ishole = polynode.IsHole();
1500 |
1501 | ####
1502 |
1503 | **See also:**
1504 | Contour, PolyTree
1505 |
1506 |
1507 |
1508 | ### ClipperLib.PolyNode.Parent()
1509 |
1510 |
1511 | PolyNode Parent(); read only
1512 |
1513 | ####
1514 |
1515 | Returns the parent PolyNode.
1516 |
1517 | The PolyTree object (which is also a PolyNode) does not have a parent and will return a null pointer.
1518 |
1519 | **Usage:**
1520 |
1521 |
1522 | var parent = polynode.Parent();
1523 |
1524 | ####
1525 |
1526 |
1527 |
1528 | ### --- PolyNode properties ---
1529 |
1530 |
1531 |
1532 | ### ClipperLib.PolyNode.IsOpen
1533 |
1534 |
1535 | Boolean IsOpen // read only property
1536 |
1537 | ####
1538 |
1539 | Returns true when the PolyNode's Contour results from a clipping operation on an open contour (path). Only top-level PolyNodes can contain open contours.
1540 |
1541 | **Usage:**
1542 |
1543 |
1544 | var isopen = polynode.IsOpen;
1545 |
1546 | ####
1547 |
1548 | **See also:**
1549 | Contour
1550 |
1551 |
1552 |
1553 | ## ClipperOffset
1554 |
1555 | The ClipperOffset class encapsulates the process of offsetting (inflating/deflating) both open and closed paths.
1556 |
1557 | This class replaces the now deprecated OffsetPaths function which is/was less flexible. The Execute method can be called multiple times using different offsets (deltas) without having to reassign paths. Offsetting can now be performed on a mixture of open and closed paths in a single operation. Also, the dual functionality of OffsetPaths' Limit parameter was not only confusing some users, but it also prevented a custom RoundPrecision being assigned when EndType was etRound and JoinType was jtMiter.
1558 |
1559 | When offsetting closed paths (polygons), it's important that:
1560 |
1561 | 1. their orientations are consistent such that outer polygons share the same orientation while holes have the opposite orientation
1562 | 2. they do not self-intersect.
1563 |
1564 |
1565 |
1566 | ### --- ClipperOffset methods ---
1567 |
1568 |
1569 |
1570 | ### ClipperLib.ClipperOffset()
1571 |
1572 |
1573 | ClipperOffset ClipperOffset(Number miterLimit = 2.0, Number roundPrecision = 0.25);
1574 |
1575 | ####
1576 |
1577 | The ClipperOffset constructor takes 2 optional parameters: MiterLimit and ArcTolerance. These two parameters corresponds to properties of the same name. MiterLimit is only relevant when JoinType is jtMiter, and ArcTolerance is only relevant when JoinType is jtRound or when EndType is etOpenRound.
1578 |
1579 | **Usage:**
1580 |
1581 |
1582 | var co = new ClipperLib.ClipperOffset(2.0, 0.25);
1583 |
1584 | ####
1585 |
1586 | **See also:**
1587 | ArcTolerance, MiterLimit
1588 |
1589 |
1590 |
1591 | ### ClipperLib.ClipperOffset.AddPath()
1592 |
1593 |
1594 | void AddPath(Path path, JoinType jointype, EndType endtype);
1595 |
1596 | ####
1597 |
1598 | Adds a path to a ClipperOffset object in preparation for offsetting. This method can be called multiple times.
1599 |
1600 | **Usage:**
1601 |
1602 |
1603 | var path = [{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}];
1604 | var co = new ClipperLib.ClipperOffset(2, 0.25);
1605 | co.AddPath(path, ClipperLib.JoinType.jtMiter, ClipperLib.EndType.etClosedPolygon);
1606 |
1607 | ####
1608 |
1609 | **See also:**
1610 | JoinType, EndType
1611 |
1612 |
1613 |
1614 | ### ClipperLib.ClipperOffset.AddPaths()
1615 |
1616 |
1617 | void AddPaths(Paths paths, JoinType jointype, EndType endtype);
1618 |
1619 | ####
1620 |
1621 | Adds paths to a ClipperOffset object in preparation for offsetting. This method can be called multiple times.
1622 |
1623 | **Usage:**
1624 |
1625 |
1626 | var paths = [[{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}],
1627 | [{X:20,Y:20},{X:20,Y:100},{X:100,Y:100},{X:100,Y:20}]];
1628 | var co = new ClipperLib.ClipperOffset(2, 0.25);
1629 | co.AddPaths(paths, ClipperLib.JoinType.jtMiter, ClipperLib.EndType.etClosedPolygon);
1630 |
1631 | ####
1632 |
1633 | **See also:**
1634 | JoinType, EndType
1635 |
1636 |
1637 |
1638 | ### ClipperLib.ClipperOffset.Clear()
1639 |
1640 |
1641 | void Clear();
1642 |
1643 | ####
1644 |
1645 | This method clears all paths from the ClipperOffset object, allowing new paths to be assigned.
1646 |
1647 | **Usage:**
1648 |
1649 |
1650 | var path = [{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}];
1651 | var co = new ClipperLib.ClipperOffset();
1652 | co.AddPath(path, ClipperLib.JoinType.jtRound, ClipperLib.EndType.etClosedPolygon);
1653 | co.Clear();
1654 |
1655 | ####
1656 |
1657 |
1658 |
1659 | ### ClipperLib.ClipperOffset.Execute()
1660 |
1661 |
1662 | void Execute(Paths solution, Number delta);
1663 | void Execute(PolyTree polytree, Number delta);
1664 |
1665 | ####
1666 |
1667 | This method takes two parameters. The first is the structure (either PolyTree or Paths) that will receive the result of the offset operation. The second parameter is the amount to which the supplied paths will be offset - negative delta values to shrink polygons and positive delta to expand them.
1668 |
1669 | This method can be called multiple times, offsetting the same paths by different amounts (ie using different deltas).
1670 |
1671 | **A note about scaling:**
1672 |
1673 | Because ClipperOffset uses integer coordinates, you have to scale coordinates to maintain precision and make arcs smooth - also in the case of integer input.
1674 |
1675 | Javascript Clipper provides four functions for this purpose: ScaleUpPath, ScaleUpPaths, ScaleDownPath and ScaleDownPaths.
1676 |
1677 | Scaling is highly recommended if JoinType is jtRound or EndType is etRound.
1678 |
1679 | **Usage:**
1680 |
1681 |
1682 | var subj = new ClipperLib.Paths();
1683 | var solution = new ClipperLib.Paths();
1684 | 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}];
1685 | var scale = 100;
1686 | ClipperLib.JS.ScaleUpPaths(subj, scale);
1687 | var co = new ClipperLib.ClipperOffset(2, 0.25);
1688 | co.AddPaths(subj, ClipperLib.JoinType.jtRound, ClipperLib.EndType.etClosedPolygon);
1689 | co.Execute(solution, -7.0);
1690 | ClipperLib.JS.ScaleDownPaths(subj, scale);
1691 | //draw solution with your own drawing function...
1692 | DrawPolygons(solution, 0x4000FF00, 0xFF009900);
1693 |
1694 | ####
1695 |
1696 | **See also:**
1697 | ScaleUpPath, ScaleUpPaths, ScaleDownPath, ScaleDownPaths.
1698 |
1699 |
1700 |
1701 | ### --- ClipperOffset properties ---
1702 |
1703 |
1704 |
1705 | ### ClipperLib.ClipperOffset.ArcTolerance
1706 |
1707 |
1708 | Number ArcTolerance
1709 |
1710 | ####
1711 |
1712 | Firstly, this field/property is only relevant when JoinType = jtRound and/or EndType = etRound.
1713 |
1714 | Since flattened paths can never perfectly represent arcs, this field/property specifies a maximum acceptable imprecision ('tolerance') when arcs are approximated in an offsetting operation. Smaller values will increase 'smoothness' up to a point though at a cost of performance and in creating more vertices to construct the arc.
1715 |
1716 | The default ArcTolerance is 0.25 units. This means that the maximum distance the flattened path will deviate from the 'true' arc will be no more than 0.25 units (before rounding).
1717 |
1718 | Reducing tolerances below 0.25 will **not** improve smoothness since vertex coordinates will still be rounded to integer values. The only way to achieve sub-integer precision is through coordinate scaling before and after offsetting (see example below).
1719 |
1720 | It's important to make ArcTolerance a sensible fraction of the offset delta (arc radius). Large tolerances relative to the offset delta will produce poor arc approximations but, just as importantly, very small tolerances will substantially slow offsetting performance while providing unnecessary degrees of precision. This is most likely to be an issue when offsetting polygons whose coordinates have been scaled to preserve floating point precision.
1721 |
1722 | **Example:** Imagine a set of polygons (defined in floating point coordinates) that is to be offset by 10 units using round joins, and the solution is to retain floating point precision up to at least 6 decimal places.
1723 | To preserve this degree of floating point precision, and given that Clipper and ClipperOffset both operate on integer coordinates, the polygon coordinates will be scaled up by 108 (and rounded to integers) prior to offsetting. Both offset delta and ArcTolerance will also need to be scaled by this same factor. If ArcTolerance was left unscaled at the default 0.25 units, every arc in the solution would contain a fraction of 44 THOUSAND vertices while the final arc imprecision would be 0.25 × 10-8 units (ie once scaling was reversed). However, if 0.1 units was an acceptable imprecision in the final unscaled solution, then ArcTolerance should be set to 0.1 × scaling_factor (0.1 × 108 ). Now if scaling is applied equally to both ArcTolerance and to Delta Offset, then in this example the number of vertices (steps) defining each arc would be a fraction of 23.
1724 |
1725 |
1726 |
1727 | **Usage:**
1728 |
1729 |
1730 | var co = new ClipperLib.ClipperOffset();
1731 | co.ArcTolerance = 1.23;
1732 |
1733 | ####
1734 |
1735 |
1736 |
1737 | ### ClipperLib.ClipperOffset.MiterLimit
1738 |
1739 |
1740 | Number MiterLimit
1741 |
1742 | ####
1743 |
1744 | This property sets the maximum distance in multiples of delta that vertices can be offset from their original positions before squaring is applied. (Squaring truncates a miter by 'cutting it off' at 1 × delta distance from the original vertex.)
1745 |
1746 | **The default value for MiterLimit is 2** (ie twice delta). This is also the smallest MiterLimit that's allowed. If mitering was unrestricted (ie without any squaring), then offsets at very acute angles would generate unacceptably long 'spikes'.
1747 |
1748 | An example of an offsetting 'spike' at a narrow angle that's a consequence of using a large MiterLimit (25) ...
1749 |
1750 | 
1751 |
1752 | **Usage:**
1753 |
1754 |
1755 | var co = new ClipperLib.ClipperOffset();
1756 | co.MiterLimit = 4.1;
1757 |
1758 | ####
1759 |
1760 | **See also:**
1761 | JoinType
1762 |
1763 |
1764 |
1765 | ## Rounding
1766 |
1767 | By using an integer type for polygon coordinates, the Clipper Library has been able to avoid problems of numerical robustness that can cause havoc with geometric computations. Problems associated with integer rounding and their possible solutions are discussed in the original documentation.
1768 |
1769 |
1770 |
1771 | ## JS
1772 |
1773 | JS is a special object to ensure backward compatibility and make it easier to run frequent tasks.
1774 |
1775 | It is not available in original Clipper.
1776 |
1777 |
1778 |
1779 | ### --- JS methods ---
1780 |
1781 |
1782 |
1783 | ### ClipperLib.JS.AreaOfPolygon()
1784 |
1785 |
1786 | Number AreaOfPolygon(Path poly, Number scale = 1);
1787 |
1788 | ####
1789 |
1790 | Returns the area of a closed Path. If the path is already scaled up, you can set scale value to force function to return downscaled area.
1791 |
1792 | **Usage:**
1793 |
1794 |
1795 | var path = [{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}];
1796 | var area = ClipperLib.JS.AreaOfPolygon (path, 1);
1797 | // area is 10000
1798 |
1799 | ####
1800 |
1801 |
1802 |
1803 | ### ClipperLib.JS.AreaOfPolygons()
1804 |
1805 |
1806 | Number AreaOfPolygons(Paths polys, Number scale = 1);
1807 |
1808 | ####
1809 |
1810 | Returns the area of a closed Paths. If it is already scaled up, you can set scale value to force function to return downscaled area.
1811 |
1812 | **Usage:**
1813 |
1814 |
1815 | var paths = [[{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}],
1816 | [{X:20,Y:20},{X:20,Y:100},{X:100,Y:100},{X:100,Y:20}]];
1817 | var area = ClipperLib.JS.AreaOfPolygons (paths, 1);
1818 | // area is now 3600
1819 |
1820 | ####
1821 |
1822 |
1823 |
1824 | ### ClipperLib.JS.BoundsOfPath()
1825 |
1826 |
1827 | IntRect BoundsOfPath(Path path, Number scale = 1);
1828 |
1829 | ####
1830 |
1831 | Returns an IntRect object which describes the bounding box of a Path. If the path is already scaled up, you can set scale value to force function to return downscaled bounds.
1832 |
1833 | **Usage:**
1834 |
1835 |
1836 | var path = [{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}];
1837 | var bounds = ClipperLib.JS.BoundsOfPath (path, 1);
1838 | // bounds is {"left":10,"top":10,"right":110,"bottom":110}
1839 |
1840 | ####
1841 |
1842 |
1843 |
1844 | ### ClipperLib.JS.BoundsOfPaths()
1845 |
1846 |
1847 | IntRect BoundsOfPaths(Paths paths, Number scale = 1);
1848 |
1849 | ####
1850 |
1851 | Returns an IntRect object which describes the bounding box of a Paths. If it is already scaled up, you can set scale value to force function to return downscaled bounds.
1852 |
1853 | **Usage:**
1854 |
1855 |
1856 | var paths = [[{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}],
1857 | [{X:20,Y:20},{X:20,Y:100},{X:100,Y:100},{X:100,Y:20}]];
1858 | var bounds = ClipperLib.JS.BoundsOfPaths (paths, 1);
1859 | // bounds is {"left":10,"top":10,"right":110,"bottom":110}
1860 |
1861 | ####
1862 |
1863 |
1864 |
1865 | ### ClipperLib.JS.Clone()
1866 |
1867 |
1868 | Path Clone(Path path);
1869 | Paths Clone(Paths paths);
1870 |
1871 | ####
1872 |
1873 | Makes a deep copy of Path or Paths so that also IntPoint objects are cloned and not only referenced.
1874 |
1875 | **Usage:**
1876 |
1877 |
1878 | var cloned_path = ClipperLib.JS.Clone(path);
1879 | // or
1880 | var cloned_paths = ClipperLib.JS.Clone(paths);
1881 |
1882 | ####
1883 |
1884 |
1885 |
1886 | ### ClipperLib.JS.Clean()
1887 |
1888 |
1889 | Path Clean(Path path);
1890 | Paths Clean(Paths paths);
1891 |
1892 | ####
1893 |
1894 | Joins vertices that are too near each other and would cause distortion in offsetting without cleaning.
1895 |
1896 | This function differs from CleanPolygon and CleanPolygons, which clean also collinear vertices.
1897 |
1898 | Ideal for situations where you need to prevent distortion and not do anything else.
1899 |
1900 | **Usage:**
1901 |
1902 |
1903 | var cleaned_path = ClipperLib.JS.Clean (path, delta);
1904 | // or
1905 | var cleaned_paths = ClipperLib.JS.Clean (paths, delta);
1906 |
1907 | ####
1908 |
1909 |
1910 |
1911 | ### ClipperLib.JS.Lighten()
1912 |
1913 |
1914 | Path Lighten(Path path, Number tolerance);
1915 | Paths Lighten(Paths paths, Number tolerance);
1916 |
1917 | ####
1918 |
1919 | Removes points that doesn't affect much to the visual appearance. If middle point is at or under certain distance (tolerance) of the line segment between start and end point, the middle point is removed.
1920 |
1921 | Helps to speedup calculations and rendering.
1922 |
1923 | **Usage:**
1924 |
1925 |
1926 | var scale = 100;
1927 | var lightened_path = ClipperLib.JS.Lighten(path, 0.1 * scale);
1928 | // or
1929 | var lightened_paths = ClipperLib.JS.Lighten(paths, 0.1 * scale);
1930 |
1931 | ####
1932 |
1933 |
1934 |
1935 | ### ClipperLib.JS.PerimeterOfPath()
1936 |
1937 |
1938 | Number PerimeterOfPath(Path path, Boolean closed, Number scale = 1);
1939 |
1940 | ####
1941 |
1942 | Returns the perimeter of a Path. If the Path is closed (ie polygon), a clone of the first vertex is added to the end of the Path and removed after calculation to ensure that whole ("polygonal") perimeter is taken into account.
1943 |
1944 | Open paths (ie lines) are measured by taking into account only the existing vertices.
1945 |
1946 | If the path goes back the same way, every line segment is calculated, which means that the returned perimeter is longer than the visual perimeter.
1947 |
1948 | If coordinates are upscaled beforehand by some scaling factor (eg. 100), and scale parameter is provided to the function, the downscaled, real perimeter is returned.
1949 |
1950 | **Usage:**
1951 |
1952 |
1953 | var path = [{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}];
1954 | var polygonal_perimeter = ClipperLib.JS.PerimeterOfPath(path, true, 1);
1955 | // polygonal_perimeter is 400
1956 |
1957 | // But...
1958 | var line_perimeter = ClipperLib.JS.PerimeterOfPath(path, false, 1);
1959 | // line_perimeter is 300
1960 |
1961 | ####
1962 |
1963 |
1964 |
1965 | ### ClipperLib.JS.PerimeterOfPaths()
1966 |
1967 |
1968 | Number PerimeterOfPaths(Paths paths, Boolean closed, Number scale = 1);
1969 |
1970 | ####
1971 |
1972 | Returns the sum of perimeters of individual paths contained in the paths. See also PerimeterOfPath.
1973 |
1974 | **Usage:**
1975 |
1976 |
1977 | var paths = [[{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}],
1978 | [{X:20,Y:20},{X:20,Y:100},{X:100,Y:100},{X:100,Y:20}]];
1979 | var polygonal_perimeter = ClipperLib.JS.PerimeterOfPaths (paths, true, 1);
1980 | // polygonal_perimeter is 720
1981 |
1982 | var line_perimeter = ClipperLib.JS.PerimeterOfPaths (paths, false, 1);
1983 | // line_perimeter is 540
1984 |
1985 | ####
1986 |
1987 |
1988 |
1989 | ### ClipperLib.JS.ScaleDownPath()
1990 |
1991 |
1992 | void ScaleDownPath(Path path, Number scale = 1);
1993 |
1994 | ####
1995 |
1996 | Divides each coordinate of Path by scale value.
1997 |
1998 | **Usage:**
1999 |
2000 |
2001 | var path = [{X:1000,Y:1000},{X:11000,Y:1000},{X:11000,Y:11000},{X:1000,Y:11000}];
2002 | ClipperLib.JS.ScaleDownPath (path, 100);
2003 | // path is [{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}];
2004 |
2005 | ####
2006 |
2007 |
2008 |
2009 | ### ClipperLib.JS.ScaleDownPaths()
2010 |
2011 |
2012 | void ScaleDownPaths(Paths paths, Number scale = 1);
2013 |
2014 | ####
2015 |
2016 | Divides each coordinate of Paths by scale value.
2017 |
2018 | **Usage:**
2019 |
2020 |
2021 | var paths = [[{X:1000,Y:1000},{X:11000,Y:1000},{X:11000,Y:11000},{X:1000,Y:11000}],
2022 | [{X:2000,Y:2000},{X:2000,Y:10000},{X:10000,Y:10000},{X:10000,Y:2000}]];
2023 | ClipperLib.JS.ScaleDownPaths (path, 100);
2024 | // path is [[{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}],
2025 | // [{X:20,Y:20},{X:20,Y:100},{X:100,Y:100},{X:100,Y:20}]];
2026 |
2027 | ####
2028 |
2029 |
2030 |
2031 | ### ClipperLib.JS.ScaleUpPath()
2032 |
2033 |
2034 | void ScaleUpPath(Path path, Number scale = 1);
2035 |
2036 | ####
2037 |
2038 | Multiplies each coordinate of a Path by scaling coefficient and rounds to the nearest integer using Math.round().
2039 |
2040 | **Usage:**
2041 |
2042 |
2043 | var path = [{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}];
2044 | ClipperLib.JS.ScaleUpPath (path, 100);
2045 | // path is now [{X:1000,Y:1000},{X:11000,Y:1000},{X:11000,Y:11000},{X:1000,Y:11000}];
2046 |
2047 | ####
2048 |
2049 |
2050 |
2051 | ### ClipperLib.JS.ScaleUpPaths()
2052 |
2053 |
2054 | void ScaleUpPaths(Paths paths, Number scale = 1);
2055 |
2056 | ####
2057 |
2058 | Multiplies each coordinate of Paths by scaling coefficient and rounds to the nearest integer using Math.round().
2059 |
2060 | **Usage:**
2061 |
2062 |
2063 | var paths = [[{X:10,Y:10},{X:110,Y:10},{X:110,Y:110},{X:10,Y:110}],
2064 | [{X:20,Y:20},{X:20,Y:100},{X:100,Y:100},{X:100,Y:20}]];
2065 | ClipperLib.JS.ScaleUpPaths (path, 100);
2066 | // path is now [[{X:1000,Y:1000},{X:11000,Y:1000},{X:11000,Y:11000},{X:1000,Y:11000}],
2067 | // [{X:2000,Y:2000},{X:2000,Y:10000},{X:10000,Y:10000},{X:10000,Y:2000}]];
2068 |
2069 | ####
2070 |
2071 |
2072 |
2073 | ### ClipperLib.JS.PolyTreeToExPolygons()
2074 |
2075 |
2076 | ExPolygons PolyTreeToExPolygons(PolyTree polytree)
2077 |
2078 | ####
2079 |
2080 | Converts PolyTree to ExPolygons.
2081 |
2082 | **Usage:**
2083 |
2084 |
2085 | var expolygons = ClipperLib.JS.PolyTreeToExPolygons(polytree);
2086 |
2087 | ####
2088 |
2089 |
2090 |
2091 | ### ClipperLib.JS.ExPolygonsToPaths()
2092 |
2093 |
2094 | Paths ExPolygonsToPaths(ExPolygons expolygons)
2095 |
2096 | ###
2097 |
2098 | Converts ExPolygons to Paths.
2099 |
2100 | **Usage:**
2101 |
2102 |
2103 | var paths = ClipperLib.JS.ExPolygonsToPaths(expolygons);
2104 |
2105 | ###
2106 |
2107 |
2108 |
2109 | ## Copyright
2110 |
2111 | Texts and images have been copied (with permission) from the original Clipper Documentation, with some modifications to fit the Javascript environment.
2112 |
2113 | Clipper Documentation is copyright 2010-2014 Angus Johnson.
2114 |
2115 | Modifications copyright 2013-2014 Timo.
2116 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # ClipperLib
2 |
3 | > forked from [Javascript Clipper](http://sourceforge.net/projects/jsclipper/)
4 |
5 | ## Description
6 |
7 | The Javascript Clipper library performs clipping and offsetting for both lines and polygons. All four boolean clipping operations are supported - intersection, union, difference and exclusive-or. Polygons can be of any shape including self-intersecting polygons.
8 |
9 | Javascript Clipper is a port of Angus Johnson's Clipper library:
10 |
11 | LIVE DEMO:
12 |
13 | Information and examples:
14 |
15 |
16 | Donate Javascript Clipper Project:
17 |
18 | Use cases:
19 | * Over 1500 schools in the UK uses Javascript Clipper in Digimap for Schools service. Digimap for Schools is an online mapping service for use by teachers and pupils. Read more:
20 | and
21 |
22 |
23 | [Javascript Clipper Web Site](https://sourceforge.net/p/jsclipper/wiki/)
24 |
25 | ## Features
26 |
27 | - Line and polygon clipping - intersection, union, difference & xor
28 | - Line and polygon offsetting with 3 types of joining - miter, square and round
29 | - Polygons can be of any shape, including self-intersecting polygons
30 | - Minkowski Addition and Minkowski Difference functions included
31 | - The library is written in Javascript
32 | - Comprehensive documentation
33 | - Demos use inline SVG and Canvas libraries
34 | - The library is significantly faster than commercial alternatives
35 | - Uses Tom Wu's fast big integer library
36 | - UMD support
37 |
38 | ## Categories
39 |
40 | Algorithms, Graphics
41 |
42 | ## Links
43 |
44 | - [Documentation](./Documentation.md)
45 | - [ChangeLog](./ChangeLog.txt)
46 |
47 | ## License
48 |
49 | [Boost Software License (BSL1.0)](http://www.boost.org/LICENSE_1_0.txt)
50 |
--------------------------------------------------------------------------------
/bower.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "clipper-lib",
3 | "version": "6.4.2",
4 | "description": "Boolean operations and offsetting library in Javascript",
5 | "authors": [
6 | "Angus Johnson (Original library)", "Timo (Translation to JS)"
7 | ],
8 | "main": "clipper.js",
9 | "moduleType": [
10 | "amd",
11 | "globals",
12 | "node"
13 | ],
14 | "keywords": [
15 | "clipper"
16 | ],
17 | "repository": "git://github.com/junmer/clipper-lib",
18 | "license": "BSL",
19 | "ignore": [
20 | "**/.*",
21 | "node_modules",
22 | "bower_components",
23 | "test",
24 | "tests",
25 | "Documentation.md",
26 | "ChangeLog.txt"
27 | ]
28 | }
29 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "clipper-lib",
3 | "version": "6.4.2",
4 | "description": "Boolean operations and offsetting library in Javascript",
5 | "files": [
6 | "clipper.js"
7 | ],
8 | "keywords": [
9 | "clipper"
10 | ],
11 | "main": "clipper",
12 | "repository": "git://github.com/junmer/clipper-lib",
13 | "scripts": {
14 | "test": "echo \"Error: no test specified\" && exit 1"
15 | },
16 | "author": ["Angus Johnson (Original library)", "Timo (Translation to JS)"],
17 | "license": "BSL"
18 | }
19 |
--------------------------------------------------------------------------------