Migration from Clipper1 to Clipper2 [C++]

[yoavmil]

I have a wrapper library clipper. (It's called amlib, for additive manufacturing, hope to go opensource someday).
I'm trying to migrate, but it's too hard.
For example, at Clipper1, Point.X/Y (uppercase), at Clipper2 Point.x/y (lowercase).

please advice.

[AngusJohnson]

If there's a chorus of people suggesting that I change point x & y to X & Y, then I'll happily oblige.

[rs0xFFFF]

Mathematics says that variables are always lowercase.

[yoavmil]

Migration is an important issue.
I've been using Clipper1 for 10 years in different companies. Obviesly I was very intersted in the Clipper2 for run time reasons.
It will be a waste if all your good work couldn't be used in legacy code. I cannot even evaluate Clipper2 because of incompatibilty.

I'm still strugling. Regarding the .x VS .X I can't think of anything smarter than 'replace all .X'.

[yoavmil]

I tried to support both versions with macros that let you choose which version to use, but it is too complex.
Another example is the enums parameters for clipping and offseting, they have different names and event different order within the enum. For example

enum ClipType { ctIntersection, ctUnion, ctDifference, ctXor };

VS

enum class ClipType { None, Intersection, Union, Difference, Xor };

Next try I'll try to replace Clipper1 with 2 unconditionaly. See how that goes and update.

[AngusJohnson]

they have different names and event different order within the enum.

Clipper2 was never intended to be backward compatible. In Clipper1 I tried to keep naming close to my original Delphi naming as I thought that that would make support easier. But in practise, this wasn't the case and it just IMHO made the C++ and C# code look odd. So in Clipper2, I've been more flexible with naming. Function names are generally the same in each of the 3 languages. But constants, variables, enums etc will now have a more language specific style.

Anyhow, for the majority of users the functions in clipper.h should be all that they'll need, and so migrating from Clipper1 to Clipper2 shouldn't really be that difficult.

[yoavmil]

I'm writing down what I've done to migrate to Clipper2, work in progress.
A lot of 'replace all':

• namespace ClipperLib to Clipper2Lib
• enums (ClipType etc)
• types (Path64, PolyPath ...)
  • PolyPath changed alot.
• .x/.X
• Clipper.ArcTolerance() became a method
• Orientation became IsPositive
• ReversePath() missing, replace with std::reverse

more changes and things I've noticed:

• Clipper::AddPaths() became private and need to use now other methods.
• Clipper::Execute() defualt fillrule is gone.
• CleanPolygons is gone. This wories me.
• ClipperOffset::Execute() signature changed, and doesn't accept FillRule, also it is different from Clipper::Execute()
  • The result should be either is in the return value or as a parameter.
  • can merge AddPaths and AddPath to Add with different overloads
• Clipper.AddSubject/AddOpenSubject. I would prefer more explicity: Clipper.Add*Closed*Subject/AddOpenSubject
• missing Clipper.AddSubject(Path64) overload.
• There is a different between:
  • double d; Point64 pt; pt + d * pt; // gives warning, and
  • double d; Point64 pt; pt + pt * d; // no warning

By now I've compiled my library, but tests are failing. More to come.

[yoavmil]

More changes I needed to do

• I copied CleanPolygons from Clipper1 to my source, because it is missing in Clipper2.
  • It's very important for me, for reducing the vertices count, for runtime reasons.
• I discovered that open paths offset changed by 50%! MAJOR SURPRISE
  • at Clipper1 when inflating open paths by delta, it was by delta both sides of the line, resulting in 2*delta width
  • at Clipper2 inflating open paths by delta is delta from end to end.
  • see if (group.end_type_ != EndType::Polygon) delta = std::abs(delta) / 2;
  • How is it at other svg renderes?
  • worth mentioning in the docs.

By now I finished migrating my library that wraps Clipper, and all 84 tests pass.
I've run a stress test, and it looks like the Clipper2 is SLOWER by 30%. I'll investigate later.

This is the stress test. It creating a grid of circles and xoring them with eachother.

	Stopwatch watch("test clipper lib");
	Polygons polys;
	Micron radius = 1000;
	for (int i = 0; i < 20; i++) {
		for (int j = 0; j < 20; j++) {
			polys = polys ^ PolyUtils::CreateCircle({radius * i * 75 / 100, radius * j * 75 / 100}, radius);
		}
		cout << "round " << i << ", area = " << polys.area() << "\n";
	}
	SvgWriter svg(DOC_FILE_NAME);
	svg.Add(polys);
	polys += radius;
	polys -= radius;

[AngusJohnson]

I discovered that open paths offset changed by 50%! MAJOR SURPRISE

Yes, I should better document this.

Edit: I've now added this to the documentation:

With closed paths (polygons), a positive delta specifies how much outer polygon contours will expand and how much inner "hole" contours will contract (and the converse with negative deltas).

With open paths (polylines), including EndType.Join, delta specifies the width of the inflated line.

[AngusJohnson]

I've run a stress test, and it looks like the Clipper2 is SLOWER by 30%. I'll investigate later.

Huh???
Attached is what i think your stress test is, comparing Clipper1 and Clipper2

Edit: Oops, the attachment was missing a crucial file. Fixed now. Anyhow, Clipper2 comfortable out performs Clipper1 in this test and the time differences become more dramatic if you increase the i & j loop counts to 30 or 40.
clipper_compare.zip

[yoavmil]

Take a look, this is my stress test based on your solution.
The different is that there is a grid of circles, same radius, xorred as created to one big polygons. In this case Clipper2 is ~30% slower.

void stressTest() {
    int64_t radius = 1000;
    {
        Timer t("starting Clipper1 ...");
        ClipperLib::Paths polys;
        for (int i = 0; i < 20; i++) {
            for (int j = 0; j < 20; j++) {
                ClipperLib::Path e = Ellipse(IntPoint(radius * i * 75 / 100, radius * j * 75 / 100), radius);
                Clipper c;
                c.AddPath(e, PolyType::ptSubject, true);
                c.AddPaths(polys, PolyType::ptClip, true);
                c.Execute(ClipperLib::ClipType::ctXor, polys, PolyFillType::pftEvenOdd);
            }
        }
    }

    {
        Timer t("starting Clipper2 ...");
        Paths64 polys64;
        for (int i = 0; i < 20; i++) {
            for (int j = 0; j < 20; j++) {
                Path64 e = Ellipse(Point64(radius * i * 75 / 100, radius * j * 75 / 100), radius);
                Clipper64 c64;
                c64.AddSubject({ e });
                c64.AddClip(polys64);
                c64.Execute(Clipper2Lib::ClipType::Xor, FillRule::EvenOdd, polys64);
            }
        }
    }
}

int main()
{
  std::cout.imbue(std::locale(""));
  srand((unsigned)time(0));

  stressTest();
  return 0;

BTW, I've noticed there is no Clipper64.AddSubject(Path64) and AddClip(Path64)

[AngusJohnson]

Take a look, this is my stress test based on your solution.

The following pseudocode explains what ISTM you're "stress test" is doing:

for 1 to 20 do 
  for 1 to another 20 do
    add a single ellipse (e) of varying size to a new Clipper (or Clipper64) object
    then XOR this ellipse with a null polygon (**polys**).

I really don't understand how this is "stress testing" anything (except the Clipper constructors and their AddPath methods).
So Clipper1 is a bit quicker than Clipper2 at doing essentially nothing.

Edit: While some of your suggestions in this thread have merit, the way you are going about it I'm finding pretty annoying.

[yoavmil]

no, it xors it with polys over and over. the circles are the same size, just different location.

                c64.AddClip(polys64); // << polys
                c64.Execute(Clipper2Lib::ClipType::Xor, FillRule::EvenOdd, polys64); // << polys

[AngusJohnson]

OK, my apologies.
I'll have another look,

[AngusJohnson]

Firstly, yes, your code above does indeed perform (multiple) clipping operations.
However, it does so in an incredibly inefficient way that I'd argue spends way too much time measuring polygon construction and Clipper object construction, and not nearly enough time testing the actual clipping operation.
The following code I'd suggest does a much better job of the latter (and again Clipper 2 comfortably out performs Clipper1):

  int64_t radius = 1000;
  int cnt = 20; //and test this with a much larger value too

  // setup Clipper1 testing
  ClipperLib::Paths polys;
  for (int i = 0; i < cnt; i++) {
    for (int j = 0; j < cnt; j++) {
      ClipperLib::Path e = Ellipse(IntPoint(radius * i * 75 / 100, radius * j * 75 / 100), radius);
      polys.push_back(e);
    }
  }
  // now time Clipper1 clipping
  {
    Timer t("starting Clipper1 ...");
    Clipper c;
    c.AddPaths(polys, PolyType::ptSubject, true);
    c.Execute(ClipperLib::ClipType::ctUnion, polys, PolyFillType::pftEvenOdd, PolyFillType::pftEvenOdd);
  }

  // setup Clipper2 testing
  Timer t("starting Clipper2 ...");
  Paths64 polys64;
  Path64 e;
  for (int i = 0; i < cnt; i++) {
    for (int j = 0; j < cnt; j++) {
      e = Ellipse(Point64(radius * i * 75 / 100, radius * j * 75 / 100), radius);
      polys64.push_back(e);
    }
  }
  // now time Clipper2 clipping
  {
    Timer t("starting Clipper2 ...");
    Clipper64 c64;
    c64.AddSubject(polys64);
    c64.Execute(Clipper2Lib::ClipType::Union, FillRule::EvenOdd, polys64);
  }

And with the same result but very much faster (for both Clipper1 and Clipper2):

[yoavmil]

I agree it isn't the most efficiant code. But somtimes this is what the code has to be. (Imagine for example recieving polygons on the fly and having to xor them upon recieving).
So you say that building Clipper and measuring the polygons take longer at Clipper2, but the actual clipping is faster. Fair enough.
Well then, we should have a "do's and don't" section in the docs.
I'm very interested in Clipper2 and runtime is my main consern.
The real test would be after I integrate Clipper2 in my commercial app, and see how it performs. I'll update here.

And again, thanks for both libraries. I've been using Clipper since 2013. And I'm actually excited to talk with you!

Edit: Ooops, sorry yoav. I accidently edited your post instead of replying to it.

[AngusJohnson]

So you say that building Clipper and measuring the polygons take longer at Clipper2, but the actual clipping is faster.

No, while that's possibly true, I suspect the real difference is that Clipper2 is much better at handling more complex operations. You'll note that Clipper1 does actually slightly outperform Clipper2 in your test above when cnt == 20. But when cnt == 50 or 100 or 200, Clipper2 does way better.