Display the globe (C++ API)

Learn how to set a basemap and display the globe by using the C++ API.

Global C++ API result

In this tutorial, you will create a global scene using a Web Map from ArcGIS Online as a basemap. The surface of the scene is defined with an elevation layer, and the camera is positioned to display an area of New York City.

Prerequisites

Before starting this tutorial, you should:

  1. Have an ArcGIS account and an API key to access ArcGIS Online services while you are developing. If you don't have an account, sign up for free.
  2. Ensure your development environment meets the system requirements.
  3. Take Install and setup steps, and create a new project, and select the C++ API as your scene setting option.

Steps

C++ applications need at least one Header file and a Source Code file (.h and .cpp).

You can find a sample header file in:

Use dark colors for code blocksCopy
 
1
Plugins\ArcGISMapsSDK\Source\ArcGISSamples\Public\SampleAPIMapCreator.h

And a sample C++ source code file in:

Use dark colors for code blocksCopy
 
1
Plugins\ArcGISMapsSDK\Source\ArcGISSamples\Private\SampleAPIMapCreator.cpp

Initialize the API

  1. Click on File on the Menu Bar and select New Level.

  2. Select Empty Level in the popup window.

    New Level

  3. Click Window in the menu bar and select World Settings.

    Open World Wettings

  4. Open Advanced under World and check the Enable Large Worlds.

    Enable Large Worlds

  5. To create these scripts in your project, you need to go to the content folder. Click Tools > New C++ Class.

  6. This will show the Choose Parent Class wizard. You want your script to attach to an Actor. Select All Classes and click on ArcGIS Actor under Actor, then click Next. ArcGIS Actor includes ArcGIS Maps SDK Subsystem Listener that allows you to use the editor mode.

    Choose Parent Class

  7. Name the Actor MapCreator and set where you like to place the Actor script. It can be set in the host project or in a different module. The Public/Private button will define whether this class will be public or private. Also, you can define the path where the file will be. After you fill out the parameters click Create Class.

    Name new Actor

  8. After Unreal Engine compiles the project, Visual Studio will automatically open the .h and the .cpp files.

Set up the project

Before working on the **.h** and the **.cpp** files, we will first set up the project.
  1. Navigate to your .cpp file folder. Create a PCH file with the .h suffix as follows:

    Use dark colors for code blocksCopy
              
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    #pragma once
    
    #include <assert.h>
    #include <atomic>
    #include <functional>
    #include <memory>
    
    #include "CoreMinimal.h"
    
    #include "ArcGISMapsSDK/API/Unreal/Dictionary.h"
  2. Open your_project_file.Build.cs file.

  3. Add this line of code after PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs; that points to your PCH file.

    Use dark colors for code blocksCopy
     
    1
    PrivatePCHHeaderFile = "Private/your_PCH_file.h";
  4. In PublicDependencyModuleNames.AddRange, add two modules as follows:

    Use dark colors for code blocksCopy
     
    1
    PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore" , "ArcGISMapsSDK","ArcGISSamples"});

Create header file

  1. When you create an ArcGIS Actor, you already have the necessary includes in the header file. Make sure you have ArcGISMapsSDK/Actors/ArcGISActor.h

  2. Set the default values for the Actor's properties and set it to public.

    Use dark colors for code blocksCopy
     
    1
    AMapCreator();
  3. Create the method that will execute your code. In our example, we named it CreateArcGISMap() and set it to private.

    Use dark colors for code blocksCopy
     
    1
    void CreateArcGISMap();
  4. For the editor mode, it's necessary to react to changes during the editor time. Add subsystem listener for the ArcGIS Map View Actor which is connected to the subsystem.

    Use dark colors for code blocksCopy
     
    1
    void OnArcGISMapViewChanged(AArcGISMapView* InArcGISMapView) override;

This is the complete source code for our header file:

Use dark colors for code blocksCopy
                         
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
#pragma once

#include "CoreMinimal.h"
#include "ArcGISMapsSDK/Actors/ArcGISActor.h"
#include "MapCreator.generated.h"

// The declaration of our Actor class
UCLASS()
class AMapCreator : public AArcGISActor
{
    GENERATED_BODY()

public:

    // Sets default values for this Actor's properties
    AMapCreator();

    // IArcGISMapsSDKSubsystemListener
    void OnArcGISMapViewChanged(AArcGISMapView* InArcGISMapView) override;

private:

    void CreateArcGISMap();

};

Include headers and add ArcGIS Renderer Component

  1. In your .cpp file, first, include all necessary headers.

    Use dark colors for code blocksCopy
                  
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    #include "MapCreator.h"
    
    #include "Engine/World.h"
    #include "Kismet/GameplayStatics.h"
    
    #include "ArcGISMapsSDK/BlueprintNodes/GameEngine/Elevation/ArcGISImageElevationSource.h"
    #include "ArcGISMapsSDK/BlueprintNodes/ArcGISRuntime/Geometry/SpatialReference.h"
    #include "ArcGISMapsSDK/BlueprintNodes/GameEngine/Layers/Base/ArcGISLayerCollection.h"
    #include "ArcGISMapsSDK/BlueprintNodes/GameEngine/Map/ArcGISMap.h"
    #include "ArcGISMapsSDK/BlueprintNodes/GameEngine/Map/ArcGISMapType.h"
    #include "ArcGISMapsSDK/BlueprintNodes/GameEngine/Map/ArcGISBasemap.h"
    #include "ArcGISMapsSDK/BlueprintNodes/GameEngine/Map/ArcGISMapElevation.h"
    #include "ArcGISMapsSDK/Components/ArcGISRendererComponent.h"
    #include "ArcGISPawn.h"
  2. In the constructor, change PrimaryActorTick.bCanEverTick to false for performance purpose. Create a new Renderer Component and attach it to your main Actor with this code:

    Use dark colors for code blocksCopy
              
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    AMapCreator::AMapCreator()
    {
    
       PrimaryActorTick.bCanEverTick = false;
       auto ArcGISRendererComponent = CreateDefaultSubobject<UArcGISRendererComponent>(TEXT("ArcGISRendererComponent"));
    
       AddOwnedComponent(ArcGISRendererComponent);
       SetRootComponent(ArcGISRendererComponent);
    
    }
    
  3. Call the method CreateArcGISMap() for the ArcGIS Subsystem Listener.

    Use dark colors for code blocksCopy
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    void AMapCreator::OnArcGISMapViewChanged(AArcGISMapView* InArcGISMapView)
    {
        AArcGISActor::OnArcGISMapViewChanged(InArcGISMapView);
    
        if (ArcGISMapView)
        {
        CreateArcGISMap();
        }
    }
    

Create ArcGIS map

  1. Create the CreateArcGISMap() function:

    Use dark colors for code blocksCopy
        
    1
    2
    3
    4
    void AMapCreator::CreateArcGISMap()
    {
    
    }
    
  2. Before adding GIS content to the function, go to your developer dashboard to get your API key.

  3. Now you start adding GIS content to the function. Go back to your code editor, and add the following code to configure an API key.

    Use dark colors for code blocksCopy
     
    1
    constexpr auto apiKey = "YOUR_API_KEY";
  4. Set the view mode with maptype by using ArcGIS Map Type enum and create ArcGIS Map.

    Use dark colors for code blocksCopy
      
    1
    2
    auto mapType = EArcGISMapType::Global;
    auto arcGISMap = UArcGISMap::CreateArcGISMapWithMapType(mapType);
  5. Then add a basemap layer with a basemap URL and the API key.

    Use dark colors for code blocksCopy
          
    1
    2
    3
    4
    5
    6
    // Add a basemap
    auto arcGISBasemap = UArcGISBasemap::CreateArcGISBasemapWithBasemapSource(
        "https://www.arcgis.com/sharing/rest/content/items/716b600dbbac433faa4bec9220c76b3a/data", apiKey);
    
    // Set the basemap
    arcGISMap->SetBasemap(arcGISBasemap);

    In this tutorial, you'll use Imagery Hybrid Web Map as a basemap. For formatting a Web Map URL used for ArcGIS Maps SDK for Unreal Engine, refer to ArcGIS REST API.

    If you want to use a raster tile layer (image tile layer) as a basemap, either with an online service or a local service, use the following code instead:

    Use dark colors for code blocksCopy
     
    1
    auto arcGISBasemap = UArcGISBasemap::CreateArcGISBasemapWithLayerSourceAndType("SERVICE_URL", EArcGISLayerType::ArcGISImageLayer, apiKey);
  6. Create a new ArcGISElevationLayer and set your map elevation with it.

    Use dark colors for code blocksCopy
        
    1
    2
    3
    4
    auto elevationSource = UArcGISImageElevationSource::CreateArcGISImageElevationSourceWithName(
        "https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer", "Elevation", apiKey);
    auto mapElevation = UArcGISMapElevation::CreateArcGISMapElevationWithElevationSource(elevationSource);
    arcGISMap->SetElevation(mapElevation);

    In this tutorial, you'll use Terrain3D as the elevation source. You can find more elevation layers in ArcGIS Online.

Create a camera

You will add ArcGIS Pawn in your level later in this tutorial. ArcGIS Pawn has ArcGIS Camera component and ArcGIS Location component to move the camera around. In this tutorial, you will set the camera position in this API source code.

  1. To populate the camera position values you configure in the ArcGIS Pawn, add the following lines.

    Use dark colors for code blocksCopy
      
    1
    2
    AArcGISPawn* arcGISPawn = Cast<AArcGISPawn>(UGameplayStatics::GetActorOfClass(GetWorld(), AArcGISPawn::StaticClass()));
    auto PawnLocationComponent = Cast<UArcGISLocationComponent>(arcGISPawn->GetComponentByClass(UArcGISLocationComponent::StaticClass()));
  2. Set the position of the camera. In this tutorial, you set the following values for the camera position.

    • Longitude: -74.054921
    • Latitude: 40.691242
    • Altitude: 3000000 Meters
    Use dark colors for code blocksCopy
      
    1
    2
    auto Position = Esri::GameEngine::Location::ArcGISPosition(-74.054921, 40.691242, 3000000, Esri::ArcGISRuntime::Geometry::SpatialReference::WGS84());
    PawnLocationComponent->SetPosition(Position);
  3. Set the rotation of the camera with the following values.

    • Heading: 65
    • Pitch: 0
    • Roll: 68
    Use dark colors for code blocksCopy
      
    1
    2
    auto Rotation = Esri::GameEngine::Location::ArcGISRotation(65, 0, 68);
    PawnLocationComponent->SetRotation(Rotation);
  4. Set the value for the ArcGISRendererViewOptions. If it's set to true you can change the layer's visibilities during the runtime.

    Use dark colors for code blocksCopy
     
    1
    FArcGISRendererViewOptions rendererViewOptions{ true };
  5. ArcGIS Map View Actor communicates with the ArcGIS Renderer Component that has the ArcGISRendererView to take care care of your camera and your map document. Set the RendererViewOptions and arcGISMap to the ArcGISMapView.

    Use dark colors for code blocksCopy
      
    1
    2
    ArcGISMapView->SetViewOptions(rendererViewOptions);
    ArcGISMapView->SetMap(arcGISMap);

You have created the C++ source code for an API scene. Compile the project and Unreal Engine will be automatically opened.

Set up ArcGIS Pawn

ArcGIS Pawn will use the values you have scripted with the C++ API.

  1. The sample pawn that comes with ArcGIS Maps SDK for Unreal Engine is located in the folder:

    Use dark colors for code blocksCopy
     
    1
    ArcGIS Maps SDK for Unreal Engine C++ Classes\ArcGISSamples\Public

    If you want to use a custom pawn, write your own in C++ script.

  2. Select ArcGIS Pawn and drag it into the level from the Content Browser.

    Pawn

Set up an ArcGIS Map View and add Actor to the level

**ArcGIS Map View** Actor will place your GIS content in Unreal Engine space, and you can enable/disable the editor mode and Mesh Colliders. In this tutorial, you will configure where your GIS content is to be placed at `0, 0, 0` of the game engine space.

You can find the ArcGIS Map View Actor here:

Plugins\ArcGIS Maps SDK for Unreal Engine C++ Classes\ArcGISSamples\Public\

  1. Drag the ArcGIS Map View Actor into the level.

    ArcGISMapView Actor

  2. Configure the Origin Position with a WKID for the values. In this tutorial, you are setting up the following Origin Position values for New York City.

    • Longitude: -74
    • Latitude: 40
    • Spatial Reference WKID: 4326
    • Altitude: 0

    This is the result of the ArcGIS Map View Actor.

    ArcGIS Map View Result

  3. Locate the Map Creator Actor in the Content Drawer. Drag and drop the Actor you created into the level.

Set up the sky and the light

  1. From the quick add menu on the toolbar, select Lights > Directional Light and drag it into the level to create a Directional Light. For more information about Directional Lights, see Lights.

    Directional Light

  2. Select the Directional Light in the Outliner, and open the Transform section in the Details window.

  3. Reset the Location and Set the Rotation to:

    • X: 0
    • Y: -28
    • Z: -28
  4. Set the Mobility to Movable.

    Directional Light Transform

  5. In the Light section, change the Intensity Value to 3.1416.

  6. In the Cascaded Shadow Maps section, change the Dynamic Shadow Distance MovableLight from 20000 to 2000000.

  7. In the Atmosphere and Cloud section, enable Atmosphere Sun Light.

  8. In the Actor > Spawn Collision Handling Method section, select Always Spawn, Ignore Collisions.

    Directional Light Actor

  9. From the quick add menu on the toolbar, select Lights > Sky Light and drag it into the level to create a Sky Light. For more information about Sky Light, see Lights.

  10. In the Transform section, reset the Location and set the Mobility to Movable.

  11. In the Light section, enable Real Time Capture.

    SkyLight

  12. From the quick add menu on the toolbar, select Visual Effects > Sky Atmosphere and drag it into the level to create a Sky. For more information about Sky Atmosphere, see Fog Effects.

  13. In the Planet section, change the Ground Radius to 6378.137207.

When the light starts loading in the Viewport, you can see the render result in the editor Viewport. Double click on the ArcGIS Pawn in the Outliner panel to snap the editor camera to the camera position.

Use the WASD keys while holding the right mouse button mouse to move around, or hold the left mouse button to pan during the editor mode.

Click the Play icon on the Tool bar, and Use the WASD keys to move around, hold the right mouse button mouse to look around or hold the left mouse button to pan.

What's next?

To explore more features and learn how to use additional services, try these tutorials:

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.