ArcGIS Runtime SDK for iOS

Add features and graphics to a scene view

In ArcGIS Runtime SDKs, geo-elements are used to represent real-world objects on a map or scene. The two types of geo-element are features and graphics, each of which has a geometry representing its shape and location on the surface of the Earth. They can also contain a set of attributes that further describe the represented object.

You can add graphics to graphics overlays and add graphics overlays to either a map view or scene view. The way you add features and graphics to scenes follows the same steps required to add them to maps, with these additional considerations:

When to use features or graphics

Features and graphics are similar to one another in that they both have a geometry and may store a set of attributes. Both features and graphics can be:

Features and graphics, however, are designed for different uses. While both can represent geographic elements, there are factors that may make one of them a better choice for specific tasks. See Features and graphics for more information.

Add features to a scene view when you want to:

  • Display data with a common attribute schema (for example, census data)
  • Display geographical data of a common geometry type (point, line, or polygon)
  • Persist or store the data beyond the current app session

Add graphics to a scene view when:

  • You want to display temporary data, such as fast-changing, fast-moving data (for example, a fleet of airliners, or voluminous data).
  • You want to display data that doesn't share a common geometry type (such as point, line, or polygon) and doesn't share a common set of attribute fields
  • The data is required only for the current app session

Add features to a scene view

Feature layers can contain any number of features of a single geometry type (point, polyline or polygon). Adding features to a scenes is the same as adding features to a map:

  1. Add features to a feature layer
  2. If you want to include features' attributes (to run queries, for example), make sure to use LOAD_ALL if building your feature layer from a service feature table
  3. Add the feature layer to the scene's operational layers

Add graphics to a scene view

Adding graphics to scenes is the same as adding graphics to maps:

  1. Add graphics to a graphics overlay
  2. Set the graphic overlays surface placement, if you prefer a surface placement other than the default DRAPED
  3. Add the graphics overlay to the scene view's graphic overlays

Any graphic you add to a scene view must be constructed from a geometry with a spatial reference.

In 3D, you can add graphics such as points, polylines, polygons, and 3D marker symbols, all into the same graphics overlay or into multiple graphics overlays.

For additional details on adding graphic overlays to a map or scene, see Add graphic overlays to your app. For details on adding graphics to a graphics overlay, see Add graphics and text to graphics overlays.

//add a graphics overlay to the scene view    
@property (nonatomic, strong) AGSGraphicsOverlay *graphicsOverlay;
self.graphicsOverlay = [[AGSGraphicsOverlay alloc] init];
[self.sceneView.graphicsOverlays addObject:self.graphicsOverlay];

Surface placement modes

For both feature layers and graphics overlays, you can specify a surface placement mode or use the default mode of DRAPED. These modes control how the z-value of your geometry is used when features and graphics are drawn.

  • DRAPED—(default) Features and graphics are drawn on the surface. The z-value has no effect.
  • ABSOLUTE—Features and graphics are drawn at a height using the z-value referenced from above the globe skin (sea level).
  • RELATIVE—Features and graphics are drawn at a height using the z-value referenced from above the surface layer.

The following code shows three points drawn in graphics overlays in the three different surface placement modes. The red graphic is draped on the surface, the blue graphic is drawn in absolute mode, and the green in relative mode

// create a draped graphics overlay
self.drapedGraphicsOverlay = [[AGSGraphicsOverlay alloc] init];
self.drapedGraphicsOverlay.sceneProperties.surfacePlacement = AGSSurfacePlacementDraped;
[self.sceneView.graphicsOverlays addObject:self.drapedGraphicsOverlay];
// create a absolute graphics overlay
self.absoluteGraphicsOverlay = [[AGSGraphicsOverlay alloc] init];
self.absoluteGraphicsOverlay.sceneProperties.surfacePlacement = AGSSurfacePlacementAbsolute;
[self.sceneView.graphicsOverlays addObject:self.absoluteGraphicsOverlay];
// create a relative graphics overlay
self.relativeGraphicsOverlay = [[AGSGraphicsOverlay alloc] init];
self.relativeGraphicsOverlay.sceneProperties.surfacePlacement = AGSSurfacePlacementRelative;
[self.sceneView.graphicsOverlays addObject:self.relativeGraphicsOverlay];
//create a point and markers
AGSPoint *point = AGSPointMake3D(-4.04, 53.06, 1000, 0, self.sceneView.spatialReference);
AGSSimpleMarkerSymbol *greenMarker = [[AGSSimpleMarkerSymbol alloc] initWithStyle:AGSSimpleMarkerSymbolStyleCircle color:UIColor.greenColor size:10];
AGSSimpleMarkerSymbol *redMarker = [[AGSSimpleMarkerSymbol alloc] initWithStyle:AGSSimpleMarkerSymbolStyleCircle color:UIColor.redColor size:10];
AGSSimpleMarkerSymbol *blueMarker = [[AGSSimpleMarkerSymbol alloc] initWithStyle:AGSSimpleMarkerSymbolStyleCircle color:UIColor.blueColor size:10];
//add the graphics in the different overlays
AGSGraphic *drapedGraphic = [[AGSGraphic alloc] initWithGeometry:point symbol:redMarker];
AGSGraphic *absoluteGraphic = [[AGSGraphic alloc] initWithGeometry:point symbol:blueMarker];
AGSGraphic *relativeGraphic = [[AGSGraphic alloc] initWithGeometry:point symbol:greenMarker];
[ addObject:drapedGraphic];
[ addObject:absoluteGraphic];
[ addObject:relativeGraphic];

Graphics rendered at different heights, despite all having the same z-value.

Graphics drawn with different surface placement options

Renderers: Controlling symbology with attributes

Just as in 2D, both feature layers and graphic overlays can use various renderers, such as simple renderers and unique value renderers, to control symbology with attributes. For details, see Symbols and renderers.

When using renderers in 3D, you can set properties to define extrusion expressions for both features and graphics. However, only graphics can have rotation expressions.

To apply extrusion to a feature layer:

  1. Set the feature layer to rendering in DYNAMIC mode
  2. Define a renderer which will be used to render the feature layer
  3. Set the renderer's scene property extrusion mode
  4. Set the renderer's scene property extrusion expression
  5. Set the renderer to the feature layer
  6. Add the feature layer to the scene

Extrusion can also be applied to graphics overlays:

  1. Define a renderer which will be used to render the graphics overlay
  2. Set the renderer's scene property extrusion mode
  3. Set the renderer's scene property extrusion expression
  4. Set the renderer to the graphics overlay

// define fill and outline for symbol       
AGSSimpleLineSymbol *line = [[AGSSimpleLineSymbol alloc] initWithStyle:AGSSimpleLineSymbolStyleSolid color:UIColor.blackColor width:1];    
AGSSimpleFillSymbol *fill = [[AGSSimpleFillSymbol alloc] initWithStyle:AGSSimpleFillSymbolStyleSolid color:UIColor.greenColor outline:line];

// create a simple renderer
AGSSimpleRenderer *renderer = [[AGSSimpleRenderer alloc] initWithSymbol:fill];
// define the extrusion mode and expression
renderer.sceneProperties.extrusionMode = AGSExtrusionModeAbsoluteHeight;
renderer.sceneProperties.extrusionExpression = @"pop2000";
graphicsOverlay.renderer = renderer;

In the image below, a graphic overlay is being extruded based on a population attribute: pop2000.

County polygons extruded on population

Only graphics overlays can have rotation expressions--used to change the heading, pitch and roll of the graphics in the graphics overlay. To set rotation expressions:

  1. Define a renderer which will be used to render the graphics overlay
  2. Set the rotation type
  3. Set the renderer's scene property heading expression
  4. Set the renderer's scene property pitch expression
  5. Set the renderer's scene property roll expression
  6. Set the renderer to the graphics overlay

// create a simple renderer and set rotation expressions
AGSSimpleRenderer *renderer = [[AGSSimpleRenderer alloc] initWithSymbol:coneSymbol];
renderer.sceneProperties.headingExpression = @"heading";
renderer.sceneProperties.pitchExpression = @"pitch";
renderer.sceneProperties.rollExpression = @"roll";

3D-specific symbols for graphics

Graphics in a 3D graphics overlay can use any of the symbols discussed in Add graphics and text to graphics overlays. You can also add:

3D symbols

Add shape-based symbols

3D shapes, such as a cone, floating on the earth's surface.

The following code snippet shows how to create a sphere symbol and render it using a point geometry in a graphic.

// sphere symbol
AGSSimpleMarkerSceneSymbol *sphereSymbol = [[AGSSimpleMarkerSceneSymbol alloc] 
 initWithStyle:AGSSimpleMarkerSceneSymbolStyleSphere color:UIColor.redColor height:3000 width:3000 depth:3000 

// sphere point
AGSPoint *spherePoint = AGSPointMake3D(-4.04, 53.16, 1000, 0, self.sceneView.spatialReference);

// add graphic to graphics overlay    
AGSGraphic *sphereGraphic = [[AGSGraphic alloc] initWithGeometry:spherePoint symbol:sphereSymbol];
[ addObject:sphereGraphic];

Add model symbols

A model symbol provides a realistic three-dimensional visualization to symbolize scene features. These models define the geometry and surface textures of real-world items such as aircraft. Create a ModelSceneSymbol using a 3D model file, passing the path to the file and a scale factor to the model symbol constructor. The supported model file types include Collada (.dae), 3D Max (.3ds), Blender 3d (.blend), and the formats listed in the Open Asset Import Library (Assimp). Depending on the model file's default orientation, you may have to rotate the symbol to get your model in the desired orientation.


Model scene symbols cannot be used with a static graphics rendering mode.

Model symbol representing a helicopter

Create these model symbols using the ModelSceneSymbol class.

// create the model symbol from file
NSURL *URL = [[NSURL alloc] initFileURLWithPath:@".../A310_FedEx.dae"];
AGSModelSceneSymbol *modelSymbol = [[AGSModelSceneSymbol alloc] initWithURL: URL scale:3000];        
modelSymbol.roll = -30;
[modelSymbol loadWithCompletion:^(NSError * _Nullable error) {
 if (error != nil) {
  NSLog(@"%@", error.localizedDescription);
 } else {
  AGSPoint *modelPoint = AGSPointMake3D(-4.04, 53.16, 5000, 0, self.sceneView.spatialReference);
  AGSGraphic *modelGraphic = = [[AGSGraphic alloc] initWithGeometry:modelPoint symbol:modelSceneSymbol attributes:nil];
  [ addObject:modelGraphic];

When you add a model symbol file of type .dae into your project you must ensure that the file is of type Data. For each file in your project go to the File Inspector. Find the Type property and change it from Default = Digital Asset Exchange to Data. This will ensure that Xcode does not compress the file and it will be read correctly.

Distance composite symbols

While model symbols closely resemble the real-world object they represent when viewed close up, when you zoom away from them, the symbols gets smaller until they're no longer visible. If you want to see the location of your graphics at any distance from the camera, use distance composite symbols. These symbols allow you to use different symbols depending on the distance the graphic is from the camera.

The code snippet below the following images shows how to set up a distance composite symbol similar to the one shown in the images.

When the camera is far away from the point, a red simple marker symbol displays.

A simple point is displayed when the camera is far away

As you zoom closer to the point, the symbol renders as a cone pointing in the aircraft's direction of travel.

A cone symbol shows heading at intermediate camera distance

When viewed even closer, the point displays as a model symbol, which is appropriate at this distance from the camera.

A model symbol displays at the nearest camera distance