Package org.horizon36596.simloop.field

Class ConvexShape

java.lang.Object
org.horizon36596.simloop.field.ConvexShape
public final class ConvexShape extends Object
A solid convex polyhedron a ball can rest on, roll along and bounce off: a convex hull given as its corner points and its triangles. A KinematicBody is made of these, in the body's own frame.

Frame and units. Whatever frame the owner uses - a KinematicBody's local frame, or the field frame for a body that never moves - in inches.

Contact is exact. contact(double, double, double, double, double[]) finds the point of the solid nearest a sphere's centre: on a face, an edge or a corner. A ball near an edge therefore touches the rounded edge of the hull grown by its radius, not a square corner. The one approximation is for a centre already inside the solid, which the physics avoids by never stepping a ball further than its own radius in one sub-step; then the ball is pushed out through the face it is least deep behind.

Season-agnostic (domain R7): a shape knows nothing about what it is part of. Immutable.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ConvexShape(String name, double[][] vertices, int[][] triangles)
    Creates a hull and checks that every face points out and the solid is convex.

  • Method Summary

    Modifier and Type
    Method
    Description
    static ConvexShape
    box(String name, double minX, double maxX, double minY, double maxY, double minZ, double maxZ)
    An axis-aligned box as a convex shape - for tests and for any season whose structure is boxes.
    boolean
    contact(double px, double py, double pz, double radius, double[] out)
    Whether a sphere touches this solid, and if so how to push it out.
    double[]
    getBoundingCentre()
    Returns the centre of that bounding sphere, {x, y, z} inches.
    double
    getBoundingRadiusInches()
    Returns the radius, inches, of a sphere about the corners' mean that holds the whole solid.
    String
    getName()
    Returns the label given at construction.
    double[]
    getVertex(int index)
    Returns corner index, {x, y, z} inches, a copy.
    int
    getVertexCount()
    Returns how many corners the hull has.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • ConvexShape

      public ConvexShape(String name, double[][] vertices, int[][] triangles)
      Creates a hull and checks that every face points out and the solid is convex.
      Parameters:
      name - a label for logs and test messages, e.g. "cell_north_floor"
      vertices - the hull's corner points, {x, y, z} inches; at least four
      triangles - the hull's faces as indices into vertices, wound counter-clockwise seen from outside so every normal points out; at least four
      Throws:
      IllegalArgumentException - if a number is not finite, an index is out of range, a triangle is degenerate, a face points inward or the solid is not convex

  • Method Details

    • getName

      public String getName()
      Returns the label given at construction.
      Returns:
      the label given at construction

    • getVertexCount

      public int getVertexCount()
      Returns how many corners the hull has.
      Returns:
      how many corners the hull has

    • getVertex

      public double[] getVertex(int index)
      Returns corner index, {x, y, z} inches, a copy.
      Parameters:
      index - which corner, 0 to getVertexCount() minus 1
      Returns:
      corner index, {x, y, z} inches, a copy

    • getBoundingRadiusInches

      public double getBoundingRadiusInches()
      Returns the radius, inches, of a sphere about the corners' mean that holds the whole solid.
      Returns:
      the radius, inches, of a sphere about the corners' mean that holds the whole solid

    • getBoundingCentre

      public double[] getBoundingCentre()
      Returns the centre of that bounding sphere, {x, y, z} inches.
      Returns:
      the centre of that bounding sphere, {x, y, z} inches

    • contact

      public boolean contact(double px, double py, double pz, double radius, double[] out)
      Whether a sphere touches this solid, and if so how to push it out.
      Parameters:
      px - the sphere's centre, inches, in this shape's frame
      py - ditto
      pz - ditto
      radius - the sphere's radius, inches
      out - on contact, filled with {normal x, normal y, normal z, depth}: the unit normal points from the solid toward the sphere's centre, and depth is how far the sphere must move along it to just touch, inches
      Returns:
      true when the sphere overlaps the solid

    • box

      public static ConvexShape box(String name, double minX, double maxX, double minY, double maxY, double minZ, double maxZ)
      An axis-aligned box as a convex shape - for tests and for any season whose structure is boxes.
      Parameters:
      name - a label
      minX - the box's extent, inches, in the owner's frame; each min below its max
      maxX - ditto
      minY - ditto
      maxY - ditto
      minZ - ditto
      maxZ - ditto
      Returns:
      the box