The Military Grid Reference System (MGRS) is the geo-coordinate standard used by NATO militaries for locating points on Earth. The MGRS is derived from the Universal Transverse Mercator (UTM) grid system and the Universal Polar Stereographic (UPS) grid system, but uses a different labeling convention.
Formatting and parsing points to/from MGRS
To format and parse a Point
to/from MGRS strings, use an MgrsFormat
.
MgrsFormat
to format points to MGRS strings
MgrsFormat mgrsFormat = MgrsFormat::newBuilder() .precision(MgrsFormatPrecision::Precision1M) .formatType(MgrsFormatType::Mgrs) .zoneSeparator(" ") .coordinateSeparator(" ") .build(); auto wgs84 = CoordinateReferenceProvider::create("EPSG:4326"); auto point = Point(wgs84.value(), {5, 45, 0}); auto stringResult = mgrsFormat.format(point); auto parsed = mgrsFormat.parse(stringResult.value());
For example, you can use this to show MGRS coordinates at the mouse location. See the Symbology sample for a demonstration.
Visualizing an MGRS grid
You can visualize the MGRS grid by using MgrsGrid
and MgrsGridLayer
.
In order of increasing complexity, you can:
-
Use the default, out-of-the-box grid styling:
MgrsGrid
with an MgrsGridLayer
to show an MGRS grid on the map
auto mgrsGridLayer = MgrsGridLayer::newBuilder().build(); map->getLayerList()->add(mgrsGridLayer);
-
Do some basic tweaks to the default styling, like changing line colors.
MgrsGrid
Color primaryColor = Color::white(); Color secondaryColor = Color::green(); Color tertiaryColor = Color::yellow(); auto primaryLabelStyle = TextStyle::newBuilder() // .fontSize(12) .fontName("monospace") .textColor(primaryColor) .haloWidth(1.0) .haloColor(Color::black()) .build(); auto secondaryLabelStyle = TextStyle::newBuilder() // .fontSize(14) .fontName("monospace") .textColor(secondaryColor) .haloWidth(1.0) .haloColor(Color::black()) .build(); auto tertiaryLabelStyle = TextStyle::newBuilder() // .fontSize(16) .fontName("monospace") .textColor(tertiaryColor) .haloWidth(1.0) .haloColor(Color::black()) .build(); MgrsGrid mgrsGrid = MgrsGrid::newBuilder() .primaryLineStyle(LineStyle::newBuilder().color(primaryColor).width(1.0).build()) .primaryLabelStyle(primaryLabelStyle) .secondaryLineStyle(LineStyle::newBuilder().color(secondaryColor).width(2.0).build()) .secondaryLabelStyle(secondaryLabelStyle) .tertiaryLineStyle(LineStyle::newBuilder().color(tertiaryColor).width(3.0).build()) .tertiaryLabelStyle(tertiaryLabelStyle) .scaleMultiplier(1.5) // make the grid more coarse .build(); auto mgrsGridLayer = MgrsGridLayer::newBuilder().grid(mgrsGrid).build(); map->getLayerList()->add(mgrsGridLayer);
-
Completely customize the styling of the MGRS grid.
MgrsGrid
styling
// Styling with completely custom scale ranges and styles auto labelStyle = TextStyle::newBuilder() // Label style used on all levels .fontSize(20) .fontName("monospace") .textColor(Color::white()) .haloColor(Color::black()) .haloWidth(1) .build(); // Always show grid zones with thick red lines, regardless of the zoom level MgrsGridSetting gridZoneSetting = MgrsGridSetting::newBuilder() .level(MgrsLevel::GridZones) .scaleRange(MapScale::maxZoomedOut(), MapScale::maxZoomedIn()) .lineStyle(LineStyle::newBuilder() // Thick red line .color(Color::red()) .width(5.0) .build()) .labelStyle(labelStyle) .build(); // When zoomed in far enough, show 100km grid squares in yellow. // Hide them when zoomed in beyond the 10km grid square scale range start MapScale startScale100Km = MapScale::fromDenominator(3'000'000.0); MapScale startScale10Km = MapScale::fromDenominator(750'000.0); MgrsGridSetting square100KmSetting = MgrsGridSetting::newBuilder() .level(MgrsLevel::Squares100Km) .scaleRange(startScale100Km, startScale10Km) .lineStyle(LineStyle::newBuilder() // Yellow line .color(Color::yellow()) .width(3.0) .build()) .labelStyle(labelStyle) .build(); // When zoomed in beyond the 100km squares, show 10km squares in green MgrsGridSetting square10KmSetting = MgrsGridSetting::newBuilder() .level(MgrsLevel::Squares10Km) .scaleRange(startScale10Km, MapScale::maxZoomedIn()) .lineStyle(LineStyle::newBuilder() // Green line .color(Color::green()) .width(2.0) .build()) .labelStyle(labelStyle) .build(); // Don't show any lower MGRS levels (Squares1Km, Squares100M, Squares10M and Squares1M) MgrsGrid mgrsGrid = MgrsGrid::newAdvancedBuilder() .setting(gridZoneSetting) // grid zones .setting(square100KmSetting) // 100km squares .setting(square10KmSetting) // 10km squares .build(); auto mgrsGridLayer = MgrsGridLayer::newBuilder().grid(mgrsGrid).build(); map->getLayerList()->add(mgrsGridLayer);
Adding an MGRS overview label to the map
When users zoom in far on the map, it’s easy for them to lose track of the grid zone or square that they’re in. To prevent that, you can show an overview label on the map. This label shows the users which grid zone and square they have reached by zooming in on the map. When you use the overview label combined with the grid labels and the mouse coordinate readout, you give the users more than one option for determining their current MGRS location.
The LuciadCPillar API gives you a utility class to generate the text for the MGRS overview label: MgrsGridTextProvider
.
It fires events whenever the overview label should change its text with a new formatted location string.
You can use this utility in a UI framework of your choice.
MgrsGridTextProvider
to the map and start listening to it.
auto textProvider = MgrsGridTextProvider(map); textProvider.addCallback(MgrsGridTextProvider::ICallback::create([](const std::string& text) { std::cout << "New MGRS location text = " << text << "\n"; }));