com.esri.arcgis.geometry
Interface IMultiPatch

All Superinterfaces:
IGeometry, Serializable
All Known Subinterfaces:
IMultiPatch2
All Known Implementing Classes:
IMultiPatch2Proxy, IMultiPatchProxy, MultiPatch

public interface IMultiPatch
extends IGeometry, Serializable

Provides access to members that identify a MultiPatch and permit controlled access to its parts.

Superseded By

IMultiPatch2

Description

A multipatch is a series of three-dimensional surfaces that are represented as groups of geometries. These geometries may be Triangle Strips, Triangle Fans, or groups of Rings (ring-groups ). In a multipatch there is one triangle strip, or triangle fan per surface, whereas there can be one or more rings per surface. A single multipatch may comprise combinations of triangle strips, triangle fans, and ring groups.

--------------------- Multipatch ---------------------

| | |

Triangle Strip Triangle Fan Rings

Triangle strips are a sequence of connected triangles 0,1,2,3,4,...n that each build from their predecessor.

Triangle fans are a sequence of connected triangles that each use the first point in the sequence as an apex 0,1,0,2,0,3,0,4,...,0,n

Triangle strips and triangle fans specify surfaces by themselves. A ring works contextually with other rings to specify a surface, but it may also be its own surface.

<->

The main difference between the ring and the triangles for a developer is when using

IPointCollection :: GetPoint(index)

for the multipatch.

If the index points to a point in a (segment of a) ring, you get a reference to a copy of the point, otherwise you get a reference to the point directly. This means that you can directly modify points in triangles but in order to modify points in a ring, you must use

IPointCollection :: UpdatePoint

Ring Groups

--------------

Rings all have the same structure, but they have a special role when defining a multipatch surface. The roles of rings are determined by the multipatch (they are not a property of the ring itself)

The roles are called:

One rule that is not enforced, but that should be followed when creating a ring group, is that all rings in a group are co-planar. This is an OpenGL 3D graphics standard.

This means, for example, that a closed cube would comprise six ring groups. Each group would have a single ring. A hole in one of the sides of the cube would not alter the number of groups. Instead, an additional ring would be added to one of the groups to represent the hole.

<->

Another rule is that there is only one group per outer ring. If, for instance, there was another co-planar ring inside the hole mentioned above, this would be represented as another group. This is because it is affectively another surface, even though it is coplanar with the side-ring and the hole-ring.

<->

Each group has a ring sequence, and in combination with the role of the rings in the sequence, a surface can be defined. A multipatch can have a number of surfaces represented by ring groups, the different roles of the rings help to determine the one group from the next, and within each group, determine the structure of the surface.

Following are some examples of using the roles of rings in the ring sequence of a group to define a surface.

---------------------------------------------------------

Multipatch 1 - First Ring designates the start of a ring group. Any subsequent surface other than Ring breaks the sequence.

Triangle strip, triangle fan, ring, ring, ring, first ring, ring

The above sequence is interpreted as five surfaces as follows:

---------------------------------------------------------

Multipatch 2 - Triangle strip, outer ring, inner ring, inner ring, ring, first ring, ring

This sequence is interpreted as four surfaces as follows:

---------------------------------------------------------

Outer ring/Inner ring nomenclature is a more structured form for the surface than First Ring/Ring series. The former explicitly defines that any subsequent inner is a hole in the ring. In the sequence "Inner" must always follow "Outer" or "Inner". It would otherwise be an error. Anything other than "Inner" would stop the sequence for the Inner/Outer group.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux


Method Summary
 IRing findBeginningRing(IRing followingRing)
          Returns the beginning ring of the ring group containing the specified following ring.
 int getBeginningRingCount(int ringTypesDesired)
          The number of beginning rings, counting only those of the desired types.
 int getFollowingRingCount(IRing beginningRing)
          The number of following rings in the ring group that starts with the specified beginning ring.
 int getRingType(IRing queryRing, boolean[] isBeginningRing)
          Gets the esriMultiPatchRingType of the input Ring and returns a boolean indicating if that ring is a beginning ring.
 IGeometry getXYFootprint()
          A reference to a cached copy of the multipatch's footprint in the x-y plane.
 void invalXYFootprint()
          Notifies the multipatch that its cached footprint has been modified by an outside agent.
 void putRingType(IRing queryRing, int ringType)
          Defines the type of the input Ring.
 void queryBeginningRings(int ringTypesDesired, int numBeginningRingsRequested, IRing[] beginningRings)
          Deprecated. This method uses C style arrays which are not supported in the ArcGIS API for Java. It is replaced by GeometryEnvironment.queryBeginningRings(com.esri.arcgis.geometry.IMultiPatch, int, com.esri.arcgis.geometry.IRing[][]).
 void queryFollowingRings(IRing beginningRing, int numFollowingRingsRequested, IRing[] followingRings)
          Deprecated. This method uses C style arrays which are not supported in the ArcGIS API for Java. It is replaced by GeometryEnvironment.queryFollowingRings(com.esri.arcgis.geometry.IMultiPatch, com.esri.arcgis.geometry.IRing, com.esri.arcgis.geometry.IRing[][]).
 
Methods inherited from interface com.esri.arcgis.geometry.IGeometry
geoNormalize, geoNormalizeFromLongitude, getDimension, getEnvelope, getGeometryType, getSpatialReference, isEmpty, project, queryEnvelope, setEmpty, setSpatialReferenceByRef, snapToSpatialReference
 

Method Detail

findBeginningRing

IRing findBeginningRing(IRing followingRing)
                        throws IOException,
                               AutomationException
Returns the beginning ring of the ring group containing the specified following ring.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getBeginningRingCount

int getBeginningRingCount(int ringTypesDesired)
                          throws IOException,
                                 AutomationException
The number of beginning rings, counting only those of the desired types.

Product Availability

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

Parameters:
ringTypesDesired - The ringTypesDesired (in)
Returns:
The beginningRingCount
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

queryBeginningRings

void queryBeginningRings(int ringTypesDesired,
                         int numBeginningRingsRequested,
                         IRing[] beginningRings)
                         throws IOException,
                                AutomationException
Deprecated. This method uses C style arrays which are not supported in the ArcGIS API for Java. It is replaced by GeometryEnvironment.queryBeginningRings(com.esri.arcgis.geometry.IMultiPatch, int, com.esri.arcgis.geometry.IRing[][]).

Populates an array with references to all beginning rings of the specified types. This method is intended for internal use only.

Remarks

When using C# or VB.NET you must use the IGeometryBridge interface to call this method.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
ringTypesDesired - The ringTypesDesired (in)
numBeginningRingsRequested - The numBeginningRingsRequested (in)
beginningRings - A reference to a com.esri.arcgis.geometry.IRing (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getFollowingRingCount

int getFollowingRingCount(IRing beginningRing)
                          throws IOException,
                                 AutomationException
The number of following rings in the ring group that starts with the specified beginning ring.

Product Availability

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

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

queryFollowingRings

void queryFollowingRings(IRing beginningRing,
                         int numFollowingRingsRequested,
                         IRing[] followingRings)
                         throws IOException,
                                AutomationException
Deprecated. This method uses C style arrays which are not supported in the ArcGIS API for Java. It is replaced by GeometryEnvironment.queryFollowingRings(com.esri.arcgis.geometry.IMultiPatch, com.esri.arcgis.geometry.IRing, com.esri.arcgis.geometry.IRing[][]).

Populates an array with references to following rings that are in the ring group that starts with the specified beginning ring. This method is intended for internal use only.

Remarks

When using C# or VB.NET you must use the IGeometryBridge interface to call this method.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
beginningRing - A reference to a com.esri.arcgis.geometry.IRing (in)
numFollowingRingsRequested - The numFollowingRingsRequested (in)
followingRings - A reference to a com.esri.arcgis.geometry.IRing (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getRingType

int getRingType(IRing queryRing,
                boolean[] isBeginningRing)
                throws IOException,
                       AutomationException
Gets the esriMultiPatchRingType of the input Ring and returns a boolean indicating if that ring is a beginning ring.

Remarks

IMultiPatch GetRingType Example

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
queryRing - A reference to a com.esri.arcgis.geometry.IRing (in)
isBeginningRing - The isBeginningRing (in/out: use single element array)
Returns:
A com.esri.arcgis.geometry.esriMultiPatchRingType constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

putRingType

void putRingType(IRing queryRing,
                 int ringType)
                 throws IOException,
                        AutomationException
Defines the type of the input Ring.

Remarks

IMultiPatch PutRingType Example

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
queryRing - A reference to a com.esri.arcgis.geometry.IRing (in)
ringType - A com.esri.arcgis.geometry.esriMultiPatchRingType constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getXYFootprint

IGeometry getXYFootprint()
                         throws IOException,
                                AutomationException
A reference to a cached copy of the multipatch's footprint in the x-y plane. If the footprint is modified, InvalXYFootprint should be called.

Description

Returns the 2D projection of the MultiPatch to the XY-Plane. The XY-Plane projection of a MultiPatch is called the "XYFootprint" of the MultiPatch. The XYFootprint is used to display MultiPatches in a 2D environment as well as perform simple time-efficient calculations.

Remarks

To ensure that the XYFootpring is current (this is especially important if you directly modify the XYFootprint or one of the MultiPatch parts), call InvalXYFootprint.

IMultiPatch XYFootprint Example

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

invalXYFootprint

void invalXYFootprint()
                      throws IOException,
                             AutomationException
Notifies the multipatch that its cached footprint has been modified by an outside agent. The footprint will be recalculated the next time it is requested.

Description

InvalXYFootprint tells the MultiPatch that the XYFootprint it holds may have changed without its knowledge and needs to be recalculated before it can be used. InvalXYFootprint should be called anytime the parts of the MultiPatch are altered without altering the MultiPatch as a whole. Operations which operate on the entire MultiPatch or utilize the MultiPatch interfaces do not require InvalXYFootprint to be called.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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