agdt-java-vector3d v0.8.0

agdt-java-vector3d

Description

A modularised Java three-dimensional (3D) Euclidean geometry library. The dimensions are defined by orthogonal coordinate axes X, Y and Z that meet at the origin point <x,y,z> where the Cartesian coordinates x=y=z=0. Coordinates are currently stored as BigRational numbers. Conceptually, from the origin, the X Axis runs in a positive direction to the right, the Y Axis runs in a positive direction up, and the Z Axis runs in a positive direction in or forwards (in other words, it is "left-handed"). The choice of left-handed or right handed is arbitrary. The decision was based on screens and the idea of graphs and zooming in and out. You may be interested in the geograhical footnote.

Unit tests are being developed along with the functional methods. The current focus is to to develop instersection and distance calculation code for dealing with:

• Envelopes - rectangular cuboids with sides aligned with the coordinate axes
• Straight line segments
• Triangles
• Rectangles
• Rectangular cuboids
• Tetrahedron.

Latest versioned releases

Developed and tested on Java Development Kit, version 15. The latest version is on GitHub.

<!-- https://mvnrepository.com/artifact/io.github.agdturner/agdt-java-vector3d -->
<dependency>
    <groupId>io.github.agdturner</groupId>
    <artifactId>agdt-java-vector3D</artifactId>
    <version>0.8</version>
</dependency>

JAR

<!-- https://mvnrepository.com/artifact/io.github.agdturner/agdt-java-vector3d -->
<dependency>
    <groupId>io.github.agdturner</groupId>
    <artifactId>agdt-java-vector3D</artifactId>
    <version>0.9-SNAPSHOT</version>
</dependency>

Dependencies

• agdt-java-generic
• agdt-java-math
• BigMath
• Please see the POM for details.

Main geometry implementations so far...

V3D_Point

Instances are infinitely small. Each coordinate is stored as an immutable BigRational

V3D_Vector

This is similar to a point in that it involves storing 3 BigRational numbers, but instead of representing a location relative to the origin of the axes, they define a general change in the x, y, and z coordinates. A vector can be applied to any geometry which essentailly shifts it relative to the origin.

V3D_Envelope

In the general case, this is a rectangular cuboid with edges aligned with the axes. However, the dimensions can collapse, so that this is essentially just a rectangle, or a line segment or a point. Each finite geometry has an envelope that bounds it. Much geometrical calculation uses these.

V3D_Line

Instances are immutable straight lines that extend infinitely. They have two points and a vector (V3D_Vector). The vector gives the direction of the line and is calculated as the difference from one point to the other. There is some small redundancy as the line could be defined simply by two points, or by a single point and a vector. Additionally, V3D_Vector instances also store the square of the magnitude and also the magnitude (if this can be stored precisely as a rational number). Alternative implementations may calculate these attributes as needed, but this implementation calculates these attributes so they are conveniently available. So, a V3D_Line instance is perhaps considerably heavier than it needs to be.

V3D_Ray

Instances are immutable straight lines that extend infinitely from a point in one direction. Essentially, they are V3D_Line instances with the first of the two points that define the line being the start of the ray that extends infinitely in the direction beyond the second point.

V3D_LineSegment

Instances are immutable and finite. Essentially, they are V3D_Line instances with the two points that define the line being the ends of the segment. A line segment is not permitted to have zero length.

V3D_Plane

Instances are immutable Planes extending infintely. They have 3 points (p, q and r) that are not collinear and two vectors (pq that gives how p is mapped onto q, and qr that gives how q is mapped onto r). The perpendicular normal vector to the plane (n) is calculated and stored. The direction of this is given by the order of the points, so each plane effectively has a front and a back. The equality of planes depends on the direction of the perpendicular normal vector as well as whether the points of each plane are coplanar.

V3D_Triangle

Instances are immutable and finite triangles. Essentially they are V3D_Plane instances and the three points {p, q and r} are the corners of the triangle. An additional vector (rp that gives how r is mapped onto p) is stored for each triangle. Each side of the triangle is also stored as a line segment for convenience. So again, as with other geometry objects, there is some redundancy in what is stored, but these additional things are stored for convenience.

V3D_Rectangle

Instances are immutable and finite rectangles. Essentially they are V3D_Plane instances and the three points (p, q and r) are the first three corners of the rectangle working around clockwise from the front of the plane. The other corner point of the rectangle (s) is also stored as are additional vectors (rs that gives how r is mapped onto s, and sp that gives how s is mapped onto p). Additionally the edges of the rectangle are stored as line segments for convenience. So again, as with other geometry objects, there is some redundancy in what is stored, but these additional things are stored for convenience.

Development progress

Most of what is implemented so far is intersection and distance from a point functionality. Not all of this is yet implemented for all geometries. The implemented intersection test implementations involve no rounding. For distance calculations, the user is asked to supply an order of magnitude which is used to provide an answer rounded to or correct to this. The default rounding is to round half up.

The aim is to have intersection functionality for all geometries including a test of whether any two geometry instances intersect and a method to get the intersection. As the geometries become more complicated, this aim becomes harder. Additional intersection funtionality that might be considered is whether or not the geometries touch or whether they overlap oe cross through each other. Additionally robust distance methods are wanted to calculate the shortest distance between any two geometries accurate to a given order of magnitude.

Intersection

So far, methods for testing if there is an intersection and for retrieving the intersection are implemented for:

• point-plane, point-line, point-ray, point-line_segement, point-rectangle, point-triangle
• plane-plane, plane-line, plane-ray, plane-line_segment
• line-line, line-ray, line-line_segment
• ray-ray, ray-line_segment
• line_segment-line_segment See the respective classes in the geometry package. What is next to do:
• plane-triangle, plane-rectangle
• line_segment-triangle, line_segment-rectangle
• triangle-triangle, triangle-rectangle
• rectangle-rectangle It would also be good to distinguish between geometries touching and overlapping.

Distance, Areas, Perimeters, Volumes

Methods for calculating these currently require the user to specify an order of magnitude so that the result are provided accurate to that precision. So far, methods for calculating the minimum distance between geometries are implemented for:

• point-plane, point-line, point-ray, point-line_segment, point-rectangle, point-triangle
• plane-plane, plane-line, plane-ray, plane-line_segment
• line-line, line-ray, line-line_segment
• ray-ray, ray-line_segment See the respective classes in the geometry package. There is a related method in With a distance calculations it is What is next to do is:
• line_segment-line_segment It might also be good to calculate the centroids and average distances, and perhaps maximum distances.

Development plans

• Implement some basic volumes including rectangular cuboids and tetrahedron.

Development history

Origins

The library began development in March 2020 with a view to supporting the development of cartesian coordinate based 3D models of space, particularly solar systems and parts of them, not least being Earth.

Summary of main changes

0.7 to 0.8

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

Contributions

• Welcome, but to save time and energy, please liaise and we can try to organise.

LICENCE

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

Acknowledgements and thanks

• The University of Leeds and externally funded research grants have supported the development of this library or the dependencies.
• Thank you openJDK contributors and all involved in creating the platform.
• Thank you Eric (et al.) for the BigMath library.
• Thank you developers and maintainers of Apache Maven, Apache NetBeans, and git which I use for developing code.
• Thank you developers and maintainers of GitHub and Maven_Central 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 other useful open source Java libraries and relevent content on: -- Wikimedia projects, in particular the English language Wikipedia -- StackExchange, in particular StackOverflow and Math.StackExchange.
• Information that has helped me develop this library is cited in the source code.
• Thank you to those that supported me personally and all who have made a positive contribution to society. Let us try to look after each other, look after this world, make space for wildlife, develop know how, safeguard this and apply it to boldy go, explore, find and maybe help or make friends with others :)

Geographical footnote

Geographers commonly use projections to represent part or all of the surface of Earth as plan view maps. These often have: the Y Axis aligned with lines of longitude, with Zero on the equator, increasing to the North pole, and decreasing to the South pole; the X Axis aligned with lines of latitude with Zero on the prime meridian and increasing to the East and decreasing to the West. Yet there are many and varied so called map projections that are used and the X Axis and Y axis do not necessarily align with the directions North, South, East and West, but the X Axis coordinates are orthogonal to the Y axis coordinates and so these form a cartesian space. In some cases, the map projections are used to represent surface elevation data and what is most common with these is to measure the heights with the Z Axis coming up from the plan view (in a so called "right-handed" way). This fits with notions of heights, where increasing height is measured from a level increasing upwards.

Geographical projections typically use a model for representing Earth relative to some axis of Earth's rotation and some estimation of a line denoting the equator. The Earth is more eliptical than spherical in these alignments, yet both speherical and eliptical parameters for projections are common. Both have a notion of a centroid point deep in the Earth.

Geographically, everything is moving and changing. The rates of movement and change vary with scale. Geographers commonly explore patterns of change in different things in regions across ranges of spatial and temporal scales using data at specific spatial and temporal resolutions. The structure of Earth, whilst conceptually well defined, is continually changing as Earth moves relative to the Sun, the Moon and other astronomical objects which can have significant other affects on Earth. More of Earth's atmosphere, for example, stretches further out towards the Sun as it heats and expands in the day. The orbit of the Earth around the Sun is complicated and the distance from the Earth to the Sun varies through time. Orbital eccentricity affects Earth surface processes and probably causes changes deep within the Earth. Earth's solar system has helicoid like motion as it traverses the Milky Way. The varying position of Earth's solar system relative to the galactic plane is likely to affect Earth's magnetic field. Nearby astronomical objects affect pressure on Earth and may alter the geoid (sea levels) significantly. How good are our best estimates of sea levels and Earth's magnetic field in the next 50 to 100 years? Are current technology and models built based on floating point numbers providing sufficient accuracy? Ocean boundaries change, water density changes with pressure and temperature (and state). Ice supported on land melts and adds to the mass. Although the total amount of ice is small relative to the total volume of water in the oceans which again is small relative to the mass of Earth. Application of this code abounds in Earth Sciences which was one of the original motivations for developing it.

f you find it useful, think it may be useful, or want to help develop the library, then please let me know.