MapGuide API Extensions v5.0

  

TIN/Contour Control

The TIN/Contour Control is an ActiveX component that extends the capability of the MapGuide Viewer API by enabling the development of applications that require the TIN generation and contouring. The Control provides a set of public methods that enable the developer to:

  • establish the points to use for the TIN,
  • set parameters related to construction of the TIN,
  • generate the TIN,
  • retrieve the coordinates of the polygons or the arcs that form the TIN,
  • infill the TIN by using the centroids of TIN polygons or by adding new points,
  • assign new Z values for TIN nodes,
  • set parameters related to contour line generation,
  • create contour lines,
  • retrieve the coordinates of the contour lines.

The control appears as a clickable button:

HgisTin

The button may be sized through the BoxWidth and BoxHeight parameters while the label is set through the ButtonLabel parameter. Clicking on the button pulls up the TIN/Contour About Dialog:

HgisTinMenu

The control allows display of the coordinates of the points selected to generate the TIN, as well as some of the parameters related to TIN and contour generation:

HgisTinListPnts

The control also allows display of the last object loaded into memory, whether it is a node, arc or polygon in the TIN, or a contour line. The following graphic portrays the attributes of a TIN polygon:

HgisTinListVerts

Loading the Control

Instructions for implementing the control on web pages are provided with the Toolkit documentation.

Parameters

Name Description
AboutDlgStatus Toggles the ability to display the About Dialog Box by clicking on the Control. A value of "0" prevents the display of the Dialog, while a value of "1" enables display (Default: "1" )
ButtonLabel The label to appear on the button (Default: "Hgis TIN" )
BoxWidth The width of the control in Twips (Default: 1500 Minimum: 200 )
BoxHeight The height of the control in Twips (Default: 500 Minimum: 50 )

TIN Generation and Contouring

The general sequence of steps for creating a TIN and contouring are as follows:

  • ensure that the coordinates of objects on the point layer to be analyzed can be accessed (validatePassword())
  • set parameters for the analysis, including the type of coordinates, default and invalid Z values, maximum number of points, border search distance and number of optimization cycles
  • submit the points to be analyzed one at at time (addPointsXY()) or as a collection of point objects (addPointsAsCollection())
  • undertake the analysis (calculateTIN())
  • add additional nodes to the TIN by infilling with:
    • additional points (addPointsXY() or addPointsAsCollection())
    • points located at the centroid of all TIN polygons (infillTINCentroids())
    • points located at the centroid of TIN polygons whose area is larger than the average polygon area (infillTINArea())
  • retrieve the TIN objects for display on a Redline layer through the MapGuide Viewer API
  • obtain the minimum and maximum Z values in the TIN (getMinZ() and getMaxZ())
  • specify the minimum and maximum contour levels, contour spacing and line smoothing
  • generate the contour lines (calculateContours())
  • retrieve the contour lines for display on a Redline layer through the MapGuide Viewer API

To obtain the geometry of each contour line created:

  • obtain the number of polygons generated (getNumContours())
  • for each polygon:
    • set the nth contour as the current object in the Control (setObjectAsContourAt())
    • retrieve the key and name (getObjectKey() and getObjectName())
    • retrieve the number of internal objects in the Contour Line (getObjectNumObjects())
    • retrieve a collection of the vertice counts of the internal objects (getObjectNumVerts())
    • retrieve a collection of the vertices of the internal objects (getObjectVertices())

A similar process may be used to retrieve the nodes, arcs and polygons of the TIN. The number of objects of a particular type may be obtained by one of the four getNumXXXX() methods. The object with a particular index may then be set as the current object in the Control by one of the four setObjectAsXXXXAt() methods. Once an object has been set as the current object, the following commands may be issued to transfer the information from the Control to the application:

  • getObjectKey()
  • getObjectName()
  • getObjectType()
  • getObjectMinX()
  • getObjectMinY()
  • getObjectMaxX()
  • getObjectMaxY()
  • getObjectNumObjects()
  • getObjectNumVerts()
  • getObjectVertices()

The key value assigned to nodes, arcs and polygons in the TIN, and to contour lines, is equivalent to the index location of the object in its respective list. The name value assigned to the nodes is controlled by the setNodeNameOut() method: the name may be either the original key value of the input point (or points in the case of shared X,Y locations), or the Z value. The name value assigned to arcs is the index values of its start and end nodes, separated by the ID Delimiter defined by setIDDelimiter(). For example, if an arc starts at node 17 and ends at node 32, then its name will be "17:32". The name value assigned to a TIN polygon is defined by the setPolygonNameOut method. The name may be either the index values of its three arcs or its three nodes, ordered in a counter-clockwise manner, with each index separated by the ID Delimiter. For example, a polygon name based on arcs may be "13:-25:42"; note that the arcs are directed. The name value assigned to a contour line is its Z value.

When computing the TIN, if more than one input point shares the same location, then the Z values of the points are averaged and the keys are appended to form a new key; the separator between the original key values is specified with the setIDDelimiter(). For example, if the ID Delimiter was set to ":" and points with key values of "13" and "6" share the same location, then the resultant key will be "13:6". Points are the X,Y,Z values that are input; nodes are the X,Y,Z values that constitute the TIN. Thus, the number of nodes in the result may not equal the number of input points.

The Z value may be altered before and/or after a TIN has been generated. In some applications, it may be necessary to generate the TIN once, then alter the Z values of the nodes in order to contour different attributes. In such cases, the setNodeZValueByKey() method may be used in order to adjust each point's/node's Z value. Remember, if two or more points shared the same location, then the resultant node will have the keys of each of the originating points.

The setDefaultZValue() method allows the user to assign a value that will be assigned to input points/nodes in cases where no Z value has been provided for the point. The setInvalidZValue() performs a similar function; however, a node that is assigned such a value is an Invalid node that will be used in TIN generation but will not be used for contouring. When points share the same location, if one point has an Invalid Z value, then the resultant node will also be assigned an Invalid Z value. The number of Invalid points may be obtained by getNumInvalidPoints(). The key of the Nth Invalid point may be retrieved by the getInvalidPointKey() method; a subsequent call to setNodeZValueByKey() can be used to establish a valid Z value for the point/node.

It is important to bear in mind the types of coordinates that are being sent to the Control's methods, which is defined by the setCoordType() method:

  • 0 - coordinates are in latitude/longitude
     
  • 1 - coordinates are in MCS units
The getVertices() method of the MGMapObject class of the MapGuide Viewer API returns coordinates in MCS units, while the getExtents() method and the digitizing methods, return coordinates in latitude/longitude. All coordinates passed to the Control must either be in MCS units or latitude/longitude, as defined by setCoordType(). If the coordinates are in latitude/longitude, then a TIN may be generated, but it cannot be either infilled or contoured.

Methods

A complete list of the public methods is provided with the Toolkit documentation.

 © 2002, Hunter GIS