Shear Geometry

Description

NOTE: The Sandbox program HapticGeometryTest has several haptic "scenes" that do not render haptic objects correctly. These are to be fixed in a future merge request. The known problems are:

• in scenes 2 and 3, haptic extruded square and rectangle do not have sharp edges
• in scene 5, the shape of the extruded rectangular hole does not match the shape of the hole in the wall in front of it
• in scenes 6, 7, and 8, the extruded holes have been taken out of the solid objects, so they are just boxes
• in scene 9, the extruded parallelogram does not render the edges of the extrusion correctly, leading to surprising pop through

This merge request contains many changes and additions to BurtSharp.Geometry, but by reviewing it in a certain order it will make more sense and be more manageable, I think. I'll try to lay that out here.

The basis of things is---surprise---GeometryBase.cs. The code that is common to Geometry2D and Geometry3D is now contained in GeometryBase, with the main differences being in how you handle rotation and shear in 2D versus 3D. The main idea here is decomposing an arbitrary 2-by-2 or 3-by-3 matrix into the product of three matrices that represent scaling, shearing, and rotation respectively. This transform can take you from a unit square/cube to any parallelogram/parallelepiped, or from a unit circle/sphere to any ellipse/ellipsoid.

To see this transforming in action, look at GameHapticsTest.cs. I take a Parallelepiped object called _prism and initialize it to be a rectangular prism with some edge lengths, position, and an orientation that makes the edges skewed from the Cartesian frame. Then I call _prism.ApplyTransform(_transGameToRobot);, which should have the effect of scaling each world-frame axis differently as we would do for a Unity activity with a workspace calibration. This transformed prism is then passed as the geometry to a new HapticBox. The haptic box is sheared to have a parallelepiped shape, which would be consistent with the visuals in a game like laundry loader. The big picture is that this entire merge request is geared toward making this example work.

Along the way, I've tried to make other improvements to the geometry classes and their organization:

• The line extent helper class was moved to GeometryTypes.cs, which is easier for when it is used in other classes like Extrusion.
• The Line and Plane classes now derive from Geometry3D, since they are meant to work as lower-dimensional objects embedded in 3D space with 3D orientation, etc. In doing so, the constructors and some of the public properties of these two classes changed slightly, but overall they were greatly simplified. (You can see that from the number of lines removed vs added.)
• Quaternions are the best way to handle 3D orientation, so that has been incorporated into Geometry3D (see paragraph further down about the quaternion code.)
• A couple of classes were moved into their own files for organization purposes, namely, Circle.cs, Square.cs, and Cube.cs.
• The Rectangle and RectangularPrism now derive from Parallelogram and Parallelepiped, respectively, because the latter are the more general versions of those shapes.
• The Ellipse class was updated to handle shear in 2D. It's an unusual case because shearing of an ellipse results in a new ellipse with different scaling and orientation.
• The Extrusion class was also made to derive from Geometry3D so it can be transformed in the same way.
• A few sandbox programs and some of the unit tests in TestGeometry.cs needed to be updated in accordance with the changes to Line and Plane.
• The unit tests for geometry are incomplete, as you can see in TestGeometry.cs. Writing these is time-intensive, so while they are nice to have I have not yet had the time.

One completely independent chunk is Quaternion.cs and the associated unit test TestQuaternion.cs. This is my implementation that's designed to suit our needs in terms of speed and the interface. There's a lot of overlap in function names with the UnityEngine.Quaternion, which is pretty much unavoidable, but they do not share any code, so be careful not to confuse the two. In just a few short merge requests we will no longer have UnityEngine as a dependency for BurtSharp, so that is part of the reason for having our own version.

The situation in BurtSharp.Haptics is thankfully much more simple. HapticExtrusion required no changes. For the HapticBox I am attempting to render only one wall at a time, and to have the pop-through option still work. The major challenge is to connect the new concept of shearing the 3D parallelepiped shape to the placement and rendering of the haptic walls. This work is ongoing.

Lastly, I added one Util function in VectorExtensions to get an arbitrary vector that is perpendicular to a given vector. Note that the file TestVectorExtensions.cs has a new test block TestGetPerpendicular() that should be reviewed, as well as a large chunk of trivial white space changes.

What to focus on

• The basic math underlying the shape transforms looks correct.
• What unit tests (if any) might be necessary to feel more confident about the geometry?
• What sandbox tests (if any) might be necessary to feel more confident about the geometry?