From a8976cb1c7d15c730b4bef993316f595fbb189af Mon Sep 17 00:00:00 2001 From: VeriTas-arch <145042207+VeriTas-arch@users.noreply.github.com> Date: Thu, 7 Nov 2024 13:59:38 +0800 Subject: [PATCH 1/4] Add a note on the convex poly constraints. --- pymunk/shapes.py | 63 ++++++++++++++++++++++++------------------------ 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/pymunk/shapes.py b/pymunk/shapes.py index 71719f1d..d22ae354 100644 --- a/pymunk/shapes.py +++ b/pymunk/shapes.py @@ -24,11 +24,11 @@ class Shape(PickleMixin, TypingAttrMixing, object): """Base class for all the shapes. - You usually dont want to create instances of this class directly but use + You usually don't want to create instances of this class directly but use one of the specialized shapes instead (:py:class:`Circle`, :py:class:`Poly` or :py:class:`Segment`). - All the shapes can be copied and pickled. If you copy/pickle a shape the + All the shapes can be copied and pickled. If you copy/pickle a shape, the body (if any) will also be copied. """ @@ -79,7 +79,7 @@ def shapefree(cp_shape: ffi.CData) -> None: @property def _id(self) -> int: - """Unique id of the Shape + """Unique id of the Shape. .. note:: Experimental API. Likely to change in future major, minor orpoint @@ -102,8 +102,8 @@ def _set_mass(self, mass: float) -> None: _set_mass, doc="""The mass of this shape. - This is useful when you let Pymunk calculate the total mass and inertia - of a body from the shapes attached to it. (Instead of setting the body + This is useful when you let Pymunk calculate the total mass and inertia + of a body from the shapes attached to it. (Instead of setting the body mass and inertia directly) """, ) @@ -118,9 +118,9 @@ def _set_density(self, density: float) -> None: _get_density, _set_density, doc="""The density of this shape. - - This is useful when you let Pymunk calculate the total mass and inertia - of a body from the shapes attached to it. (Instead of setting the body + + This is useful when you let Pymunk calculate the total mass and inertia + of a body from the shapes attached to it. (Instead of setting the body mass and inertia directly) """, ) @@ -168,7 +168,7 @@ def _set_collision_type(self, t: int) -> None: _set_collision_type, doc="""User defined collision type for the shape. - See :py:meth:`Space.add_collision_handler` function for more + See :py:meth:`Space.add_collision_handler` function for more information on when to use this property. """, ) @@ -295,7 +295,7 @@ def update(self, transform: Transform) -> BB: return BB(_bb.l, _bb.b, _bb.r, _bb.t) def cache_bb(self) -> BB: - """Update and returns the bounding box of this shape""" + """Update and returns the bounding box of this shape.""" _bb = cp.cpShapeCacheBB(self._shape) return BB(_bb.l, _bb.b, _bb.r, _bb.t) @@ -391,7 +391,7 @@ def _hashid(self, v: int) -> None: cp.cpShapeSetHashID(self._shape, v) def __getstate__(self) -> _State: - """Return the state of this object + """Return the state of this object. This method allows the usage of the :mod:`copy` and :mod:`pickle` modules with this class. @@ -407,9 +407,9 @@ def __getstate__(self) -> _State: class Circle(Shape): - """A circle shape defined by a radius + """A circle shape defined by a radius. - This is the fastest and simplest collision shape + This is the fastest and simplest collision shape. """ _pickle_attrs_init = Shape._pickle_attrs_init + ["radius", "offset"] @@ -445,7 +445,7 @@ def unsafe_set_radius(self, r: float) -> None: @property def radius(self) -> float: - """The Radius of the circle""" + """The Radius of the circle.""" return cp.cpCircleShapeGetRadius(self._shape) def unsafe_set_offset(self, o: Tuple[float, float]) -> None: @@ -468,7 +468,7 @@ def offset(self) -> Vec2d: class Segment(Shape): - """A line segment shape between two points + """A line segment shape between two points. Meant mainly as a static shape. Can be beveled in order to give them a thickness. @@ -483,7 +483,7 @@ def __init__( b: Tuple[float, float], radius: float, ) -> None: - """Create a Segment + """Create a Segment. It is legal to send in None as body argument to indicate that this shape is not attached to a body. However, you must attach it to a body @@ -516,7 +516,7 @@ def _get_b(self) -> Vec2d: def unsafe_set_endpoints( self, a: Tuple[float, float], b: Tuple[float, float] ) -> None: - """Set the two endpoints for this segment + """Set the two endpoints for this segment. .. note:: This change is only picked up as a change to the position @@ -535,7 +535,7 @@ def normal(self) -> Vec2d: return Vec2d(v.x, v.y) def unsafe_set_radius(self, r: float) -> None: - """Set the radius of the segment + """Set the radius of the segment. .. note:: This change is only picked up as a change to the position @@ -547,7 +547,7 @@ def unsafe_set_radius(self, r: float) -> None: @property def radius(self) -> float: - """The radius/thickness of the segment""" + """The radius/thickness of the segment.""" return cp.cpSegmentShapeGetRadius(self._shape) def set_neighbors( @@ -578,14 +578,15 @@ def __init__( ) -> None: """Create a polygon. - A convex hull will be calculated from the vertexes automatically. + A convex hull will be calculated from the vertexes automatically. Note + that concave ones will be converted to a convex hull. - Adding a small radius will bevel the corners and can significantly + Add a small radius will bevel the corners and can significantly reduce problems where the poly gets stuck on seams in your geometry. It is legal to send in None as body argument to indicate that this shape is not attached to a body. However, you must attach it to a body - before adding the shape to a space or used for a space shape query. + before adding the shape to a space or using for a space shape query. .. note:: Make sure to put the vertices around (0,0) or the shape might @@ -615,8 +616,8 @@ def __init__( :param Body body: The body to attach the poly to :param [(float,float)] vertices: Define a convex hull of the polygon - with a counterclockwise winding. - :param Transform transform: Transform will be applied to every vertex. + with a counterclockwise winding + :param Transform transform: Transform will be applied to every vertex :param float radius: Set the radius of the poly shape """ @@ -652,10 +653,10 @@ def radius(self) -> float: def create_box( body: Optional["Body"], size: Tuple[float, float] = (10, 10), radius: float = 0 ) -> "Poly": - """Convenience function to create a box given a width and height. + """Convenience function to create a box with given width and height. The boxes will always be centered at the center of gravity of the - body you are attaching them to. If you want to create an off-center + body you are attaching them to. If you want to create an off-center box, you will need to use the normal constructor Poly(...). Adding a small radius will bevel the corners and can significantly @@ -680,7 +681,7 @@ def create_box_bb(body: Optional["Body"], bb: BB, radius: float = 0) -> "Poly": """Convenience function to create a box shape from a :py:class:`BB`. The boxes will always be centered at the center of gravity of the - body you are attaching them to. If you want to create an off-center + body you are attaching them to. If you want to create an off-center box, you will need to use the normal constructor Poly(..). Adding a small radius will bevel the corners and can significantly @@ -700,7 +701,7 @@ def create_box_bb(body: Optional["Body"], bb: BB, radius: float = 0) -> "Poly": return self def get_vertices(self) -> List[Vec2d]: - """Get the vertices in local coordinates for the polygon + """Get the vertices in local coordinates for the polygon. If you need the vertices in world coordinates then the vertices can be transformed by adding the body position and each vertex rotated by the @@ -722,8 +723,8 @@ def get_vertices(self) -> List[Vec2d]: :rtype: [:py:class:`Vec2d`] """ verts = [] - l = cp.cpPolyShapeGetCount(self._shape) - for i in range(l): + lines = cp.cpPolyShapeGetCount(self._shape) + for i in range(lines): v = cp.cpPolyShapeGetVert(self._shape, i) verts.append(Vec2d(v.x, v.y)) return verts @@ -748,7 +749,7 @@ def unsafe_set_vertices( cp.cpPolyShapeSetVerts(self._shape, len(vertices), vertices, transform) def __getstate__(self) -> _State: - """Return the state of this object + """Return the state of this object. This method allows the usage of the :mod:`copy` and :mod:`pickle` modules with this class. From 436edadd569576424e4c97d33d7b20f5ef660db7 Mon Sep 17 00:00:00 2001 From: VeriTas-arch <145042207+VeriTas-arch@users.noreply.github.com> Date: Thu, 7 Nov 2024 14:02:13 +0800 Subject: [PATCH 2/4] minor change --- pymunk/shapes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pymunk/shapes.py b/pymunk/shapes.py index d22ae354..65eaf65a 100644 --- a/pymunk/shapes.py +++ b/pymunk/shapes.py @@ -564,7 +564,7 @@ def set_neighbors( class Poly(Shape): - """A convex polygon shape + """A convex polygon shape. Slowest, but most flexible collision shape. """ From c61b4c9fa319d2cea484a41362a300f16af256a6 Mon Sep 17 00:00:00 2001 From: Veritas <145042207+VeriTas-arch@users.noreply.github.com> Date: Sat, 9 Nov 2024 03:13:16 +0000 Subject: [PATCH 3/4] doc: add more description on convex ploy transformation. --- pymunk/shapes.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pymunk/shapes.py b/pymunk/shapes.py index 65eaf65a..b2c03f2c 100644 --- a/pymunk/shapes.py +++ b/pymunk/shapes.py @@ -579,7 +579,8 @@ def __init__( """Create a polygon. A convex hull will be calculated from the vertexes automatically. Note - that concave ones will be converted to a convex hull. + that concave ones will be converted to a convex hull using the Quickhull + algorithm. Add a small radius will bevel the corners and can significantly reduce problems where the poly gets stuck on seams in your geometry. From 4feef9529bbca230bb664e20d5317143e62e2e78 Mon Sep 17 00:00:00 2001 From: Veritas <145042207+VeriTas-arch@users.noreply.github.com> Date: Sat, 9 Nov 2024 12:20:20 +0000 Subject: [PATCH 4/4] review fix --- pymunk/shapes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pymunk/shapes.py b/pymunk/shapes.py index b2c03f2c..5d1162fc 100644 --- a/pymunk/shapes.py +++ b/pymunk/shapes.py @@ -582,7 +582,7 @@ def __init__( that concave ones will be converted to a convex hull using the Quickhull algorithm. - Add a small radius will bevel the corners and can significantly + Adding a small radius will bevel the corners and can significantly reduce problems where the poly gets stuck on seams in your geometry. It is legal to send in None as body argument to indicate that this