Georeferencing a Level

How to use the georeferencing plugin to associate locations in a UE4 level map with locations in physical space

Windows
MacOS
Linux
On this page

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.

ellipsoid 3D model, axes relation diagram, and formula

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.

Geographic CRS representation

  • Latitude = Elevation in degrees to the Equator

  • Longitude = Azimuth in degrees to the Prime Meridian (Greenwich)

  • Altitude = Height in meters to the reference ellipsoid.

Angles are expressed in decimal degrees, or DMS (Degrees, Minutes Seconds).

There are, in fact, two kinds of latitude definitions; when the datum is not a sphere, local normal to the ellipsoid model is involved, 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.

Geocentric CRS representation

  • Origin = Earth center

  • X Axis points to the Equator/Prime Meridian (Greenwich) intersection.

  • Z Axis aligns with the Earth's axis of rotation.

  • Y Axis is orthogonal to the former two axes.

Coordinates are expressed in meters.

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.

planar-projection-1.png

cone-projection-1.png

cylinder-projection-1.png

planar-projection-2.png

cone-projection-2.png

cylinder-projection-2.png

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

For instance, we have the Universal Transverse Mercator projection that is 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.

Earth showing meridian zones Cylinder mapping to earth for the projection

This is a Cartesian coordinate system, but on top of the XYZ coordinates, we need a Zone and Hemisphere identifier to define the origin. Specific assumptions are necessary to make sure that 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.

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, each Actor has coordinates defined relative to this level origin, so to know an arbitrary georeferenced location, we need to locate the engine origin on Earth.

We will consider 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, we consider that the ground is modeled in a projected mode, and that all coordinates can be defined 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. In that case, we expect the geometry to 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, we make the assumption that 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:

    • The Level origin is located 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 the axes are aligned to the engine ones.

    • The Level origin is located at an arbitrary point on the planet surface. Like 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 the plane geometry is oriented in such a way that the Front and Right vectors are matching the North and East vectors.

Flat plane mapped to a round planet

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 inverses the Y coordinate at some point when converting coordinates (this is transparent to the end user).

We chose the following axes conventions:

flat coordinate axes convention

ecef coordinate axes convention

When the Unreal Frame is matching the Tangent Frame

When the Unreal Frame is matching the ECEF Frame

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

The system automatically handles the World Origin offset shifting that is activated 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.

Georeferencing plugin

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 System Actor

Property

Description

Geo Referencing

Planet Shape

Flat or Round. This depends only on your project geometry shape/scale.

Projected CRS

Identified by a string. Can be any CRS supported by the PROJ library. Refer to the https://epsg.io/ website to find appropriate CRS definitions.

Geographic CRS

Identified by a string. Can be any CRS supported by the PROJ library. Refer to the https://epsg.io/ website to find appropriate CRS definitions.

Origin Location

Origin Location in Projected CRS

Determines whether the Origin is defined using the Projected or the Geographic CRS coordinates.

Origin at Planet Center

Round Planet only. Determines whether the origin is defined as the planet center.

Origin Projected Coordinates Easting

Origin east-west coordinate when using Projected CRS coordinates.

Origin Projected Coordinates Northing

Origin north-south coordinate when using Projected CRS coordinates.

Origin Projected Coordinates Up

Origin up-down coordinate when using Projected CRS coordinates.

Origin Latitude

Origin north-south coordinate when using Geographic CRS coordinates.

Origin Longitude

Origin east-west coordinate when using Geographic CRS coordinates.

Origin Altitude

Origin up-down coordinate when using Geographic CRS coordinates.

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/.

Editor error message

Log error message

In the screenshot below, our 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.

Origin Location in Projected CRS enabled Origin Location in Projected CRS disabled

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 Origin at Planet Center is checked, it means that you are using the ECEF case. The origin is explicitly defined 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.

Origin at Planet Center enabled Origin at Planet Center disabled

Converting Coordinates

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

Find georeferencing Blueprint node

Georeferencing output function nodes 1 Georeferencing output function nodes 2

The possible conversions are explained in the picture below.

It is important to note that 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 will output specific structures (FCartesianCoordinates, FGeographicCoordinates), and we recommend using these structures during all computations, then getting their float approximations at the final step.

Conversion paths

Unreal Engine CRS is your level coordinate system. Every actor has its coordinates in FVector variables. The first step is 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 will first convert 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 that 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.

Optimal Blueprint paths for conversions

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.

Blueprint node options for obtaining values

Formatting

FCartesianCoordinates

FGeographicCoordinates

To Compact Text

({X}, {Y}, {Z})

({Latitude}, {Longitude}) {Altitude}m

With Latitude, Longitude possibly written as {Degree}° {Minutes}' {Seconds}"

To Full Text

X={X}, Y={Y}, Z={Z}

Latitude={Latitude} Longitude={Longitude} Altitude={Altitude}m

With Latitude, Longitude possibly written as {Degree}° {Minutes}' {Seconds}"

To Separate Texts

{X}

{Y}

{Z}

{Latitude}

{Longitude}

{Altitude}

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. This can be used, for example, to move a pawn that will follow the planet surface.

Get ENUVectors at Geographic Location Blueprint node

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.

Get Tangent Transform at Geographic Location Blueprint node

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.

Get Planet Center Transform Blueprint node

Additional Tools and Content

The Georeferencing system comes with additional tools that are located in the Georeferencing Content folder in the Content Browser. You will be able to display these if you select Show Plugin Content in the View Options dropdown menu.

Georeferencing Status Bar

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

Georeferencing widget

You can duplicate it and customize it to your liking.

Georeferencing widget in action in Viewport

Coordinates Inspector Utility Widget

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

Coordinates Inspector widget

Coordinates Inspector widget in action in Viewport

Location Probes and Rebasing Actors

In the GeoReferencing/Models/LocationProbe/BP_LocationProbe folder, a BP_Location Probe Blueprint is available to perform 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.

Location Probe and Rebasing Actors Location Probe Blueprints

Location Probes in action in Viewport

To deal with large coordinates, Unreal Engine is able to shift the origin to ensure accuracy.

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

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

Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Dismiss