CoordConversions

CoordConversions is a powerful TypeScript library designed to facilitate seamless conversions among various geographic coordinate formats: Decimal Degrees (DD), Degrees-Minutes (DM), and Degrees-Minutes-Seconds (DMS). This tool enhances geographic data handling by providing comprehensive features for parsing, validating, and formatting coordinates along with hemisphere indicators.

Key Features

• Bidirectional Conversions: Effortlessly convert between DD, DM, and DMS formats, ensuring flexibility in geographic data representation.
• Smart Parsing: Automatically detect and handle various input formats, simplifying the process of interpreting geographic coordinates.
• Robust Validation: Ensure data integrity through range checks and format validation to prevent errors in coordinate entries.
• Type Safety: Designed with complete TypeScript support, benefiting from comprehensive type definitions for increased reliability.
• Precision Control: Customize the precision of the output to meet specific formatting requirements.
• Coordinate Pair Handling: Easily work with latitude and longitude pairs together, streamlining multiple conversions in single operations.
• Rich Formatting Options: Offer a variety of ways to format coordinates for clear and reader-friendly display.
• Thoroughly Tested: Includes a complete test suite to guarantee reliability and correctness with round-trip validation.
• Lightweight Design: Built with zero dependencies, resulting in a minimal footprint and fast performance.
• Modern Build Technologies: Supports ES modules and CommonJS, ensuring compatibility with a wide range of environments.

Getting Started

import {
  // For individual coordinates
  parseToDD, // Parse values to Decimal Degrees (DD)
  ddToDM, // Convert DD to Degrees-Minutes (DM)
  ddToDMS, // Convert DD to Degrees-Minutes-Seconds (DMS)
  dmToDD, // Convert DM to DD
  dmsToDD, // Convert DMS to DD
  formatDD, // Format DD for display
  formatDM, // Format DM for display
  formatDMS, // Format DMS for display
  // For coordinate pairs
  parsePairToDD, // Parse a pair of values to Decimal Degrees (DD)
  ddPairToDM, // Convert a pair of DD values to Degrees-Minutes (DM)
  ddPairToDMS, // Convert a pair of DD values to Degrees-Minutes-Seconds (DMS)
  dmPairToDD, // Convert a pair of DM values to DD
  dmsPairToDD, // Convert a pair of DMS values to DD
  formatDDPair, // Format a pair of DD values for display
  formatDMPair, // Format a pair of DM values for display
  formatDMSPair, // Format a pair of DMS values for display
  // Coordinate type for type safety
  CoordinateType,
} from "coordconversion";

To convert coordinates using CoordConversions, utilize the following function examples:

Individual Coordinate Conversion

Use the following parse -> convert -> format flow:

1. Start with a coordinate parsing function:

   const dd = parseToDD("45° 7' 22.8\" N", CoordinateType.LAT);
   

2. Convert the parsing result to another format:

   const dm = ddToDM(dd);
   

3. Format the conversion result into a human-readable string:

   const formatted = formatDM(dm);
   console.log(formatted); // e.g. "45° 7.38' N"
   

Handling Coordinate Pairs

Perform operations on pairs of coordinates in an efficient manner:

1. Parse a coordinate pair:

   const [lat, lon] = parsePairToDD("48.8544° N", "123.5005° W");
   

2. Convert the parsed values to Degrees-Minutes:

   const [latDM, lonDM] = ddPairToDM(lat, lon);
   

3. Format both for display:

   const [latStr, lonStr] = formatDMPair(latDM, lonDM);
   console.log(latStr, lonStr); // e.g. "48° 51.26' N", "123° 30.03' W"
   

Advanced Functionality

The library allows for custom precision settings, options for clamping values during conversions, and batch processing of coordinates to enhance usability in diverse applications. Comprehensive error handling and validation mechanisms ensure robust performance while converting and formatting geographic coordinates.

This library is ideal for developers working on projects involving geographical data processing, mapping, and location-based services.