hypership / geo
Manage 3D coordinates to navigate in a galaxy
Requires (Dev)
- phpunit/phpunit: ~9.5
README
Introduction
This library provides features to represent and manipulate geographical objects in a 3D system.
It's initially built to represent several bodies in a galaxy.
It requires PHP 8.1 to use enumerations.
Classes to represent coordinates
These classes allow to represent a point in different 3D coordinates systems.
Each class allows converting to other coordinates systems.
Point3D
Represents a 3D point, identified by a (x, y, z) cartesian coordinates.
PointSpherical
Represents a 3D point, identified by a (r, θ, φ) spherical coordinates, as used in physics and following ISO 80000-2:2019 convention:
- r denotes the radial distance
- θ denotes the inclination
- φ denotes the azimuth
This class could be used to denote the elevation instead of inclination as θ, but if so, switch back to the inclination before converting to cylindrical or cartesian coordinates:
$point->theta += M_PI_2 $cylindricalPoint = $point->toCylindrical()
PointPolarZ
Represents a 3D point, identified by a (ρ, φ, z) cylindrical coordinates:
- (ρ, φ) denotes the polar coordinates like in 2D:
- ρ the radial distance
- φ the azimuth
- z the height or axial coordinate
This notation follows the ISO 31-11:1992 standard.
Alternatives to represent coordinates
Octocube
Maps 3D coordinates into a cube, divided in 8 sections.
Each section is called sector, numbered from 1 to 8:
_____ _______
/ 5 / 6 / |
/- - -/- - -/ |
/_____/____ / | |
| | | |/|
| 7 | 8 | / | 2
|_____|_____|/| |
| | | |/
| 3 | 4 | /
|_____|_____|/
The point (0, 0, 0) is at the cube center.
*Use the octocube to represent octants
As a 2D plane can be divided into quadrants, a 3D space can be divided in octants. See https://en.wikipedia.org/wiki/Octant_(solid_geometry).
To get the list of sign of an octant, instead of its number,
you can use the method getBaseVector
.
Gets a point furthermore far away from the centre
If you've a point P and wants to get another point, with the warranties it will go furthermore from the center and never reach another octant (ie the point will belong to the same octant), you can use:
$point = new Point3D(-7, 4, -5);
$sector = Octocube::getSectorFromPoint3D($point);
echo "Point belongs to sector C", $sector;
$vector = Octocube::getBaseVector($sector);
$point->translate(...$vector);
echo $point;
This code will output:
Point belongs to sector C1
xyz: [-8.00, 5.00, -6.00]
This technique has been tested with map builders, where you need to increase the content built indefinitely.
Helper classes
Math
Methods:
- equals(a, b, Ɛ): compare two floats
a
andb
, using|a - b| < Ɛ
formula. - normalizeAngle(a): normalize the angle
a
into a[0, 2π[
interval. - normalizeAngle(a, λ): normalize the angle
a
into a[λ, λ + 2π[
interval.
Constants:
- M_EPSILON: default value for Ɛ.
Pitfalls
Don't compare floats using == or === operator
When comparing two float numbers, our library takes care to use |a - b| < Ɛ
and provide a Math::equals
method for that.
In your own code, this is something you also need to do. For example, you want to avoid this kind of scenario:
$point = new PointSpherical(...); // Some transformations for $point if ($point->phi === 0.0) { // No inclination }
You can instead use if (Math::equals($point->phi, 0.0)) {}
.
Trigonometry and floats create big error margins
A situation where you need to be very careful is when a lot of trigonometry operations are involved. There is one place in our library that especially happens: PointSpherical::distance multiplies several times cosines and sinus by r.r'. The more far away your points is, the more you multiply roundings inserted both by float numbers and cos/sin functions.
An example of such code:
$point_a = new PointSpherical(116.645456, 2.131662, 1.893856); $point_b = new PointSpherical(113.703512, 2.165501, -0.726525); $distance = $point_a->distance($point_b);
This distance has a 10^-5 error margin.
If you need to compute distances, you'll get the better accuracy using Point3D. The PointPolarZ distance method is also fairly precise.