ngageoint/mgrs-android

Military Grid Reference System Android Library

MGRS Android

Military Grid Reference System Android Lib

The MGRS Library was developed at the National Geospatial-Intelligence Agency (NGA) in collaboration with BIT Systems. The government has "unlimited rights" and is releasing this software to increase the impact of government investments by providing developers with the opportunity to take things in new directions. The software use, modification, and distribution rights are stipulated within the MIT license.

Pull Requests

If you'd like to contribute to this project, please make a pull request. We'll review the pull request and discuss the changes. All pull request contributions to this project will be released under the MIT license.

Software source code previously released under an open source license and then modified by NGA staff is considered a "joint work" (see 17 USC § 101); it is partially copyrighted, partially public domain, and as a whole is protected by the copyrights of the non-government authors and must be released according to the terms of the original open source license.

About

MGRS Android is an Android library providing Military Grid Reference System functionality, a geocoordinate standard used by NATO militaries for locating points on Earth. MGRS App is a map implementation utilizing this library.

Usage

View the latest Javadoc

Tile Provider

// Context context = ...;
// GoogleMap map = ...;

// Tile size determined from display density
MGRSTileProvider tileProvider = MGRSTileProvider.create(context);

// Manually specify tile size
MGRSTileProvider tileProvider2 = MGRSTileProvider.create(512, 512);

// GZD only grid
MGRSTileProvider gzdTileProvider = MGRSTileProvider.createGZD(context);

// Specified grids
MGRSTileProvider customTileProvider = MGRSTileProvider.create(context,
        GridType.GZD, GridType.HUNDRED_KILOMETER);

map.addTileOverlay(new TileOverlayOptions().tileProvider(tileProvider));

Tile Provider Options

int x = 8;
int y = 12;
int zoom = 5;

// Manually get a tile or draw the tile bitmap
Tile tile = tileProvider.getTile(x, y, zoom);
Bitmap tileBitmap = tileProvider.drawTile(x, y, zoom);

double latitude = 63.98862388;
double longitude = 29.06755082;
LatLng latLng = new LatLng(latitude, longitude);

// MGRS Coordinates
MGRS mgrs = tileProvider.getMGRS(latLng);
String coordinate = tileProvider.getCoordinate(latLng);
String zoomCoordinate = tileProvider.getCoordinate(latLng, zoom);

String mgrsGZD = tileProvider.getCoordinate(latLng, GridType.GZD);
String mgrs100k = tileProvider.getCoordinate(latLng, GridType.HUNDRED_KILOMETER);
String mgrs10k = tileProvider.getCoordinate(latLng, GridType.TEN_KILOMETER);
String mgrs1k = tileProvider.getCoordinate(latLng, GridType.KILOMETER);
String mgrs100m = tileProvider.getCoordinate(latLng, GridType.HUNDRED_METER);
String mgrs10m = tileProvider.getCoordinate(latLng, GridType.TEN_METER);
String mgrs1m = tileProvider.getCoordinate(latLng, GridType.METER);

Custom Grids

Grids grids = Grids.create();

grids.setColor(GridType.GZD, Color.red());
grids.setWidth(GridType.GZD, 5.0);

grids.setLabelMinZoom(GridType.GZD, 3);
grids.setLabelMaxZoom(GridType.GZD, 8);
grids.setLabelTextSize(GridType.GZD, 32.0);

grids.setMinZoom(GridType.HUNDRED_KILOMETER, 4);
grids.setMaxZoom(GridType.HUNDRED_KILOMETER, 8);
grids.setColor(GridType.HUNDRED_KILOMETER, Color.blue());

grids.setLabelColor(GridType.HUNDRED_KILOMETER, Color.orange());
grids.setLabelBuffer(GridType.HUNDRED_KILOMETER, 0.1);
grids.getLabelPaint(GridType.HUNDRED_KILOMETER).setTypeface(Typeface.DEFAULT_BOLD);

grids.setColor(Color.darkGray(), GridType.TEN_KILOMETER, GridType.KILOMETER,
        GridType.HUNDRED_METER, GridType.TEN_METER);

grids.disable(GridType.METER);

grids.enableLabeler(GridType.TEN_KILOMETER);

MGRSTileProvider tileProvider = MGRSTileProvider.create(context, grids);

Installation

Pull from the Maven Central Repository (AAR, POM, Source, Javadoc)

api 'mil.nga.mgrs:mgrs-android:2.2.3'

Build

Build this repository using Android Studio and/or Gradle.

Project Setup

Include as repositories in your project build.gradle:

repositories {
    google()
    mavenCentral()
    mavenLocal()
}

Normal Build

Include the dependency in your module build.gradle with desired version number:

api 'mil.nga.mgrs:mgrs-android:2.2.3'

As part of the build process, run the "publishToMavenLocal" task on the mgrs-android Gradle script to update the Maven local repository.

Local Build

Replace the normal build dependency in your module build.gradle with:

api project(':mgrs')

Include in your settings.gradle:

include ':mgrs'

From your project directory, link the cloned SDK directory:

ln -s ../mgrs-android/mgrs mgrs

Remote Dependencies

• MGRS Java (The MIT License (MIT)) - MGRS Library

MGRS App

APK

The MGRS App provides a Military Grid Reference System map using this library.

mgrs-android's Issues

Draw tile with higher level of zoom

Discussed in #1

^{Originally posted by ValerioJiang May 13, 2023}
Hello,

i'm currently trying to draw a tile filling it with a color, and i tried with getting latitude and longitude of the four points of tile

@Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;
        if (ActivityCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED && ActivityCompat.checkSelfPermission(this, Manifest.permission.ACCESS_COARSE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
            ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, FINE_PERMISSION_CODE);
            return;
        }
        mMap.setMyLocationEnabled(true);

        // inside on map ready method
        // we will be displaying polygon on Google Maps.
        // on below line we will be adding polyline on Google Maps.




        double latitude = 63.98862388;
        double longitude = 29.06755082;


        LatLng latLng = new LatLng(latitude, longitude);

        MGRSTileProvider tileProvider = MGRSTileProvider.create(this, GridType.METER);

        // Draw a rectangle on the canvas with the paint color


        LatLng southWest = new LatLng(tileProvider.getMGRS(latLng).getGridZone().getBounds().getSouthwest().getLatitude(),tileProvider.getMGRS(latLng).getGridZone().getBounds().getSouthwest().getLongitude());
        LatLng northWest = new LatLng(tileProvider.getMGRS(latLng).getGridZone().getBounds().getNorthwest().getLatitude(),tileProvider.getMGRS(latLng).getGridZone().getBounds().getNorthwest().getLongitude());
        LatLng southEast = new LatLng(tileProvider.getMGRS(latLng).getGridZone().getBounds().getSoutheast().getLatitude(),tileProvider.getMGRS(latLng).getGridZone().getBounds().getSoutheast().getLongitude());
        LatLng northEast = new LatLng(tileProvider.getMGRS(latLng).getGridZone().getBounds().getNortheast().getLatitude(),tileProvider.getMGRS(latLng).getGridZone().getBounds().getNortheast().getLongitude());





        CameraPosition cameraPosition = new CameraPosition.Builder()
                .target(latLng)      // Sets the center of the map to location user
                .zoom(10)                   // Sets the zoom
                .bearing(90)                // Sets the orientation of the camera to east
                .tilt(40)                   // Sets the tilt of the camera to 30 degrees
                .build();
        // Add polylines to the map.
        // Polylines are useful to show a route or some other connection between points.
    mMap.addPolyline(new PolylineOptions()

                .clickable(true)
                .add( southWest, northWest, northEast, southEast, southWest)

    );

        mMap.addTileOverlay(new TileOverlayOptions().tileProvider(tileProvider));
        mMap.addMarker(new MarkerOptions().position(latLng).title(""));
        mMap.moveCamera(CameraUpdateFactory.newCameraPosition(cameraPosition));
    }

The result was that it draw correctly the borders of the tile that i'm interested, but if i want a tile with a higher zoom level it doesn't have any method that supports it, something like this

LatLng northEast = new LatLng(tileProvider.getMGRS(latLng).getGridZone(Gridtype.TEN_METER).getBounds().getNortheast().getLatitude(),tileProvider.getMGRS(latLng).getGridZone(Gridtype.TEN_METER).getBounds().getNortheast().getLongitude());

Can you please tell me if there is a way to know to get the four points of a smaller tile with higher level of zoom?

Thank you very much

Incorrect grid ref for polar region (lat 90.0, lon 0.0)

I'm writing some Unit Tests for an Android app I'm writing which uses this mgrs-android library. It appears this library gives an incorrect value for the grid of the North pole (the South pole is fine interestingly enough) at latitude 90.0°.

This could be an extremely rare edge case with this library, or it could be that there is a bug with how this library handles the MGRS polar regions.

Version Information:

mgrs-android 2.2.2
Development EnvironmentNot Applicable

Expected Results:

• According to the Earthpoint.us calculator, the North Pole should have the 1m mgrs as ZAH0000000000. Putting this into Google Maps gives the correct location at the North Pole.

Observed Results:

• This library gives the grid 31XEV0000097964, which is a point (of a much lower latitude) in the Norwegian Sea off the coast of Norway:

• It could be that this is just an extreme edge case with a latitude of exactly +90.0°. It's possible though that this library may be incorrectly handling many coordinates within the polar regions which use a special convention specific to the MGRS system. If it's the latter case, it would be important to fix this code for reliable use of this code in arctic environments.

Output:

• See above

Steps to Reproduce:

1. Set up an Android app with this library
2. Attempt to calculate the MGRS for 90.0, 0.0

Relevant Code:

package com.openathena;

import org.junit.Test;
import static org.junit.Assert.assertEquals;

public class CoordTranslatorTest {

    @Test
    public void testToMGRS1m() {
        // values from generated from https://www.earthpoint.us/convert.aspx
        assertEquals("31NAA6602100000", CoordTranslator.toMGRS1m(0.0,0.0));
        assertEquals("ZAH0000000000", CoordTranslator.toMGRS1m(90.0, 0.0));
        assertEquals("BAN0000000000", CoordTranslator.toMGRS1m(-90.0,0.0));
    }

    @Test
    public void testToMGRS10m() {
        // values from generated from https://www.earthpoint.us/convert.aspx
        assertEquals("12SVD97877615", CoordTranslator.toMGRS10m(35.028056, -111.023333));
        assertEquals("18SUJ23400740", CoordTranslator.toMGRS10m(38.897778, -77.036389));
        assertEquals("37UDB13247930", CoordTranslator.toMGRS10m(55.751667, 37.617778));
    }

    @Test
    public void testToMGRS100m() {
        // values from generated from https://www.earthpoint.us/convert.aspx
        assertEquals("45RVL926958", CoordTranslator.toMGRS100m(27.988056, 86.925278));
        assertEquals("54PXT736577", CoordTranslator.toMGRS100m(11.373333, 142.591667));
        assertEquals("19TCG023363", CoordTranslator.toMGRS100m(41.854021, -71.381068));
    }
}