ccg-v3d

Description

A three-dimensional (3D) Euclidean geometry Java library. The library is modularised, based on openJDK 17, and has very few lightweight dependencies.

Point positions in space are defined using cartesian coordinates with orthogonal X, Y and Z axes that meet at the origin - a point <x,y,z> where x=y=z=0. Coordinates are either stored as BigRational numbers - a subset of rational numbers, or Math_BigRationalSqrt - that also support non-rational square roots. With these numbers, the precision of calculations is done to a user specified Order of Magnitude (OOM). Additionally, coordinates can also be stored in IEEE double precision and calculations are done as precisely as this allows often requiring an epsilon (a small value) to be specified to determine whether two vectors are the same or whether an intersection occurs.

The coordinate system is "right handed", so: if X increases to the right of this page; and, Y increases towards the top of this page, then Z increases out from the page, (see Orientation and the note on the choice of right over left handedness for details of why this handedness was chosen. This library is being developed to support large scale Earth Science applications, but may have other uses. Notes about the cartesian origin, and projections are also provided below.

Supporting both IEEE double precision floating point and more arbitrary precision numbers could be useful for exploring precision issues.

Latest versioned releases

<!-- https://mvnrepository.com/artifact/io.github.agdturner/ccg-v3d -->
<dependency>
    <groupId>io.github.agdturner</groupId>
    <artifactId>ccg-v3d</artifactId>
    <version>0.19</version>
</dependency>

JAR

<!-- https://mvnrepository.com/artifact/io.github.agdturner/ccg-v3d -->
<dependency>
    <groupId>io.github.agdturner</groupId>
    <artifactId>ccg-v3d</artifactId>
    <version>0.20-SNAPSHOT</version>
</dependency>

Sonatype SNAPSHOT Directory

Getting Started

Please fork the repository and create a clone. Using Maven is recommended (and your favourite Integrated Development Environment). The unit tests show how the library might be used for calculating things like the intersection of two geometries, or the minimum distance between two geometries. Another entry point is ccg-r3d - a rendering library for geometry visualisation.

Details

Lightweight Geometry

• These are in the uk.ac.leeds.ccg.v3d.geometry.light and uk.ac.leeds.ccg.v3d.geometry.d.light packages. These use V3D_V or V3D_VDouble as vectors which can be used to represent points.
• V3D_VLine and V3D_VLineDouble representing finite straight lines and comprise two vectors.
• V3D_VTriangle and V3D_VTriangleDouble represent triangles as three finite lines which are the edges of the triangle.
• V3D_VTetrahedron and V3D_VTetrahedronDouble represent tetrahedra which comprise 4 triangles.

  Heavyweight Geometry

• These are in the uk.ac.leeds.ccg.v3d.geometry and uk.ac.leeds.ccg.v3d.geometry.d packages.
• V3D_Vector and V3D_VectorDouble are used for vectors
• V3D_Point and V3D_PointDouble represent points. A vector called rel gives the location of the point relative to another vector called offset.
• V3D_Line and V3D_LineDouble represent infinite lines that pass through a point and along a vector.
• V3D_Ray and V3D_RayDouble represent rays that extends from a point in one direction given by a vector.
• V3D_Plane and V3D_PlaneDouble represent infinite plane geometry. The plane is defined by a point and a normal vector and can also be constructed using 3 points that are not collinear or coincident.
• V3D_Envelope and V3D_EnvelopeDouble represent Axis Aligned Bounding Boxes. The dimensions of these can collapse so the envelope can be considered more like a rectangle with all the x, or all the y, or all the z being the same; or a line segment with all the x and all the y being the same, or all the x and all the z being the same, or all the y and all the z being the same; or a point where all the x and all the y and all the z are the same. Envelopes are useful for ruling out intersections.
• V3D_LineSegment and V3D_LineSegmentDouble are for representing single continuous finite lines between two points.
• V3D_Triangle and V3D_TriangleDouble are for triangles. These are defined by a plane and three points.
• V3D_Tetrahedron and V3D_TetrahedronDouble represent tetrahedra.

Geometry collections

• There are rudimentary classes for: collections of collinear and coplanar points, and collinear line segments; Rectangle, coplanar convex hulls and polygon; coplanar and non-coplanar triangles; and tetrahedrons.

Development plans and progress

• Translating (moving) geometries to new locations is supported.
• Rotating geometries is supported.
• Scaling and warping geometries is not yet supported.
• Apache Commons Geometry (see also: Apache Commons Geometry GitHub Repository) appears to be developing some similar arbitrary precision geometrical functionality... Collaboration should be explored!
• Intersections -- It would be useful to be able to distinguish between geometries that touch at a point, along a line or line_segment or over an area; and those that overlap (all or part of) another geometry. -- Geometry intersections calculations for triangular or simpler geometries are supported. -- Implementations of methods to calculate the intersection between tetrahedrons and simpler geometries are wanted.
• Distances -- There are methods for calculating the minimum distance between geometries including triangles and simpler geometries. -- Implementations of methods to calulate distances between tetrahedrons and simpler geometries are wanted.
• New geometries are wanted for surfaces.
• Surface Areas, Perimeters and Volumes -- For some shapes there are implementations of methods for calculating these.

Origins

The library began development in March 2020. The original idea was to create a simple gravitational model of our solar system and learn more about 3D modelling and to also think about how to calculate the volumes of ice on Earth.

Summary of changes

0.16 to 0.20

Changed to use BigRational directly and Math_BigRational for aditional arithmetic.

0.15 to 0.16

• Major simplification of V3D_Envelope. V3D_Plane are now always stored as a point and a normal vector. Each traingle is associated with a plane.

  0.14 to 0.15

• Added more tests for intersections.

  0.13 to 0.14

• Added a package of lightweight geometries.
• Enabled some rotation using quaternions.

  0.10 to 0.13

• Added an offset vector for geometries to allow them to be translated.

  0.9 to 0.10

• Added V3D_Tetrahedron class, and V3D_TetrahedronPoly, V3D_TrianglePolyPlanar and V3D_LineSegmentPolyCollinear collection classes.

  0.8 to 0.9

• Change from left-handed to right handed coordinate system.

  0.7 to 0.8

• Simplifications to the intersection methods removing the static methods.
• Added a V3D_Ray class.

Contributions and supporting users

• Contributions are welcome.

LICENCE

• APACHE LICENSE, VERSION 2.0: https://www.apache.org/licenses/LICENSE-2.0

Acknowledgements and thanks

• The University of Leeds has supported the development of this library and some of the dependencies.
• Thank you to those that have and continue to develop the Java language.
• Thank you Eric (et al.) for the BigMath library.
• Thank you developers and maintainers of Apache Maven, Sonatype Nexus Repository Manager, Apache NetBeans, git and GitHub for supporting the development of this code and for providing a means of creating a community of users/developers.
• Thank you developers, maintainers and contributors of useful information content made available on the Web. Key information that has helped to develop this library is cited in the source code.

Notes

origin

For a solar system model or a model of Earth, it is probably best to set the origin at the centre of mass (CoM).

Handedness

Handedness or chirality concerns the assignment of coordinate axes/directions. The choice of left-handed or right-handed is somewhat arbitrary, but this library uses a right-handed system as is more commonly used in much of geography and physics (video). Originally the library began using a left-handed system based on the logic of vertical viewing screens, graphs and zooming in and out by the viewer moving closer and further away from the screen.

Projections

• Spherical and ecliptic coordinate systems and Discrete_global_grid systems are being used for some applications.
• Geographical projections are commonly used to represent part or all of the surface of Earth as plan view maps. Equirectangular_projections have: the Y Axis used for lines of latitude, with zero on the equator, increasing to the North pole, and decreasing to the South pole; the X Axis used for lines of longitude, typically with zero on the prime meridian, increasing to the East, and decreasing to the West; and the Z axis represents height (often a measure of a surface height like above or below mean sea-level. The choice of the meridian is arbitrary. For a 3D coordinate system with the origin at the centre of mass of Earth, the Y axis could be used for the axis of Earth's rotation) aligning with latitude...

References

Similar software for review

• VTK-m - README
  • Languages: C/C++.
  • Uses floating point for the coordinate system.
• VisIt
  • Open Source, interactive, scalable, visualization, animation and analysis tool.
  • Langauges: C 75.8%, C++ 12.8%, Python 3.8%, Java 3.0%
  • Github repository
• Fides
  • Fides enables complex scientific workflows to seamlessly integrate simulation and visualization. This is done by providing a data model in JSON that describes the mesh and fields in the data to be read. Using this data model, Fides maps ADIOS2 data arrays (from files or streams) to VTK-m datasets, enabling visualization of the data using shared- and distributed-memory parallel algorithms.
  • Can be used with Paraview
• ParaView
  • Open source post-processing visualization engine.
  • Uses VTK - an open-source, freely available software system for 3D computer graphics, modeling, image processing, volume rendering, scientific visualization, and 2D plotting