com.esri.arcgis.editor
Interface IEditorZ

All Superinterfaces:

Serializable

All Known Implementing Classes:

Editor, IEditorZProxy

public interface IEditorZ
extends Serializable

Provides access to members that access and manipulate the z-environment of the editor.

Description

This interface is new at ArcGIS 9.3.

Remarks

For more information on capturing and editing features containing z values, refer to How to work with Z-values in the Editor.

Product Availability

Available with ArcGIS Desktop.

Method Summary

void	applyZ(IPoint point) Applies editor's Z-capture logic to point if it isn't already z-aware.
void	drapeGeometry(IGeometry geometry, boolean addVertices, IGeometry[] outputGeometry) Drapes a geometry to the current surface..
void	finalizeZs(IGeometry geometry) Resolves NaN Zs to definite values.
INotifyZFinalize	getNotifyZFinalize() Callback used to notify if ZCapture mode fails.
IFunctionalSurface	getSurface() Surface used for Z capture.
int	getZCaptureType() Determines method used for z-capture.
double	getZDrapingTolerance() Determines the allowable error from the surface when draping.
double	getZOffset() Determines offset applied to z-value when new vertex is added to edit sketch.
IMarkerSymbol	getZSnapSymbol() Symbol used to indicate when vertex is snapped in Z.
IFeatureConstruction	initializeFeatureConstruction() Initialize a FeatureConstruction object that will use the Editor's ZEnvironment settings.
boolean	isDraping() Indicates whether sketches are draped onto the surface.
boolean	isUseZDrapingTolerance() Indicates whether the ZDrapingTolerance property is used when adding segments to the edit sketch.
boolean	isUseZOffset() Indicates whether new z-values are modified by the ZOffset property.
void	setDraping(boolean useDraping) Indicates whether sketches are draped onto the surface.
void	setNotifyZFinalizeByRef(INotifyZFinalize callback) Callback used to notify if ZCapture mode fails.
void	setSurfaceByRef(IFunctionalSurface surface) Surface used for Z capture.
void	setUseZDrapingTolerance(boolean useZDrapingTolerance) Indicates whether the ZDrapingTolerance property is used when adding segments to the edit sketch.
void	setUseZOffset(boolean useZOffset) Indicates whether new z-values are modified by the ZOffset property.
void	setZCaptureType(int zCaptureType) Determines method used for z-capture.
void	setZDrapingTolerance(double zDrapingTolerance) Determines the allowable error from the surface when draping.
void	setZOffset(double zOffset) Determines offset applied to z-value when new vertex is added to edit sketch.
void	setZSnapSymbolByRef(IMarkerSymbol symbol) Symbol used to indicate when vertex is snapped in Z.

Method Detail

drapeGeometry

void drapeGeometry(IGeometry geometry,
                   boolean addVertices,
                   IGeometry[] outputGeometry)
                   throws IOException,
                          AutomationException

Drapes a geometry to the current surface.. If addVertices is false, existing vertex Z's will be modified but no new vertices added.

Remarks

Drapes the input geometry on the editor's current surface (defined by IEditorZ::Surface). If addVertices is FALSE, then only Z values for existing vertices in the input geometry will be updated. If addVertices is TRUE, then new vertices will be inserted at changes in elevation defined by the surface. Existing vertices are not updated when addVertices is TRUE.

Product Availability

Available with ArcGIS Desktop.

Parameters:

geometry - A reference to a com.esri.arcgis.geometry.IGeometry (in)

addVertices - The addVertices (in)

outputGeometry - 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.

applyZ

void applyZ(IPoint point)
            throws IOException,
                   AutomationException

Applies editor's Z-capture logic to point if it isn't already z-aware.

Remarks

This method checks to determine that incoming point is Z-aware; if it is not, this method will set it to be Z-aware and apply the current Z assignment behavior to the incoming point in the following order: ZCaptureType, ZOffset. If the z-assignment fails (usually because the z-capture type is surface, and the retrieval of the z-value fails) then the client can receive this message through INotifyZFinalize, and is given an opportunity to specify a valid z-value.

Note: If the incoming point is already z-aware then this method does not alter the incoming point.

Product Availability

Available with ArcGIS Desktop.

Parameters:

point - A reference to a com.esri.arcgis.geometry.IPoint (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

finalizeZs

void finalizeZs(IGeometry geometry)
                throws IOException,
                       AutomationException

Resolves NaN Zs to definite values.

Remarks

This method ensures a particular geometry has a valid set of z values defined. This method attempts to interpolate the z-value of any non-simple points in the geometry; if result is non-simple then the Failed method of the class implementing INotifyZFinalize and hooked into IEditorZ::NotifyZFinalize is given an opportunity to manipulate the Z values. If the client handles this, the method checks for simplicity and defines the offending z-values as necessary to successfully store the feature (using IEditSketch2::CurrentZ).

Product Availability

Available with ArcGIS Desktop.

Parameters:

geometry - A reference to a com.esri.arcgis.geometry.IGeometry (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getZCaptureType

int getZCaptureType()
                    throws IOException,
                           AutomationException

Determines method used for z-capture.

Remarks

ZCaptureType defines the current method the editor uses to assign z-values for newly created or edited vertices. The default value is esriZCaptureCurrentZ. When using one either esriCaptureInterpolateZ or esriCaptureSurfaceZ, the resulting z-value may not be defined; if these sources do not produce a valid z-value (non-NaN) then the editor applies the value defined in IEditSketch2::CurrentZ.

Product Availability

Available with ArcGIS Desktop.

Returns:

A com.esri.arcgis.editor.esriZCaptureType constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setZCaptureType

void setZCaptureType(int zCaptureType)
                     throws IOException,
                            AutomationException

Determines method used for z-capture.

Product Availability

Available with ArcGIS Desktop.

Parameters:

zCaptureType - A com.esri.arcgis.editor.esriZCaptureType constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isUseZOffset

boolean isUseZOffset()
                     throws IOException,
                            AutomationException

Indicates whether new z-values are modified by the ZOffset property.

Remarks

Use this property to define whether an offset (specified through IEditorZ::ZOffset) is applied to a z-value captured using the editor. Default value is FALSE.

Product Availability

Available with ArcGIS Desktop.

Returns:

The useZOffset

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setUseZOffset

void setUseZOffset(boolean useZOffset)
                   throws IOException,
                          AutomationException

Indicates whether new z-values are modified by the ZOffset property.

Remarks

This property will apply an offset to the z-value generated by the editor's ZCaptureType. Default value is 0. The ZOffset is not applied unless IEditorZ::UseZOffset is TRUE.

Product Availability

Available with ArcGIS Desktop.

Parameters:

useZOffset - The useZOffset (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getZOffset

double getZOffset()
                  throws IOException,
                         AutomationException

Determines offset applied to z-value when new vertex is added to edit sketch.

Remarks

This property will apply an offset to the z-value generated by the editor's ZCaptureType. Default value is 0. The ZOffset is not applied unless IEditorZ::UseZOffset is TRUE.

Product Availability

Available with ArcGIS Desktop.

Returns:

The zOffset

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setZOffset

void setZOffset(double zOffset)
                throws IOException,
                       AutomationException

Determines offset applied to z-value when new vertex is added to edit sketch.

Product Availability

Available with ArcGIS Desktop.

Parameters:

zOffset - The zOffset (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isUseZDrapingTolerance

boolean isUseZDrapingTolerance()
                               throws IOException,
                                      AutomationException

Indicates whether the ZDrapingTolerance property is used when adding segments to the edit sketch.

Remarks

Determines whether a draping tolerance (defined in IEditorZ::ZDrapingTolerance) is applied to limit the number of points added to the sketch. Default value is FALSE.

Product Availability

Available with ArcGIS Desktop.

Returns:

The useZDrapingTolerance

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setUseZDrapingTolerance

void setUseZDrapingTolerance(boolean useZDrapingTolerance)
                             throws IOException,
                                    AutomationException

Indicates whether the ZDrapingTolerance property is used when adding segments to the edit sketch.

Product Availability

Available with ArcGIS Desktop.

Parameters:

useZDrapingTolerance - The useZDrapingTolerance (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getZDrapingTolerance

double getZDrapingTolerance()
                            throws IOException,
                                   AutomationException

Determines the allowable error from the surface when draping.

Remarks

Double value that defines the maximum offset used to generalize the draped geometry. Will only remove points inserted via draping; does not affect any points explicitly defined by the user. Default value is 0. ZDrapingTolerance is only applied when IEditorZ::UseZDrapingTolerance is TRUE.

Product Availability

Available with ArcGIS Desktop.

Returns:

The zDrapingTolerance

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setZDrapingTolerance

void setZDrapingTolerance(double zDrapingTolerance)
                          throws IOException,
                                 AutomationException

Determines the allowable error from the surface when draping.

Product Availability

Available with ArcGIS Desktop.

Parameters:

zDrapingTolerance - The zDrapingTolerance (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isDraping

boolean isDraping()
                  throws IOException,
                         AutomationException

Indicates whether sketches are draped onto the surface.

Remarks

This property determines whether new segments added to the edit sketch are draped onto the defined surface. This behavior is only active when the editor's ZCaptureType is SurfaceZ. When draping is TRUE and the ZCaptureType is SurfaceZ then a new vertex will be inserted at each elevation change in the surface (triangle edges in TINs, cell boundaries in Rasters). When using very accurate surfaces, the number of points can be very high. To minimize the number of vertices inserted into the sketch, a tolerance can be defined using IEditorZ::ZDrapingTolerance; this uses the Douglas-Poiker algorithm to determine significant vertices in Z. The Default value is FALSE.

Product Availability

Available with ArcGIS Desktop.

Returns:

The useDraping

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setDraping

void setDraping(boolean useDraping)
                throws IOException,
                       AutomationException

Indicates whether sketches are draped onto the surface.

Product Availability

Available with ArcGIS Desktop.

Parameters:

useDraping - The useDraping (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getSurface

IFunctionalSurface getSurface()
                              throws IOException,
                                     AutomationException

Surface used for Z capture.

Remarks

This property defines the surface used to calculate new z-values. By default, the surface for the editor is built from any available sources (Terrains, Tins, and Rasters) added to the map.

If you choose to use a particular surface for z-capture, assign your surface to this property. This overrides the default "composite" surface defined by the available surfaces defined in your map. This surface does not need to be obtained through a layer in the map, although this is an efficient way to access surface-related information. Any layer associated with this surface does not need to be visible in order to be used for z-capture.

Setting this property to NULL will revert back to the "composite" surface defined by the surfaces in the map.

This property is only active when the editor's ZCaptureType is set to SurfaceZ.

Product Availability

Available with ArcGIS Desktop.

Returns:

A reference to a com.esri.arcgis.geometry.IFunctionalSurface

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setSurfaceByRef

void setSurfaceByRef(IFunctionalSurface surface)
                     throws IOException,
                            AutomationException

Surface used for Z capture.

Product Availability

Available with ArcGIS Desktop.

Parameters:

surface - A reference to a com.esri.arcgis.geometry.IFunctionalSurface (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getZSnapSymbol

IMarkerSymbol getZSnapSymbol()
                             throws IOException,
                                    AutomationException

Symbol used to indicate when vertex is snapped in Z.

Remarks

Use this property to change the symbol displayed when the editor snaps to a particular snap agent in Z coordinate space. The Z snap symbol is displayed if you are working with an edit sketch that is Z-aware and the Z-snapping is set. The ZSnapSymbol is identical to the editor's SnapSymbol by default; if SnapTips (IEditProperties2::SnapTips) are enabled, the Z-value of the snapped location is added to the SnapTip when displayed.

The snap agent knows to draw the snap symbol twice, once to get rid of the old symbol and once to draw the symbol at its new location. When setting the symbol, don't forget to set its ROP property (on the ISymbol interface) to esriROPNotXOrPen. This setting allows the symbol to erase itself when drawn twice in the same location.

Product Availability

Available with ArcGIS Desktop.

Returns:

A reference to a com.esri.arcgis.display.IMarkerSymbol

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setZSnapSymbolByRef

void setZSnapSymbolByRef(IMarkerSymbol symbol)
                         throws IOException,
                                AutomationException

Symbol used to indicate when vertex is snapped in Z.

Product Availability

Available with ArcGIS Desktop.

Parameters:

symbol - A reference to a com.esri.arcgis.display.IMarkerSymbol (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getNotifyZFinalize

INotifyZFinalize getNotifyZFinalize()
                                    throws IOException,
                                           AutomationException

Callback used to notify if ZCapture mode fails.

Remarks

Callback mechanism used when Z capture fails; allows the registered client an opportunity to define Zs prior to editor applying default fallback behavior to ensure Z simplicity (ensures Zs are not defined as NaN and geometry is Z-aware). To receive notification when Z assignment fails, you will need to implement INotifyZFinalize on your class and assign a reference to this property. Only one class can modify or receive this notification; you should code defensively to ensure that another extension is not already plugged in. To unhook, set the NotifyZFinalize property to null.

Product Availability

Available with ArcGIS Desktop.

Returns:

A reference to a com.esri.arcgis.editor.INotifyZFinalize

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setNotifyZFinalizeByRef

void setNotifyZFinalizeByRef(INotifyZFinalize callback)
                             throws IOException,
                                    AutomationException

Callback used to notify if ZCapture mode fails.

Product Availability

Available with ArcGIS Desktop.

Parameters:

callback - A reference to a com.esri.arcgis.editor.INotifyZFinalize (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

initializeFeatureConstruction

IFeatureConstruction initializeFeatureConstruction()
                                                   throws IOException,
                                                          AutomationException

Initialize a FeatureConstruction object that will use the Editor's ZEnvironment settings.

Product Availability

Available with ArcGIS Desktop.

Returns:

A reference to a com.esri.arcgis.geodatabase.IFeatureConstruction

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.