Geographic Calculations

/**
 * Computes the spherical area of a GeoJSON feature in steradians
 * @param object - GeoJSON feature or geometry
 * @returns Area in steradians (4π steradians = full sphere)
 */
function geoArea(object: GeoJSON.Feature | GeoJSON.Geometry): number;

import { geoArea } from "d3-geo";

// Calculate area of a polygon
const polygon = {
  type: "Polygon",
  coordinates: [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]]
};
const area = geoArea(polygon); // Returns area in steradians

// Calculate area of a country feature
const country = {
  type: "Feature",
  properties: { name: "Example" },
  geometry: {
    type: "Polygon",
    coordinates: [/* country boundary coordinates */]
  }
};
const countryArea = geoArea(country);

/**
 * Computes the spherical bounding box of a GeoJSON feature
 * @param object - GeoJSON feature or geometry
 * @returns Bounding box as [[west, south], [east, north]] in degrees
 */
function geoBounds(object: GeoJSON.Feature | GeoJSON.Geometry): [[number, number], [number, number]];

import { geoBounds } from "d3-geo";

// Get bounds of a line string
const line = {
  type: "LineString",
  coordinates: [[-10, -5], [10, 5], [20, 15]]
};
const bounds = geoBounds(line); // [[-10, -5], [20, 15]]

// Get bounds for fitting a projection
const feature = { /* GeoJSON feature */ };
const bounds = geoBounds(feature);
const projection = geoMercator().fitExtent([[0, 0], [960, 500]], feature);

/**
 * Computes the spherical centroid of a GeoJSON feature
 * @param object - GeoJSON feature or geometry
 * @returns Centroid as [longitude, latitude] in degrees
 */
function geoCentroid(object: GeoJSON.Feature | GeoJSON.Geometry): [number, number];

import { geoCentroid } from "d3-geo";

// Find centroid of a polygon
const polygon = {
  type: "Polygon",
  coordinates: [[[0, 0], [2, 0], [2, 2], [0, 2], [0, 0]]]
};
const center = geoCentroid(polygon); // [1, 1]

// Find centroid of a feature collection
const features = {
  type: "FeatureCollection",
  features: [/* array of features */]
};
const centroid = geoCentroid(features);

/**
 * Computes the great-arc distance between two points
 * @param a - First point as [longitude, latitude] in degrees
 * @param b - Second point as [longitude, latitude] in degrees
 * @returns Distance in radians (multiply by earth radius for actual distance)
 */
function geoDistance(a: [number, number], b: [number, number]): number;

import { geoDistance } from "d3-geo";

// Calculate distance between New York and London
const newYork = [-74.006, 40.7128];
const london = [-0.1278, 51.5074];
const distanceRadians = geoDistance(newYork, london);

// Convert to kilometers (Earth radius ≈ 6371 km)
const distanceKm = distanceRadians * 6371; // ~5585 km

// Calculate distance for route planning
const waypoints = [
  [-74.006, 40.7128], // New York
  [-87.6298, 41.8781], // Chicago
  [-122.4194, 37.7749]  // San Francisco
];
const totalDistance = waypoints.reduce((sum, point, i) => {
  if (i === 0) return 0;
  return sum + geoDistance(waypoints[i - 1], point);
}, 0);

/**
 * Computes the length of the perimeter of a GeoJSON feature
 * @param object - GeoJSON feature or geometry
 * @returns Length in radians (multiply by earth radius for actual length)
 */
function geoLength(object: GeoJSON.Feature | GeoJSON.Geometry): number;

import { geoLength } from "d3-geo";

// Calculate length of a line string
const route = {
  type: "LineString",
  coordinates: [[-74, 40], [-87, 41], [-122, 37]]
};
const routeLength = geoLength(route);
const routeLengthKm = routeLength * 6371; // Convert to kilometers

// Calculate perimeter of a polygon
const polygon = {
  type: "Polygon",
  coordinates: [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]]
};
const perimeter = geoLength(polygon);

// Calculate total length of multiple features
const multiLineString = {
  type: "MultiLineString",
  coordinates: [
    [[-74, 40], [-87, 41]],
    [[-87, 41], [-122, 37]]
  ]
};
const totalLength = geoLength(multiLineString);

/**
 * Tests whether a point is contained by a GeoJSON feature
 * @param object - GeoJSON feature or geometry
 * @param point - Test point as [longitude, latitude] in degrees
 * @returns true if point is contained, false otherwise
 */
function geoContains(object: GeoJSON.Feature | GeoJSON.Geometry, point: [number, number]): boolean;

import { geoContains } from "d3-geo";

// Test if point is inside a polygon
const polygon = {
  type: "Polygon",
  coordinates: [[[0, 0], [2, 0], [2, 2], [0, 2], [0, 0]]]
};
const isInside = geoContains(polygon, [1, 1]); // true
const isOutside = geoContains(polygon, [3, 3]); // false

// Test point-in-country functionality
const country = { /* GeoJSON country polygon */ };
const city = [-74.006, 40.7128]; // New York coordinates
const isInCountry = geoContains(country, city);

// Filter points by region
const region = { /* GeoJSON polygon */ };
const points = [[-74, 40], [-87, 41], [-122, 37]];
const pointsInRegion = points.filter(point => geoContains(region, point));

/**
 * Returns an interpolator between two points along a great arc
 * @param a - Start point as [longitude, latitude] in degrees
 * @param b - End point as [longitude, latitude] in degrees
 * @returns Interpolator function that takes t (0-1) and returns interpolated point
 */
function geoInterpolate(a: [number, number], b: [number, number]): (t: number) => [number, number];

import { geoInterpolate } from "d3-geo";

// Create interpolator between two cities
const newYork = [-74.006, 40.7128];
const london = [-0.1278, 51.5074];
const interpolate = geoInterpolate(newYork, london);

// Get midpoint
const midpoint = interpolate(0.5);

// Generate points along great circle route
const routePoints = [];
for (let t = 0; t <= 1; t += 0.1) {
  routePoints.push(interpolate(t));
}

// Animate movement along great circle
function animateAlongPath(start, end, duration) {
  const interpolate = geoInterpolate(start, end);
  const startTime = Date.now();
  
  function frame() {
    const elapsed = Date.now() - startTime;
    const t = Math.min(elapsed / duration, 1);
    const currentPosition = interpolate(t);
    
    // Update map marker position
    updateMarker(currentPosition);
    
    if (t < 1) requestAnimationFrame(frame);
  }
  
  requestAnimationFrame(frame);
}