I've done a much larger review and testing. Comparing it to different vector implementations, and looking at how it inter-operates with pygame and OpenGL APIs.
TLDR; these things need to be fixed: - scalar construction is buggy. - One naming improvement I'd like help with is .elementwise() ? I think it's too long. - float('NaN') and float('inf') behaviour is not tested. - Construction from Color, and Rect needs to be defined. There's other useful functionality that could be added later I think. I'll finish off the narrative documentation and example program, and then await feedback before the Experimental notice is lifted. This process has already uncovered a bunch of things that are missing, so I expect more to pop up. IMHO, it's already one of the best vector2/vector3 implementations in python. And I like that people will be able to use their knowledge of this API with GLSL (a bit). *A) GLSL shadling language vectors* https://en.wikibooks.org/wiki/GLSL_Programming/Vector_and_Matrix_Operations#Components https://www.khronos.org/registry/OpenGL/specs/gl/GLSLangSpec.4.60.pdf Here's what I've found missing/different. 1) Single scalar constructor should Vector2(1) == Vector2(1, 1) # currently it makes Vector2(1, 0) 2) Lower dimensional to higher dimension contructors should work: Vector3(1, Vector2(2, 3)) == Vector3(1, 2, 3) 3) the GLSL documentation uses "component wise", whereas we use elementwise() Additionally, I think elementwise() is quite long, and should probably be a property. A shorter name here would be nice. 4) Missing functions: abs abs(Vector2(2,-1).elementwise()) works. sign floor trunc round roundEven ceil fract mod modf min max clamp mix step smoothstep faceForward are missing ... more Section 8.3, Common Functions https://www.khronos.org/registry/OpenGL/specs/gl/GLSLangSpec.4.30.pdf The functions operate component wise. Vector2(1, 3).min(Vector2(4, -2)) == Vector2(1, -2) We have min() and max() in python, but unfortunately they use some weird magic, and not a dunder magic method. "Classes that act like numbers" http://www.diveintopython3.net/special-method-names.html#acts-like-number __floor__ __ceil__ __trunc__ 5) swizzling only there with xyzw Seems like rgba, and stpq should be available. {x, y, z, w} Useful when accessing vectors that represent points or normals {r, g, b, a} Useful when accessing vectors that represent colors {s, t, p, q} Useful when accessing vectors that represent texture coordinates Perhaps vec3.rgb would return a pygame.Color *B) Compared to the CookBook 2d vector class...* https://www.pygame.org/wiki/2DVectorClass missing: get_angle() perpendicular http://mathworld.wolfram.com/PerpendicularVector.html perpendicular_normal projection (not in here, but the inverse is the rejection) https://en.wikipedia.org/wiki/Vector_projection *C) Compred to box2d vec2* https://github.com/pybox2d/pypybox2d/blob/master/pypybox2d/src/vec2module.c missing: contains() isn't there, but you can do: 2 in v2 clamp min max *D) pyeuclid* rotate_around(axis, theta) https://github.com/ezag/pyeuclid/blob/master/euclid.py#L565 copy() Rect, and Surface have this in pygame too Vector2(Vector2(1,2)) work however. *E) planar* https://pythonhosted.org/planar/vectorref.html almost_equals https://pythonhosted.org/planar/vectorref.html#planar.Vec2.almost_equals Should be called isclose like python3.5+ math.isclose https://docs.python.org/3/library/math.html#math.isclose scaled_to https://pythonhosted.org/planar/vectorref.html#planar.Vec2.scaled_to perpendicular clamped *Extras* Additional functionality not done is the buffer stuff. Which is commented out in math.c I guess the purpose is to allow a Vector2/3 to act with it's storage coming in an array. This would be super useful if you allocated a big array and wanted to act on one element easily. Again, I think this could come later without harming backwards compatibility. There is partial support in the code for a Vector4. There's nothing done for 2x2, 3x3 or 4x4 matrix. Which are all quite useful in games (and in GLSL). These can all come later without harming backwards compatibility. *Existing pygame APIs.* There are some differences between Vector3 and Rect and Color types. Vectors allow some niceties which people might come to expect from Rect and Color. v2[:] = (3,4) v2.xy = (3,4) Vector3(0) -> Vector3(0, 0, 0) Also, Rect has methods like copy() which are missing in Vector3. Passing a color into pygame gives a very strange result. >>> Vector2(pygame.Color(2,3,4, 111)) <Vector2(3.37522e+07, 0)> I think Vector3(Color('red')) should work to give you Vector(1, 0, 0). And Vector3(Color(255, 255, 255)) should give you Vector3(1, 1, 1). Or maybe not. Maybe it should raise an error because Color is 4 elements. Vector3().rgb = Color(255, 255, 255) makes a lot more sense to be Vector3(1, 1, 1). Should a rect be able to to be used to construct a Vector2? Especially when people have been using rects for the position of things. >>> Vector2(pygame.Rect(2,3,4,111)) ValueError: Vector2 must be initialized with 2 real numbers or a sequence of 2 real numbers It should use the x, and y parts of a rect. IMHO. >>> Vector2(pygame.Rect(2,3,4,111)) Vector2(2, 3) *OpenGL API interactions.* Converting in another direction would be useful. Where OpenGL has y at the bottom left. Getting OpenGL compat coords would be nice. Requires knowledge of screen height/axis dimensions. *pymunk intergration.* pymunk already has some pygame utils which do swapping of Y coordinates. Would be good to consider that. On Tue, Feb 27, 2018 at 11:43 AM, René Dudfield <ren...@gmail.com> wrote: > I won't move pygame.math.Vector2/3 into pygame or pygame.locals namespace > for now. > That's potentially breaking things which already have their own Vector2/3. > This type of API change will wait for pygame 2. > > Narrative documentation is missing, and I'm working on that now. >