godotengine / godotengine/godot-docs

Class Geometry2D is completely misleading because it seems to use a different Y direction

Open
#8,477 0 comments 1 reaction 0 assignees View on GitHub
area:class reference bug
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

**Your Godot version:** 4.1.3

**Issue description:**
If I understand correctly, Godot uses:
- right-hand convention for 3D space axes (+X=right, +Y=up, +Z=back)
- left-hand convention for 3D mesh winding order (i.e. clockwise when looking towards the visible side)
- **opposite direction for 2D space and UV (+X=right, +Y=down)**

I thought this convention was consistent (mostly) everywhere.
So, in everything 2D, I'd expect +Y to be down, unless told otherwise. In fact `Vector2.DOWN` docs say:
> DOWN = Vector2(0, 1)
> Down unit vector. Y is down in 2D, so this vector points +Y.

However, `Geometry2D` seems to operate differently, ***with no indication whatsoever*** in the class documentation.
```gdscript
@tool
extends EditorScript
func _run():
# In +Y=DOWN|SOUTH, this is: north -> southeast -> southwest
var p: PackedVector2Array = [Vector2(0, -1), Vector2(1, 1), Vector2(-1, 1)]
# if +Y is down, this should be clockwise
print(Geometry2D.is_polygon_clockwise(p)) # expected true, but prints false
```
Either this is a serious bug in this method or class, or a completely misleading documentation.

Does `Geometry2D` exceptionally use +Y=up convention consistently?
If so, it should be indicated in the class description, and preferably every method too where it may cause confusion (e.g. every method mentioning CW or CCW order).
> NOTE: All methods in this class consider +Y to point UP instead of DOWN.

A similar clarification may also be appropriate on `Geometry3D` if it's a different convention (I didn't test anything there).

**URL to the documentation page:**
[Geometry2D](https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#geometry2d)
[Geometry2D.is_polygon_clockwise(PackedVector2Array)](https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-is-polygon-clockwise)

---

A separate issue in this class too.
Method [triangulate_delaunay](https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-triangulate-delaunay) doesn't say explicitly that the order of the triangle vertices in the output is unspecified (apparently, each triangle can be either clockwise or counterclockwise). It would be nice if this is said explicitly, since the other triangulate method says it's always CCW, one could assume it applies here too.
> [...] Output triangles are in no particular order (e.g. it may contain both clockwise and counter clockwise triangles). [...]

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.