Skip to content
generated from agdturner/ccg-v2d

A modularised Java Euclidean (3D) geometry library.

License

Notifications You must be signed in to change notification settings

agdturner/ccg-v3d

Repository files navigation

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

Heavyweight Geometry

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

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

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

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

About

A modularised Java Euclidean (3D) geometry library.

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Languages