3DAnalyst


Supported with:
Library dependencies: System, SystemUI, Geometry, Display, Server, Output, Geodatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, DataSourcesNetCDF, GeoDatabaseDistributed, GeoDatabaseExtensions, Carto, NetworkAnalysis, Location, GeoAnalyst, Animation, Maplex, Geoprocessing, NetworkAnalyst, Schematic, SpatialAnalyst

Additional library information: Contents, Object Model Diagram

The 3DAnalyst library contains classes for working with 3D scenes, in a similar way that the Carto library contains classes for working with 2D maps. The Scene class is one of the main classes of the library; it is the container for data similar to the Map class. The Camera class 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).

See the following sections for more information about this namespace:

Scene

The Scene class is central to 3D Analyst and allows you to access the 3D view and the data it contains. Although developers can use the Scene object in their applications, it is more common for developers to use a higher level object, such as the SceneControl or an ArcGIS for Desktop application. The higher level object allows the developer to 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. Contained in a Scene object, the SceneGraph class handles the 3D drawing and rendering functionalities. The general relationship is shown in the following illustration:
A SceneControl and a set of scene commands exists in the Controls library with a ToolbarControl, TOCControl, and helper classes for creating custom commands.
When creating custom commands, tools, or menus, use the SceneHookHelper object, which makes it straightforward to create a command that works with the SceneControl, ToolbarControl, and the ArcScene application. The SceneHookHelper object is used to hold onto the hook and the ISceneHookHelper interface it implements can return the SceneViewer, Scene, SceneGraph, and Camera regardless of the type of hook that is passed.
The following code example (ICommand.create() method) shows how to get a handle to the scene using the SceneHookHelper:
[Java]
ISceneHookHelper sceneHookHelper;
IScene scene;
// ..
public void onCreate(Object hook)throws UnknownHostException, IOException{
    sceneHookHelper = new SceneHookHelper();
    sceneHookHelper.setHookByRef(hook);
    scene = sceneHookHelper.getScene();
}

SceneGraph

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 graphic applications and performs the following functions:
In addition to the preceding functions, the SceneGraph class also helps with 3D rendering by implementing the IDisplay3D interface, which converts the layer data and symbology into drawing calls; therefore, the SceneGraph class plays a pivotal role in visualization in 3D Analyst.
The SceneGraph class is often the access point to other 3D rendering related classes. The most important interfaces that the SceneGraph class implements are ISceneGraph, IViewer3D, and IDisplay3D. Use ISceneGraph to handle general renderering operations, IViewer3D to manage scene viewers, and IDisplay3D to perform flashings, and so on.
Another useful interface is ISceneGraphEvents. If you need to make some OpenGL calls to assist your visualization, you can embed those calls in a beforeDraw event or an afterDraw event. The following code example shows a common way to get a handle of the SceneGraph:
[Java]
// To get the SceneGraph.
IScene scene = getScene();
ISceneGraph sceneGraph = scene.getSceneGraph();
// To get a camera of the active viewer.
ICamera camera = sceneGraph.getActiveViewer().getCamera();
// Some actions.
// To refresh and redraw all viewers.
sceneGraph.refreshViewers();
// To redraw an individual viewer (the active viewer), use
sceneGraph.getActiveViewer().redraw(true);

3D properties

There are several types of layers frequently used in Scene including graphics, features, triangulated irregular networks (TINs), and raster layers. Each of these layers can have their own 3D properties, such as base height, extrusions, and so on; which are available on their respective layer property pages on the user interface (UI). Through ArcObjects, you can get and set these properties and reapply them to accommodate your specific 3D visualization needs. See the following illustration for their relationships:
Layer 3D properties should be accessed via ILayerExtensions. Currently, there is only one layer extension of I3DProperties type that is used by Scene; therefore, getting a handle to it is straightforward.
The following code example allows you to get a handle to the 3D properties of the first layer in the scene:
[Java]
IScene scene = getScene();

IFeatureLayer featureLayer = (IFeatureLayer)scene.getLayer(0);
I3DProperties i3DProperties = null;
ILayerExtensions layerExtensions = (ILayerExtensions)featureLayer;

for (int i = 0; i < layerExtensions.getExtensionCount(); i++){
    if (layerExtensions.getExtension(i)instanceof I3DProperties){
        i3DProperties = (I3DProperties)layerExtensions.getExtension(i);
        //Get or set the feature layer 3D Properties.
        i3DProperties.setSmoothShading(true);
        break;
    }
}

Scene exporters

Scene exporters are used to convert scenes to formats usable in other applications. Available exporters include VRMLExporter, AVIExporter, and QuickTimeExporter. The Virtual Reality Modeling Language (VRML) exporter, for use in Scene only, converts the scene to VRML 2.0 format. This is an open industry standard for 3D graphic formats. The Audio Video Interleave (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 illustration shows all three classes that implement the ISceneExporter3D interface:
At ArcGIS 9.2, animations in scenes can be created using ArcObjects available in the Animation library. The ArcObjects in the 3DAnalyst library used for creating animations at ArcGIS 9.0 and ArcGIS 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.
The following code example shows the minimum way to export the scene to a VRML model. The assumption is that you have data already added to the scene. The script exports a VRML model using the default settings. If you want to use your customized settings, use the ISceneVideoExporter and IVRMLExporter interfaces.
[Java]
IScene scene = getScene();

ISceneViewer sceneViewer = scene.getSceneGraph().getActiveViewer();
// ...

//Export VRML.
VRMLExporter vrmlExporter = new VRMLExporter();
vrmlExporter.setExportFileName("C:\\temp\\test.wrl");
vrmlExporter.exportScene(scene);

Scene and Globe viewer

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 displays in the main application window. Subviewers are opened in separate floating windows. The viewer with current focus is 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 illustration shows the relationship between the Scene and Scene viewer and the Globe and Globe viewer:
The following code example shows a way to get a Camera object using both the ISceneViewer and I3DViewer interfaces. The usage for both interfaces is very similar. The Camera object returned is the same using either interface because both pointers (pSV and p3DV) are pointing to the same viewer (the active viewer) and there is only one Camera object for each viewer.
[Java]
IScene scene = getScene();
ISceneGraph sceneGraph = scene.getSceneGraph();
ISceneViewer sceneViewer = sceneGraph.getActiveViewer();
I3DViewer i3DViewer = (I3DViewer)sceneGraph.getActiveViewer();
ICamera camera1 = sceneViewer.getCamera();
ICamera camera2 = i3DViewer.getCamera();
if (camera1.equals(camera2)){
    System.out.println("Camera 1 is equal to camera 2");
}

3D symbols

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, such as cubes, spheres, and tubes. They can also use complex and textured geometry, such as 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 illustration shows an overview of these symbols. For a detailed view of these 3D symbol components, see the 3DAnalyst Object Model diagram.
TextureLineSymbol and TextureFillSymbol have one associated GeometryMaterial (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 class that is associated with a Multipatch geometry. This, in turn, can be instantiated by using the GeneralMultipatchCreator class or imported using the Import3DFile class. All symbol templates stored in the ESRI provided 3D Marker Symbol styles are created by using the GeneralMultipatchCreator class or the Import3DFile class. The end result of using these two classes 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, use the IGeneralMultipatchInfo interface of the Multipatch class from the Geometry library. A multipatch can be persisted as the geometry (shape) of a feature in a feature class in 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). See the following illustration:
The following code example 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 consists of a textured multipatch feature class (query multipatch geometry property) or a point feature layer symbolized using a 3D marker symbol (query 3D marker symbol property).
[Java]
IScene scene = getScene();

IFeatureLayer featureLayer = (IFeatureLayer)scene.getLayer(0);
IFeatureClass featureClass = featureLayer.getFeatureClass();
IFeatureCursor featureCursor = featureClass.search(null, true);
IFeature feature = featureCursor.nextFeature();

//If textured multipatch.
if (featureClass.getShapeType() == esriGeometryType.esriGeometryMultiPatch){
    IGeneralMultiPatchInfo patchInfo = (IGeneralMultiPatchInfo)feature.getShape();
    System.out.println("Material Count in the 1st Feature of the 1st Layer: {0} " +
        patchInfo.getMaterialCount());
}

//Else, if point feature layer.
else if (featureClass.getShapeType() == esriGeometryType.esriGeometryPoint){
    IGeoFeatureLayer geoFeatureLayer = (IGeoFeatureLayer)featureLayer;
    IFeatureRenderer featureRenderer = geoFeatureLayer.getRenderer();
    ISymbol symbol = featureRenderer.getSymbolByFeature(feature);

    //If 3D marker symbol.
    if (symbol instanceof IMarker3DSymbol){
        IMarker3DSymbol p3DMarker = (IMarker3DSymbol)symbol;
        System.out.println(p3DMarker.getMaterialCount());
    }
}

Animations

Animations allow you to create dynamic visual effects by storing actions (behavior of objects), which can later be replayed. 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 the newly introduced Animation library. The ArcObjects in the 3DAnalyst library used for creating animations at ArcGIS 9.0 and ArcGIS 9.1 can still be used, and existing projects using these objects should still compile. If you see any issues with compilation of projects, 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.
An animation consists of one or more animation tracks (AGAnimationTracks) that 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, and AGAnimationTypeTimeLayer are available out-of-the-box in Scene. Developers can optionally implement their custom types.