Skip to content

Static tools summary

Jump to bottom
SylvainBertrand edited this page Apr 30, 2020 · 3 revisions

The general convention for Euclid is that geometries such as Point3D and Capsule3D use redirection to static tools class and that the user should not have to use the most of the tools summarized in the following. But that's in perfect world where the API of each individual geometry provides every single method for every single use-case... That's definitely not the case at this moment as the API for each geometry is a continuous work-in-progress. So whenever a method is missing, feel free to take a look at these tools to find the feature you're looking for, and feel free to report the signature of the missing method you were looking for.

Very useful tools for testing

Random generators

Euclid*RandomTools: these classes implements numerous generators for creating randomized geometries. Particularly useful for unit testing. Complete list:

  • EuclidCoreRandomTools: for the types defined in the main project, such as Point3D, RotationMatrix, RigidBodyTransform.
  • EuclidGeometryRandomTools: for the types defined in the geometry project, such as Line2D, ConvexPolygon2D, Plane3D, BoundingBox3D.
  • EuclidShapeRandomTools: for the types defined in the shape project, such as Box3D, Torus3D, ConvexPolytope3D.
  • EuclidFrameRandomTools: for the types defined in the frame project, such as FramePoint3D, FrameQuaternion, FrameLine3D, FrameConvexPolygon3D.
  • EuclidFrameShapeRandomTools: for the types defined in the frame-shape project, such as FrameCapsule3D, FrameConvexPolytope3D, FrameEllipsoid3D.

Assertions

Euclid*TestTools: these classes implements numerous methods for perform assertions on geometries. Complete list:

  • EuclidCoreTestTools: for the types defined in the main project, such as Point3D, RotationMatrix, RigidBodyTransform.
  • EuclidGeometryTestTools: for the types defined in the geometry project, such as Line2D, ConvexPolygon2D, Plane3D, BoundingBox3D.
  • EuclidShapeTestTools: for the types defined in the shape project, such as Box3D, Torus3D, ConvexPolytope3D.
  • EuclidFrameTestTools: for the types defined in the frame project, such as FramePoint3D, FrameQuaternion, FrameLine3D, FrameConvexPolygon3D.
  • EuclidFrameShapeTestTools: for the types defined in the frame-shape project, such as FrameCapsule3D, FrameConvexPolytope3D, FrameEllipsoid3D.

Frame API tester

  • EuclidFrameAPITester implements a reflection based testing framework that can be used notably to ensure that a frame implementation of a geometry is consistent with the original frameless geometry.

General useful tools

Main project:

  • EuclidCoreTools provides very generic tools such as for computing the norm of a vector up to 4 dimensions, or defining singletons representing a zero point/vector.
  • TupleTools extended methods specific to tuples for getting the dot product, test if two tuples are equal, and testing if a tuple's components are all zero.

Geometry tools:

  • EuclidGeometryTools when missing a method from a geometry such as LineSegment3D or Plane3D, this is where to look first. This class implements all the underlying algorithms used in the geometry objects defined in the geometry project and much more. This class only rely on types from the main project such that its API is very flexible. The ideal extent that this tools class should cover has not been properly defined yet resulting in a class with massive amount of methods related to some extent to geometry. Suggestions about: API restriction or augmentation, location within Euclid, are very welcome.

Shape project:

  • EuclidShapeTools provides the underlying math and algorithms used in the shapes.
  • EuclidShapeCollisionTools host for the implementation of collision queries between two shapes. This class provides only analytical implementations, which is much faster than doing numerical detection. If you cannot find a method for a given combination of two shapes, e.g. two ellipsoids, this simply means that I have not been able to implement an analytical collision detection algorithm for it yet or that there is none. In which case, you want to either use GilbertJohnsonKeerthiCollisionDetector which fully handles non-penetrating shapes or indicate that they are penetrating, in which case the more expensive ExpandingPolytopeAlgorithm can be used to get further information.
  • EuclidPolytopeTools provides factories to create common types of convex polytopes, such as cube, pyramid, cone, icosahedron.
  • ConvexPolytope3DTroublesomeDataset can be of interest when using ConvexPolytope3D and discovering a new edge-case that is not handled properly. Static methods are provided there to create as a String the implementation of a class that allows to re-create the exact same polytope. This simplifies the creation of unit tests to highlight an issue with convex polytope or the collision algorithms: GilbertJohnsonKeerthiCollisionDetector and ExpandingPolytopeAlgorithm.

Frame project:

  • ReferenceFrameTools most notable tools are factories for creating new reference frames.
  • EuclidFrameTools provides every single method implemented in EuclidGeometryTools that relies on 2+ geometry arguments and redefines arguments and return type with their frame counterpart and performs additional reference frame checks on these arguments.

Frame shape project:

  • EuclidFrameShapeTools provides underlying implementations used in the frame shapes for evaluating the axis-aligned bounding box from the perspective of a frame that is not necessarily equal to the shape's frame.
  • EuclidFrameShapeCollisionTools extension of EuclidShapeCollisionTools to include the reference frame framework. When a combination of two frame shapes cannot be found, see FrameGilbertJohnsonKerrthiCollisionDetector or FrameExpandingPolytopeAlgorithm.

Factories

Factories classes provide a variety of implementations of different geometries. Principal features that these factories provide are:

  • the ability to create geometries that are linked to some data holder. This allows to wrap an object from a third party library and make it compatible with Euclid types and tools.
  • the ability to wrap geometries and assign listeners for observing read and write accesses.

These tools are currently (April 2020) under development and are susceptible to change rapidly in the near future. Complete list:

  • EuclidCoreFactories: for the types defined in the main project, such as Point3D, Vector3D.
  • EuclidFrameFactories: for the types defined in the frame project, such as FramePoint3D, FrameQuaternion.
  • EuclidGeometryFactories: destined for the types defined in the geometry project, now limited to BoundingBox2D nad BoundingBox3D.

Tools less likely to be needed

IO tools:

For now, as in April 2020, the IO tools are used to gather in a common place the methods to generating the String representation of any geometry. It is considered that some time in the future, these classes will host tools to also parse a geometry from a String, which may affect the general interest to use them directly. But now, they used to implement the Object.toString() method for each geometry. Complete list:

  • EuclidCoreIOTools: for the types defined in the main project, such as Point3D, RotationMatrix, RigidBodyTransform.
  • EuclidGeometryIOTools: for the types defined in the geometry project, such as Line2D, ConvexPolygon2D, Plane3D, BoundingBox3D.
  • EuclidShapeIOTools: for the types defined in the shape project, such as Box3D, Torus3D, ConvexPolytope3D.
  • EuclidFrameIOTools: for the types defined in the frame project, such as FramePoint3D, FrameQuaternion, FrameLine3D, FrameConvexPolygon3D.
  • EuclidFrameShapeIOTools: for the types defined in the frame-shape project, such as FrameCapsule3D, FrameConvexPolytope3D, FrameEllipsoid3D.

Specific to main project:

  • EuclidHashCodeTools centralizes tools calculating hash-code for each geometry when implementing Object.hashCode(). Main use-case for it would be for a custom implementation of a geometry.
  • Orientation conversion helpers:
    • AxisAngleConversion: converts any type of orientation to axis-angle.
    • QuaternionConversion: converts any type of orientation to quaternion.
    • RotationMatrixConversion: converts any type of orientation to 3-by-3 rotation matrix.
    • RotationVectorConversion: converts any type of orientation to rotation vector. A rotation vector differs from Euler angles. Its magnitude represents the angle of rotation and when normalized represents the axis of rotation.
    • YawPitchRollConversion: converts any type of orientation to yaw-pitch-roll. Yaw-pitch-roll is a set of Euler angles with the three rotation axes being in order: z, y, and x axes.
  • Algebra for the different orientation representations:
    • AxisAngleTools: algebra for axis-angle.
    • Matrix3DTools: algebra for generic 3-by-3 matrix.
    • QuaternionTools: algebra for quaternion.
    • RotationMatrixTools: algebra specific for 3-by-3 rotation matrix.
    • YawPitchRollTools: algebra for yaw-pitch-roll orientations.
  • Matrix3DFeatures: gathers tools for generic 3-by-3 matrix to test for various features, such as, getting the determinant, querying if a matrix is symmetric or skewed.

Specific to geometry project:

  • EuclidGeometryPolygonTools: declare the underlying algorithms used with ConvexPolygon2D such as the evaluation of the convex hull of a list of 2D points.

Specific to shape project:

  • EuclidEllipsoid3DTools provides implementation to compute closest point to a query with a 3D ellipsoid. This algorithm being surprisingly complicated, it deserved its own space.
  • EuclidPolytopeConstructionTools gathers the tools used in ConvexPolytope3D that focus around building a 3D convex polytope.
  • EuclidPolytopeTools gathers the tools used in ConvexPolytope3D.
  • IcoSphereFactory factory for building an icosphere, see https://en.wikipedia.org/wiki/Geodesic_polyhedron.
  • GJKTools collects specialized tools needed for GilbertJohnsonKeerthiCollisionDetector. I strongly recommend not using these tools for another context.
  • EPATools collects specialized tools needed for ExpandingPolytopeAlgorithm. I strongly recommend not using these tools for another context.
Clone this wiki locally