godotengine / godotengine/godot-docs

Methods in Gemetry2D don't explain how to use is_polygon_clockwise to tell boundaries from holes

Open
#9,919 1 comment 0 reactions 0 assignees View on GitHub
area:class reference enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

**Your Godot version:**

4.3

**Issue description:**

There are some methods in the [Geometry2D doc page](https://docs.godotengine.org/en/stable/classes/class_geometry2d.html) (see URLs below) that return an `Array[PackedVector2Array]` with this indication:

> The operation may result in an outer polygon (boundary) and inner polygon (hole) produced which could be distinguished by calling [is_polygon_clockwise](https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-is-polygon-clockwise)

but without telling how to use the result from `is_polygon_clockwise` to distinguish boundaries from holes.

It would be less confusing to explicitly state which convention is used by Geometry2D: are clockwise polygons used to represent holes or boundaries?

Looking through the [geometry2d.cpp source](https://github.com/godotengine/godot/blob/77dcf97d82cbfe4e4615475fa52ca03da645dbd8/core/math/geometry_2d.cpp#L198), it looks like the implementation relies on the [Clipper2 Lib](https://www.angusj.com/clipper2/Docs/Overview.htm) that states:

> Clipping closed paths:
>
> Clipping operations will always return [Positive](https://www.angusj.com/clipper2/Docs/Units/Clipper/Functions/IsPositive.htm) oriented solutions (unless the Clipper object's [ReverseSolution](https://www.angusj.com/clipper2/Docs/Units/Clipper.Engine/Classes/Clipper64/Properties/ReverseSolution.htm) property has been enabled). This means that outer polygon contours will wind anti-clockwise (in Cartesian coordinates), and inner hole contours will wind clockwise.

Hoping I got everything right, the indication of the methods listed below could be changed to this:

> The operation may result in an outer polygon (boundary) and inner polygon (hole) produced which could be distinguished by calling [is_polygon_clockwise](https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-is-polygon-clockwise) and checking if the result is true (the polygon is a boundary) or false (the polygon is a hole).

The proposed description already flips the results of `is_polygon_clockwise` to adapt the Clipper2 Cartesian coordinates in the expected "y+ is down" screen coordinates.

**URL to the documentation page (if already existing):**
https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-clip-polygons
https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-exclude-polygons
https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-intersect-polygons
https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-merge-polygons
https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-offset-polygon
https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-offset-polyline

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.