ExMgrs

Elixir library for converting between latitude/longitude coordinates and MGRS (Military Grid Reference System) coordinates. Built with Rust NIFs for maximum speed and accuracy using the embedded geoconvert-rs Rust library.

Features

Convert decimal degrees (lat/lon) to MGRS grid reference string
Convert MGRS grid reference string back to decimal degrees
Format MGRS strings with proper spacing
Configurable precision levels (1-5 digits, default 5)
ECEF (Earth-Centered, Earth-Fixed) coordinate conversions
EGM96 geoid model for MSL (Mean Sea Level) altitude conversions
Safe for the BEAM: no unsafe Rust code in application or geoconvert library

Understanding Altitude: HAE vs MSL

This library works with two altitude systems. Understanding the difference matters when altitude accuracy is important (aviation, surveying, GPS integration):

HAE (Height Above Ellipsoid) -- also called "ellipsoidal height" or simply "alt" in GPS contexts. This is the raw geometric distance above the WGS84 reference ellipsoid, a smooth mathematical surface that approximates the Earth's shape. GPS receivers natively output HAE.

MSL (Mean Sea Level) -- the height above the geoid, a gravity-based surface that approximates actual sea level. This is what altimeters, aviation charts, topographic maps, and most real-world applications use.

The two differ by the geoid undulation (N) at each point on Earth:

HAE = MSL + N
MSL = HAE - N

The undulation varies from roughly -106m to +85m depending on location. For example, in Los Angeles the geoid is about 33m below the ellipsoid, so a GPS reading of 0m HAE corresponds to about 33m MSL.

This library uses the EGM96 geoid model (15-minute grid, ~2MB embedded at compile time) to convert between the two systems.

Naming conventions

Functions with hae in the name explicitly accept or return ellipsoidal height
Functions with msl in the name accept or return mean sea level height
Functions with alt in the name are aliases for their hae counterparts, for users more familiar with "altitude" than "HAE"
In ExMgrs.Ecef, the default from_latlon/3 and from_mgrs/2 treat height as HAE

Installation

From Hex (Recommended)

Add ex_mgrs to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_mgrs, "~> 0.0.5"}
  ]
end

Then run:

mix deps.get
mix compile

Note: This package uses precompiled Rust NIFs for fast installation. No Rust toolchain is required for most platforms (macOS, Linux, Windows). Precompiled binaries are automatically downloaded during installation.

If precompiled binaries are not available for your platform, the package will automatically fall back to compiling from source, which requires the Rust toolchain to be installed.

Supported Platforms

Precompiled binaries are provided for:

macOS: x86_64 (Intel), aarch64 (Apple Silicon)
Linux: x86_64 (glibc), x86_64 (musl), aarch64 (glibc), aarch64 (musl)
Windows: x86_64 (MSVC), x86_64 (GNU)

Force Build from Source

To force compilation from source instead of using precompiled binaries:

RUSTLER_PRECOMPILATION_EXAMPLE_BUILD=true mix deps.compile ex_mgrs --force

From Source (Development)

If you want to contribute or use the latest development version:

# Clone with submodules to get the geoconvert library
git clone --recursive https://github.com/cortfritz/ex_mgrs.git
cd ex_mgrs

# If you already cloned without --recursive, initialize submodules:
git submodule update --init --recursive

# Install dependencies and compile
mix deps.get
mix compile

# Run tests
mix test

Usage

MGRS Conversions

# Convert latitude/longitude to MGRS
iex> ExMgrs.latlon_to_mgrs(34.0, -118.24, 5)
{:ok, "11SLT8548562848"}

# Convert MGRS to latitude/longitude
iex> ExMgrs.mgrs_to_latlon("11SLT8548562848")
{:ok, {34.0, -118.24}}

# Format MGRS string with proper spacing
iex> ExMgrs.format_mgrs("11SLT8548562848")
{:ok, "11S LT 85485 62848"}

# Use different precision levels
iex> ExMgrs.latlon_to_mgrs(34.0, -118.24, 3)
{:ok, "11SLT854628"}

ECEF Conversions

# Lat/lon to ECEF (height is HAE, defaults to 0)
iex> ExMgrs.Ecef.from_latlon_hae(34.0, -118.24, 500.0)
{:ok, {-2_493_090.59, -4_655_089.08, 3_553_494.47}}

# Same thing using the alt alias
iex> ExMgrs.Ecef.from_latlon(34.0, -118.24, 500.0)
{:ok, {-2_493_090.59, -4_655_089.08, 3_553_494.47}}

# ECEF back to lat/lon/HAE
iex> ExMgrs.Ecef.to_latlon_hae(-2_493_090.59, -4_655_089.08, 3_553_494.47)
{:ok, {34.0, -118.24, 500.0}}

# MGRS to ECEF
iex> ExMgrs.Ecef.from_mgrs_hae("11SLT8548562848", 500.0)
{:ok, {-2_493_090.59, -4_655_089.08, 3_553_494.47}}

# ECEF to MGRS (returns {mgrs, hae})
iex> ExMgrs.Ecef.to_mgrs_hae(-2_493_090.59, -4_655_089.08, 3_553_494.47)
{:ok, {"11SLT8548562848", 500.0}}

# Euclidean distance between two ECEF points
iex> ExMgrs.Ecef.distance(point1, point2)
1234.56

Geoid / MSL Conversions

# Get geoid undulation at a location
iex> ExMgrs.Geoid.undulation(34.0, -118.24)
{:ok, -32.87}

# Convert between HAE and MSL
iex> ExMgrs.Geoid.hae_to_msl(34.0, -118.24, 500.0)
{:ok, 532.87}

iex> ExMgrs.Geoid.msl_to_hae(34.0, -118.24, 532.87)
{:ok, 500.0}

# alt aliases work the same way
iex> ExMgrs.Geoid.alt_to_msl(34.0, -118.24, 500.0)
{:ok, 532.87}

# Lat/lon + MSL to ECEF (converts through geoid automatically)
iex> ExMgrs.Geoid.latlon_msl_to_ecef(34.0, -118.24, 500.0)
{:ok, {x, y, z}}

# ECEF to lat/lon + MSL
iex> ExMgrs.Geoid.ecef_to_latlon_msl(x, y, z)
{:ok, {34.0, -118.24, 500.0}}

# MGRS + MSL to ECEF
iex> ExMgrs.Geoid.mgrs_msl_to_ecef("11SLT8548562848", 500.0)
{:ok, {x, y, z}}

# ECEF to MGRS + MSL
iex> ExMgrs.Geoid.ecef_to_mgrs_msl(x, y, z)
{:ok, {"11SLT8548562848", 500.0}}

# MGRS with altitude conversions
iex> ExMgrs.Geoid.mgrs_hae_to_msl("11SLT8548562848", 500.0)
{:ok, {34.0, -118.24, 532.87}}

iex> ExMgrs.Geoid.mgrs_msl_to_hae("11SLT8548562848", 532.87)
{:ok, {34.0, -118.24, 500.0}}

Conversion Matrix

From	To	Function
lat/lon + HAE	ECEF	`Ecef.from_latlon_hae/3` or `Ecef.from_latlon/3`
ECEF	lat/lon + HAE	`Ecef.to_latlon_hae/3` or `Ecef.to_latlon/3`
MGRS + HAE	ECEF	`Ecef.from_mgrs_hae/2` or `Ecef.from_mgrs/2`
ECEF	MGRS + HAE	`Ecef.to_mgrs_hae/4` or `Ecef.to_mgrs/4`
lat/lon + MSL	ECEF	`Geoid.latlon_msl_to_ecef/3`
ECEF	lat/lon + MSL	`Geoid.ecef_to_latlon_msl/3`
MGRS + MSL	ECEF	`Geoid.mgrs_msl_to_ecef/2`
ECEF	MGRS + MSL	`Geoid.ecef_to_mgrs_msl/4`
HAE	MSL	`Geoid.hae_to_msl/3` or `Geoid.alt_to_msl/3`
MSL	HAE	`Geoid.msl_to_hae/3` or `Geoid.msl_to_alt/3`
MGRS + HAE	lat/lon + MSL	`Geoid.mgrs_hae_to_msl/2` or `Geoid.mgrs_alt_to_msl/2`
MGRS + MSL	lat/lon + HAE	`Geoid.mgrs_msl_to_hae/2` or `Geoid.mgrs_msl_to_alt/2`

Development

Prerequisites

Elixir >= 1.18.2 and <= 1.19.2
Rust (managed by Rustler)
Git (for submodules when developing from source)

Setup

# Clone the repository with submodules (for development)
git clone --recursive https://github.com/cortfritz/ex_mgrs.git
cd ex_mgrs

# If you already cloned without --recursive, initialize submodules:
git submodule update --init --recursive

# Install dependencies
mix deps.get

# Compile (includes Rust NIF compilation)
mix compile

# Run tests
mix test

# Format code
mix format

Note: This project includes a mise.toml file configured for Elixir 1.19.2-otp-28. If you use mise, it will automatically use this version. You can override this locally or use any version within the required range (>= 1.18.2 and <= 1.19.2) with your preferred version manager.

Architecture

This library includes coordinate conversion functionality in two ways:

For Development:

native/geoconvert/ - Git submodule pointing to the upstream geoconvert-rs repository
To update from upstream: git submodule update --remote

For Hex Packages:

native/geoconvert_embedded/ - Embedded copy of geoconvert source included in Hex packages
Ensures users can install from Hex without needing git submodules

Common Structure:

lib/ex_mgrs.ex - Main public API (lat/lon and MGRS conversions)
lib/ex_mgrs/ecef.ex - ECEF coordinate conversions (pure Elixir)
lib/ex_mgrs/geoid.ex - EGM96 geoid model and MSL conversions (pure Elixir)
lib/ex_mgrs/native.ex - NIF interface
native/geoconvert_nif/ - Thin Rust NIF wrapper that interfaces with geoconvert
priv/egm96-15.bin - EGM96 geoid undulation grid (embedded at compile time)

Contributing

We welcome contributions! Please follow these guidelines:

Getting Started

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Make your changes following the project conventions
Ensure tests pass: mix test
Format your code: mix format
Commit with a descriptive message
Push and create a pull request

Development Guidelines

Follow Elixir community conventions
Add tests for new functionality
Update documentation as needed
Ensure NIFs compile successfully
Validate roundtrip conversions in tests

Reporting Issues

Please use GitHub Issues to report bugs or request features. Include:

Elixir version (required: >= 1.18.2 and <= 1.19.2)
Rust version
Rustler version (this project uses ~> 0.36)
Operating system
Steps to reproduce
Expected vs actual behavior

Safety

This NIF is safe for your Elixir/Erlang host process:

Application code: The NIF wrapper (native/geoconvert_nif/) contains no unsafe blocks
geoconvert library: The embedded coordinate conversion library is 100% safe Rust
rustler: The NIF binding library (v0.36) contains unsafe code internally to interface with the BEAM's C NIF API, but exposes only safe Rust APIs. Rustler catches Rust panics before they unwind into C, preventing BEAM crashes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Documentation can be generated with ExDoc:

mix docs

Once published to Hex, docs will be available at https://hexdocs.pm/ex_mgrs.