re-added getCenterOfBounds and documented a lot of changes especially…

… regarding the method names in the changelog

CHANGELOG.md

@@ -1,13 +1,58 @@
 # Breaking Changes in 3.0.0
 
--   All functions are pure now. No input data is mutated anymore.
+-   All functions are pure function now. No input data is mutated anymore. You give the same input, you get the same output. No side effects or whatsoever.
 -   Artificial limitation to 8 decimal places in decimal coordinates was removed
--   `sexagesimal2decimal` was renamed to `sexagesimalToDecimal`
--   `getCenter()` is not returning the distance in addition to the center anymore
--   `getBoundsOfDistance()` now returns the _exact_ points due to the removal of the artificial 8 decimal place limitation
+    <!-- -   `sexagesimal2decimal` was renamed to `sexagesimalToDecimal` -->
+-   `getBoundsOfDistance()` now returns the _exact_ coordinates due to the removal of the artificial 8 decimal place limitation
 -   `getCompassDirection()` does no longer return an object with an _exact_ and a _rough_ direction but only the exact direction as string
 -   3rd parameter to `getCompassDirection()` is no longer a string ("circle", "line") but a function to determine the bearing (you can pass `getRhumbLineBearing` or `getGreatCircleBearing`). The function receives the origin and the destination as 1st and 2nd parameter. If no 3rd parameter was given, `getRhumbLineBearing(origin, dest)` is used by default.
 -   There is now a new helper function `roughCompassDirection(exact)` if you _really_ only need a very rough (and potentially inaccurate) direction.
 -   `orderByDistance()` does no longer modify its input so does not add a `distance` and `key` property to the returned coordinates
 -   The result of `getSpeed()` is now always returned as meters per second. It can be converted using the new convenience function `convertSpeed(mps, targetUnit)`
--   The point (or distance) is no consistently the same parameter for each functions using either of them (it wasn't before, how confusing is that?)
+-   The point (or distance) is no consistently the first parameter for each functions using either of them (it wasn't before, how confusing is that?)
+-   `findNearest()` does not take `offset` and `limit` parameters. It's only a convenience method to get the single one nearest point from a set of coordinates. If you need more than one, have a look at the implementation and implement your own logic using `orderByDistance`
+-   Whereever distances are involved, they are returned as meters or meters per second. No more defaulting to kilometers or kilometers per hour.
+-   The method how sexagesimal is formatted differs a little bit. It may now potentially return ugly float point units like `52° 46' 21.0004"` in rare cases but it is also more accurate then it was before.
+
+## Method status in 3.0.0
+
+-   ❗ getKeys -> getCoordinateKeys
+-   ❗ validate -> isValidCoordinate
+-   ❗ getLat -> getLatitude (might be re-added for convenience)
+-   ❗ getLon -> getLongitude (might be re-added for convenience)
+-   ‼ latitude -> removed
+-   ‼ longitude -> removed
+-   ‼ getElev -> removed (might be re-added)
+-   ‼ elevation -> removed
+-   ‼ coords -> removed (might be re-added as getCoordinate or getNormalizedCoordinate)
+-   ‼ ll -> removed (bccause wtfsrsly?)
+-   ❗ getDistance -> getPreciseDistance
+-   ❗ getDistanceSimple -> getDistance
+-   ✅ getCenter
+-   ✅ getBounds
+-   ✅ getCenterOfBounds
+-   ✅ getBoundsOfDistance (missing tests)
+-   ❗ isPointInside -> isPointInPolygon
+-   ‼ preparePolygonForIsPointInsideOptimized -> still missing
+-   ‼ isPointInsideWithPreparedPolygon -> still missing
+-   ‼ isInside -> removed (too ambiguous)
+-   ❗ isPointInCircle -> isPointWithinRadius
+-   ‼ withinRadius -> removed
+-   ✅ getRhumbLineBearing
+-   ❗ getBearing -> getGreatCircleBearing
+-   ✅ getCompassDirection
+-   ‼ getDirection -> removed (might be added back)
+-   ✅ orderByDistance
+-   ✅ isPointInLine
+-   ❗ getDistanceFromLine -> untested
+-   ‼ isPointNearLine -> still missing
+-   ✅ getPathLength
+-   ✅ getSpeed
+-   ✅ computeDestinationPoint
+-   ‼ convertUnit -> still missing (will be remamed to convertDistance because too ambiguous)
+-   ❗ useDecimal -> toDecimal
+-   ❗ decimal2sexagesimal -> decimalToSexagesimal
+-   ❗ sexagesimal2decimal -> sexagesimalToDecimal
+-   ✅ isDecimal
+-   ✅ isSexagesimal
+-

src/getBounds.ts

@@ -10,11 +10,12 @@ const getBounds = (points: any[]) => {
     // TODO: Re-add support for elevation
     return points.reduce(
         (stats, point) => {
-            stats.maxLat = Math.max(getLatitude(point), stats.maxLat);
-            stats.minLat = Math.min(getLatitude(point), stats.minLat);
-            stats.maxLng = Math.max(getLongitude(point), stats.maxLng);
-            stats.minLng = Math.min(getLongitude(point), stats.minLng);
-            return stats;
+            return {
+                maxLat: Math.max(getLatitude(point), stats.maxLat),
+                minLat: Math.min(getLatitude(point), stats.minLat),
+                maxLng: Math.max(getLongitude(point), stats.maxLng),
+                minLng: Math.min(getLongitude(point), stats.minLng),
+            };
         },
         {
             maxLat: -Infinity,

src/getCenterOfBounds.test.js

@@ -0,0 +1,48 @@
+import getCenterOfBounds from './getCenterOfBounds';
+
+const polygon = [
+    { latitude: 51.513357512, longitude: 7.45574331 },
+    { latitude: 51.515400598, longitude: 7.45518541 },
+    { latitude: 51.516241842, longitude: 7.456494328 },
+    { latitude: 51.516722545, longitude: 7.459863183 },
+    { latitude: 51.517443592, longitude: 7.463232037 },
+    { lat: 51.5177507, lon: 7.464755532 },
+    { latitude: 51.517657233, longitude: 7.466622349 },
+    { latitude: 51.51722995, longitude: 7.468317505 },
+    { latitude: 51.516816015, longitude: 7.47011995 },
+    { latitude: 51.516308606, longitude: 7.471793648 },
+    { latitude: 51.515974782, longitude: 7.472437378 },
+    { latitude: 51.515413951, longitude: 7.472845074 },
+    { latitude: 51.514559338, longitude: 7.472909447 },
+    { latitude: 51.512195717, longitude: 7.472651955 },
+    { latitude: 51.511127373, longitude: 7.47140741 },
+    { latitude: 51.51029939, longitude: 7.469948288 },
+    { latitude: 51.509831973, longitude: 7.468446251 },
+    { latitude: 51.509978876, longitude: 7.462481019 },
+    [7.460678574, 51.510913701],
+    { latitude: 51.511594777, longitude: 7.459434029 },
+    { latitude: 51.512396029, longitude: 7.457695958 },
+    { latitude: 51.513317451, longitude: 7.45574331 },
+];
+
+const polygon2 = [
+    { latitude: 51.513357512, longitude: 7.45574331 },
+    { latitude: 51.515400598, longitude: 7.45518541 },
+    { latitude: 51.516241842, longitude: 7.456494328 },
+    { latitude: 51.516722545, longitude: 7.459863183 },
+    { latitude: 51.517443592, longitude: 7.463232037 },
+];
+
+describe('getCenterOfBounds', () => {
+    it('should get the center of bounds for a polygon 🤷', () => {
+        expect(getCenterOfBounds(polygon)).toEqual({
+            latitude: 51.513791,
+            longitude: 7.464047,
+        });
+
+        expect(getCenterOfBounds(polygon2)).toEqual({
+            latitude: 51.515401,
+            longitude: 7.459209,
+        });
+    });
+});

src/getCenterOfBounds.ts

@@ -0,0 +1,23 @@
+import getBounds from './getBounds';
+import { GeolibInputCoordinates } from './types';
+
+/*
+ * Calculates the center of the bounds of geo coordinates.
+ *
+ * On polygons like political borders (eg. states) this may gives a closer
+ * result to human expectation, than `getCenter`, because that function can be
+ * disturbed by uneven distribution of point in different sides. Imagine the
+ * US state Oklahoma: `getCenter` on that gives a southern point, because the
+ * southern border contains a lot more nodes, than the others.
+ */
+const getCenterOfBounds = (coords: GeolibInputCoordinates[]) => {
+    const bounds = getBounds(coords);
+    const latitude = bounds.minLat + (bounds.maxLat - bounds.minLat) / 2;
+    const longitude = bounds.minLng + (bounds.maxLng - bounds.minLng) / 2;
+    return {
+        latitude: parseFloat(latitude.toFixed(6)),
+        longitude: parseFloat(longitude.toFixed(6)),
+    };
+};
+
+export default getCenterOfBounds;