com.esri.arcgis.analyst3d
Class RasterSurface

java.lang.Object
  extended by com.esri.arcgis.analyst3d.RasterSurface
All Implemented Interfaces:
IRasterSurface, ISurface, IFunctionalSurface, IFunctionalSurface2, com.esri.arcgis.interop.RemoteObjRef, Serializable

public class RasterSurface
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, IRasterSurface, IFunctionalSurface, IFunctionalSurface2, ISurface

The ESRI raster surface component.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server. Requires 3D Analyst Extension.

Supported Platforms

Windows, Solaris, Linux

See Also:
Serialized Form

Constructor Summary
RasterSurface()
          Constructs a RasterSurface using ArcGIS Engine.
RasterSurface(Object obj)
          Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
RasterSurface theRasterSurface = (RasterSurface) obj;
 
Method Summary
 void asPolygons(IFeatureClass pFeatureClass, int type, IDoubleArray pClassBreaks, ILongArray pClassCodes, Object fieldName)
          Converts the surface to a polygon feature class representing slope or aspect.
 void contour(double referenceContourHeight, double interval, IFeatureClass pFeatureClass, String fieldName, int digitsAfterDecimalPoint)
          Output contours based on the specified root value and interval.
 void contourList(IDoubleArray pBreaks, IFeatureClass pFeatureClass, String fieldName, int digitsAfterDecimalPoint)
          Output a list of contours corresponding to the specified eleveation values.
 boolean equals(Object o)
          Compare this object with another
 double getAspectDegrees(IPoint pPoint)
          Returns the aspect at the specified location in degrees.
 double getAspectRadians(IPoint pPoint)
          Returns the aspect at the specified location in radians.
static String getClsid()
          getClsid.
 void getContour(IPoint pPoint, IPolyline[] ppContour, double[] pElevation)
          Returns a countour passing through the queried point.
 IPolygon getDomain()
          The interpolation domain of the surface.
 double getElevation(IPoint pPoint)
          Returns the z value of the specified location.
 void getLineOfSight(IPoint pObserver, IPoint pTarget, IPoint[] ppObstruction, IPolyline[] ppVisibleLines, IPolyline[] ppInvisibleLines, boolean[] pbIsVisible, boolean bApplyCurvature, boolean bApplyRefraction, Object pRefractionFactor)
          Computes the visibility of a line-of-sight from the observer to the target.
 void getProfile(IGeometry pShape, IGeometry[] ppProfile, Object pStepSize)
          Returns a polyline with z values interpolated from the surface.
 double getProjectedArea(double referenceHeight, int type)
          Returns the projected area of the surface above or below an input z value.
 IRaster getRaster()
          A raster.
 IRasterBand getRasterBand()
          The raster band of a raster surface.
 double getSampleDistance()
          The sample distance for interpolated shapes and profiles.
 double getSlopeDegrees(IPoint pPoint)
          Returns the slope at the specified location in degrees.
 double getSlopePercent(IPoint pPoint)
          Returns the slope at the specified location in percent.
 double getSlopeRadians(IPoint pPoint)
          Returns the slope at the specified location in radians.
 IPolyline getSteepestPath(IPoint pPoint)
          Returns the steepest path downhill from the specified point.
 double getSurfaceArea(double referenceHeight, int type)
          Returns the area measured on its surface above or below an input z value.
 double getVolume(double reference, int type)
          Returns the volume above or below an input z value.
 double getZ(double x, double y)
          The surface Z = f(x,y).
 double getZFactor()
          Multiplication factor applied to all z values to provide unit-congruency between coordinate components.
 int hashCode()
          the hashcode for this object
 void interpolateShape(IGeometry pShape, IGeometry[] ppOutShape, Object pStepSize)
          Interpolates z values for a defined geometric shape.
 void interpolateShapeVertices(IGeometry pShape, IGeometry[] ppOutShape)
          Interpolates z values for a defined geometric shape at its vertices only.
 boolean isVoidZ(double value)
          Returns TRUE if the passed value is equal to the surface's void value.
 IPoint locate(IRay pRay, int hint)
          Returns the intersection of the query ray and the surface.
 IDoubleArray locateAll(IRay pRay, int hint)
          Returns the distances of intersections of the query ray and the surface.
 void putRaster(IRaster raster, int bandIndex)
          Sets a raster with a specified band index.
 void queryNormal(IPoint pLocation, IVector3D pNormal)
          Returns the vector normal to the specified triangle.
 void queryPixelBlock(double xOrigin, double yOrigin, double xPixelSize, double yPixelSize, int type, Object valueForNoData, Object block)
          Derives slope, aspect, hillshade, or elevation from the input surface and writes the result to the provided PixelBlock.
 void querySurfaceLength(IGeometry pShape, double[] pLength, Object pStepSize)
          Returns the length of an input polyline measured on the surface.
 void setDomain(IPolygon rhs1)
          The interpolation domain of the surface.
 void setRasterBand(IRasterBand rasterBand)
          The raster band of a raster surface.
 void setSampleDistance(double pSampleDistance)
          The sample distance for interpolated shapes and profiles.
 void setZFactor(double pFactor)
          Multiplication factor applied to all z values to provide unit-congruency between coordinate components.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.esri.arcgis.interop.RemoteObjRef
getJintegraDispatch, release
 

Constructor Detail

RasterSurface

public RasterSurface()
              throws IOException,
                     UnknownHostException
Constructs a RasterSurface using ArcGIS Engine.

Throws:
IOException - if there are interop problems
UnknownHostException - if there are interop problems

RasterSurface

public RasterSurface(Object obj)
              throws IOException
Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
RasterSurface theRasterSurface = (RasterSurface) obj;

Construct a RasterSurface using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to RasterSurface.

Parameters:
obj - an object returned from ArcGIS Engine or Server
Throws:
IOException - if there are interop problems
Method Detail

getClsid

public static String getClsid()
getClsid.


equals

public boolean equals(Object o)
Compare this object with another

Overrides:
equals in class Object

hashCode

public int hashCode()
the hashcode for this object

Overrides:
hashCode in class Object

setRasterBand

public void setRasterBand(IRasterBand rasterBand)
                   throws IOException,
                          AutomationException
The raster band of a raster surface.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server. Requires 3D Analyst Extension.

Supported Platforms

Windows, Solaris, Linux

Specified by:
setRasterBand in interface IRasterSurface
Parameters:
rasterBand - A reference to a com.esri.arcgis.datasourcesraster.IRasterBand (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getRasterBand

public IRasterBand getRasterBand()
                          throws IOException,
                                 AutomationException
The raster band of a raster surface.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server. Requires 3D Analyst Extension.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getRasterBand in interface IRasterSurface
Returns:
A reference to a com.esri.arcgis.datasourcesraster.IRasterBand
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

putRaster

public void putRaster(IRaster raster,
                      int bandIndex)
               throws IOException,
                      AutomationException
Sets a raster with a specified band index.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server. Requires 3D Analyst Extension.

Supported Platforms

Windows, Solaris, Linux

Specified by:
putRaster in interface IRasterSurface
Parameters:
raster - A reference to a com.esri.arcgis.geodatabase.IRaster (in)
bandIndex - The bandIndex (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getRaster

public IRaster getRaster()
                  throws IOException,
                         AutomationException
A raster.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server. Requires 3D Analyst Extension.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getRaster in interface IRasterSurface
Returns:
A reference to a com.esri.arcgis.geodatabase.IRaster
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSampleDistance

public void setSampleDistance(double pSampleDistance)
                       throws IOException,
                              AutomationException
The sample distance for interpolated shapes and profiles.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server. Requires 3D Analyst Extension.

Supported Platforms

Windows, Solaris, Linux

Specified by:
setSampleDistance in interface IRasterSurface
Parameters:
pSampleDistance - The pSampleDistance (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSampleDistance

public double getSampleDistance()
                         throws IOException,
                                AutomationException
The sample distance for interpolated shapes and profiles.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server. Requires 3D Analyst Extension.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSampleDistance in interface IRasterSurface
Returns:
The pSampleDistance
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getZ

public double getZ(double x,
                   double y)
            throws IOException,
                   AutomationException
The surface Z = f(x,y).

Product Availability

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

Specified by:
getZ in interface IFunctionalSurface
Parameters:
x - The x (in)
y - The y (in)
Returns:
The z
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getDomain

public IPolygon getDomain()
                   throws IOException,
                          AutomationException
The interpolation domain of the surface.

Description

Returns the Polygon Domain in which the FunctionalSurface is defined. The Domain is the region in which all (x, y) coordinates have a single corresponding Z value on the FunctionalSurface.

If the surface is a raster the returned polygon will be 2D. If it's a TIN it will be 3-D.

Remarks

Use IFunctionalSurface2::Domain to set the Domain.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getDomain in interface IFunctionalSurface
Returns:
A reference to a com.esri.arcgis.geometry.IPolygon
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setDomain

public void setDomain(IPolygon rhs1)
               throws IOException,
                      AutomationException
The interpolation domain of the surface.

Description

Sets the Polygon Domain in which the FunctionalSurface is defined. The Domain is the region in which all (x, y) coordinates have a single corresponding Z value on the FunctionalSurface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
setDomain in interface IFunctionalSurface2
Parameters:
rhs1 - A reference to a com.esri.arcgis.geometry.IPolygon (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getZFactor

public double getZFactor()
                  throws IOException,
                         AutomationException
Multiplication factor applied to all z values to provide unit-congruency between coordinate components.

Description

All surface Z values are multiplied by the ZFactor before surface calculations are made. Factoring is necessary for some operations, like slope and line-of-sight, to produce correct results if the Z values are not in the same unit of measure as XY.

Example: if XY units are in meters and Z units are in feet specify a factor of 0.3048 to convert the Z's from feet to meters. If XY units are in feet and Z units are in meters specify a factor of 3.281 to convert the Z's from meters to feet.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getZFactor in interface ISurface
Returns:
The pFactor
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setZFactor

public void setZFactor(double pFactor)
                throws IOException,
                       AutomationException
Multiplication factor applied to all z values to provide unit-congruency between coordinate components.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
setZFactor in interface ISurface
Parameters:
pFactor - The pFactor (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getProjectedArea

public double getProjectedArea(double referenceHeight,
                               int type)
                        throws IOException,
                               AutomationException
Returns the projected area of the surface above or below an input z value.

Description

Returns the 2D projected/planar area of the surface relative to a specified reference plane.

The plane used in the calculation is horizontal and is therefore defined simply by height. You indicate the height and whether the area is to be calculated above or below it.

Note, the area is not the 3D volume between the plane and the surface. Rather, think of the intersection between the plane and the surface. If you outline the intersection you end up with one or more polygons. If you want the projected area above the plane, it's the summed area of these polygons. If you want the area below the plane the polygons represent holes inside an outer polygon, the interpolation zone. The area below the plane is that of the interpolation zone minus the holes.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getProjectedArea in interface ISurface
Parameters:
referenceHeight - The referenceHeight (in)
type - A com.esri.arcgis.geodatabase.esriPlaneReferenceType constant (in)
Returns:
The pArea
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSurfaceArea

public double getSurfaceArea(double referenceHeight,
                             int type)
                      throws IOException,
                             AutomationException
Returns the area measured on its surface above or below an input z value.

Description

Returns the 3D area of the surface relative to a specified reference plane. The area is measured along the slope of a surface, taking height into consideration. The surface area will always be greater than the 2D planimetric extent of the model (unless the surface is flat).

The plane used in the calculation is horizontal and is therefore defined simply by height. You indicate the height and whether the area is to be calculated above or below it.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSurfaceArea in interface ISurface
Parameters:
referenceHeight - The referenceHeight (in)
type - A com.esri.arcgis.geodatabase.esriPlaneReferenceType constant (in)
Returns:
The pArea
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getVolume

public double getVolume(double reference,
                        int type)
                 throws IOException,
                        AutomationException
Returns the volume above or below an input z value.

Description

Calculates the cubic space between the TIN surface and a horizontal plane located at the specified elevation.

If you choose to calculate volume above the plane, the area of consideration is that which is above the plane and the underside of the surface. If you choose below the plane the area of consideration is below the plane and the topside of the surface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getVolume in interface ISurface
Parameters:
reference - The reference (in)
type - A com.esri.arcgis.geodatabase.esriPlaneReferenceType constant (in)
Returns:
The pVolume
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

queryNormal

public void queryNormal(IPoint pLocation,
                        IVector3D pNormal)
                 throws IOException,
                        AutomationException
Returns the vector normal to the specified triangle.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
queryNormal in interface ISurface
Parameters:
pLocation - A reference to a com.esri.arcgis.geometry.IPoint (in)
pNormal - A reference to a com.esri.arcgis.geometry.IVector3D (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getElevation

public double getElevation(IPoint pPoint)
                    throws IOException,
                           AutomationException
Returns the z value of the specified location.

Description

Returns the height for the specified location.

Bilinear interpolation is used on a raster surface. Linear interpolation is used on a TIN surface

A void value is returned if the query point does not fall within the interpolation zone of the surface. You can check for this case using ISurface.IsVoidZ on the returned value.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getElevation in interface ISurface
Parameters:
pPoint - A reference to a com.esri.arcgis.geometry.IPoint (in)
Returns:
The pElevation
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSlopeDegrees

public double getSlopeDegrees(IPoint pPoint)
                       throws IOException,
                              AutomationException
Returns the slope at the specified location in degrees.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSlopeDegrees in interface ISurface
Parameters:
pPoint - A reference to a com.esri.arcgis.geometry.IPoint (in)
Returns:
The pSlope
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSlopeRadians

public double getSlopeRadians(IPoint pPoint)
                       throws IOException,
                              AutomationException
Returns the slope at the specified location in radians.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSlopeRadians in interface ISurface
Parameters:
pPoint - A reference to a com.esri.arcgis.geometry.IPoint (in)
Returns:
The pSlope
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSlopePercent

public double getSlopePercent(IPoint pPoint)
                       throws IOException,
                              AutomationException
Returns the slope at the specified location in percent.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSlopePercent in interface ISurface
Parameters:
pPoint - A reference to a com.esri.arcgis.geometry.IPoint (in)
Returns:
The pSlope
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getAspectDegrees

public double getAspectDegrees(IPoint pPoint)
                        throws IOException,
                               AutomationException
Returns the aspect at the specified location in degrees.

Description

Returns the aspect of the surface, in degrees, for the specified location. Aspect is defined as the direction of steepest slope. The possible range of values falls between 0.0 and 360. 0.0 represents a north facing slope with increasing values changing aspect in a clockwise direction. For example, 90 degrees is due east, 180 degrees due south, and 270 degrees due west.

For some operations it may be desirable to work with aspect in radians rather than degrees. Use AspectRadians for this.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getAspectDegrees in interface ISurface
Parameters:
pPoint - A reference to a com.esri.arcgis.geometry.IPoint (in)
Returns:
The pAspect
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getAspectRadians

public double getAspectRadians(IPoint pPoint)
                        throws IOException,
                               AutomationException
Returns the aspect at the specified location in radians.

Description

Returns the aspect of the surface, in radians, for the specified location. Aspect is defined as the direction of steepest slope. The possible range of values falls between 0.0 and 6.283185. 0.0 represents a north facing slope with increasing values changing aspect in a clockwise direction. For example, 1.570796 radians is due east, 3.141593 radians due south, and 4.712389 radians due west.

For some operations it may be desirable to work with aspect in degrees rather than radians. Use AspectDegrees for this.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getAspectRadians in interface ISurface
Parameters:
pPoint - A reference to a com.esri.arcgis.geometry.IPoint (in)
Returns:
The pAspect
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isVoidZ

public boolean isVoidZ(double value)
                throws IOException,
                       AutomationException
Returns TRUE if the passed value is equal to the surface's void value.

Description

Returns TRUE or FALSE depending on whether the specified Z is considered NODATA. Mathmatical operations cannot be performed on NODATA.

Some functions, such as ISurface.GetElevation, return a floating point number representing some characteristic of the surface for a given location. If the location does not fall within the interpolation zone some value representing NODATA must be returned. IsVoidZ can be used to evaluate if the result is NODATA.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
isVoidZ in interface ISurface
Parameters:
value - The value (in)
Returns:
The pbIsVoid
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

interpolateShape

public void interpolateShape(IGeometry pShape,
                             IGeometry[] ppOutShape,
                             Object pStepSize)
                      throws IOException,
                             AutomationException
Interpolates z values for a defined geometric shape.

Description

The Shape is an input 2D geometry. The method interpolates heights for it from the surface, and outputs the result as 3D geometry into OutShape.

The input geometry can be a point, polyline or polygon. Portions of the input not falling within the interpolation zone of the surface will be clipped. A NULL pointer ('Nothing' in VisualBasic) is returned when the input falls entirely off the surface.

If specified, input polylines and polygons will be densified by the stepSize. This takes place before interpolating heights from the surface. The densification ensures no two vertices are spaced more than stepSize apart.

The stepSize argument isn't very important when the surface is a TIN as the default sampling scheme of using input vertices and triangle edge intersections is sufficient to capture all surface information. If the surface is a raster it becomes more important. Generally, the smaller the interval the greater the detail (unless smaller than 1/2 cellsize), but at an increased cost in processing time and size of resulting geometry. The default stepSize for raster based surface is set equal to the cellsize.

InterpolateShape will handle differences in spatial reference between the input shape and the surface. It will project (a copy of) the input geometry to match the surface for the sake of interpolation. It will then re-project the output geometry so it's the same as the input shape.

Notes:

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
interpolateShape in interface ISurface
Parameters:
pShape - A reference to a com.esri.arcgis.geometry.IGeometry (in)
ppOutShape - A reference to a com.esri.arcgis.geometry.IGeometry (out: use single element array)
pStepSize - A Variant (in, optional, pass null if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

interpolateShapeVertices

public void interpolateShapeVertices(IGeometry pShape,
                                     IGeometry[] ppOutShape)
                              throws IOException,
                                     AutomationException
Interpolates z values for a defined geometric shape at its vertices only.

Description

Takes an input polyline or polygon, interpolates heights for its vertices from the surface, and outputs the result as 3D geometry. A NULL pointer ('Nothing' in VB) is returned if any portion of the input feature falls outside the surface.

InterpolateShapeVertices will handle differences in spatial reference between the input shape and the surface. It will project (a copy of) the input geometry to match the surface for the sake of interpolation. It will then re-project the output geometry so it's the same as the input shape.

Notes:

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
interpolateShapeVertices in interface ISurface
Parameters:
pShape - A reference to a com.esri.arcgis.geometry.IGeometry (in)
ppOutShape - A reference to a com.esri.arcgis.geometry.IGeometry (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getProfile

public void getProfile(IGeometry pShape,
                       IGeometry[] ppProfile,
                       Object pStepSize)
                throws IOException,
                       AutomationException
Returns a polyline with z values interpolated from the surface.

Description

Takes an input polyline or polygon, interpolates heights for it from the surface, and outputs the result as 3D geometry.

The input geometry should be polyline or polygon based. Portions of the input not falling within the interpolation zone of the surface will be clipped. A Null pointer ('Nothing' in Visual Basic) is returned when the input falls entirely off the surface.

If specified, the input geometry will be densified by the stepSize. This takes place before interpolating heights from the surface. The densification ensures no two vertices are spaced more than stepSize apart.

Notes:

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getProfile in interface ISurface
Parameters:
pShape - A reference to a com.esri.arcgis.geometry.IGeometry (in)
ppProfile - A reference to a com.esri.arcgis.geometry.IGeometry (out: use single element array)
pStepSize - A Variant (in, optional, pass null if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getLineOfSight

public void getLineOfSight(IPoint pObserver,
                           IPoint pTarget,
                           IPoint[] ppObstruction,
                           IPolyline[] ppVisibleLines,
                           IPolyline[] ppInvisibleLines,
                           boolean[] pbIsVisible,
                           boolean bApplyCurvature,
                           boolean bApplyRefraction,
                           Object pRefractionFactor)
                    throws IOException,
                           AutomationException
Computes the visibility of a line-of-sight from the observer to the target.

Description

Returns information about the line of sight between two points, an observer and target. Information returned includes whether the target is visible, the location of the first obstruction point if it isn't, and both the visible and invisible portions of the sight line along the surface.

Both the observer and target points need to be 3D. Any vertical offsets that need to be applied should already be accounted for in their Z values.

The obstruction point is set, as a 3D point, if the target is not visible from the observer. In this case the first intersection point, from the observer toward the target, between the surface and line of sight is used. The variable for the obstruction point need not reference an instantiated object. GetLineOfSight will automatically create the point. If the target is visible, there is no obstruction point and the returned object will be a Null pointer ('Nothing' in VB).

The visible and invisible polylines represent that which is seen from the observation point and that which is not. The variables used for these features need not reference instantiated objects. The function will create them. The line of sight may be entirely visible, entirely invisible, or a combination. These polylines will have Z values interpolated from the surface. If there is no output for one or the other of these polylines the corresponding pointer will be Null ('Nothing' in VB).

Set bApplyCurvature to True to have earth curvature taken into consideration. The default is False. It can be set to True if the surface has a defined projected coordinate system that includes defined ZUnits.

Set bApplyRefraction to True to have refraction of visible light taken into consideration. The default is False. It can be set to True if the surface has a defined projected coordinate system that includes defined ZUnits.

The default refraction factor is 0.13.

Notes:

This member should not be used in .NET. As a substitute, .NET developers must use IGeoDatabaseBridge2.GetLineOfSight.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getLineOfSight in interface ISurface
Parameters:
pObserver - A reference to a com.esri.arcgis.geometry.IPoint (in)
pTarget - A reference to a com.esri.arcgis.geometry.IPoint (in)
ppObstruction - A reference to a com.esri.arcgis.geometry.IPoint (out: use single element array)
ppVisibleLines - A reference to a com.esri.arcgis.geometry.IPolyline (out: use single element array)
ppInvisibleLines - A reference to a com.esri.arcgis.geometry.IPolyline (out: use single element array)
pbIsVisible - The pbIsVisible (out: use single element array)
bApplyCurvature - The bApplyCurvature (in)
bApplyRefraction - The bApplyRefraction (in)
pRefractionFactor - A Variant (in, optional, pass null if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

querySurfaceLength

public void querySurfaceLength(IGeometry pShape,
                               double[] pLength,
                               Object pStepSize)
                        throws IOException,
                               AutomationException
Returns the length of an input polyline measured on the surface.

Description

Returns the 3D length of the polyline by interpolating heights from the surface and calculating the sum of 3D distances between the vertices. Portions of the line falling outside the interpolation zone are excluded from the calculation.

The stepSize argument isn't very important when the surface is a TIN as the default sampling scheme of using input vertices and triangle edge intersections is sufficient to capture all surface information. If the surface is a raster it becomes more important. Generally, the smaller the interval the greater the detail (unless smaller than 1/2 cellsize), but at an increased cost in processing time and size of resulting geometry. The default stepSize for raster based surface is set equal to the cellsize.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
querySurfaceLength in interface ISurface
Parameters:
pShape - A reference to a com.esri.arcgis.geometry.IGeometry (in)
pLength - The pLength (out: use single element array)
pStepSize - A Variant (in, optional, pass null if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

locate

public IPoint locate(IRay pRay,
                     int hint)
              throws IOException,
                     AutomationException
Returns the intersection of the query ray and the surface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
locate in interface ISurface
Parameters:
pRay - A reference to a com.esri.arcgis.geometry.IRay (in)
hint - The hint (in)
Returns:
A reference to a com.esri.arcgis.geometry.IPoint
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

locateAll

public IDoubleArray locateAll(IRay pRay,
                              int hint)
                       throws IOException,
                              AutomationException
Returns the distances of intersections of the query ray and the surface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
locateAll in interface ISurface
Parameters:
pRay - A reference to a com.esri.arcgis.geometry.IRay (in)
hint - The hint (in)
Returns:
A reference to a com.esri.arcgis.system.IDoubleArray
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getContour

public void getContour(IPoint pPoint,
                       IPolyline[] ppContour,
                       double[] pElevation)
                throws IOException,
                       AutomationException
Returns a countour passing through the queried point.

Description

Returns the contour and height corresponding to a specified query point.

If the query point falls outside the interpolation zone, or on an area of zero slope, a nil polyline (nothing) is returned along with a void value for the height. You can check for a void height using ISurface.IsVoidZ.

The IPolyline pointer that is passed need not be referencing an instantiated object. GetContour will instantiate the object itself.

The returned contour elevation will be NaN when the returned contour is empty.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getContour in interface ISurface
Parameters:
pPoint - A reference to a com.esri.arcgis.geometry.IPoint (in)
ppContour - A reference to a com.esri.arcgis.geometry.IPolyline (out: use single element array)
pElevation - The pElevation (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

contourList

public void contourList(IDoubleArray pBreaks,
                        IFeatureClass pFeatureClass,
                        String fieldName,
                        int digitsAfterDecimalPoint)
                 throws IOException,
                        AutomationException
Output a list of contours corresponding to the specified eleveation values.

Description

Creates contours, based on a list of heights, sending the ouput to a polyline based feature class.

The pBreaks height list contains the elevation values for which contours will be derived.

Contours will be written to the specified 2D polyline feature class. It should be an empty feature class and is typically created immediately before calling Contour.

Do not have WorkspaceEdit turned on as this member needs to add a field to the feature class, a scheme editing operation not supported by WorkspaceEdit.

fieldName is used to name the field added to the feature class to store each contour's height.

digitsAfterDecimalPoint controls the precision of the output height values. Use a value of 0 if you want heights recorded as integers, as is likely when both the rootHeight and interval values are integers.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
contourList in interface ISurface
Parameters:
pBreaks - A reference to a com.esri.arcgis.system.IDoubleArray (in)
pFeatureClass - A reference to a com.esri.arcgis.geodatabase.IFeatureClass (in)
fieldName - The fieldName (in)
digitsAfterDecimalPoint - The digitsAfterDecimalPoint (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

contour

public void contour(double referenceContourHeight,
                    double interval,
                    IFeatureClass pFeatureClass,
                    String fieldName,
                    int digitsAfterDecimalPoint)
             throws IOException,
                    AutomationException
Output contours based on the specified root value and interval.

Description

Creates contours, based on a specified interval, sending the ouput to a polyline based feature class.

The rootHeight is the height from which potential contours are generated, both above and below, at the specified interval. It does not mean minimum contour. Rather it permits you to have contours that aren't based on 0.0. For example, if you want a 5 unit contour interval, but need them at heights of -8, -3, 2, 7, and 12 you'd provide a rootHeight of -3 or 2, or even -13. Note the root height need not be a height within the surface z range. You can use any value but only those contours that fall within the surface's z range will be created. The default rootHeight is 0.0.

The interval defines at what frequency, in height, the contours will be generated. Smaller intervals produce more contours.

Contours will be written to the specified 2D polyline feature class. It should be an empty feature class and is typically created immediately before calling Contour.

Do not have WorkspaceEdit turned on as this member needs to add a field to the feature class, a scheme editing operation not supported by WorkspaceEdit.

fieldHeight is used to name the field added to the feature class to store each contour's height.

digitsAfterDecimalPoint controls the precision of the output height values. Use a value of 0 if you want heights recorded as integers, as is likely when both the rootHeight and interval values are integers.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
contour in interface ISurface
Parameters:
referenceContourHeight - The referenceContourHeight (in)
interval - The interval (in)
pFeatureClass - A reference to a com.esri.arcgis.geodatabase.IFeatureClass (in)
fieldName - The fieldName (in)
digitsAfterDecimalPoint - The digitsAfterDecimalPoint (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

asPolygons

public void asPolygons(IFeatureClass pFeatureClass,
                       int type,
                       IDoubleArray pClassBreaks,
                       ILongArray pClassCodes,
                       Object fieldName)
                throws IOException,
                       AutomationException
Converts the surface to a polygon feature class representing slope or aspect.

Description

Converts the surface into a 2D polygon based feature class representing areas classified by slope or aspect.

Polygons will be written to the specified 2D polygon feature class. It should be an empty feature class and is typically created immediately before calling AsPolygons.

Do not have WorkspaceEdit turned on as this member adds fields to the feature class. The adding of fields is a schema editing operation not supported by WorkspaceEdit.

The esriSurfaceConversionType enumeration specifies whether the surface is classified on slope or aspect.

The pClassBreaks parameter is an array of doubles that defines the classification. Let's say there were 4 values placed in it: 1, 5, 10, and 15. The classification would result in 5 classes defined as follows:


 1:  <= 1

 5:  >  1 and <= 5

10:  >  5 and <= 10

15:  > 10 and <= 15

     > 15

The pClassCodes parameter is an array of long integers used to specify a class code for each class. You need to specify one more code than the number of class breaks to capture the last implied class (based on example the '>15' class). This code is written to the output feature class attribute table. The ClassCodes array can be 'Nothing' in which case the codes are automatically assigned 1..n.

When the esriSurfaceConversionType is set to esriDegreeAspect, the output code will automatically be set to -1 for polygons with undefined aspect (flat areas). This code can be overridden by providing it as an additional value at the end of the pClassCodes array. The method will know to use it because the code array will be one larger than necessary to capture the classification.

The optional FieldName argument is used to specify a name for the class code field. Defaults are provided if not specified. When esriSurfaceConversionType is esriDegreeAspect the default field name is 'AspectCode'. For both slope options it will be 'SlopeCode'. The field name is not to exceed 10 characters if writing to a shapefile as this is a dBase file limit.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
asPolygons in interface ISurface
Parameters:
pFeatureClass - A reference to a com.esri.arcgis.geodatabase.IFeatureClass (in)
type - A com.esri.arcgis.geodatabase.esriSurfaceConversionType constant (in)
pClassBreaks - A reference to a com.esri.arcgis.system.IDoubleArray (in)
pClassCodes - A reference to a com.esri.arcgis.system.ILongArray (in)
fieldName - A Variant (in, optional, pass null if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSteepestPath

public IPolyline getSteepestPath(IPoint pPoint)
                          throws IOException,
                                 AutomationException
Returns the steepest path downhill from the specified point.

Description

Returns the steepest downhill path, the direction of steepest slope, from the specified query point. It will start at the query point and end in a pit or the edge of the surface. The returned polyline will be 3D.

The resulting polyline pointer will be set to Nil (nothing) if the query point falls outside the surface or on a flat area.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSteepestPath in interface ISurface
Parameters:
pPoint - A reference to a com.esri.arcgis.geometry.IPoint (in)
Returns:
A reference to a com.esri.arcgis.geometry.IPolyline
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

queryPixelBlock

public void queryPixelBlock(double xOrigin,
                            double yOrigin,
                            double xPixelSize,
                            double yPixelSize,
                            int type,
                            Object valueForNoData,
                            Object block)
                     throws IOException,
                            AutomationException
Derives slope, aspect, hillshade, or elevation from the input surface and writes the result to the provided PixelBlock.

Description

xOrigin and yOrigin represent the map coordinates of the upper left cell center of the output pixel block.

xPixelSize and yPixelSize are the horizontal and vertical dimensions of the cells in the output pixel block.

type is an esriRasterizationType enumeration that indicates what type of surface information is written; elevation or a derivative.

valueForNodata is the value written into the pixel block for areas of NoData. It's a variant that must be set to the the same numeric type as the target raster (see rstPixelType). It should be the same value and variant type used as when constructing/defining the output raster via IRasterProps.NoDataValue.

block is a pointer to pixel data used for writing output values. It should be retrieved from a pixel block from the output raster via IPixelBlock3.PixelDataByRef.

Notes:

This member should not be used in .NET. As a substitute, .NET developers must use IGeoDatabaseBridge2.QueryPixelBlock.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
queryPixelBlock in interface ISurface
Parameters:
xOrigin - The xOrigin (in)
yOrigin - The yOrigin (in)
xPixelSize - The xPixelSize (in)
yPixelSize - The yPixelSize (in)
type - A com.esri.arcgis.geodatabase.esriRasterizationType constant (in)
valueForNoData - A Variant (in)
block - A Variant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.