Cesium for Unreal v1.7.0 has been released. Here’s a guide to upgrading

[agallegos]

Cesium for Unreal v1.7.0 was just released, bringing improvements to performance and workflow. This release also changed how sublevels work with Cesium for Unreal, and renamed/removed some C++ functions. Read on to learn how these changes may impact your existing projects, and how to use the new workflows.

Want to see the full changelog? Find it here.

Using Sublevels
Previously, you would have to manually check for sublevels to add them to the Georeference, and you’d have to switch between them using a parameter on the Georeference. Here’s how this workflow has changed:

• Changing the active Sublevel
  Changing the active Sublevel is much easier than before. Simply double-click on the level in the Levels panel. The Jump to Current Level button has been removed.
  In the Cesium Sublevels section of the Details of CesiumGeoreference, you’ll see a new Enabled parameter.
  
  This parameter allows you to ignore a sublevel during play without removing it entirely. It also affects how the camera moves when switching between sublevels.

  • If Enabled is checked on a sublevel, when you switch to that level the main Georeference Origin will automatically change to the sublevel’s origin, and the camera will be at the location of the sublevel.
  • If Enabled is NOT checked on a sublevel, the camera and main Georeference Origin will not change when you double-click on that sublevel. This can be useful if you need to set a sublevel’s origin to where your camera currently is. As such, the Place Georeference Origin Here button will still change the origin of a sublevel if Enabled is not checked. Using this button will automatically change Enabled to true.

• Adding a new Sublevel
  When creating a new sublevel, use the Levels window. Unlike in the previous workflow, you do not have to set the Georeference Origin prior to creating the level - you’ll do it later. After your new sublevel is created, make sure to set it to the correct Layer.
  You’ll see that your new level has automatically appeared on the Georeference.
  Double-click it in the Levels panel to set it as the active sublevel. The name of the level should become blue and bold, and you’ll see the level name in the lower right side of the viewport.
  

  
  
  Once that level is active, you can use the Place Georeference Origin Here button to set the origin of your sublevel.

• Changing a Sublevel’s Georeference Origin
  The Place Georeference Origin Here button on the CesiumGeoreference Actor will always set the origin of the active sublevel, even if the Enabled parameter on the sublevel is not checked. This means it’s easier to change the location of a sublevel by mistake. If you want to avoid changing the position of any sublevels, be sure the Persistent Level is the active level before changing the Georeference Origin. If you make a mistake in changing the Georeference Origin, you can use Ctrl-Z/Undo.
  You no longer have to manually edit the longitude, latitude, and height of the sublevel in the Details panel, though you still can if you would like. Be advised that changing the sublevel’s origin manually will not change the main Georeference Origin, and so you will not see the camera view change until you switch to another level and back.

• Cesium Tilesets and Actors in Sublevels
  If you were previously using Cesium tilesets or other actors inside of sublevels, the plugin would automatically create a CesiumGeoreference inside the sublevel. Now, tilesets and Cesium actors in sublevels can use the CesiumGeoreference in the persistent level. You should remove any instances of CesiumGeoreference or CesiumCreditSystem from sublevels.

CesiumSunSky
CesiumSunSky has undergone the following changes that may be confusing to those familiar with the old system:

• CesiumSunSky has been converted from Blueprints to C++. All variables and functions are still accessible via Blueprint.
• The CesiumGeoreference Actor no longer has a SunSky property - Connecting the CesiumSunSky and CesiumGeoreference should now be done on the CesiumSunSky actor.
• There’s a new parameter in the Details panel of CesiumSunSky called Update Atmosphere At Runtime, which is enabled by default. When this is enabled, the SkyAtmosphere will automatically adjust its radius to avoid the atmospheric artifacts that can appear when viewing the world from a distance. If you notice that the atmosphere is changing in a way that negatively impacts your project, disable it here. Disabling this setting may also improve performance.

CesiumGeoreference Component
The CesiumGeoreference component has been renamed to CesiumGlobeAnchor component. The Georeference property of GlobeAwareDefaultPawn, DynamicPawn, and CesiumSunSky is now accessed through each actor’s CesiumGlobeAnchor component.

CesiumGeoreference C++ Changes
Some C++ functions in CesiumGeoreference have changed. If you’re using any of the below functions, be sure to adjust your code accordingly. If you were previously accessing them via Blueprint, they should redirect automatically.

The following Blueprints and C++ functions on CesiumGeoreference have been renamed.

• TransformLongitudeLatitudeHeightToUe to TransformLongitudeLatitudeHeightToUnreal
• InaccurateTransformLongitudeLatitudeHeightToUe to InaccurateTransformLongitudeLatitudeHeightToUnreal
• TransformUeToLongitudeLatitudeHeight to TransformLongitudeLatitudeHeightToUnreal
• InaccurateTransformUeToLongitudeLatitudeHeight to InaccurateTransformUnrealToLongitudeLatitudeHeight
• TransformEcefToUe to TransformEcefToUnreal
• InaccurateTransformEcefToUe to InaccurateTransformEcefToUnreal
• TransformUeToEcef to TransformUnrealToEcef
• InaccurateTransformUeToEcef to InaccurateTransformUnrealToEcef
• TransformRotatorUeToEnu to TransformRotatorUnrealToEastNorthUp
• InaccurateTransformRotatorUeToEnu to InaccurateTransformRotatorUnrealToEastNorthUp
• TransformRotatorEnuToUe to TransformRotatorEastNorthUpToUnreal
• InaccurateTransformRotatorEnuToUe to InaccurateTransformRotatorEastNorthUpToUnreal

The following C++ functions on CesiumGeoreference have been removed:

• GetGeoreferencedToEllipsoidCenteredTransform and GetEllipsoidCenteredToGeoreferencedTransform moved to GeoTransforms, which is accessible via the getGeoTransforms function on CesiumGeoreference.
• GetUnrealWorldToEllipsoidCenteredTransform has been replaced with TransformUnrealToEcef except that the latter takes standard Unreal world coordinates rather than absolute world coordinates. If you have absolute world coordinates, subtract the World’s OriginLocation before calling the new function.
• GetEllipsoidCenteredToUnrealWorldTransform has been replaced with TransformEcefToUnreal except that the latter returns standard Unreal world coordinates rather than absolute world coordinates. If you want absolute world coordinates, add the World’s OriginLocation to the return value.
• AddGeoreferencedObject should be replaced with a subscription to the new OnGeoreferenceUpdated event.

If you’re experiencing other problems after updating to the latest plugin version, let us know here!

[creplogle]

These are definitely breaking changes for C++ projects. I don’t recommend upgrading without researching first. Specific examples, that I admit are documented in the changelog as breaking changes, are not adequately addressed. For example, the GetUnrealWorldToEllipsoidCenteredTransform and GetEllipsoidCenteredToUnrealWorldTransform changes are particularly major issues as the recommended replacements (TransformUnrealToEcef and TransformEcefToUnreal aren’t really replacements. The original methods return a matrix, while the replacements return a vector. In my case I have code based on the aircraft track example that needs to compute the up vector for orienting a satellite. I’m not just transforming ECEF to Unreal, I need the transform matrix. The change log should be updated with examples that help users adapt to these types of significant changes or provide references to such examples. I changed my original code from

const glm::dmat4& ecefToUnreal = this->CesiumGeoreference->GetEllipsoidCenteredToUnrealWorldTransform();

to

const GeoTransforms& geoTransforms = this->CesiumGeoreference->GetGeoTransforms();
const glm::dmat4& ecefToUnreal = geoTransforms.GetEllipsoidCenteredToAbsoluteUnrealWorldTransform();

Last note, if your project fails to load in the editor due to missing DLL symbols, nuke your project/Binaries/Win64 directory and rebuild. That should fix the problem.

[Emil]

Thank you for this! Now my stuff works again! Searched everywhere (I thought) for that transform!

[creplogle]

Glad to help out.

[qsl888]

Can,t open project after update 1.7.0.
"nuke your project/Binaries/Win64 directory and rebuild. "
How to do ?

[qsl888]

can’t work 1.7.0…
How to recover 1.6.3 ?

[creplogle]

Use Windows Explorer or a command line and delete the entire Win64 directory under your project/Binaries directory. This isn’t anything you do inside the Unreal Editor, this is deleting a directory through Windows.