com.esri.arcgis.geodatabaseextensions
Interface ITerrain

All Superinterfaces:
Serializable
All Known Implementing Classes:
ITerrainProxy, Terrain

public interface ITerrain
extends Serializable

Provides access to members used to acquire information about a Terrain and to retrieve DynamicSurface objects from which raster and TIN surfaces are made.

Description

The ITerrain interface is used to acquire information about a terrain and its data sources. Additionally, it's used to retrieve DynamicSurface objects which extract terrain information in the form of rasters, TINs, and measurement points.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.


Method Summary
 IDynamicSurface createDynamicSurface()
          Returns an implicit surface from which TINs and rasters are derived.
 void extractFromEmbeddedDataSource(int index, IFeatureClass pFeatureClass, IEnvelope pAOI, double resolution, ITrackCancel pTrackCancel)
          Copys features of an embedded data source to the specified feature class.
 ITerrainDataSource getDataSource(int index)
          Returns one of the feature classes participating in the terrain.
 int getDataSourceCount()
          The number of feature classes participating in the terrain.
 IEnumEnvelope getDirtyTiles()
          Returns all dirty tiles.
 IEnvelope getExtent()
          The approximate xyz extent of the terrain.
 IFeatureDataset getFeatureDataset()
          The feature dataset which contains the terrain.
 int getID()
          The database identifier of the terrain.
 int getMaxOverviewTerrainPoints()
          The maximum number of points in the most generalized representation of a Terrain.
 int getMaxPointsPerShape()
          The maximum number of vertices per multipoint.
 String getName()
          What the terrain is called.
 double getPointCount(IEnvelope pAOI, double resolution)
          Returns the approximate number of points in the terrain within a given area and at a particular pyramid level.
 ITerrainPyramidLevel getPyramidLevel(int index)
          The vertical deviation permitted in one level of a terrain pyramid tile relative to the full resolution data.
 int getPyramidLevelCount()
          The number of pyramid levels in the terrain.
 int getPyramidType()
          The pyramid type of this Terrain.
 double getSize()
          The total number of points in the Terrain.
 ISpatialReference getSpatialReference()
          The coordinate system and xyz domain of the terrain.
 double getTileSize()
          The horizontal distance used to spatially index and partition terrain data.
 boolean isDirty()
          Indicates whether or not a partial rebuild is needed.
 boolean isValid()
          Indicates whether or not a full build is required.
 void queryTileInfo(int[] pRowBegin, int[] pRowEnd, int[] pColBegin, int[] pColEnd, double[] pXMin, double[] pYMin, double[] pTileSize, int[] pRowCountDomain, int[] pColCountDomain)
          Returns horizontal partitioning information about the terrain data.
 

Method Detail

getName

String getName()
               throws IOException,
                      AutomationException
What the terrain is called.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
The pName
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getID

int getID()
          throws IOException,
                 AutomationException
The database identifier of the terrain.

Description

ID is the internal database identifier for the terrain.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
The pID
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSize

double getSize()
               throws IOException,
                      AutomationException
The total number of points in the Terrain.

Description

Size is the total number of 3D mass point and breakline vertices in the terrain. The count does not consider the effect of clip or erase features and it does not include vertices of z-less features.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
The pcPoints
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isValid

boolean isValid()
                throws IOException,
                       AutomationException
Indicates whether or not a full build is required.

Description

Indicates whether the terrain schema has been modified since the last Build. When IsValid is FALSE the terrain must be built in order to be used.

Schema edits on terrains include the addition or removal of feature classes and pyramid levels.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
The pbIsValid
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isDirty

boolean isDirty()
                throws IOException,
                       AutomationException
Indicates whether or not a partial rebuild is needed.

Description

Indicates whether edits have taken place on feature classes that participate in the terrain. When IsDirty is TRUE a Build is needed to reconstruct the pyramid layers for the terrain tiles in which the edits have occurred.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
The pbIsDirty
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSpatialReference

ISpatialReference getSpatialReference()
                                      throws IOException,
                                             AutomationException
The coordinate system and xyz domain of the terrain.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
A reference to a com.esri.arcgis.geometry.ISpatialReference
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getExtent

IEnvelope getExtent()
                    throws IOException,
                           AutomationException
The approximate xyz extent of the terrain.

Description

Extent returns the tile boundary of the terrain for XY and Z.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
A reference to a com.esri.arcgis.geometry.IEnvelope
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getFeatureDataset

IFeatureDataset getFeatureDataset()
                                  throws IOException,
                                         AutomationException
The feature dataset which contains the terrain.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
A reference to a com.esri.arcgis.geodatabase.IFeatureDataset
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getDataSourceCount

int getDataSourceCount()
                       throws IOException,
                              AutomationException
The number of feature classes participating in the terrain.

Description

The DataSourceCount represents the number of feature classes that participate in the terrain. This includes regular and embedded feature classes.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
The pcDataSources
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getDataSource

ITerrainDataSource getDataSource(int index)
                                 throws IOException,
                                        AutomationException
Returns one of the feature classes participating in the terrain.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:
index - The index (in)
Returns:
A reference to a com.esri.arcgis.geodatabaseextensions.ITerrainDataSource
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getPyramidLevelCount

int getPyramidLevelCount()
                         throws IOException,
                                AutomationException
The number of pyramid levels in the terrain.

Description

The PyramidLevelCount is the number of pyramid levels defined for the terrain excluding the implicit full resolution level and also the coarsest level, the terrain overview.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
The pcPyramidLevels
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getPyramidLevel

ITerrainPyramidLevel getPyramidLevel(int index)
                                     throws IOException,
                                            AutomationException
The vertical deviation permitted in one level of a terrain pyramid tile relative to the full resolution data.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:
index - The index (in)
Returns:
A reference to a com.esri.arcgis.geodatabaseextensions.ITerrainPyramidLevel
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getTileSize

double getTileSize()
                   throws IOException,
                          AutomationException
The horizontal distance used to spatially index and partition terrain data.

Description

The TileSize is the horizontal distance of the side of a terrain tile. Tiles are square. Terrain uses a tile system to divide measurement data into manageable chunks for iterative processing. The size should be set relative to the average point spacing of the data used to build the terrain such that each tile holds between one and two hundred thousand mass points and breakline vertices.

See also ITerrain.QueryTileInfo.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
The pSize
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getPyramidType

int getPyramidType()
                   throws IOException,
                          AutomationException
The pyramid type of this Terrain.

Description

At this time the only type of terrain pyramid is one based on z-tolerance. On a tile by tile basis, subsets of measurements are selected to contribute to pyramid levels. The surface for each level can only deviate from the next higher higher level of detail by an amount up to the z-tolerance.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
A com.esri.arcgis.geodatabaseextensions.esriTerrainPyramidType constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getMaxOverviewTerrainPoints

int getMaxOverviewTerrainPoints()
                                throws IOException,
                                       AutomationException
The maximum number of points in the most generalized representation of a Terrain.

Description

The overview is the coarsest representation of a terrain. It's like a vector based thumbnail. The primary intention of the overview is to enable a terrain to draw quickly when zoomed to its full extent, when detail and accuracy are not needed. The default for MaxOverviewTerrainPoints is 50,000.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
The pcPoints
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getMaxPointsPerShape

int getMaxPointsPerShape()
                         throws IOException,
                                AutomationException
The maximum number of vertices per multipoint.

Description

Terrain pyramids are comprised of mass points and breakline vertices. These are stored as a collection of multipoints. MaxPointsPerShape controls how large an individual multipoint can get. The default is 5000.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
The pcPoints
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

queryTileInfo

void queryTileInfo(int[] pRowBegin,
                   int[] pRowEnd,
                   int[] pColBegin,
                   int[] pColEnd,
                   double[] pXMin,
                   double[] pYMin,
                   double[] pTileSize,
                   int[] pRowCountDomain,
                   int[] pColCountDomain)
                   throws IOException,
                          AutomationException
Returns horizontal partitioning information about the terrain data.

Description

The feature dataset containing the terrain is logically tiled, in its entirety, to form the tile scheme with its origin in the southwest corner. Tiles are square. Row and column numbering starts at base 1. The data area of the terrain may not fill the extent of the feature dataset so it's possible that only a subset of rows and columns are involved. This method provides the info about those tiles overlapping the terrain extent.

The returned row and column numbers represent the rectangular subset of tiles that intersect the terrain extent. Row and column numbering start at base 1 with the first row and column being in the southwest corner of the feature dataset.

The xmin and ymin are the real world coordinates for the lower left corner of the origin tile of the terrain.

The tilesize is the horizontal length of one of the square tiles and is equal to that specified when the terrain was created.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:
pRowBegin - The pRowBegin (out: use single element array)
pRowEnd - The pRowEnd (out: use single element array)
pColBegin - The pColBegin (out: use single element array)
pColEnd - The pColEnd (out: use single element array)
pXMin - The pXMin (out: use single element array)
pYMin - The pYMin (out: use single element array)
pTileSize - The pTileSize (out: use single element array)
pRowCountDomain - The pRowCountDomain (out: use single element array)
pColCountDomain - The pColCountDomain (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getDirtyTiles

IEnumEnvelope getDirtyTiles()
                            throws IOException,
                                   AutomationException
Returns all dirty tiles.

Description

Each envelope returned by the enumerator represents the map based extent of a dirty tile.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
A reference to a com.esri.arcgis.geodatabaseextensions.IEnumEnvelope
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getPointCount

double getPointCount(IEnvelope pAOI,
                     double resolution)
                     throws IOException,
                            AutomationException
Returns the approximate number of points in the terrain within a given area and at a particular pyramid level.

Description

GetPointCount returns the number of points and breakline vertices, at a particular pyramid level, for those terrain tiles intersected by a given envelope. This yields a relatively quick estimate, albeit over-estimated, of the size of the terrain for that area and vertical tolerance. Only 3-D measurements are counted. Z-less line and polygon vertices are excluded.

GetPointCount will return an error when called on a terrain that is in need of being built. That is, when ITerrain.IsValid returns FALSE. Ensure the terrain IsValid before calling this member.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:
pAOI - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
resolution - The resolution (in)
Returns:
The pcPoints
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

createDynamicSurface

IDynamicSurface createDynamicSurface()
                                     throws IOException,
                                            AutomationException
Returns an implicit surface from which TINs and rasters are derived.

Description

CreateDynamicSurface will return an error when called on a terrain that is in need of being built. That is, when ITerrain.IsValid returns FALSE. Ensure the terrain IsValid before calling this member.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
A reference to a com.esri.arcgis.geodatabaseextensions.IDynamicSurface
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

extractFromEmbeddedDataSource

void extractFromEmbeddedDataSource(int index,
                                   IFeatureClass pFeatureClass,
                                   IEnvelope pAOI,
                                   double resolution,
                                   ITrackCancel pTrackCancel)
                                   throws IOException,
                                          AutomationException
Copys features of an embedded data source to the specified feature class.

Description

Copies points from an embedded source into the target feature class.

index references the data source to use. This should be in the range of 0 to n-1 where n represents the number of data sources in the terrain, but it must also be a source which is embedded.

pFeatureClass is the target feature class, where the points will be written.

pAOI is the area of interest envelope. Points within the AOI will be extracted. This can be set to a NULL pointer ('Nothing' in VB) if the entire extent of the terrain is desired.

resolution indicates which pyramid level should be used for extraction. A value of 0.0 will extract the full resolution data. Any other value should correspond to one of the values used to define the terrain's pyramid. If you don't provide an exact match the software will round down to the next closest level.

pTrackCancel is a reference to a Cancel Tracker object that can be used to monitor progress and/or cancel the process. This can be set to a NULL pointer ('Nothing' in VB) if desired.

Notes

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:
index - The index (in)
pFeatureClass - A reference to a com.esri.arcgis.geodatabase.IFeatureClass (in)
pAOI - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
resolution - The resolution (in)
pTrackCancel - A reference to a com.esri.arcgis.system.ITrackCancel (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.