Print

SclGetValueByName

Overview

Some Scl objects have one or more parameters whose values can be obtained, and in some cases, set to satisfy the needs of the Scl programmer. The Scl objects whose values may be obtained and/or set include:

• Swa objects:
  • Point
  • Segment
  • String
  • Triangle
  • Trisolation
  • Triobject
  • Swa
• Database objects:
  • Row handle

Only those attributes that have a physical storage equivalent (for example, the X field for a point in a string file) may have their value set while other attributes whose values are dependent on a number of constituent objects may only be queried. A good example of this type of value is the 2D length of a segment since this is dependent on the points in the segment.

SclGetValueByName uses a descriptive name to describe the attribute for which a value is required. Scl retrieves the value for the attribute of interest by performing a search through the list of known attribute names to determine an equivalent integer index for the attribute of interest. This equivalent integer index is then used to obtain the value of interest.

If the attribute values being obtained are being processed inside a for or while loop, and if there are likely to be many iterations of the loop, an alternate strategy that is more efficient in its use of CPU resources can be used. This alternative method uses SclGetAttributeIndex to obtain the integer index value for the attribute of interest outside the loop and then uses SclGetValueByIndex inside the loop. By performing the index lookup outside the iteration loop performance is enhanced by a small margin.

Synopsis

$ObjectHandle SclGetValueByName $AttributeName
$ObjectHandle SclGetValueByName $AttributeName NewObjectHandle
set value [$TrisolationHandle SclGetValueByName namedAttributeName]

Description

Returns the value of the requested attribute from the specified Scl object. Depending on the type of attribute for which the value is being obtained, the value is either returned as the result of the function or it is assigned to the NewObjectHandle argument.

The second form of SclGetValueByName shown above is only used if the attribute being queried is a triangle vertex or neighbour triangle. That is, the attribute name is either v0, v1, v2, n0, n1 or n2.

The third form of SclGetValueByName is used only when getting the value of a named attribute.

Arguments

• ObjectHandle

The ObjectHandle variable must contain a handle to an Scl object to which the SclGetValueByName command can be applied. Permitted Scl object types for the SclGetValueByName command are:

• Swa objects
  • Point
  • Segment
  • String
  • Triangle
  • Trisolation
  • Triobject
  • Swa
• Database objects
  • Row handle
• TrisolationHandle

Passed by value. A handle to the trisolation for which to retrieve the named attribute value.

• AttributeName

Passed by Value. The name of the attribute for which the value is required. Each Scl object type has a specific set of attributes that can be queried. The attribute names that can be queried for each Scl object type are shown below.

Scl object type/s	Attribute name/s	Description	Returned value
Point	x, y, z	The X, Y or Z values for a point	A floating point number
	desc	The description value for a point.	A string of characters.
	d1, d2, d3, ...	Individual subfields, using a comma as delimiter between fields, of the point description field obtained using the desc attribute. The maximum number of subfields is 100 with a maximum number of characters, including comma delimiters, of 512.	A string of characters
Segment String Swa	desc, d1, d2, d3, ...	The description value, or subfields, for a segment, string or Swa. Note that while this value can be set and queried, the segment, string or Swa description is not saved to the string file using the SclSwaSaveStringFile command. The description value for segment, string and Swa objects is useful for storing essential data that applies to the segment, string or Swa when developing advanced applications using Scl.	A string of characters
	xmin, xmax, ymin, ymax, zmin, zmax	The minimum or maximum, X, Y or Z value of the segment, string of Swa.	A real number.
	2dlength, 3dlength	The 2 dimensional or 3 dimensional length of the segment, string or swa.	A real number
	closure	The closure state of the segment, string or swa. A segment is closed only if the first and last points of the segment have the same X, Y and Z values. The closure state of a string is closed if all segments of the string are closed, open if all segments of the string are open and indeterminate if neither of these states are satisfied. The closure state of a Swa is closed if all strings of the swa are closed, open if all strings of the swa are open and indeterminate if neither of these states are satisfied.	closed, open or indeterminate depending on the closure state.
	area	The area of the segment, string or swa but only if the segment, string or swa is closed. See closure above.	A real number
	bestfitarea	The area of the segment, string or swa projected onto the best fit plane of the segment for which the area is calculated. The segment, string or swa must be closed. See closure above.	A real number
	shapetype	The type of shape, convex or concave, of the segment, string or Swa. A segment is convex if the segment is closed and if all internal angles of the segment are <= 180 degrees. If any internal angle is > 180 degrees the segment is concave. If the segment is open its shape type is indeterminate. A string is convex if all its segments are convex, concave if all its segments are concave otherwise indeterminate. A Swa is convex if all its strings are convex, concave if all its strings are concave otherwise indeterminate.	convex, concave or indeterminate
	direction	The direction of a segment, string or Swa is determined on the projection of the data into the XY plane. At the segment level, the segment must be closed and it must have a non zero area to have any concept of direction. An area > 0 implies a segment that is clockwise in direction while an area < 0 implies that a segment is anti-clockwise in direction. Any segment that has an area of 0 has an indeterminate direction. Any segment that self intersects will have an ambiguous direction that cannot be trusted. If all segments of a string are clockwise then the string is clockwise. If all segments of a string are anti-clockwise the string is anti-clockwise. Otherwise the string direction is indeterminate. If all strings of a Swa are clockwise then the Swa is clockwise. If all strings of a Swa are anti-clockwise the Swa is anti-clockwise. Otherwise the Swa direction is indeterminate.	clockwise, anti-clockwise or indeterminate
triangle	v0, v1, v2	The point handle of the point that exists at any of the 3 triangle vertices.	The value returned is an Scl point handle and can be used with SclGetValueByName to determine the X, Y and Z values of the vertices.
	n0, n1, n2	The triangle handle of a neighbouring triangle. Neighbouring triangles share a common edge so a triangle may have up to three neighbours.	If the neighbouring triangle exists the value returned is an Scl triangle handle.
trisolation	closure	The closure state of a trisolation is closed only if all triangles in the trisolation have a triangle as a neighbour on all three edges.	The values closed or open are returned appropriately.
	volume	The volume of the trisolation is returned only if the trisolation is closed and has no self intersections.	A real number
trisolation and triobject	<named attribute>	The value of a specific named attribute in the trisolation or triobject.	A character string
Triangle Trisolation Triobject	desc, d1, d2, d3, ...	The description value, or subfields, for a triangle, trisolation or Triobject. Unlike segments, strings and Swas, this value can be set AND queried with the value set and queried being loaded from or saved to the DTM file.	A character string
Viewport	visibility, facevisibility, edgevisibility, selectability, rendering, edgelighting, colourinterpolation title, readonly, rotationincrement, zoomfactor, projection, stereo, hiddensurfaces, 3daxis, controls, blockmodeledges, blockmodelfaces	A number of attributes for viewports and for graphics layers in viewports can be retrieved using a valid viewport handle. All these attributes are described fully in the SclViewport command documentation. Click here to jump to the appropriate section of the manual.	A character string
Row handle	Column name	The name of any column in the database table to which the row handle applies may be used. Note that a row handle can only be obtained by using the SclQuery command.	The value from the specified column of the current row.

• NewObjectHandle

If obtaining triangle vertices or neighbouring triangles using the attributes v0, v1, v2, n0, n1 or n2 then the handle of the object requested is assigned to the variable named here.

• namedAttributeName

Passed by value. The name of the named attribute in the trisolation for which to retrieve the value.

Returns

$ObjectHandle SclGetValueByName $AttributeName
This form of the SclGetValueByName command returns the value of interest as result of the command.

$ObjectHandle SclGetValueByIndex $AttributeIndex NewObjectHandle
This form of the SclGetValueByIndex command returns the results of the command into the NewObjectHandle variable. This form is only used if the AttributeIndex argument is for a triangle vertex or neighbour triangle.

If a triangle has one or more edges located on the trisolation boundary then no neighbour triangle exists for these particular edges. When querying a triangle object for neighbouring triangles (by using the attributes n0, n1, n2) a value of $SCL_TRUE is returned if a valid triangle object was assigned to the NewObjectHandle variable. If no neighbour triangle exists then a value of $SCL_FALSE is returned and NewObjectHandle should not be used.

set value [$TrisolationHandle SclGetValueByName namedAttributeName]
This form of the command returns the value of the specified named attribute.

Examples

#
# This example selects a point and then displays all attribute data for the
# point, segment, and string that it is possible to query 
#
set status [ SclSelectPoint PointHandle "Select a point" layer string_id \
segment_no point_no digx digy digz description ]
if {$status == $SCL_OK} {
  puts ">>>> Point attributes <<<<"
  puts "X = [$PointHandle SclGetValueByName x]"
  puts "Y = [$PointHandle SclGetValueByName y]"
  puts "Z = [$PointHandle SclGetValueByName z]"
  puts "Desc = [$PointHandle SclGetValueByName desc]"
  #  the segment attributes
  $PointHandle SclGetParent SegmentHandle 
  puts ">>>> Segment attributes <<<<"
  puts "xmin = [$SegmentHandle SclGetValueByName xmin]"
  puts "xmax = [$SegmentHandle SclGetValueByName xmax]"
  puts "ymin = [$SegmentHandle SclGetValueByName ymin]"
  puts "ymax = [$SegmentHandle SclGetValueByName ymax]"
  puts "zmin = [$SegmentHandle SclGetValueByName zmin]"
  puts "zmax = [$SegmentHandle SclGetValueByName zmax]"
  puts "2D length = [$SegmentHandle SclGetValueByName 2dlength]"
  puts "3D length = [$SegmentHandle SclGetValueByName 3dlength]"
  puts "Closure = [$SegmentHandle SclGetValueByName closure]"
  puts "Area = [$SegmentHandle SclGetValueByName area]"
  puts "Best Fit Area = [$SegmentHandle SclGetValueByName bestfitarea]"
  puts "Direction = [$SegmentHandle SclGetValueByName direction]"
  puts "Shapetype = [$SegmentHandle SclGetValueByName shapetype]"
  #  the string attributes
  $SegmentHandle SclGetParent StringHandle 
  puts ">>>> String attrbutes <<<<"
  puts "xmin = [$StringHandle SclGetValueByName xmin]"
  puts "xmax = [$StringHandle SclGetValueByName xmax]"
  puts "ymin = [$StringHandle SclGetValueByName ymin]"
  puts "ymax = [$StringHandle SclGetValueByName ymax]"
  puts "zmin = [$StringHandle SclGetValueByName zmin]"
  puts "zmax = [$StringHandle SclGetValueByName zmax]"
  puts "2D length = [$StringHandle SclGetValueByName 2dlength]"
  puts "3D length = [$StringHandle SclGetValueByName 3dlength]"
  puts "Closure = [$StringHandle SclGetValueByName closure]"
  puts "Area = [$StringHandle SclGetValueByName area]"
  puts "Best Fit Area = [$StringHandle SclGetValueByName bestfitarea]"
  puts "Direction = [$StringHandle SclGetValueByName direction]"
  puts "Shapetype = [$StringHandle SclGetValueByName shapetype]"
}

# This example displays the name and value of each named attribute in all the trisolations 
# in the active layer
SclGetActiveViewport ViewportHandle
$ViewportHandle SclGetActiveLayer SwaHandle
$SwaHandle SclGetTriobjects TriobjectsHandle
$TriobjectsHandle SclIterateFirst TriobjectsIterator
while {[$TriobjectsIterator SclIterateNext TriobjectHandle] == $SCL_TRUE} {
  $TriobjectHandle SclIterateFirst TrisolationIterator
  while {[$TrisolationIterator SclIterateNext TrisolationHandle] == $SCL_TRUE} {   
    set names [$TrisolationHandle SclGetAttributeNames]
    puts "Object: [$TriobjectHandle SclGetId]"
	puts "Name       Value"
	foreach name $names {
	  set theName [$TrisolationHandle SclGetValueByName $name]
	  puts "$name     $theName"
	}
  }
}