Skip to main content

Using a Geospatially Accurate Sun

This tutorial will show you how to use the CesiumSunSky blueprint to enhance the realism of your project. A non-geospatially accurate sun may be suitable for many projects, but the real-world position of the sun is an important factor in industries like aerospace, simulation, urban planning, and AEC. In this tutorial, you’ll learn how to modify the sky, in both physically-accurate and artistic ways.

The first four sections of this page show the process for setting up a level with CesiumSunSky. The sections afterward detail the various components that make up CesiumSunSky. To get straight to the component reference, click the “Reference: Component Breakdown” header in the left sidebar.

The CesiumSunSky actor is derived from the Sun Position Calculator plugin. The documentation page on the Sun Position Calculator explains many of the features of this actor, but read on to learn how the Cesium version works together with other Cesium for Unreal actors.

You’ll learn how to:

  • Understand the CesiumSunSky Actor and how it interacts with the Georeference
  • Create a scene with a geospatially accurate sky
  • Modify the time of day with Blueprints and change time of day during play
  • Use emissive materials with physically-accurate lighting

Prerequisites

  • Unreal Engine (at least 4.26 or later) and the Cesium for Unreal plugin are installed.
Information

See the Cesium for Unreal Quickstart to learn how to install Cesium for Unreal and connect it with Cesium ion.

1Create a basic level

See the Quickstart for detailed instructions.

1Create a new blank level.

2Using the Cesium window, add Cesium World Terrain + Bing Maps Aerial imagery. Then, add CesiumSunSky.

Now, the scene has a world and lighting. However, it isn’t yet geospatially accurate.

Information

Is your scene bright white with the CesiumSunSky actor added? If so, open your Project Settings. Search “Extend default luminance range”. You’ll want to ensure the “Extend default luminance range in Auto Exposure” option is checked. To learn more about why this happens and the implications, visit the section Reference: Directional Light and Sun Intensity below.

2Ensure Sun Position Accuracy

1In the World Outliner, select the CesiumSunSky actor. In the Details panel, you’ll see the following parameters:

Like the CesiumGeoreference, the CesiumSunSky uses Latitude and Longitude coordinates. It’s possible to set these manually, but connecting CesiumSunSky to the Georeference will automatically set these coordinates.

2If you add CesiumSunSky through the Cesium panel, it will automatically connect itself to the Georeference, and this step is optional.
In the World Outliner panel, select CesiumGeoreference-1. Open the Cesium Sun Sky dropdown in the Details panel, and select CesiumSunSky from the menu that appears.

You’ll notice that the sky changed slightly. Now that the Georeference has a reference to CesiumSunSky, it will move and edit CesiumSunSky as needed. If you open the CesiumSunSky actor again, you’ll see that the coordinates have been updated to match the Georeference. Note that you can still edit the Latitude and Longitude values on the CesiumSunSky directly, but they will now be reset whenever the Georeference updates.

3There’s one more setting that will need to be changed for accuracy. Right below the parameters for Latitude and Longitude, find the Time Zone parameter. The default Georeference location is Denver, Colorado, USA. For this location, set the Time Zone to -6.0. The Time Zone parameter represents the time offset from Greenwich Mean Time (GMT).

Unlike Latitude and Longitude, the Time Zone is not set automatically by the Georeference. Time zones are not always the same along the same longitudes, and may be different for geopolitical reasons, such as Daylight Savings. In practice, the Time Zone parameter impacts the accuracy of the Solar Time setting. For full geospatial accuracy, take care to input the correct time zone for your location on the chosen date.

4Below the Time Zone parameter, you’ll see a section titled Date And Time. You’ll return to the Solar Time parameter in the next step. For now, take a look at the date options. The default date is September 21, 2019, but these parameters can be changed to represent any date. Right below the Month, Day, and Year parameters, you’ll find a small arrow. Click on this to open the advanced options.

The expanded Date options.

The SunSky will handle Daylight Savings Time switches automatically as long as the Use Daylight Saving Time parameter is checked. For full geospatial accuracy, ensure the values for DST Start Month, DST Start Day, DST End Month, DST End Day, and DST Switch Hour are correct for your location.

5Scroll back up in the Details panel to the top of the Date And Time section. At the top, you’ll see a parameter labeled Solar Time.

Now that the Latitude, Longitude, and Time Zone are set, you can use the Solar Time parameter to change the time of day accurately.

Information

Even if you aren’t creating an application that requires geospatial accuracy, it is still helpful to set the Time Zone when you change the Georeference Origin. If the Time Zone is incorrect, the Solar Time parameter will no longer align with the sun position and light level.

3Change Time Of Day In Play

You can use Blueprints to change the time of day at runtime. This requires a reference to the instance of CesiumSunSky in your level.

The image below shows an example Blueprint to change the time of day. First, you must set the Solar Time variable on CesiumSunSky with a float in the range from 0.0-22.0. Then, you must call the Update Sun function on CesiumSunSky.

If you are using the DynamicPawn or deprecated FloatingPawn as your Player Pawn, there is already a Widget set up to change the Solar Time.

1In the scene you created, open the World Settings window.

2Locate the setting GameMode Override.

3Select the dropdown, currently labeled “None”. From the menu that appears, select “FloatingGameMode”.

4Press the Play button.

5In game, press the T key on your keyboard to pull up the Time Of Day widget. This widget is a slider that can be used to change the Solar Time of Cesium SunSky.

6Pressing T also unlocked the mouse cursor. Click and drag the green button on the Time of Day slider and see how the sun changes. To close the Time of Day widget, press T again or use the X button on the widget.

Information

If the Time of Day slider doesn’t seem to align properly to a full sunrise-to-sunset range, make sure the Time Zone of the CesiumSunSky is set correctly.

4Use an Alternative Directional Light

In some situations, you may prefer to use a Directional Light actor that is placed in the scene as the sun, rather than the Directional Light within CesiumSunSky. You can instruct CesiumSunSky to use an alternative light by following the steps below.

1First, you’ll create a new Directional Light. If you already have an alternative Directional Light in your scene, you can skip this step. In the Place Actors panel, open the Lights tab. Click and drag a Directional Light into the scene.

2With the new Directional Light selected, open the Details panel. In the Transform section, set the Mobility to Movable. This will allow CesiumSunSky to control the angle of the light.

3Scroll down in the Details panel until you find the Atmosphere and Cloud section. Check the box Atmosphere Sun Light. This will ensure that the new Directional Light can be drawn in the atmosphere.

Information

Most of the other settings on the Directional Light can be set as you desire. For guidance on creating a physically-accurate sun, visit the Reference: Directional Light and Sun Intensity section below.

4Click on CesiumSunSky in the World Outliner. In the Details panel, locate the Sun section.

5Click on the dropdown next to Level Directional Light. From the menu that appears, select your new Directional Light.

6Check the box labeled Use Level Directional Light. If the new Directional Light is set to a lower Intensity, like 10 lux, the scene will temporarily go dark as the camera adjusts to the lower luminance, but it will go back to normal quickly.

This parameter will allow you to toggle between the two lights. It will disable the light that is not being used. When Use Level Directional Light is enabled, CesiumSunSky will set the angle of the Directional Light in the level based on the geographic location and time of day.

The level Directional Light’s Light Color has been set to pink for demonstration purposes.

Reference: Component Breakdown

At the very top of the Details panel, you’ll see a section showing the components of the CesiumSunSkyBlueprint.

SunSky is made up of three major components - SkyLightDirectionalLight, and SkyAtmosphere. The SkyLight has not been modified from the base SunSky actor in CesiumSunSky, and won’t be detailed on this page. However, it is still an important component for realistic lighting.

Using this components panel, you’ll be able to edit the values for these components in your scene. To get started, select the DirectionalLight.

Reference: Directional Light and Sun Intensity

The Directional Light component represents the sun. The angle of the Directional Light component is set automatically by the CesiumSunSky blueprint, based on the Solar Time value. There are many settings that can be tweaked on the Directional Light. The following sections will explain some of the most common ones that you may need to change, but does not cover every setting. For more information on directional lights, visit the Unreal Engine documentation page.

Information

The Directional Light on CesiumSunSky is set to Movable, and is a fully dynamic light. Movable lights have a high performance cost. If your level never requires the Georeference Origin or the Time of Day to change, consider creating a new Static or Stationary Directional LightSky Atmosphere, and Sky Light and assigning them the same values as the CesiumSunSky components, then removing CesiumSunSky from the level.

Sun Intensity

Take a look at the Intensity parameter on the Directional Light component. By default, this is set to 111000 lux - the approximate intensity of bright sunlight. Depending on the weather conditions and time of day of your project, you may wish to change this to a higher or lower value. However, for physically-accurate values, it’s best not to set this value above 120,000 lux.

The default intensity value for a directional light in Unreal Engine is 10.0. A value of 100,000+ is significantly larger, and as a result some assets may not behave as expected. Notably, unlit materials will appear dark when used in a scene with a physically-accurate sun intensity. If your project makes use of unlit or emissive materials, you’ll need to take additional steps to ensure these materials will render correctly.

Option 1: Raise values of emissive materials

If physical accuracy of your lighting is a priority, you can increase the intensity of emissive and unlit materials. Because the light intensity is about 10,000 times brighter than expected, emissive materials will also need to be about 10,000 times brighter in order to render as expected. This can be controlled by multiplying the emissive value of a material in the Material Graph.

An example material setup using the Unlit shading model.

Emissive multipliers from left to right: 1.0, 1110.0, 11100.0, 111000.0. The directional light intensity is 111,000.

Option 2: Lower the light intensity

If physically-accurate lighting is not a priority, it may be simpler to reduce the directional light intensity. Setting the Intensity of the Directional Light component to 10.0 will cause emissive and unlit materials to render as they would with a default Directional Light. However, the lights in your scene will no longer be physically accurate.

Information

Did your scene go black when you reduced the Intensity of the Directional Light, or bright white when you changed it back? The camera’s Auto Exposure takes a few seconds to adjust between the two luminance ranges. If you need to speed up this adjustment period, create a Post Process Volume.

In the following image, the emissive material property is using a multiplier of 1.0.

Left: Directional light intensity of 111,000. Right: Directional light intensity of 10.

If you decide to reduce the directional light intensity, keep in mind that it may be more difficult to maintain lighting accuracy when adding other light sources.

Information

To learn more about physically-based light units in Unreal Engine, visit the documentation.

Light color and temperature

Right below the Intensity parameter is the Light Color parameter. Double-clicking on the white bar will open a color picker.

Using this parameter, you can adjust the hue of the sun. Changing this value will not result in a physically-accurate sun, but this setting can be used to achieve various artistic effects.

Alternatively, you can use the Temperature value to set the color temperature. This setting is found below the previous settings, and the Use Temperature box must be checked in order to change the Temperature value.

Using Temperature instead of Light Color can help maintain a realistic look when changing the hue of the directional light.

Temperature of light from left to right: 3000, 6500, 12000.

Shadow distance

As you explore the world, you may notice that objects don’t appear to cast shadows until you are near to them. This allows for higher performance, but your project may require shadows at greater distances.

You can control the distance at which to draw shadows using the Dynamic Shadow Distance MoveableLight parameter in the Cascaded Shadow Maps section on the Directional Light component. Use the search function in the Details panel to quickly find this parameter.

Changing this value from 20,000 to 200,000 will result in shadows that are visible from a much greater distance. Bear in mind that this may come with performance drawbacks. 20,000 is the maximum value available on the slider, so higher values will need to be manually typed in.

While increasing the shadow distance helps with faraway shadows, it means that the shadows are lower resolution. If you are building a human-scale experience, a larger shadow distance may not be the best choice.

Top: Dynamic Shadow Distance 20,000. Bottom: Dynamic Shadow Distance 200,000.

If you require distant shadows and higher quality shadows up close, you’ll find the setting Num Dynamic Shadow Cascades under the Dynamic Shadow Distance. By default, this parameter is set to 5.

Raising this setting will allow higher resolution shadows, but will have a negative impact on performance. In addition, even with additional shadow cascades the shadows may not be as high-resolution as they would be with a lower Dynamic Shadow Distance.

Num Dynamic Shadow Cascades raised from 5 to 10.

Alternatively, you can raise the Cascade Distribution Exponent. This produces higher quality shadows near the camera, at the cost of faraway shadow quality.

Information

To learn more about dynamic shadows, visit the Unreal Engine Documentation.

Reference: Sky Atmosphere

The other major component of CesiumSunSky is the SkyAtmosphere component. Sky Atmosphere creates the appearance of an atmosphere and allows control over scattering and other density settings. This component is also responsible for drawing the sun in the sky.

With and without Sky Atmosphere enabled.

In CesiumSunSky, the Transform Mode of the component has been set to Planet Top at Component Transform in order to work properly with the Georeference. This setting, along with the fact that the atmosphere is set to movable, prevents the horizon line of the atmosphere from being too high and causing black bars on the horizon.

Like the Directional Light, the Sky Atmosphere has many parameters that can be adjusted to achieve different effects. Some of these settings are pictured above, and control atmospheric scattering.

Information

For a full summary of the Sky Atmosphere options, visit the Unreal Engine Documentation.

Next steps

Now that you know how CesiumSunSky works, check out the Lighting and Rendering Scenes tutorial to learn about post-processing and taking screenshots.

Content and code examples at cesium.com/learn are available under the Apache 2.0 license. You can use the code examples in your commercial or non-commercial applications.