How to use SCL commands to make points in Surpac

Certainly, one of my favorite features of Surpac is the ability to script and automate tasks using TCL. Using the record macro function allows for an easy way to loop and repeat a series of existing functions within Surpac, and can unlock a lot of potential for creative Surpac users.

Once we’ve mastered the ability manipulate the existing tools in Surpac using the within our macros, the next logical step to becoming a bonafide Surpac guru is to be able to create points, lines and triangles in the graphics workspace. In this post we will walk through the steps required to use TCL and SCL to create some new data into an existing layer in Surpac.

To start, let’s review the hierarchy of data in the Surpac workspace.

So, for a point to exist in the graphics workspace, it needs to have its complete address in the data hierarchy including Segment, String, Layer and Viewport. Let’s look at some the SCL commands we will need to know. Notice how the first 5 commands are related to the data hierarchy we just saw.

SclGetActiveViewport

SclGetActiveViewport ViewportHandle

This function will create a TCL variable which contains the unique name of the viewport. In this case the variable is called “ViewportHandle” but you can use anything you like here, as long it is valid as the name of a variable in TCL.

SclGetActiveLayer

$ViewportHandle SclGetActiveLayer SwaHandle

This function needs the name of the viewport for its query so we will pass it the name of the viewport using the variable name we made in SclGetActiveViewport. It will make another new variable for us, this time called “SwaHandle”

SclCreateString

$SwaHandle SclCreateString StringHandle 4

This function will create another variable, “StringHandle” and requires us to specify the layer that the string is meant to exist in, as well as the layer and string number that we will assign to the points. This needs to be a positive integer, here I’m using string # 4.

SclCreateSegment

$StringHandle SclCreateSegment SegmentHandle 0

Here’s where things get fun. The syntax here is identical to SclCreateString where we create another new variable called “SegmentHandle” and an argument that specifies the segment number, here I’ve used segment # 0. However, a problem arises if string 4 segment 0 already exists in the graphics workspace. To get around this I use another SCL command SclCountItems.

Combining these two functions gives us:

$StringHandle SclCreateSegment SegmentHandle [$StringHandle SclCountItems]

SclCreatePoint

$SegmentHandle SclCreatePoint PointHandle [$SegmentHandle SclCountItems]

The syntax here follows the same as SclCreateSegment and we can also use SclCountItems here too.

The points will now actually exist, and could be drawn to the graphics workspace, however their coordinates will at a default at the origin (0,0,0) in the graphics workspace. To give them some meaningful coordinates we need our next command

SclSetValueByName

$PointHandle SclSetValueByName x $x_coordinate

$PointHandle SclSetValueByName y $y_coordinate

$PointHandle SclSetValueByName z $z_coordinate

When making new points, SclSetValueByName is typically used three times, to specify all three coordinates for the new point. Optionally you can also set d-fields with SclSetValueByName.

$PointHandle SclSetValueByName d1 “d1_value_goes_here”

$PointHandle SclSetValueByName d2 123.456

SclDraw

$SwaHandle SclDraw

The final thing we need to do is to tell Surpac to draw the new points on the screen. This can be done at any level of the hierarchy below Viewport, but I typically save the action of drawing, until I’m done making all of the contributions to the layer, and I will draw everything at once.

Let’s combine these functions into a simple example.

Information on Additional Commands

In addition to the functions discussed in this post, the example used several simple TCL commands. Information about these functions can be found by using the following links