Home

Awesome

openupm Static Badge

ViRGiS Geometry Package

Open-Source (Boost-license) Unity library for 3D geometric computing.

This package is forked from Geometry3Sharp which was a package developed by GradientSpace. That package is now archived and will not be maintained.

This package has been extensively re-engineered for use with Unity as part of the ViRGiS Project

Version 4 - Breaking Changes

Version 4 of the package has been released. This has many improvements to the Unity Integration (see the CHANGELOG.md ).

This Version has the following BREAKING CHANGEs :

Vector3d v = new Vector3d(...) { axisOrder= AxisOrder.ENU }

Projects using ViRGiS Geometry

Credits

Many thanks to GradientSpace for creating this package.

Many, many data structures and algorithms have been ported from the WildMagic5 and GTEngine C++ libraries, which are developed by David Eberly at Geometric Tools. WildMagic5 and GTEngine are distributed under the Boost license as well, available here. Any errors in code marked as ported from WildMagic5/GTEngine are most certainly ours!

The MeshSignedDistanceGrid class was implemented based on the C++ SDFGen code written by Christopher Batty and Robert Bridson.

This package uses the Burst Triangulation Package for shape triangulation.

Installation

The Package can be installed from Open UPM. If you use this method, the dependencies will be automatically loaded provided the relevent scoped registry is included in your project's manifest.json :

scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": [
        "com.openupm",
        "com.virgis.geometry",
	"com.andywiecko"
      ]
    }
  ],

The Package can also be installed using the Unity Package Manager directly from the GitHub Repo.

Primitives

ViRGiS Geometry supports transparent conversion with Unity types.

[!NOTE] All VirgisGeometry primitives are available as double types. Using these types to hold and manipulate data and only converting to Unity Vectors and Meshes for the actual presentation retains the precision of the data!

ViRGiS Geometry has the following Primitive types mostly implemented as Structs:

The majority of these have implicit or explicit conversions to UnityEngine (e.g. Vector3 ) and Unity.Mathematics (e.g. float3 ) types as shown in the table below. The conversions are all implicit where the conversions can be done without precision loss (e.g. float to float) and explicit where there is precision loss (e.g. double to float).

[!NOTE] These conversions will not work for equations, so to add a Vector3f and a Vector3, you will need to explicitly cast one to the other.

<img width="857" alt="Screenshot 2024-06-24 at 11 01 14" src="https://github.com/ViRGIS-Team/ViRGiS-Geometry/assets/2239795/a961aa37-6fd7-4f6c-a26f-e18210dec5ce">

Axis Order

One of the biggest confusions when dealing with data in the Unity world is the axis order. Simply put, most data realms represent data as being "Z up" (i.e. Z is the vertical dimension) but Unity represents data using "Y up" (i.e. Y is the vertical dimension),

Trying to keep track of this in your code as you go from importing data to manipulating data to saving data will induce paranoia!

Therefore, we have introduced the concept of "Axis Order" into VirgisGeometry, using conventions from the Geo Data. This concept is implemented on:

Basically, each of the three axis is represented as being North, South, East, West, Up or Down. Note that the choice of horizontal axes (e.g. which is North and which is East) is to some extent arbitrary unless you are using AR, however historically there has been a preference for right handed coordinate systems. However, the choice of vertical axis is critical since we perceive that axis very different.

VirgisGeometry supports the following axis, the first two being the most common for data and the third represents the Unity Game Space axis order:

[!NOTE] The axis order is only used when casting Vectors and Meshes to Unity Vector3s and Meshes, at which point the order is checked and if neccesary changed to ensure that the result is corrrectly in EUN order. This does mean that - if you do not explicitly set the Vector3d axis order, the cast will assume that you want to rotate the data from a Z up Vector3d to a Y up Vector3. It you do not, then set the data as being in EUN coordinates already!

When casting FROM Unity to VirgisGeometry, the data is NOT changed but the axis order is set. This ensures round trip integrity but means that the resulting Vector3d (for instance) is in EUN. If you are exporting the data or manipulating it, you need to confirm that you are using the right axis order yourself.

For Vectors, the axis order can be checked and changed in one call, e.g. :

Vector3 v = ...;
v.ChangeAxisOrderTo(AxisOrder.ENU);

This is a NOP if the AxisOrder is correct and should be called before any AxisOrder critical operation on the Vector since you may not know the whole life history of the Vector.

For DMesh3 the axis order for all verteces can be changed with the Transform function - note that you need to give it the transformation matrix to make the change AND the target axis order.

Transforms

Unity Transforms can be represented and used with VirgisGeometry enitiies using transformation matricies. Doing the transform in VirgisGeometry has the advantage of preserving double precision.

Transformation matricies are represented in VirgisGeometry as Matrix4d and in Unity as Matrix4x4. There are instrinsic casts between these types (but keep in mind axis order).

You can use a Matrix4d directly on a vector using matrix multiplication or you can cast a matrix to a TransformSequence which allows you to add more transformations etc.

You can convert a Unity Transform to a transformation matrix using Transform.localToWorldMatrix and Transform.worldToLocalMatrix.

Mesh Entities

The main mesh entity in this package is the DMesh3 and this is the main attraction of this package. It is a very efficient and effective tool for managing and manipulating mesh entities.

There are explicit conversions between Unity Mesh and DMesh3. Note that there is an intrincsic loss of precision in going from DMesh3 to Unity Mesh so the round trip is not recommended.

The DMesh3 includes a simply routine to calculate the UVs for a mesh. This is intended for mesh that are largely planar (but does not care which reference frame they are planar in) and will return unexpected results if the mesh is not planar.

Geometry Entitiies

There are a multitude of Geometric entities in this package. A few which we find of particular value:

The Polygon can then be meshed using fast Delaunay algorithms - preserving the vertices, the boundaries and holes and the vertex order which makes it very easy to map the triangulation back into the original 3D vertices.

Tutorials

Several tutorials for using g3Sharp have been posted on the Gradientspace blog:

Main Classes

Core

Math

Approximation

Solvers

Color

Distance Queries

Intersection Queries

Containment

Meshes

Mesh Selections

Mesh Operations

Spatial Data Structures

2D Curves

2D Computational Geometry

3D Curves

3D Solids

I/O

Misc