fix: make it uniformly distributed; fix tests; add to README

Author: sagi

README.md

@@ -74,6 +74,24 @@ Where:
 - **`radius`** *required* The distance (meters) from `centerPoint`.
 - **`randomFn`** *optional* A random function. Output is >=0 and <=1. Allows usage of seeded random number generators (see [`seedrandom`](https://www.npmjs.com/package/seedrandom)) - more predictability when testing.
 
+### `randomLocation.randomAnnulusPoint(...)`
+
+Outputs a Point ( `{ latitude: ..., longitude: ... }`) of random coordinates in a region bounded by two concentric circles (annulus).
+
+Function definition:
+
+```js
+const randomCircumferencePoint= (centerPoint, radius, randomFn = Math.random) => { ... }
+```
+
+Where:
+
+- **`centerPoint`** *required* An object with a `latitude` and `longitude` fields.
+- **`innerRadius`** *required* The readius of the smaller circle.
+- **`outerRadius`** *required* The readius of the larger circle.
+- **`randomFn`** *optional* A random function. Output is >=0 and <=1. Allows usage of seeded random number generators (see [`seedrandom`](https://www.npmjs.com/package/seedrandom)) - more predictability when testing.
+
+
 
 ## Usage
 

src/index.js

@@ -70,23 +70,33 @@ const randomCirclePoint = (centerPoint, radius, randomFn = Math.random) => {
 };
 
 /**
+ * Returns a random point in a region bounded by two concentric circles (annulus).
+ *
+ * centerPoint - the center point of both circles.
+ * innerRadius - the radius of the smaller circle.
+ * outerRadius - the radius of the larger circle
+ * randomFn -  *optional* A random function. Output is >=0 and <=1. Allows
+ * usage of seeded random number generators - i.e. allows us to predict
+ * generated random coordiantes. default is Math.random()
  *
- * Given a center point C and a smaller radius and bigger radius, return a point that is
- *  between the two circles
  */
 const randomAnnulusPoint = (
   centerPoint,
   innerRadius,
   outerRadius,
   randomFn = Math.random
 ) => {
-  if (innerRadius > outerRadius) {
-    throw new Error('innerRadus should be smaller');
+  if (innerRadius >= outerRadius) {
+    throw new Error(
+      `innerRadius (${innerRadius}) should be smaller than outerRadius (${outerRadius})`
+    );
   }
 
+  const deltaRadius = outerRadius - innerRadius;
+
   return randomCircumferencePoint(
     centerPoint,
-    Math.floor(Math.random() * (outerRadius - innerRadius + 1) + innerRadius),
+    innerRadius + Math.sqrt(randomFn()) * deltaRadius,
     randomFn
   );
 };

src/index.test.js

@@ -109,45 +109,63 @@ describe('random-location', () => {
     });
   });
 
-  describe('random generation of points between circles', () => {
-    test('between circles given center point and inner and outer radius', () => {
+  describe('random generation of random annulus points', () => {
+    test('innerRadius is larger than outerRadius', () => {
       // Eiffel Tower
       const P1 = {
         latitude: 48.8583736,
         longitude: 2.2922926,
       };
-      const R = 1000; // meters
-      const R2 = 2000;
+      const innerRadius = 1000; // meters
+      const outerRadius = 123;
+      expect(() =>
+        randomLocation.randomAnnulusPoint(P1, innerRadius, outerRadius)
+      ).toThrow(
+        `innerRadius (${innerRadius}) should be smaller than outerRadius (${outerRadius})`
+      );
+    });
+
+    test('on an annulus of two concentric circles', () => {
+      // Eiffel Tower
+      const P1 = {
+        latitude: 48.8583736,
+        longitude: 2.2922926,
+      };
+      const innerRadius = 1000; // meters
+      const outerRadius = 2000;
 
       for (let i = 0; i < 100; i++) {
-        const randomPoint = randomLocation.randomAnnulusPoint(P1, R, R2);
+        const randomPoint = randomLocation.randomAnnulusPoint(
+          P1,
+          innerRadius,
+          outerRadius
+        );
         const distance = Math.floor(randomLocation.distance(P1, randomPoint));
-        expect(distance).toBeLessThanOrEqual(R2 + 1);
-        expect(distance).toBeGreaterThanOrEqual(R);
+        expect(distance).toBeLessThanOrEqual(outerRadius);
+        expect(distance).toBeGreaterThanOrEqual(innerRadius);
       }
     });
-
-    test('between inner and outer circle given seed random', () => {
+    test('on an annulus of two concentric circles; using seedrandom', () => {
       // Eiffel Tower
       const P1 = {
         latitude: 48.8583736,
         longitude: 2.2922926,
       };
-      const R = 1234; // meters
-      const R2 = 2300;
+      const innerRadius = 1000; // meters
+      const outerRadius = 2000;
       const seed = 'this is another seed';
+      const randomFn = seedrandom(seed);
 
       for (let i = 0; i < 100; i++) {
-        const randomFn = seedrandom(seed);
         const randomPoint = randomLocation.randomAnnulusPoint(
           P1,
-          R,
-          R2,
+          innerRadius,
+          outerRadius,
           randomFn
         );
         const distance = Math.floor(randomLocation.distance(P1, randomPoint));
-        expect(distance).toBeLessThanOrEqual(R2 + 1);
-        expect(distance).toBeGreaterThanOrEqual(R);
+        expect(distance).toBeLessThanOrEqual(outerRadius);
+        expect(distance).toBeGreaterThanOrEqual(innerRadius);
       }
     });
   });