PHPackages                             hypership/geo - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. hypership/geo

ActiveLibrary[Utility & Helpers](/categories/utility)

hypership/geo
=============

Manage 3D coordinates to navigate in a galaxy

0.1.0(4y ago)020BSD-2-ClausePHP

Since Jan 22Pushed 4y ago1 watchersCompare

[ Source](https://github.com/hypership/geo)[ Packagist](https://packagist.org/packages/hypership/geo)[ RSS](/packages/hypership-geo/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (1)Versions (2)Used By (0)

hypership/geo
=============

[](#hypershipgeo)

Introduction
------------

[](#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
--------------------------------

[](#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

[](#point3d)

Represents a 3D point, identified by a (x, y, z) cartesian coordinates.

### PointSpherical

[](#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

[](#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
-------------------------------------

[](#alternatives-to-represent-coordinates)

### Octocube

[](#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)](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
--------------

[](#helper-classes)

### Math

[](#math)

Methods:

- **equals(a, b, Ɛ)**: compare two floats `a` and `b`, 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
--------

[](#pitfalls)

### Don't compare floats using == or === operator

[](#dont-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

[](#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.

###  Health Score

20

—

LowBetter than 13% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

1623d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8fa275e3c93d0f423ef8b7c1a848e6e4ea325225ea268e5fcce744e8ce3dd43b?d=identicon)[dereckson](/maintainers/dereckson)

---

Top Contributors

[![dereckson](https://avatars.githubusercontent.com/u/135563?v=4)](https://github.com/dereckson "dereckson (3 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/hypership-geo/health.svg)

```
[![Health](https://phpackages.com/badges/hypership-geo/health.svg)](https://phpackages.com/packages/hypership-geo)
```

###  Alternatives

[rossriley/phrocco

Literate documentation for PHP

963.0k](/packages/rossriley-phrocco)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)