/**
 * @module LocationUtils
 * @description A comprehensive collection of utility functions for working with geographic locations and coordinates.
 * Provides methods for calculating distances, bearings, and destinations using the Haversine formula,
 * converting between coordinate formats (DD, DMS), working with the Geolocation API,
 * managing bounding boxes, and handling coordinate transformations.
 * @example
 * ```typescript
 * import { LocationUtils } from 'houser-js-utils';
 *
 * // Calculate distance between two points
 * const distance = LocationUtils.calculateDistance(40.7128, -74.0060, 51.5074, -0.1278);
 * console.log(`Distance: ${distance.toFixed(2)} km`);
 *
 * // Format coordinates in DMS format
 * const formatted = LocationUtils.formatCoordinate(40.7128, -74.0060, 'DMS');
 * console.log(formatted); // "40° 42' 46.08" N, 74° 0' 21.60" W"
 *
 * // Get current position
 * const position = await LocationUtils.getCurrentPosition();
 * console.log(`Current location: ${position.coords.latitude}, ${position.coords.longitude}`);
 * ```
 */
export declare const LocationUtils: {
    /**
     * Calculates the bearing (direction) between two geographic coordinates using the Haversine formula.
     * @param lat1 - The first latitude in degrees
     * @param lon1 - The first longitude in degrees
     * @param lat2 - The second latitude in degrees
     * @param lon2 - The second longitude in degrees
     * @returns The bearing in degrees (0-360) from north
     * @example
     * ```typescript
     * // Calculate bearing from New York to London
     * const bearing = LocationUtils.calculateBearing(40.7128, -74.0060, 51.5074, -0.1278);
     * console.log(`Bearing: ${bearing.toFixed(1)}°`); // "Bearing: 77.5°"
     *
     * // Calculate bearing between two points in the same city
     * const localBearing = LocationUtils.calculateBearing(40.7128, -74.0060, 40.7589, -73.9851);
     * console.log(`Local bearing: ${localBearing.toFixed(1)}°`); // "Local bearing: 45.2°"
     * ```
     */
    calculateBearing(lat1: number, lon1: number, lat2: number, lon2: number): number;
    /**
     * Calculates a new coordinate point based on a starting point, distance, and bearing using the Haversine formula.
     * @param lat - The starting latitude in degrees
     * @param lon - The starting longitude in degrees
     * @param distance - The distance to travel in kilometers
     * @param bearing - The bearing (direction) in degrees (0-360)
     * @returns An object containing the new latitude and longitude coordinates
     * @example
     * ```typescript
     * // Calculate a point 100km northeast of New York
     * const destination = LocationUtils.calculateDestination(40.7128, -74.0060, 100, 45);
     * console.log(`Destination: ${destination.latitude.toFixed(4)}, ${destination.longitude.toFixed(4)}`);
     * // "Destination: 41.4000, -73.1000"
     *
     * // Calculate a point 50km south of a location
     * const southPoint = LocationUtils.calculateDestination(40.7128, -74.0060, 50, 180);
     * console.log(`South point: ${southPoint.latitude.toFixed(4)}, ${southPoint.longitude.toFixed(4)}`);
     * ```
     */
    calculateDestination(lat: number, lon: number, distance: number, bearing: number): {
        latitude: number;
        longitude: number;
    };
    /**
     * Calculates the great-circle distance between two geographic coordinates using the Haversine formula.
     * @param lat1 - The first latitude in degrees
     * @param lon1 - The first longitude in degrees
     * @param lat2 - The second latitude in degrees
     * @param lon2 - The second longitude in degrees
     * @returns The distance in kilometers
     * @example
     * ```typescript
     * // Calculate distance between New York and London
     * const distance = LocationUtils.calculateDistance(40.7128, -74.0060, 51.5074, -0.1278);
     * console.log(`Distance: ${distance.toFixed(1)} km`); // "Distance: 5570.2 km"
     *
     * // Calculate distance between two points in the same city
     * const localDistance = LocationUtils.calculateDistance(40.7128, -74.0060, 40.7589, -73.9851);
     * console.log(`Local distance: ${localDistance.toFixed(2)} km`); // "Local distance: 8.45 km"
     * ```
     */
    calculateDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
    /**
     * Stops watching the user's position that was previously started with watchPosition.
     * @param watchId - The watch ID returned by watchPosition
     * @throws {Error} If geolocation is not supported by the browser
     * @example
     * ```typescript
     * // Start watching position
     * const watchId = LocationUtils.watchPosition(position => {
     *   console.log('Position updated:', position.coords);
     * });
     *
     * // Later, stop watching
     * LocationUtils.clearWatch(watchId);
     * console.log('Position watching stopped');
     * ```
     */
    clearWatch(watchId: number): void;
    /**
     * Formats geographic coordinates as a string in either decimal degrees (DD) or degrees, minutes, seconds (DMS) format.
     * @param lat - The latitude in degrees
     * @param lon - The longitude in degrees
     * @param format - The format to use: 'DD' for decimal degrees or 'DMS' for degrees, minutes, seconds
     * @returns A formatted coordinate string
     * @example
     * ```typescript
     * // Decimal degrees format
     * const dd = LocationUtils.formatCoordinate(40.7128, -74.0060, 'DD');
     * console.log(dd); // "40.712800, -74.006000"
     *
     * // Degrees, minutes, seconds format
     * const dms = LocationUtils.formatCoordinate(40.7128, -74.0060, 'DMS');
     * console.log(dms); // "40° 42' 46.08" N, 74° 0' 21.60" W"
     *
     * // Southern hemisphere example
     * const sydney = LocationUtils.formatCoordinate(-33.8688, 151.2093, 'DMS');
     * console.log(sydney); // "33° 52' 7.68" S, 151° 12' 33.48" E"
     * ```
     */
    formatCoordinate(lat: number, lon: number, format?: "DMS" | "DD"): string;
    /**
     * Gets the user's current position using the browser's Geolocation API.
     * @param options - Geolocation options for accuracy, timeout, and maximum age
     * @returns A Promise that resolves with the GeolocationPosition object
     * @throws {Error} If geolocation is not supported by the browser
     * @example
     * ```typescript
     * try {
     *   const position = await LocationUtils.getCurrentPosition({
     *     enableHighAccuracy: true,
     *     timeout: 5000,
     *     maximumAge: 0
     *   });
     *
     *   console.log(`Latitude: ${position.coords.latitude}`);
     *   console.log(`Longitude: ${position.coords.longitude}`);
     *   console.log(`Accuracy: ${position.coords.accuracy} meters`);
     * } catch (error) {
     *   console.error('Error getting position:', error);
     * }
     * ```
     */
    getCurrentPosition(options?: PositionOptions): Promise<GeolocationPosition>;
    /**
     * Calculates the center point of a geographic bounding box.
     * @param bounds - The bounding box with north, south, east, and west coordinates
     * @returns An object containing the latitude and longitude of the center point
     * @example
     * ```typescript
     * const bounds = {
     *   north: 41.0,
     *   south: 40.0,
     *   east: -73.0,
     *   west: -74.0
     * };
     *
     * const center = LocationUtils.getBoundsCenter(bounds);
     * console.log(`Center: ${center.latitude.toFixed(4)}, ${center.longitude.toFixed(4)}`);
     * // "Center: 40.5000, -73.5000"
     * ```
     */
    getBoundsCenter(bounds: {
        north: number;
        south: number;
        east: number;
        west: number;
    }): {
        latitude: number;
        longitude: number;
    };
    /**
     * Calculates a bounding box for a given radius around a center point.
     * @param lat - The center latitude in degrees
     * @param lon - The center longitude in degrees
     * @param radius - The radius in kilometers
     * @returns A bounding box with north, south, east, and west coordinates
     * @example
     * ```typescript
     * // Get bounding box for 10km radius around New York
     * const bounds = LocationUtils.getBoundsForRadius(40.7128, -74.0060, 10);
     * console.log('Bounding box:', bounds);
     * // {
     * //   north: 40.8028,
     * //   south: 40.6228,
     * //   east: -73.9060,
     * //   west: -74.1060
     * // }
     *
     * // Check if a point is within this radius
     * const isInside = LocationUtils.isWithinBounds(40.7589, -73.9851, bounds);
     * console.log(`Point is within 10km: ${isInside}`); // true
     * ```
     */
    getBoundsForRadius(lat: number, lon: number, radius: number): {
        north: number;
        south: number;
        east: number;
        west: number;
    };
    /**
     * Checks if a coordinate point is within a geographic bounding box.
     * @param lat - The latitude to check in degrees
     * @param lon - The longitude to check in degrees
     * @param bounds - The bounding box with north, south, east, and west coordinates
     * @returns True if the coordinate is within the bounds, false otherwise
     * @example
     * ```typescript
     * const bounds = {
     *   north: 41.0,
     *   south: 40.0,
     *   east: -73.0,
     *   west: -75.0
     * };
     *
     * // Check if New York is within bounds
     * const isInside = LocationUtils.isWithinBounds(40.7128, -74.0060, bounds);
     * console.log(`New York is within bounds: ${isInside}`); // true
     *
     * // Check if London is within bounds
     * const isLondonInside = LocationUtils.isWithinBounds(51.5074, -0.1278, bounds);
     * console.log(`London is within bounds: ${isLondonInside}`); // false
     * ```
     */
    isWithinBounds(lat: number, lon: number, bounds: {
        north: number;
        south: number;
        east: number;
        west: number;
    }): boolean;
    /**
     * Parses a coordinate string in decimal degrees format into latitude and longitude values.
     * @param coordinate - The coordinate string in "latitude, longitude" format
     * @returns An object containing the parsed latitude and longitude
     * @throws {Error} If the coordinate string is invalid or cannot be parsed
     * @example
     * ```typescript
     * // Parse a coordinate string
     * const coord = LocationUtils.parseCoordinate("40.7128, -74.0060");
     * console.log(`Latitude: ${coord.latitude}, Longitude: ${coord.longitude}`);
     * // "Latitude: 40.7128, Longitude: -74.0060"
     *
     * try {
     *   // Invalid format
     *   const invalid = LocationUtils.parseCoordinate("invalid");
     * } catch (error) {
     *   console.error('Error:', error.message); // "Invalid coordinate format"
     * }
     * ```
     */
    parseCoordinate(coordinate: string): {
        latitude: number;
        longitude: number;
    };
    /**
     * Converts an angle from radians to degrees.
     * @param radians - The angle in radians
     * @returns The angle in degrees
     * @example
     * ```typescript
     * const degrees = LocationUtils.toDeg(Math.PI);
     * console.log(`${degrees}°`); // "180°"
     *
     * const halfCircle = LocationUtils.toDeg(Math.PI / 2);
     * console.log(`${halfCircle}°`); // "90°"
     * ```
     */
    toDeg(radians: number): number;
    /**
     * Converts an angle from degrees to radians.
     * @param degrees - The angle in degrees
     * @returns The angle in radians
     * @example
     * ```typescript
     * const radians = LocationUtils.toRad(180);
     * console.log(radians); // 3.141592653589793 (Math.PI)
     *
     * const halfCircle = LocationUtils.toRad(90);
     * console.log(halfCircle); // 1.5707963267948966 (Math.PI / 2)
     * ```
     */
    toRad(degrees: number): number;
    /**
     * Starts watching the user's position using the browser's Geolocation API.
     * @param callback - The callback function to be called with position updates
     * @param options - Geolocation options for accuracy, timeout, and maximum age
     * @returns A watch ID that can be used to stop watching with clearWatch
     * @throws {Error} If geolocation is not supported by the browser
     * @example
     * ```typescript
     * // Start watching position with high accuracy
     * const watchId = LocationUtils.watchPosition(
     *   position => {
     *     console.log('Position updated:');
     *     console.log(`Latitude: ${position.coords.latitude}`);
     *     console.log(`Longitude: ${position.coords.longitude}`);
     *     console.log(`Accuracy: ${position.coords.accuracy} meters`);
     *   },
     *   {
     *     enableHighAccuracy: true,
     *     timeout: 5000,
     *     maximumAge: 0
     *   }
     * );
     *
     * // Later, stop watching
     * LocationUtils.clearWatch(watchId);
     * ```
     */
    watchPosition(callback: (position: GeolocationPosition) => void, options?: PositionOptions): number;
};