readme touchups

Author: springmeyer

README.md

@@ -1,189 +1,163 @@
 # arc.js
-> Calculate great circle routes as lines in GeoJSON or WKT format.
 
-[**Try the interactive demo**](https://danespringmeyer.com/arc.js/) - Click to plot great circle arcs on a map!
+Calculate great circle routes as lines in GeoJSON or WKT format.
 
-Algorithms from [Ed Williams' Aviation Formulary](https://edwilliams.org/avform.htm#Intermediate)
+[**🌍 Try the interactive demo**](https://danespringmeyer.com/arc.js/) - Click to plot great circle arcs on a map!
 
-Includes basic support for splitting lines that cross the dateline, based on
-a partial port of code from GDAL's OGR library.
+**Features:**
+- Full TypeScript support with type definitions
+- Works in Node.js (CommonJS & ES modules) and browsers
+- Generates GeoJSON and WKT output formats
+- Handles dateline crossing automatically
+- Based on [Ed Williams' Aviation Formulary](https://edwilliams.org/avform.htm#Intermediate) algorithms and the GDAL source code
 
-## Install
+## Installation
 
 ```bash
-$ npm install --save arc
+npm install arc
 ```
 
-## Usage
+## Quick Start
 
-### Node.js (CommonJS)
-For Node.js projects using CommonJS modules:
+### CommonJS (Node.js)
 ```js
-var arc = require('arc');
-var gc = new arc.GreatCircle({x: -122, y: 48}, {x: -77, y: 39});
+const arc = require('arc');
+const gc = new arc.GreatCircle({x: -122, y: 48}, {x: -77, y: 39});
+const line = gc.Arc(100);
+console.log(line.json()); // GeoJSON output
 ```
 
-### Node.js (ES Modules)
-For Node.js projects using ES modules:
+### ES Modules (Node.js, bundlers)
 ```js
-import * as arc from 'arc';
-const gc = new arc.GreatCircle({x: -122, y: 48}, {x: -77, y: 39});
+import { GreatCircle } from 'arc';
+const gc = new GreatCircle({x: -122, y: 48}, {x: -77, y: 39});
+const line = gc.Arc(100);
+console.log(line.json()); // GeoJSON output
 ```
 
 ### TypeScript
-Full TypeScript support with type definitions:
 ```typescript
-import { GreatCircle, Coord, Arc, CoordinatePoint } from 'arc';
+import { GreatCircle, CoordinatePoint } from 'arc';
 
 const start: CoordinatePoint = { x: -122, y: 48 };
 const end: CoordinatePoint = { x: -77, y: 39 };
 const gc = new GreatCircle(start, end);
+const line = gc.Arc(100);
 ```
 
-### Browser
-For direct browser usage (creates global `arc` object):
+### Browser (Global)
 ```html
 <script src="./arc.js"></script>
 <script>
-  var gc = new arc.GreatCircle({x: -122, y: 48}, {x: -77, y: 39});
+  const gc = new arc.GreatCircle({x: -122, y: 48}, {x: -77, y: 39});
+  const line = gc.Arc(100);
 </script>
 ```
 
-### Bundlers (Webpack, Rollup, etc.)
-Works with all modern bundlers:
-```js
-import { GreatCircle } from 'arc';
-// or
-const { GreatCircle } = require('arc');
-```
-
-## API
-
-### JavaScript Examples
+## API Reference
 
-**1)** Create start and end coordinates
+### Basic Usage
 
-First we need to declare where the arc should start and end
+#### 1. Define coordinates
+Coordinates use `x` for longitude and `y` for latitude (both in degrees):
 
 ```js
-var start = { x: -122, y: 48 };
-var end = { x: -77, y: 39 };
+const start = { x: -122, y: 48 };  // Seattle
+const end = { x: -77, y: 39 };     // Washington DC
 ```
 
-Note that `x` here is longitude in degrees and `y` is latitude in degrees.
-
-**2)** Create GreatCircle object
-
-Next we pass the start/end to the `GreatCircle` constructor, along with an optional object representing the properties for this future line.
-
+#### 2. Create a GreatCircle
 ```js
-var generator = new arc.GreatCircle(start, end, {'name': 'Seattle to DC'});
+const gc = new GreatCircle(start, end, { name: 'Seattle to DC' });
 ```
 
-**3)** Generate a line arc
-
-Then call the `Arc` function on the `GreatCircle` object to generate a line:
-
+#### 3. Generate the arc
 ```js
-var line = generator.Arc(100, {offset: 10});
+const line = gc.Arc(100, { offset: 10 });
 ```
 
-### TypeScript Examples
+**Parameters:**
+- `npoints` (number): Number of intermediate points (higher = more accurate)
+- `options.offset` (number): Dateline crossing threshold in degrees (default: 10)
 
-**1)** Import types and create coordinates
+### TypeScript Support
 
 ```typescript
 import { GreatCircle, CoordinatePoint, ArcOptions } from 'arc';
 
-const start: CoordinatePoint = { x: -122, y: 48 };
-const end: CoordinatePoint = { x: -77, y: 39 };
-```
-
-**2)** Create GreatCircle with typed properties
-
-```typescript
+// Define custom properties interface
 interface RouteProperties {
   name: string;
   color?: string;
-  distance?: number;
 }
 
+const start: CoordinatePoint = { x: -122, y: 48 };
+const end: CoordinatePoint = { x: -77, y: 39 };
 const properties: RouteProperties = { name: 'Seattle to DC', color: 'blue' };
-const generator = new GreatCircle(start, end, properties);
-```
-
-**3)** Generate arc with typed options
 
-```typescript
+const gc = new GreatCircle(start, end, properties);
 const options: ArcOptions = { offset: 10 };
-const line = generator.Arc(100, options);
+const line = gc.Arc(100, options);
 
-// TypeScript knows the return type is Arc
-const geojson = line.json(); // Returns GeoJSONFeature
-const wkt = line.wkt();      // Returns string
+// Fully typed return values
+const geojson = line.json(); // GeoJSONFeature
+const wkt = line.wkt();      // string
 ```
 
-The `line` will be a raw sequence of the start and end coordinates plus an arc of
-intermediate coordinate pairs.
+**Available Types:** `CoordinatePoint`, `ArcOptions`, `Coord`, `GreatCircle`, `Arc`, `GeoJSONFeature`
+
+### Output Formats
+
+#### Raw Arc Object
+The generated arc contains intermediate coordinate pairs:
 
 ```js
-> line
 {
   properties: { name: 'Seattle to DC' },
   geometries: [
     {
-      coords:
-       [ [ -122, 48 ],
-         [ -112.06162, 47.724167 ],
-         [ -102.384043, 46.608132 ],
-         [ -93.227189, 44.716217 ],
-         [ -84.74824, 42.144155 ],
-         [ -77, 39 ] ],
+      coords: [
+        [-122, 48],
+        [-112.06162, 47.724167],
+        [-102.384043, 46.608132],
+        [-93.227189, 44.716217],
+        [-84.74824, 42.144155],
+        [-77, 39]
+      ],
       length: 6
     }
   ]
 }
 ```
 
-#### Arc options
-
-The first argument to `Arc` specifies the number of intermediate vertices you want in the resulting line. The higher the number the more dense and accurate the line will be.
-
-The second argument is an optional object to declare options. The `offset` option controls the likelyhood that lines will be split which cross the dateline. The higher the number the more likely. The default value is 10, which means lines within 10 degress of the dateline will be split. For lines that cross and dateline and are also near the poles you will likely need a higher value to trigger splitting. It is unclear to me (@springmeyer) what the drawbacks are of high offsets. I simply ported the code from GDAL's OGR library (`gdal/ogr/ogrgeometryfactory.cpp`) and have not taken the time to fully comprehend how it works.
-
-**4)** Convert line to GeoJSON geometry
-
-To serialize to a GeoJSON geometry:
-
+#### GeoJSON Format
 ```js
-> line.json();
-{ geometry:
-   { type: 'LineString',
-     coordinates: [ [Object], [Object], [Object], [Object], [Object], [Object] ] },
+const geojson = line.json();
+// Returns:
+{
   type: 'Feature',
-  properties: { name: 'Seattle to DC' } }
+  geometry: {
+    type: 'LineString',
+    coordinates: [[-122, 48], [-112.06162, 47.724167], ...]
+  },
+  properties: { name: 'Seattle to DC' }
+}
 ```
 
-Or to WKT (Well known text):
-
+#### WKT Format
 ```js
-> line.wkt();
-'LINESTRING(-122 48,-112.061619 47.724167,-102.384043 46.608131,-93.227188 44.716217,-84.748239 42.144155,-77 38.999999)'
+const wkt = line.wkt();
+// Returns:
+'LINESTRING(-122 48,-112.061619 47.724167,-102.384043 46.608131,...)'
 ```
 
-## TypeScript
-
-```typescript
-import { GreatCircle, CoordinatePoint } from 'arc';
+### Dateline Crossing
 
-const start: CoordinatePoint = { x: -122, y: 48 };
-const end: CoordinatePoint = { x: -77, y: 39 };
-const gc = new GreatCircle(start, end);
-```
+The library automatically handles routes that cross the international dateline. The `offset` option (default: 10) controls how close to the dateline a route must be before it gets split into multiple segments. For routes near the poles, you may need a higher offset value.
 
-Available types: `CoordinatePoint`, `ArcOptions`, `Coord`, `GreatCircle`, `Arc`, `GeoJSONFeature`
+## Examples
 
-It is then up to you to add up these features to create fully fledged geodata. See the [interactive demo](https://danespringmeyer.com/arc.js/) for sample code to create a GeoJSON feature collection from multiple routes.
+See the [interactive demo](https://danespringmeyer.com/arc.js/) for sample code showing how to create GeoJSON feature collections from multiple routes.
 
 ## License