EDN: ESRI Developer Network
Supported with: ArcGIS Engine with 3D Analyst Extension, ArcGIS Desktop with 3D Analyst Extension
Library dependencies: System, SystemUI, Carto, Display, Geometry, Output, GeoDatabase, DataSourcesFile, DataSourcesGDB, DataSourcesRaster, Controls, Animation
The 3DAnalyst library contains objects for working with 3D scenes, in a similar way that the Carto library contains objects for working with 2D maps. The Scene object is one of the main objects of the library; it is the container for data similar to the Map object. The Camera object specifies how the scene is viewed regarding the positioning of the features relative to the observer. A scene consists of one or more layers that specify the data in the scene and how the data is drawn. The 3DAnalyst library provides the base for customization of the scene. Although it also addresses some aspects of globe (see the GlobeCore library for more details).
The objects that implement this functionality are grouped into a number of library subsystems. These library subsystems are:
Note, a SceneControl and a set of scene commands exists in the Controls Library, together with a ToolbarControl, TOCControl and helper objects for creating your own custom commands.
The Scene coclass is central to 3D Analyst and allows you to access the 3D view and the data it contains. Although developers can directly make use of the Scene object in their applications, it is more common for developers to use a higher level object such as the SceneControl or ArcGIS desktop application. The higher level object allows the developer to fine control the 3D view and implements interfaces such as IScene, ISceneBookmarks, IAGAnimationTracks, and so on. There is only one Scene object instantiated in an ArcScene application or a scene control (or SceneControl). Contained in a Scene object, the SceneGraph coclass handles the 3D drawing/rendering functionalities. The general relationship is shown in the following diagram.
'To get the Scene object from within ArcScene's VBA IDE: Dim pDoc As ISxDocument: Set pDoc = ThisDocument Dim pScene As IScene: Set pScene = pDoc.Scene 'Further actions...
ISceneHookHelper m_pSceneHookHelper;
IScene m_pScene;
..
public void OnCreate(object hook)
{
m_pSceneHookHelper = new SceneHookHelperClass ();
m_pSceneHookHelper.Hook = hook;
m_pScene = m_pSceneHookHelper.Scene;
}
The SceneGraph in 3DAnalyst, internally implemented as a directed acyclic graph (DAG), provides a hierarchical organization of the scene that makes some processes more efficient in 3D graphics applications. It performs three main functions:
In addition to these functions, the SceneGraph coclass also helps with the 3D rendering by implementing the IDisplay3D interface, which converts the layer data and symbology into drawing calls. Therefore, the SceneGraph coclass plays a pivotal role in visualization in 3D Analyst.
The SceneGraph coclass is often the access point to other 3D rendering-related coclasses. The most important interfaces that the SceneGraph coclass implements are ISceneGraph, IViewer3D, and IDisplay3D. Use ISceneGraph to handle general renderering operations, IViewer3D to manage scene viewers, and IDisplay3D to perform flashings, etc. Another useful interface is ISceneGraphEvents. If you need to make some OpenGL calls to assist your visualization, you could embed those calls in a BeforeDraw event or an AfterDraw event. The following code shows a common way to get a handle of the SceneGraph.
'To get the SceneGraph: Dim pScene As IScene Set pScene = GetScene() Dim pSG As ISceneGraph Set pSG = pScene.SceneGraph 'To get a camera of the active viewer: Dim pCam As ICamera Set pCam = pSG.ActiveViewer.Camera 'Some actions... 'To refresh/redraw all viewers: pSG.RefreshViewers 'To redraw an individual viewer (e.g. the active viewer), use pSG.ActiveViewer.Redraw True
//To get the SceneGraph IScene pScene = GetScene(); ISceneGraph pSG = pScene.SceneGraph; //To get a camera of the active viewer ICamera pCamera = pSG.ActiveViewer.Camera; //Some actions... //To refresh/redraw all viewers: pSG.RefreshViewers(); //To redraw an individual viewer (e.g. the active viewer), use pSG.ActiveViewer.Redraw(true);
There are several types of layers frequently used in scene including graphics, feature, TIN, and raster layers. Each of these layers can have their own 3D properties such as base height, extrusions etc., which are available on their respective layer property pages on the user interface. Through ArcObjects, you could get and set these properties and re-apply them to accommodate your specific 3D visualization needs. See the following diagram for their relationships.
Layer 3D properties should be accessed via LayerExtension collections. At ArcGIS 9.0, there's only one layer extension, of I3DProperties type, used by scene, so getting a handle of it is straight forward. The following code allows you to get a handle to the 3D properties of the first layer in the scene.
Dim pScene As IScene: Set pScene = GetScene();
Dim pFeatLyr As IFeatureLayer: Set pFeatLyr = pScene.Layer(0)
Dim p3DProp As I3DProperties
Dim pLyrExt As ILayerExtensions: Set pLyrExt = pFeatLyr
Dim i As Integer
For i = 0 To pLyrExt.ExtensionCount - 1
If TypeOf pLyrExt.Extension(i) Is I3DProperties Then
Set p3DProp = pLyrExt.Extension(i)
Exit For
End If
Next i
'Get/Set the feature layer 3D properties:
With p3DProp
'Actions...
End With
IScene pScene = GetScene();
IFeatureLayer pFeatLyr = (IFeatureLayer) pScene.get_Layer(0);
I3DProperties p3DProp = null;
ILayerExtensions pLyrExt = (ILayerExtensions) pFeatLyr;
for(int i=0; i<pLyrExt.ExtensionCount; i++)
{
if(pLyrExt.get_Extension(i) is I3DProperties)
{
p3DProp = (I3DProperties) pLyrExt.get_Extension(i);
break;
}
}
//Get or set the feature layer 3D Properties.
p3DProp.SmoothShading = true;
Scene exporters are used to convert scenes to formats usable in other applications. Available exporters include VRMLExporter, AVIExporter, and QuickTimeExporter. The VRML exporter, for use in scene only, converts the scene to VRML 2.0 format. This is an open, industry-standard, 3D graphics format. The AVI and QuickTime exporters can be used in both scene and globe. These convert the animation defined in a document to one of these two common video formats.The following diagram shows that all three coclasses implement the ISceneExporter3D interface.
At ArcGIS 9.2, animations in scene can be created using ArcObjects available in the newly introduced Animation library. It is important to note here that the ArcObjects in the 3DAnalyst library used for creating animations at ArcGIS 9.0/9.1 can still be used to export the animations to AVI or QuickTime formats but, it is highly recommended that you use the new objects in the Animation library for ArcGIS 9.2 projects. Please see the Animations section below.
The following code shows the minimum way to export the scene to a VRML model. The assumption is that you have some data already added to the scene. The script exports a VRML model, all using the default settings. If you want to use your own customized settings, query interface (QI) to ISceneVideoExporter and IVRMLExporter for VRMLExporter.
Dim pScene As IScene Set pScene = GetScene() Dim pSV As ISceneViewer Set pSV = pScene.SceneGraph.ActiveViewer 'Export VRML: Dim pVRML As ISceneExporter3d Set pVRML = New VRMLExporter pVRML.ExportFileName = "D:\temp\test.wrl" pVRML.ExportScene pScene
IScene pScene = GetScene(); ISceneViewer pSV = pScene.SceneGraph.ActiveViewer; //Export VRML ISceneExporter3d pVRML = new VRMLExporterClass(); pVRML.ExportFileName = "C:\\temp\\test.wrl"; pVRML.ExportScene(pScene);
The scene viewer represents a 3D display window in scene. The equivalent in ArcGlobe is the globe viewer. Both application programs support one or more viewers. The primary viewer is displayed in the main application window. Sub-viewers are opened in separate floating windows. The viewer with current focus is referred to as the ActiveViewer. The perspective of a scene viewer is controlled by the Camera of the Scene (the equivalent for Globe is GlobeCamera). I3DViewer extracts some common properties and methods applicable to both scene and globe viewers and adds others, for example, full screen viewing, so it can be used by both a Scene and a Globe. The following diagrams illustrate these relationships.
| Scene and Scene viewer | Globe and Globe viewer |
|---|---|
 |
 |
The following code shows a way to get the Camera object using both the ISceneViewer and I3DViewer interfaces. The usage for both interfaces is very similar. The camera object returned turns out to be the same using either interface because both pointers (pSV and p3DV) are pointing to the same viewer (the currently active viewer) and there's only one camera object for each viewer.
Dim pScene As IScene: Set pScene = GetScene() Dim pSG As ISceneGraph: Set pSG = pScene.SceneGraph Dim pSV As ISceneViewer: Set pSV = pSG.ActiveViewer Dim p3DV As I3DViewer: Set p3DV = pSG.ActiveViewer Dim pCam1 As ICamera: Set pCam1 = pSV.Camera Dim pCam2 As ICamera: Set pCam2 = p3DV.Camera MsgBox pCam1 Is pCam2 'returns True
IScene pScene = GetScene();
ISceneGraph pSceneGraph = pScene.SceneGraph;
ISceneViewer pSceneViewer = pSceneGraph.ActiveViewer;
I3DViewer p3DViewer = (I3DViewer) pSceneGraph.ActiveViewer;
ICamera pCam1 = pSceneViewer.Camera;
ICamera pCam2 = p3DViewer.Camera;
if(pCam1.Equals(pCam2)) MessageBox.Show("pCam1 is equal to pCam2");
3D symbols provide enhanced capabilities for feature representation in 3D viewing environments. There are several types of 3D symbols for points, polylines, and polygons. They offer simple geometry primitives like cubes, spheres, and tubes. They can also use complex and textured geometry, like models of buildings or planes. This variety of capabilities is useful for the more abstract demands of scientific visualization as well as photo-realism for simulation. Supported 3D marker symbols are SimpleMarker3DSymbol, Marker3DSymbol, and CharacterMarker3DSymbol. Supported 3D line symbols are SimpleLine3DSymbol and TextureLineSymbol. TextureFillSymbol is used for polygons. The following diagram provides an overview of these symbols. For a detailed view of these 3D symbol components, please refer to the 3DAnalyst Object Model diagram.
TextureLineSymbol and TextureFillSymbol have one associated GeometryMaterial; it can be read and set (by reference) using the symbol's Texture property. A 3D marker symbol can have multiple instances of GeometryMaterial. Each is maintained by the GeometryMaterialList coclass that is associated with a Multipatch geometry. This, in turn, can be instantiated by using the GeneralMultipatchCreator coclass or imported using the Import3DFile coclass. In fact all symbol templates stored in the ESRI-provided 3D Marker Symbol styles are created by using either the GeneralMultipatchCreator coclass or the Import3DFile coclass. The end result of using these two coclasses is a MultiPatch geometry that, when used with GeometryMaterial, can have color, texture (that is, image), or both. To get the properties of a MultiPatch geometry, whether its textured or not, you would need to use the IGeneralMultipatchInfo interface of the Multipatch coclass from the Geometry library. Beginning with ArcGIS 9.0, a Multipatch can be persisted as the geometry (shape) of a feature in a feature class in either a personal geodatabase (*.mdb) or in ArcSDE. The same geometry, if persisted as the shape of a feature in a shapefile, would lose its GeometryMaterial (color and texture).
The following code allows you to get the GeometryMaterial count for the first feature of the first layer (assuming it is a feature layer) in the scene. It shows both ways to query the property when the layer itself consists of a textured multipatch feature class (query multipatch geometry property) or just a point feature layer symbolized using a 3D marker symbol (query 3D marker symbol property).
Dim pScene As IScene: Set pScene = GetScene()
Dim pFeatLyr As IFeatureLayer: Set pFeatLyr = pScene.Layer(0)
Dim pFeatCls As IFeatureClass: Set pFeatCls = pFeatLyr.FeatureClass
Dim pFeatCur As IFeatureCursor: Set pFeatCur = pFeatCls.Search(Nothing, True)
Dim pFeature As IFeature: Set pFeature = pFeatCur.NextFeature
If pFeatCls.ShapeType = esriGeometryMultiPatch Then 'Textured Multipatch
Dim pMltPchInfo As IGeneralMultiPatchInfo: Set pMltPchInfo = pFeature.Shape
MsgBox "Material Count in the 1st Feature of the 1st Layer: " & pMltPchInfo.MaterialCount
ElseIf pFeatCls.ShapeType = esriGeometryPoint Then 'Point Feature Layer
Dim pGeoFeatLyr As IGeoFeatureLayer: Set pGeoFeatLyr = pFeatLyr
Dim pRenderer As IFeatureRenderer: Set pRenderer = pGeoFeatLyr.Renderer
Dim pSymbol As ISymbol: Set pSymbol = pRenderer.SymbolByFeature(pFeature)
If TypeOf pSymbol Is IMarker3DSymbol Then '3D Marker Symbol
Dim p3DMarker As IMarker3DSymbol: Set p3DMarker = pSymbol
MsgBox p3DMarker.MaterialCount
End If
End If
IScene pScene = GetScene();
IFeatureLayer pFeatLyr = (IFeatureLayer) pScene.get_Layer(0);
IFeatureClass pFeatCls = pFeatLyr.FeatureClass;
IFeatureCursor pFeatCur = pFeatCls.Search(null,true);
IFeature pFeature = pFeatCur.NextFeature();
//If Textured Multipatch
if(pFeatCls.ShapeType == esriGeometryType.esriGeometryMultiPatch)
{
IGeneralMultiPatchInfo pMltPchInfo = (IGeneralMultiPatchInfo) pFeature.Shape;
MessageBox.Show(string.Format("Material Count in the 1st Feature of the 1st Layer: {0} ", pMltPchInfo.MaterialCount));
}
//Else if Point Feature Layer
else if(pFeatCls.ShapeType == esriGeometryType.esriGeometryPoint)
{
IGeoFeatureLayer pGeoFtrLyr = (IGeoFeatureLayer) pFeatLyr;
IFeatureRenderer pRenderer = pGeoFtrLyr.Renderer;
ISymbol pSymbol = pRenderer.get_SymbolByFeature(pFeature);
//if 3D Marker Symbol
if(pSymbol is IMarker3DSymbol)
{
IMarker3DSymbol p3DMarker = (IMarker3DSymbol) pSymbol;
MessageBox.Show(p3DMarker.MaterialCount.ToString());
}
}
Animations allow you to create dynamic visual effects by storing actions (behavior of objects), which can replayed later. In scene, you can create animations to visualize changes in the view, in the scene properties, in the layer properties, and temporal changes in the data.
At ArcGIS 9.2, animations can be created using using the newly introduced Animation library. It is important to note here that the ArcObjects in the 3DAnalyst library used for creating animations at ArcGIS 9.0/9.1 can still be used and existing projects using these objects should still compile. If you see any issues with compilation of projects, please make sure that you reference the new Animation library. However, it is highly recommended that you use the new objects in the Animation library for ArcGIS 9.2 projects.
As described in the Animation library overview, an animation consists of one or more animation tracks (AGAnimationTracks) which control changes of the properties of an object, such as the scene's background color, the visibility of a layer, or a camera location. Each track is associated to a certain AGAnimationType. AGAnimationType; AGAnimationTypeCamera, AGAnimationTypeLayer, AGAnimationTypeScene, AGAnimationTypeTimeLayer are available out-of-the-box in scene. Developers can optionally implement their own custom types.