Class myphysicslab.lab.engine2D.Polygon

Provided By
All Implemented Interfaces

A RigidBody made of connected Edges and Vertexes.

See 2D Physics Engine Overview about the rigid body physics engine.

Body Coordinates

For explanation of body vs. world coordinates see Body Coordinates, myphysicslab.lab.model.MassObject and myphysicslab.lab.model.CoordType.

Methods that return a location often have names ending with either 'body' or 'world' to indicate the coordinate system. Similarly, parameters of methods often end with 'body' or 'world'.

Structure of a Polygon

A Polygon consists of a set of connected Edges, which together form one or more paths. A Polygon can have more than one path, for example a donut shape would have 2 paths: one for the outer Edge and one for the inner Edge.

A path in a Polygon consists of a linked list of Edges and Vertexes:

An Edge has a starting and ending Vertex, and a Vertex has a previous and next Edge. So we can follow a path from the starting Vertex until returning again to the starting Vertex when the path is then closed.

The list of paths is simply a list of starting Vertexes. Each path wraps around to its starting Vertex to form a closed loop. A path must have at least one Vertex and one Edge.

A path is used when drawing the Polygon. For collision handling, the collection of Edges and Vertexes are what matters, how they are linked into a path is irrelevant.

The Edges in a Polygon are stored in an array, and Edges can be referred to by their index in this array, see #getEdges and myphysicslab.lab.engine2D.Edge#getIndex.

The list of Vertexes may include automatically generated 'mid-point Vertexes' for curved Edges. These Vertexes are added to give better collision detection for curved Edges. See myphysicslab.lab.engine2D.Vertex about end-point vs. mid-point Vertexes.

Creating a Polygon

  • First create a Polygon with the constructor; it has no Vertexes or Edges.

  • Call #startPath to begin making a path. You can start with a single Vertex or an Edge.

  • Use #addEdge as many times as desired to add Edges. Or use the shortcut methods #addStraightEdge, #addCircularEdge or #addCircularEdge2.

  • (optional) Use #closePath if you want to add another path with startPath.

  • Call #finish which will close the current path and calculate the centroid for the Polygon.

Note that just creating an Edge can add it to the existing linked list of Vertexes and Edges being formed in the currently open path. The #addEdge method completes the process of adding the Edge to the Polygon.

For examples of creating a Polygon see myphysicslab.lab.engine2D.Shapes.

Centroids & Proximity Testing

We need a quick way to know if objects are close enough to warrant the more expensive tests that are done to find collisions and contacts. To this end, we find the smallest circle that encloses the object. The center of this circle is the 'centroid' or geometric center of the object. The radius is the "centroid radius".

There is a similar centroid and centroid radius for each Edge, which gives the smallest circle that encloses that Edge. We use a cache to keep the world coordinates of the centroid of each Edge, to avoid the cost of repeatedly calling the bodyToWorld method. See #getEdgeCentroidWorld.

Some of the proximity tests can be found in myphysicslab.lab.engine2D.UtilityCollision#checkVertexes. Of note is that we expand the centroid radius by the distance that the Vertex has travelled during the current time step. And that we use the distance squared in these tests, to avoid the computational cost of the square root function.

Special Edge for Proximity Testing

Walls are a special case for proximity testing. Because they are typically long and thin, their proximity circle is huge compared to the wall object; and so the proximity test fires many false positives.

To remedy this, we allow specifying a 'special edge' via #setSpecialEdge which changes how the proximity testing is done for this object.

When there is a special edge (there can only be one per object), then the proximity test still looks at the distance between the centroid of each object, but now only the portion of that distance that is normal to the special edge. Also, a special centroid radius is defined for the object that is used in this proximity test. For a wall, this special centroid radius is half of the (short) width of the wall object.

Only the special edge is tested for collisions, so care should be taken to avoid objects being able to collide into any of the non-special edge walls.

Old Copy Is Used For Collision Detection

A Polygon keeps a copy of its previous state before the last time step of the differential equation solver. The copy is used for collision detection, to determine how a collision may have happened; for example whether a Vertex crossed over an Edge during the last time step. The copy is not a fully functional Polygon, it is only useful for the purposes of looking at the previous location and orientation of the body. See #saveOldCopy, #getOldCopy, and #eraseOldCopy.

Minimum Height

The minimum height of a Polygon is used for potential energy calculations, see myphysicslab.lab.engine2D.Polygon#getMinHeight.

The minimum height can be explicitly set for each Polygon, see #setMinHeight. If it is not set, the method #getMinHeight will try to determine the minumum height by calculating the smallest distance between the center of mass and the body's Edges.

Some cautions about getMinHeight:

  • The getMinHeight calculation can fail for more complicated shapes or when the center of mass is outside of the body.

  • The getMinHeight calculation will be incorrect for a circle or oval when the center of mass is not on one of the axes of the circle/ellipse.

  • The minimum height is cached, and should be recalculated if the center of mass changes. To do so, call setMinHeight(NaN) and the next time getMinHeight is called it will recalculate.

new Polygon( opt_name, opt_localName )


name of this Polygon for scripting (language independent)


localized name of this Polygon, for display to user

Instance Methods

Instance Properties

Static Properties

Type Definitions