Georeferencing a Level

Georeferencing means to associate an environment with locations in physical space. The term is commonly used in the geographic information systems field to describe the process of associating a physical map or raster image of a map with spatial locations. Once the environment has been georeferenced, Unreal Engine can express actual geographic coordinates (such as latitude/longitude or UTM coordinates).

Prerequisites

• The GeoReferencing plugin must be enabled to use the features described here.

Theoretical Background

Coordinate Reference Systems (CRS) and Ellipsoids

When it comes to locating objects on a planet, one must choose a Coordinate Reference System (CRS) to express the location.

What makes it complicated is that planets are neither planes nor spheres: they are ellipsoids. There are different ellipsoid models (called datums), the most well-known one being the WGS84 for Earth.

For example, with the WGS84 ellipsoid, there is an approximate 22km of difference between the lengths of the axes!

• a = 6 378 137.0 m
• b = 6 356 752.314 245 m
• 1/f = 298.257 223 563

Each Coordinate Reference System defines locations using the ellipsoid model it is based on. However, there are different kinds of CRS, each with additional properties.

Geographic CRS

A geographic CRS uses polar coordinates to express the location of one point on the planet.

There are, in fact, two kinds of latitude definitions; when the datum is not a sphere, local normal to the ellipsoid model is involved, which makes for more complex calculations, but that is out of scope here.

Geocentric CRS

A geocentric CRS uses Cartesian coordinates to define the location of any point on the planet, with the origin located at the planet center.

The following image shows the Earth-Centered, Earth-Fixed (ECEF) CRS, which is the standard reference CRS used in distributed simulation protocols such as DIS/HLA.

Projected CRS

A projected coordinate system is a Geographic Coordinate System in which the planet has been "flattened" using a map projection. This is what we have always used when looking at paper maps. There are different ways to project a sphere to a plane, so there are lots of possible map projections, with more or less deformation, depending on the area mapped.

Most basic projections are using planar, conical or cylindrical shapes.

One of the most frequently used projections is the Mercator projection, which has several variants.

For instance, there is the Universal Transverse Mercator projection, widely used in the Simulation Industry. This CRS divides Earth into 60 parts, or zones, and projects each of these north / south-oriented zones using a cylindrical projection that is tangent to the central meridian of each zone.

This is a Cartesian coordinate system, but in addition to the XYZ coordinates, it needs a Zone and Hemisphere identifier to define the origin. Specific assumptions are necessary to make sure all coordinates are positive.

Each 6°-wide UTM zone has a central meridian located by definition at X=500,000 meters. This central meridian is an arbitrary value convenient for avoiding any negative coordinates. All easting values will be greater than this central value, and all westing values will be lower, but all values will be positive.

If you're in the Northern Hemisphere, the equator has a northing value of 0 meters. In the Southern Hemisphere, the equator starts at 10,000,000 meters. This is because all values south of the equator will be subtracted from this value while being kept positive. This is called a false northing because y-coordinates in the Southern Hemisphere will avoid negative values.

There are derivatives of this system such as the Military Grid Reference System (MGRS).

How to Describe a CRS

There are so many possible projection systems that conventions have been defined to declare their particular settings, such as Ellipsoid, Units, Meridians, Projections, and so on. This data can be saved in various formats, with the most-used being Well-Known-Text (WKT) and the European Petroleum Survey Group (EPSG) code.

Several websites, like http://epsg.io/, give information about each CRS, the details of which are outside the scope of this document.

It is very important to know the CRS that you want to use to convert coordinates to the right values.

References

For more information about geodesy (the field of mathematics that deals with the shape and area of Earth), you can have a look at the following links.

• CRS: https://en.wikipedia.org/wiki/Geographic_coordinate_system
• Geographic CRS : https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84
• ECEF: https://en.wikipedia.org/wiki/ECEF
• Mercator Projection : https://en.wikipedia.org/wiki/Mercator_projection
• UTM Projection: https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system
• MGRS: https://en.wikipedia.org/wiki/Military_Grid_Reference_System

Georeferencing Plugin

Unreal Engine comes with a Georeferencing plugin that you can use to define the level origin coordinates in one specific CRS, and provides functions to convert coordinates between each different CRS. In Unreal Engine, each Actor has coordinates defined relative to this level origin, so to know an arbitrary georeferenced location, you need to locate the engine origin on Earth.

Consider these two different cases:

• Flat Planet: Your Unreal Engine environment is small enough to be approximated by a flat ground surface (smaller than some hundreds of km). In that case, you can model the ground in a projected mode, and define all coordinates in a projected CRS with one simple translation offset.
• Round Planet: Your Unreal Engine environment is so big that you need to take into account the planet curvature (this is almost certainly the case if you are using the Large World Coordinates feature). In that case, your environment geometry can cover the whole planet, with a spherical or ellipsoidal shape. In this case, there are two ways to place your origin: at the center of the planet shape, or at any point on the surface. In the latter case, Unreal Engine assumes the Z-axis is pointing up, and normal to the ellipsoid at this point.

These cases can be illustrated by the image below.

• On a Flat Planet, your environment is the green square. The modeling origin chosen for your level is the P point. It's an arbitrary location on the planet, and it can be defined using Geographic coordinates (latitude and longitude), or using Cartesian coordinates, but in a specific projected CRS. The XYZ coordinates are then represented within the CRS as east / north / up directions.

• On a Round Planet, you have two different choices:

  • Locate your Level origin at the planet center. This is the ECEF case, there is no geometry at the origin, but instead at coordinates with large values depending on the planet radius. The ECEF CRS is a Cartesian coordinate system, and its axes are aligned to the Unreal Engine axes.
  • Locate your Level origin at an arbitrary point on the planet surface. As in the Flat Planet case, these coordinates can be expressed in a Geographic or Projected CRS. It is more convenient to keep the Up direction of the level aligned with the ellipsoid normal at this location, and make sure you orient the plane geometry in such a way that the Front and Right vectors are matching the North and East vectors.

In the geospatial industry, most coordinates are expressed in right-handed frames, but Unreal Engine uses a left-handed coordinate system. To remain consistent with geospatial usage, the Georeferencing plugin expresses coordinates using right-handed logic. This means that it inverts the Y coordinate at some point when converting coordinates (this is transparent to the end user).

For the Georeferencing plugin, we chose the following default axes conventions:

If you prefer to use another convention, you will have to perform a coordinate swap before invoking the Georeferencing functions.

Unreal Engine automatically handles the World Origin offset shifting you activate when you use World Composition or when you perform a manual rebasing.

Setting up the Georeferencing System

From the main menu, go to Edit > Plugins, then enable the Georeferencing plugin. Restart Unreal Engine.

Once enabled, you can use this plugin to convert coordinates between four systems:

• The Unreal Engine coordinate system
• A Projected CRS of your choice
• A Geographic CRS of your choice
• The standard ECEF CRS

From the Place Actors panel, find the Geo Referencing System Actor, drag it into your level, then select it to view its properties in the Details panel.

Geo Referencing

Origin Location

Using invalid strings for the CRS projection identifications will generate an error message. Make sure you are using a correct CRS definition as defined on https://epsg.io/.

In the screenshot below, the geometry is flat, then modeled in a projected CRS. The EPSG Code 32617 is for UTM North Zone 17, and the coordinates correspond to a location near Epic Games HQ. EPSG:4326 is the WGS84 ellipsoid, meaning that all geographic coordinates in latitude, longitude, and altitude will be defined in relation accordingly.

For floating point accuracy reasons, these origin values have to be integers to avoid bad roundings. Consider this constraint when modeling your environment. Internally, the Georeferencing plugin does all its computations in double precision to maintain accuracy at any planet location.

When Round Planet is selected, an extra checkbox is displayed to set up your origin location.

• If you check Origin at Planet Center, it means that you are using the ECEF case. The origin is explicitly defined at the planet center as described previously, and no further information is required.
• Otherwise, you can set the Level Origin at an arbitrary location on the ellipsoid using the CRS of your choice.

Converting Coordinates

In order to convert coordinates, you need to access the Georeferencing system, then call one of the functions in the Georeferencing category.

The possible conversions are explained in the picture below.

It is important you remember the Georeferencing system works in double precision, and cannot directly expose the coordinates in the Blueprint system that only support single precision floating values. The system outputs specific structures (FCartesianCoordinates, FGeographicCoordinates), and we recommend using these structures during all computations, then getting their float approximations at the final step.

Unreal Engine CRS is your level coordinate system. Every Actor has its coordinates in FVector variables. The first step is for you to transform these coordinates into a Georeferenced CRS, but still using Cartesian coordinates, (ECEF or Projected), depending on your case. You then have the ability to convert this location to geographic coordinates.

When you transform Unreal Engine coordinates into Projected or ECEF coordinates, the computation path depends on the Flat Planet / Round Planet property.

For example, if you are on a Round Planet and ask for an Engine to Projected conversion, it first converts the coordinates to ECEF (basic translation), then to Projected (complex projection). These intermediate steps are illustrated by the Green and Red circular arrows. That means, if you are interested in getting the geographic coordinates only, the optimal path for performance will be UE > ECEF > Geographic if you are on a Round Planet, and UE > Projected > Geographic on a Flat Planet.

Obtaining Values

Once you have the FCartesianCoordinates or FGeographicCoordinates, you have different options to get the values:

• In Blueprint, by calling ToFloatApproximation (this approximation corresponds to the conversion from double precision to Blueprint single precision).
• By using custom C++ code to do your own processing; if you want to maintain the full double precision, we recommend getting these values by writing functions that will directly take one of the FCartesianCoordinates or FGeographicCoordinates structures.
• By converting them to a display text, with possible rounding options.

Tangent Vectors and Transforms

You can use the Georeferencing system to get the Tangent vectors (East, North, Up) expressed in the Unreal Engine CRS by using the Get ENUVectors at Geographic Location node. You can use this, for example, to move a pawn that will follow the planet surface.

You can also get the Tangent Transform at any location on the planet using the Get Tangent Transform at Geographic Location node. Combining this transformation with a local object transformation will get the world-space transformation of your object to the Unreal Engine CRS.

A very specific function node is also provided: Get Planet Center Transform. If you have your own ellipsoidal planet mesh that you want to position in a way that it will be tangent to the origin that you declared in your Georeferencing settings, call this function to set this Actor transformation and it will be oriented to the location you defined.

Additional Tools and Content

The Georeferencing system comes with additional tools located in the Georeferencing Content folder in the Content Browser. You can display these if you select Show Plugin Content in the View Options dropdown menu.

Georeferencing Status Bar

You can find a sample UMG widget in /GeoReferencing/UI/UMG_GeoStatusBar, which, once added to the viewport, will display the current view location in various CRS: Projected, Geographic, and ECEF.

You can duplicate it and customize it to your liking.

Coordinates Inspector Utility Widget

You can find a special Editor Utility Widget in /GeoReferencing/UtilityWidgets/EUW_CoordinatesInspector. If you run it inside the editor, it displays a panel where you can control the georeferenced coordinates of your view, and of the point located under your mouse.

Location Probes and Rebasing Actors

In the GeoReferencing/Models/LocationProbe/BP_LocationProbe folder, you can find a BP_Location Probe Blueprint for performing in-game coordinate measurements.

Drop it in your level, add it to any location, and it will display its coordinates in each CRS.

You can even spawn a grid of probes using one of the provided Spawner Blueprints to automate the process.

To deal with large coordinates, you can have Unreal Engine shift the origin to ensure accuracy.

This rebasing system is automatically used during World Composition, but you can also control it directly. For that purpose, a BP_Rebasing Actor is provided as an example to demonstrate how you can control this system.

The Georeferencing system always considers the current origin offset in its computations.