mgrs

Bidirectional MGRS/lat-long coordinate conversion CLI and Rust library. Reads and writes 10 geospatial formats with automatic format detection.

Author

Albert Hui albert@securityronin.com

Features

• Bidirectional conversion: MGRS to lat/lon (default) and lat/lon to MGRS (--to-mgrs)
• 10 formats, all bidirectional: CSV, GeoJSON, KML, KMZ, GPX, WKT, TopoJSON, Shapefile, GeoPackage, FlatGeobuf
• Cross-format conversion: Any input format to any output format (e.g., GeoJSON to KML, Shapefile to CSV)
• Auto-detection: Detects both input and output formats from file extensions
• Auto-detect MGRS columns: Finds MGRS columns automatically, no configuration needed
• Streaming: Processes CSV rows one at a time — handles large files without loading everything into memory
• Strict mode: Optionally abort on first conversion error
• Optional heavy deps: Shapefile, GeoPackage, and FlatGeobuf support can be disabled at compile time
• Library API: Use as a Rust library in your own projects

Installation

From crates.io

cargo install mgrs

Without optional formats

cargo install mgrs --no-default-features

This builds without Shapefile, GeoPackage, and FlatGeobuf support, avoiding the heavier native dependencies (SQLite, FlatBuffers).

Windows binary

Download mgrs-x86_64-pc-windows-msvc.zip from the latest release.

From source

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

The binary will be at target/release/mgrs.

Usage

MGRS to Lat/Lon (default)

# CSV to stdout
mgrs input.csv

# Output as GeoJSON (format auto-detected from extension)
mgrs input.csv -o output.geojson

# Explicit format flag
mgrs input.csv --format geojson -o output.geojson

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

# GPX waypoints
mgrs input.csv -f gpx -o output.gpx

# WKT points
mgrs input.csv -f wkt -o output.wkt

# Shapefile (requires -o, creates .shp/.shx/.dbf)
mgrs input.csv -f shapefile -o output.shp

# GeoPackage (requires -o)
mgrs input.csv -f geopackage -o output.gpkg

# FlatGeobuf
mgrs input.csv -f flatgeobuf -o output.fgb

Cross-Format Conversion

Any supported input format can be converted to any output format:

# GeoJSON to CSV
mgrs input.geojson -o output.csv

# KML to GeoJSON
mgrs input.kml -o output.geojson

# Shapefile to KML
mgrs input.shp -o output.kml

# GeoPackage to CSV (stdout)
mgrs input.gpkg -f csv

# Explicit input format override
mgrs data.json -F geojson -o output.csv

Lat/Lon to MGRS

# Reverse conversion
mgrs input.csv --to-mgrs

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

Other Options

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

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

Flags

Supported Formats

All formats support both reading and writing. Format is auto-detected from file extensions.

Note: Shapefile and GeoPackage write to the filesystem and require the --output flag.

Feature Flags

Heavy native dependencies are optional Cargo features (all enabled by default):

To build without these:

cargo build --release --no-default-features

The remaining 7 formats (CSV, GeoJSON, KML, KMZ, GPX, WKT, TopoJSON) are always available.

Exit Codes

Library Usage

Add to your Cargo.toml:

[dependencies]
mgrs = "0.4"

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.