Add Geometry2D Functions to Support Merging Complex Polygons

[samjudd]

Geometry2D provides functions for performing boolean operations on 2 polygons, but the result of that merge can be polygons with multiple contours. The Geometry2D does not then have any functions that can futher performs operations on the multi-contour polygons.

The Clipper2 library provides support for merging these multi-contour polygons with other ones, so this PR is just to expose that functionality to GDScript so that people can use it. This is done through just making new functions similar to the existing API but accepting arrays of PackedVector2Arrays so these complex polygons can be operated on.

[Ivorforce]

Hello, thank you for contributing to the Godot engine!
Proposals for adding new features should be associated with a feature proposal. Most importantly, it should include a use-case for merging complex polygons together. Examples with images would be most appreciated.

[samjudd]

Hi! Thanks for the feedback! This is working towards the feature proposal linked, though I took a bit of a different approach to solving the issue than in the feature proposal that I thought was a bit simpler. godotengine/godot-proposals#10395

for some examples with images, let's say I wanted to merge this polygon (stored in data as a PackedVector2Array since it is a simple contour).

with this one (also a simple 2D contour stored as a PackedVector2Array).

I can use the builtin Geometry2D function merge_polygons!

However, in this case (and in many others) this merge operation will return an array of 2D polygons comprising both the outer contour and a hole generated while merging the two (the outer contour is shown in blue and the hole is shown in yellow below).

However, all the current Geometry2D merge operations only take in individual PackedVector2Arrays as inputs, so merging two polygons with holes (represented by arrays of PackedVector2Arrays) quickly can become quite a complicated scripting task. The clipper2d library has the functionality built-in to merge these arrays of polygons efficiently, so this PR is simply to expose those functions to GDScript so people can use them!

Let me know if this feature proposal + explanation is what you are looking for, happy to make a new feature proposal or expand further on this if that is necessary, thanks!

[fire]

I believe @smix8 was working on a CSG 2d implementation?

[Calinou]

I believe @smix8 was working on a CSG 2d implementation?

Yes, see:

• Add 2D CSG boolean operations #99911

[smix8]

The linked proposal is more complex for good reason. It tries to abstract away all the performance obstacles that scripting has by keeping things internal until the final commit. A boolean ops API that needs to shuffle and return entire TypedArray returns all the time to users in scripting does not performance scale at all.

[samjudd]

Ahh yep, makes a lot of sense on the performance side of things. My thinking behind this approach unlock people to have this capability in a small way, and then if large-scale merging is a thing many people want to do and the performance is needed, it doesn't close the door to what was in the proposal later. Is that kinda philosophical approach preferred for godot, or would we rather go for something bigger from the start?

Another question I have is does the CSG PR linked here kinda make these changes to Geometry2D just not needed anymore or do you see both things needing to be done?

Thanks!

[smix8]

CSG2D and the linked GeometryOperations from the proposal try to solve the boolean ops need for two major but very different Godot user groups.

The CSG2D is targeted at beginners and "code challenged" users that like to use Nodes for their ease of use and visual feedback, e.g. a gameplay or level designer on a project that needs to test things out but can not necessarily write working geometry involving code. For smaller projects that is also all that people need for performance.

The GeometryOperations is for all users that can work with code as it is a scaleable solution that works to any level of complexity. It also can work with threads while nodes have a natural problem with threads. Being a reusable RefCounted it also does not trash language binds with garbage collectors like CSharp at the same level as a full array returning function does.

I am the wrong person to ask about "Does Godot need a medium-difficult-medium-performance solution?" because my personal answer is always no. I have never encountered those medium-medium users in all those years. If someone can code they learn even server api use within less than an hour given the right documentation.