mgrs 0.3.0

Bidirectional MGRS/lat-long coordinate conversion CLI with CSV, GeoJSON, KML, and GPX output
Documentation
mgrs-0.3.0 has been yanked.

mgrs

Bidirectional MGRS/lat-long coordinate conversion CLI and Rust library. Reads CSV files and outputs to CSV, GeoJSON, KML, or GPX.

Author

Albert Hui albert@securityronin.com

Features

  • Bidirectional conversion: MGRS to lat/lon (default) and lat/lon to MGRS (--to-mgrs)
  • Multiple output formats: CSV, GeoJSON, KML, GPX
  • Auto-detection: Finds MGRS columns automatically, no configuration needed
  • Streaming: Processes rows one at a time — handles large files without loading everything into memory
  • Strict mode: Optionally abort on first conversion error
  • Library API: Use as a Rust library in your own projects

Installation

From crates.io

cargo install mgrs

From source

git clone https://github.com/4n6h4x0r/mgrs.git
cd mgrs
cargo build --release

The binary will be at target/release/mgrs.

Usage

# Convert MGRS to lat/lon (CSV to stdout)
mgrs input.csv

# Output as GeoJSON
mgrs input.csv --format geojson -o output.geojson

# Output as KML with custom name column
mgrs input.csv --format kml --name-column "Site Name" -o output.kml

# Output as GPX waypoints
mgrs input.csv --format gpx -o output.gpx

# Specify the MGRS column explicitly
mgrs input.csv --column "Grid Ref"

# Abort on first error
mgrs input.csv --strict

# Reverse: convert lat/lon to MGRS
mgrs input.csv --to-mgrs

# Control MGRS precision (1-5, default 6)
mgrs input.csv --to-mgrs --precision 3

Flags

Flag Short Description Default
--to-mgrs Convert lat/lon to MGRS (default is MGRS to lat/lon) off
--format -f Output format: csv, geojson, kml, gpx csv
--output -o Output file path (omit for stdout) stdout
--column -c Column name or index containing coordinates auto-detect
--precision -p Decimal places in output coordinates 6
--strict Abort on first conversion error off
--name-column Column for placemark/waypoint names (KML/GPX) first text column

Input Format

CSV files with either:

  • An MGRS column (default mode): values like 18SUJ2337006519 or 18S UJ 23370 06519
  • Latitude/Longitude columns (--to-mgrs mode): columns with names containing "lat" and "lon"/"lng"

Output Formats

Format Description
CSV Original columns plus appended Latitude/Longitude (or MGRS) columns
GeoJSON FeatureCollection with Point features; all CSV columns become properties
KML Placemark elements with ExtendedData carrying all CSV fields
GPX wpt (waypoint) elements with names from --name-column or first text column

Exit Codes

Code Meaning
0 All rows converted successfully
1 Fatal error (bad input file, unknown format, etc.)
2 Partial success — some rows failed conversion

Library Usage

Add to your Cargo.toml:

[dependencies]
mgrs = "0.2"

use mgrs::convert::{mgrs_to_latlon, latlon_to_mgrs};

// MGRS to Lat/Lon
let coord = mgrs_to_latlon("18SUJ2337006519").unwrap();
println!("{}, {}", coord.latitude, coord.longitude);

// Lat/Lon to MGRS
let mgrs = latlon_to_mgrs(38.8977, -77.0365, 5).unwrap();
println!("{}", mgrs.0);

License

Dual-licensed under MIT or Apache-2.0, at your option.