refactor(great-circle): extract bisection constant and add inline comments

- Extract 50-iteration bisection count into ANTIMERIDIAN_BISECTION_ITERATIONS constant
- Add inline comments explaining each phase of the Arc() algorithm
- Clean up comments across src/ for clarity and consistency
- Add Thomas Hervey to contributors in package.json

Author: thomas-hervey

package.json

@@ -14,7 +14,8 @@
   ],
   "contributors": [
     "Dane Springmeyer <dane.springmeyer@gmail.com>",
-    "John Gravois <jagravois@gmail.com>"
+    "John Gravois <jagravois@gmail.com>",
+    "Thomas Hervey <thomasahervey@gmail.com>"
   ],
   "repository": {
     "type": "git",

src/arc.ts

@@ -4,9 +4,9 @@ import type { Position } from 'geojson';
 
 /**
  * Arc class representing the result of great circle calculations
- * 
+ *
  * @param properties - Optional properties object
- * 
+ *
  * @example
  * ```typescript
  * const arc = new Arc({ x: 45.123456789, y: 50.987654321 });
@@ -23,14 +23,14 @@ export class Arc {
 
     /**
      * Convert to GeoJSON Feature
-     * 
+     *
      * @returns GeoJSON Feature with LineString or MultiLineString geometry
-     * 
+     *
      * @example
      * ```typescript
      * const gc = new GreatCircle({x: -122, y: 48}, {x: -77, y: 39});
      * const arc = gc.Arc(3);
-     * console.log(arc.json()); 
+     * console.log(arc.json());
      * // { type: 'Feature', geometry: { type: 'LineString', coordinates: [[-122, 48], [-99.5, 43.5], [-77, 39]] }, properties: {} }
      * ```
      */
@@ -39,8 +39,7 @@ export class Arc {
         if (this.geometries.length === 0) {
             return {
                 type: 'Feature',
-                // NOTE: coordinates: null is non-standard GeoJSON (RFC 7946 specifies empty array [])
-                // but maintained for backward compatibility with original arc.js behavior
+                // NOTE: coordinates: null is non-standard GeoJSON (RFC 7946 specifies empty array []) but maintained for backward compatibility with original arc.js behavior.
                 geometry: { type: 'LineString', coordinates: null as any },
                 properties: this.properties
             };
@@ -78,9 +77,9 @@ export class Arc {
 
     /**
      * Convert to WKT (Well Known Text) format
-     * 
+     *
      * @returns WKT string representation
-     * 
+     *
      * @example
      * ```typescript
      * const arc = new Arc({ name: 'test-arc' });
@@ -93,7 +92,7 @@ export class Arc {
         }
 
         let wktParts: string[] = [];
-        
+
         for (const geometry of this.geometries) {
             if (!geometry || geometry.coords.length === 0) {
                 wktParts.push('LINESTRING EMPTY');

src/great-circle.ts

@@ -4,15 +4,20 @@ import { Arc } from './arc.js';
 import { _LineString } from './line-string.js';
 import { roundCoords, R2D } from './utils.js';
 
+// Number of bisection iterations used to locate the antimeridian crossing.
+// More iterations = higher precision but more interpolate() calls.
+// 50 iterations yields sub-degree precision, which is more than sufficient for most web mapping applications (i.e., not survey grade).
+const ANTIMERIDIAN_BISECTION_ITERATIONS = 50;
+
 
 /**
  * Great Circle calculation class
  * http://en.wikipedia.org/wiki/Great-circle_distance
- * 
+ *
  * @param start - Start point
  * @param end - End point
  * @param properties - Optional properties object
- * 
+ *
  * @example
  * ```typescript
  * const greatCircle = new GreatCircle({ x: 45.123456789, y: 50.987654321 }, { x: 46.123456789, y: 51.987654321 });
@@ -32,7 +37,7 @@ export class GreatCircle {
         if (!end || end.x === undefined || end.y === undefined) {
             throw new Error("GreatCircle constructor expects two args: start and end objects with x and y properties");
         }
-        
+
         this.start = new Coord(start.x, start.y);
         this.end = new Coord(end.x, end.y);
         this.properties = properties || {};
@@ -55,10 +60,10 @@ export class GreatCircle {
     /**
      * Interpolate along the great circle
      * http://williams.best.vwh.net/avform.htm#Intermediate
-     * 
+     *
      * @param f - Interpolation factor
      * @returns Interpolated point
-     * 
+     *
      * @example
      * ```typescript
      * const greatCircle = new GreatCircle({ x: 45.123456789, y: 50.987654321 }, { x: 46.123456789, y: 51.987654321 });
@@ -78,11 +83,11 @@ export class GreatCircle {
 
     /**
      * Generate points along the great circle
-     * 
+     *
      * @param npoints - Number of points to generate
      * @param options - Optional options object
      * @returns Arc object
-     * 
+     *
      * @example
      * ```typescript
      * const greatCircle = new GreatCircle({ x: 45.123456789, y: 50.987654321 }, { x: 46.123456789, y: 51.987654321 });
@@ -91,11 +96,7 @@ export class GreatCircle {
      */
     Arc(npoints: number = 100, _options?: ArcOptions): Arc {
         // NOTE: With npoints ≤ 2, no antimeridian splitting is performed.
-        // A 2-point antimeridian route returns a single LineString spanning ±180°.
-        // Renderers that support coordinate wrapping (e.g. MapLibre GL JS) handle this
-        // correctly, whereas splitting would produce two disconnected straight-line stubs
-        // with no great-circle curvature — arguably worse behavior. This is a known
-        // limitation; open for maintainer discussion if a MultiLineString split is preferred.
+        // A 2-point antimeridian route returns a single LineString spanning ±180°. Renderers that support coordinate wrapping (e.g. MapLibre GL JS) handle this correctly, whereas splitting would produce two disconnected straight-line stubs with no great-circle curvature — arguably worse behavior. This is a known limitation; open for maintainer discussion if a MultiLineString split is preferred.
         if (!npoints || npoints <= 2) {
             const arc = new Arc(this.properties);
             const line = new _LineString();
@@ -105,19 +106,16 @@ export class GreatCircle {
             return arc;
         }
 
-        // NOTE: options.offset was previously used as dfDateLineOffset in the GDAL-ported
-        // heuristic. It is kept in ArcOptions for backwards compatibility but is a no-op here.
+        // NOTE: options.offset was previously used as dfDateLineOffset in the GDAL-ported heuristic. It is kept in ArcOptions for backwards compatibility but is a no-op here.
 
+        // Sample npoints evenly spaced positions along the great circle arc.
         const delta = 1.0 / (npoints - 1);
         const first_pass: [number, number][] = [];
         for (let i = 0; i < npoints; ++i) {
             first_pass.push(this.interpolate(delta * i));
         }
 
-        // Analytical antimeridian splitting via bisection.
-        // For each consecutive pair of points where |Δlon| > 180 (opposite sides of ±180°),
-        // binary-search for the exact crossing fraction f* using interpolate(), then insert
-        // [±180, lat*] boundary points and start a new segment. 50 iterations → sub-nanodegree precision.
+        // Walk the sampled points, splitting into segments wherever the arc crosses the antimeridian.
         const segments: [number, number][][] = [];
         let current: [number, number][] = [];
 
@@ -131,21 +129,25 @@ export class GreatCircle {
 
             const prev = first_pass[i - 1]!;
 
+            // A longitude jump > 180° between adjacent samples indicates an antimeridian crossing.
             if (Math.abs(pt[0] - prev[0]) > 180) {
+                // Bisect to find the interpolation fraction f* at which the arc crosses ±180°.
                 let lo = delta * (i - 1);
                 let hi = delta * i;
 
-                for (let iter = 0; iter < 50; iter++) {
+                for (let iter = 0; iter < ANTIMERIDIAN_BISECTION_ITERATIONS; iter++) {
                     const mid = (lo + hi) / 2;
                     const [midLon] = this.interpolate(mid);
                     const [loLon] = this.interpolate(lo);
+                    // If mid and lo are on the same side of ±180°, the crossing is in [mid, hi].
                     if (Math.abs(midLon - loLon) < 180) {
                         lo = mid;
                     } else {
                         hi = mid;
                     }
                 }
 
+                // Compute the latitude at the crossing point and close/open segments at ±180°.
                 const [, crossingLat] = this.interpolate((lo + hi) / 2);
                 const fromEast = prev[0] > 0;
 
@@ -161,6 +163,7 @@ export class GreatCircle {
             segments.push(current);
         }
 
+        // Build one LineString per segment and collect them into an Arc.
         const arc = new Arc(this.properties);
         for (const seg of segments) {
             const line = new _LineString();

src/index.ts

@@ -5,4 +5,10 @@ export { GreatCircle } from './great-circle.js';
 export { roundCoords, D2R, R2D } from './utils.js';
 
 // Export types
-export type { CoordinatePoint, ArcOptions, GeoJSONFeature, LineString, MultiLineString } from './types.js';
+export type {
+  ArcOptions,
+  CoordinatePoint,
+  GeoJSONFeature,
+  LineString,
+  MultiLineString
+} from './types.js';

src/utils.ts

@@ -2,10 +2,10 @@ import type { Position } from './types.js';
 
 /**
  * Round coordinate decimal values to 6 places for precision
- * 
+ *
  * @param coords - A coordinate position (longitude, latitude, optional elevation)
  * @returns Rounded coordinate position
- * 
+ *
  * @example
  * ```typescript
  * const coords = [45.123456789, 50.987654321];
@@ -22,7 +22,7 @@ export function roundCoords(coords: Position): Position {
     for (let i = 0; i < coords.length; i++) {
         const coord = coords[i];
         if (coord !== undefined) {
-            // https://stackoverflow.com/questions/11832914/how-to-round-to-at-most-2-decimal-places-if-necessary
+            // NOTE: This logic follows https://stackoverflow.com/questions/11832914/how-to-round-to-at-most-2-decimal-places-if-necessary
             rounded[i] = Math.round(
                 (coord + Number.EPSILON) * MULTIPLIER
             ) / MULTIPLIER;