SclCreatePoint

Overview

The SWA (Surpac Work Area) is where all String and DTM data processed by Surpac applications is stored. A complete description of the SWA can be found here.

The SclCreatePoint command creates a new point, at a specified position, in a segment and returns a handle to that point for future operations on that point. In contrast to the SclCreateString and SclCreateSegment commands which return the handle to the string or segment if one already exists, SclCreatePoint will always create a new point at the specified position, provided of course the position is valid. New points can therefore be inserted in between existing points in a segment.

Synopsis

$SegmentHandle SclCreatePoint PointHandle $PointPosition

Description

Create a point at the specified position in the specified segment and return the handle to that point for later use by other Scl commands. If a point already exists at the specified position then the new point is inserted at that position and all existing points whose position is >= the position of the new point have their position increased by 1.

Arguments

SegmentHandle

Passed by value. This is the handle to the segment in which the point is to be created. The segment handle must previously been obtained by using SclCreateSegment or SclIterateNext to obtain the handle to an existing segment in the set of segments for a string.

PointHandle

Passed by reference. This is the variable to which the point handle is assigned. This point handle must be used in later references to the point for modifying the point attributes. When a point is first created it has X, Y and Z values of 0.0 and an empty point description field.

Points have a number of attributes that may be queried or set using the Attribute Management commands in Scl. The point attributes that may be operated on using these commands include:

X, Y, Z - the coordinate values for the point
D1, D2, D3, etc. - Individual, comma separated, sub fields of the point description field
desc - The entire point description field

PointPosition

Passed by value. This is the position in the segment at which the point is to be created. The point position must be >= 0 and <= the number of points in a segment. For an empty segment that contains no only permitted value point position is 0.

A point will always be created, provided the point position is valid. If the point position is less than the number of points in the segment, this is only possible when a segment contains at least 1 point, the new point is inserted at the specified position and all other points whose position is greater than the specified point position will have their point position increased by 1.

This makes it possible to insert new points between existing points in a segment.

Examples

#
# create a swa then create a string (number = 1)in that swa 
# then a create a segment with a single point 
# save the string to a string file and finally destroy the swa
#
SclCreateSwa swahandle "temporary swa"
$swahandle SclCreateString stringhandle 1
$stringhandle SclCreateSegment segmenthandle 0
$segmenthandle SclCreatePoint pointhandle 0
$pointhandle SclSetValueByName x 1.0
$pointhandle SclSetValueByName y 2.0
$pointhandle SclSetValueByName z 3.0
$swahandle SclSwaSaveStringFile test1.str
SclDestroy swahandle
puts "String 1 created with 1 segment and 1 point and saved to test1.str"

#
# this example creates a segment with 2 points and shows how the
# second point that is created is inserted into the segment so that it
# is ordered before the first point that is created
SclCreateSwa SwaHandle "temporary swa"
$SwaHandle SclCreateString StringHandle 1
$StringHandle SclCreateSegment SegmentHandle 0
$SegmentHandle SclCreatePoint PointHandle 0
$PointHandle SclSetValueByName x 1.0
$PointHandle SclSetValueByName y 2.0
$PointHandle SclSetValueByName z 3.0
# now insert the second point before the first point
$SegmentHandle SclCreatePoint PointHandle 0
$PointHandle SclSetValueByName x 4.0
$PointHandle SclSetValueByName y 5.0
$PointHandle SclSetValueByName z 6.0
$SwaHandle SclSwaSaveStringFile test1.str
SclDestroy SwaHandle
puts "String 1 created with 1 segment and 2 points and saved to test1.str"

#
# this example creates a segment with 2 points and shows how the
# second point that is created at the end of the segment by using
# SclCountItems to determine how many points exist in the segment
SclCreateSwa SwaHandle "temporary swa"
$SwaHandle SclCreateString StringHandle 1
$StringHandle SclCreateSegment SegmentHandle 0
$SegmentHandle SclCreatePoint PointHandle 0
$PointHandle SclSetValueByName x 1.0
$PointHandle SclSetValueByName y 2.0
$PointHandle SclSetValueByName z 3.0
# now add the second point at the end of the segment
$SegmentHandle SclCreatePoint PointHandle [$SegmentHandle SclCountItems]
$PointHandle SclSetValueByName x 4.0
$PointHandle SclSetValueByName y 5.0
$PointHandle SclSetValueByName z 6.0
$SwaHandle SclSwaSaveStringFile test1.str
SclDestroy SwaHandle
puts "String 1 created with 1 segment and 2 points and saved to test1.str"