godotengine / godotengine/godot-docs
Methods in Gemetry2D don't explain how to use is_polygon_clockwise to tell boundaries from holes
- 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.