Javascript Clipper Wiki
Boolean operations and offsetting library in Javascript
Brought to you by:
timo23414
Menu
▾
▴
Main_Demo 6
Donate Javascript Clipper Project
Main Demo of Javascript Clipper 6
LIVE DEMO: http://jsclipper.sourceforge.net/6.4.2.2/main_demo.html
The Main Demo program presents key features of Javascript Clipper Library. These are primary boolean operations: union, intersection, difference and xor and polygon offsetting. Also some other features are presented, like area calculation and lightening.
In this wiki and it's sub pages we will cover several examples of these operations. The purpose of this wiki is to show the robustness and usability of this library.
The Main Demo is a javascript driven html page. It uses Javascript Clipper library (clipper.js) for polygon calculation operations and jQuery and Raphaël JS for accessing DOM. The graphical backend is inline SVG. Note! Javascript Clipper library can be used with any JS libraries or without any library.
Table of Contents
Visual appearance
The program has this like visual appearance:
Polygon Explorer
Polygon Explorer shows details of polygons. The image below shows an example of using Polygon Explorer:
Hovering
If you hover the point counts in column Points in subpolygons, you see a hover effect on the corresponding sub polygon in SVG window. The same applies to column Points, in which case you see a hover effect of the whole multi-polygon.
Clicking
If you click the point counts in column Points in subpolygons, you see the corresponding sub polygon enlarged with little red stroked yellow filled circles on the points of polygon and an red arrow that shows the starting point and the direction of sub polygon.
Additionally when clicking, you see the coordinates of the subpolygon in the input field of Polygon Explorer. To edit this sub polygon, you can copy the coordinates of the input field and paste them in the Subj or Clip input fields on Your own custom polygons fieldset.
If you hover or click point counts in column Points, the details of the whole polygon (ie. all sub polygons) are shown.
Additionally when clicking, you see also area, perimeter, width and height of multi-polygon or sub polygon.
Transform
Main demo has now a transform tool. You can rotate or distort polygons. The transform is applied before clipping and offsetting. You can easily test hundreds of different polygons using transform tool, because new polygon coordinates are always created when you transform.
Custom polygon sets (Polygon importer)
One feature of the Main Demo is the ability to import your own polygon sets or modify existing ones. Polygon set is a pair of Subject and Clip polygon.
To use this feature click Custom radiobutton in Polygons fieldset. The Your own custom polygons fieldset appears and there you can add, modify and remove custom polygon sets. The image below shows an example of using Custom Polygons:
Possible input formats
The coordinates of custom polygons are typed (or pasted) into the Subject and Clip input fields. The program is rather permissive what it comes to input formats.
You can type the coordinates in the following formats:
1) The program uses as an inner default the following format: JSON-stringified array of arrays of point objects eg. [[{"X":100,"Y":100},{"X":200,"Y":100},{"X":200,"Y":200},{"X":100,"Y":200}],[{"X":110,"Y":110},{"X":210,"Y":110},{"X":210,"Y":210},{"X":110,"Y":210}]]. This format allows to input multi-polygons. Each sub polygon is an array of point objects. This format makes it easy to transfer polygons to other programs that use Clipper library and is suitable for storing polygons in database.
2) JSON-stringified array of point objects eg. [{"X":100,"Y":100},{"X":200,"Y":100},{"X":200,"Y":200},{"X":100,"Y":200}]. This format doesn't allow to input multi-polygons.
3) JSON-stringified array of arrays of coordinates without "X" and "Y" eg. [[100,100,200,100,200,200,100,200],[110,110,210,110,210,210,110,210]]. This format allows to input multi-polygons. Each sub polygon is an array of coordinates so that each x coordinate is followed by an y coordinate. This format makes it easy to transfer polygons to other programs that use Clipper library and is suitable for storing polygons in database.
4) JSON-stringified array of x and y coordinates eg. [100,100,200,100,200,200,100,200] or [100 100 200 100 200 200 100 200] or [100 100,200 100,200 200,100 200] or the same without []:s. This format doesn't allow to input multi-polygons.
5) SVG path strings with commands MLVHZ or mlvhz eg. M100,100 L200,100 L200,200 L100, 200Z M110,110 L210,110 L210,210 L110, 210Z. This format allows to input multi-polygons. Each subpolygon starts with M (moveto) command.
Despite of the input format, the string is converted to format 1 in all cases. The X and Y can be written in upper- or lowercase.
Output formats
There are three output formats. The desired output format is selected using dropdown in Polygon Explorer. The available formats are:
-
Clipper: [[{"X":100,"Y":100},{"X":200,"Y":200}]]
-
Plain: [[100,100,200,200]]
-
SVG: M100,100L200,200Z
There are two places where the selected format has effect:
1) The coordinates input field in Polygon Explorer. This field shows coordinate values, when you click numbers in Polygon Explorer. This field is used only for showing coordinates, not for inputting.
2) the Subj and Clip input fields in Your own custom polygons fieldset. These two fields are used for inputting and outputting.
How own polygons are stored
Custom polygon sets are saved in browser's Local Storage, so they should be tolerant for page reload and browser crashes. All custom polygon sets are stored as one array and in Local Storage there is only one string, which you can see and using browser's debugging tools.
Cleaning
Clipper has SimplifyPolygons() and SimplifyPolygon() functions, which converts complex polygons (polygons that have self-intersections) to simple ones using internally union of itself, but for some reason it cannot handle situations where vertices are very near each other or/and have micro-self-intersections, eg. (20.64,10.66) and (20.63,10.67). These micro-self-intersections causes breaking polygons as a result of offsetting. The problem exists only in offsetting (especially when joinType is Miter and miterLimit is big), not Boolean operations.
The following image shows an example of this distortion:
In the above image, the offset delta is -5.0, miterLimit 100 and coordinates are upscaled by 100.
When you increase the scaling factor to 100,000, the distortion decreases, but still exists as the following image shows:
Near Point Removal, Clean() function
To avoid polygon breakage, we provide a method that is not (yet) included in original Clipper, but we provide it as a helper function ClipperLib.Clean(). When the polygon is cleaned, the result is as expected:
The uncleaned solution had 445 vertices, and after cleaning the count decreased to 378, when cleaned using cleaning delta 0.1. This means that if the distance between two sequential vertices is 0.1 or below it, the points are merged.
Near Point Removal method helps to avoid polygon breakage due to micro-self-intersections and/or very-near-vertices. It merges two adjacent vertices that are under or at certain distance of each other. The reducing (or simplifying) algorithm is Radial Removal.
This method should be enough (together with SimplifyPolygons() and AutoFix attribute) to remove all micro-self-intersections before offsetting.
The following image shows the principle of Clean() function:
Middle Point Removal, Lighten() function
In many cases the resulted polygon has vertices that are not needed and causes unnecessary overload when handled and drawn. Eg. square can consist of 30 points, although 4 is enough. If the polygon is offsetted using join type Round, the arcs on corners can have unnecessary points. If the polygon is a map or a result of tracing of bitmap image, the possibility for unnecessary vertices increases.
Note! The following example of arcs in Clipper Offset function is a bit outdated, because Clipper 6 has now ArcTolerance value, and increasing it you can reduce the point count.
As an example of the need for reducing is the arcs that Clipper produces. When using large scaling values, the count of vertices in arcs can be too high. In the following example, the count of vertices is 256, which is too much.
If we Lighten() the polygon, the count of vertices decreases to 32, which seems to be enough for this polygon:
There are many polygon simplifying methods, eg.
- Nth Point, Radial distance
- Perpendicular Distance
- Reumann-Witkam
- Opheim
- Lang
- Douglas-Peucker
We provide an implementation of Perpendicular Distance on our ClipperLib.Lighten() function. Although it's not as precise as Douglas-Peucker which is popular algorithm and cannot safely remove so much points, it is fast and reliable, if the tolerance is not too high.
This is a local middle-point removal method, which scans the vertices and removes the middle vertex of three sequantial vertices, if the distance of the middle vertex to the line between start and end vertex is below certain tolerance value. The following image shows the removal principe:
When the tolerance is low, this is a safe method for removing unnecessary vertices that doesn't affect much to the visual appearance.
Clean and Lighten in Main Demo
In the Main Demo, both Clean() and Lighten() functions are implemented:
Using text boxes, you can adjust the Clean Delta and Lighten Tolerance. The default values (0.1) in both produces usually good results.
The order of the executing these functions matters. Clean() is used to remove too-near-vertices before offsetting and Lighten() is used to reduce unnecessary points and it's used after offsetting. Of course both functions are safe to use whenever needed, but in Main Demo the order is this.
Benchmark
Benchmarking feature of the Main Demo is used for comparing the speed of Clipper library in different browsers. There are three kind of benchmarking:
1) Speed of individual function calls. When you make an boolean or offsetting operation, the time that browser uses for executing the corresponding Clipper library functions is measured and reported in the right panel of Main Demo.
2) Normal integer benchmark. This is a complete set of boolean and offsetting operations with 5 polygon sets. The scale value is 100. The benchmark report is more detailed and includes eg. average, range and standard deviation.
3) Big integer benchmark. Exactly the same as Normal integer benchmark, but the scale value is 100,000,000 and big integer calculations are used.
Performance in browsers
We have not yet measured performance of Clipper 6, but meanwhile you can see the benchmarks of Clipper 5.
Screen captures of polygon operations (not all but many)
With the Main Demo program it is possible to test all boolean operations and offsetting of various sample polygons and also random polygons and random rectangles and you can even import your own polygons. Below are a set of these, not all but most of samples.
Great Britain and Arrows
Intersection, union, difference, xor of Great Britain map and 4 Arrows:
Main Demo - Great Britain and Arrows
Clipping and Offsetting Text
The complete set of operations (intersection, union, difference, xor and offsetting) can be seen here:
Grid and Glyph
Eroding and dilating Glyph shape:
Grid and Star
Intersection, union, difference, xor of a grid and a star:
Random Polygons
Intersection, union, difference, xor of random polygons:
Random Rectangles
Intersection, union, difference, xor of random polygons:
Compatibility and issues
The Main Demo is tested in all major modern desktop browsers (IE10 pre, IE9, Firefox, Chrome, Safari, Opera) in Windows and Mac. Please see the tested browser versions in
the benchmark page.
Main Demo uses custom bewel SVG filter (to beautify polygons visually), which works in filter capable browsers. In Polygon Explorer there is a non scaling stroke, which unfortunately does not work in IE9 or IE10.
Opera 12.02 in Windows 7 and Mac OS X has some SVG drawing issue (odd horizontal lines in some polygons). IE9 and Safari 5.1.7 are very slow, so avoid using them with this library.
The Main Demo does not support older browsers (eg. IE8 and older), which have not support for html5 (eg. inline SVG and local storage).
The Clipper library itself should work in older browsers also and there are no known issues regarding to Clipper library, but because of poor drawing support in older browsers, it's not meaningful to make thorough testing in them.
