String maths (old function)

The help topic describes the function STRING MATHS — an old function that you can no longer run from the main menu of Surpac, but can still run in a macro.

For information about the newer maths function, see Maths. For information about expressions you can use in maths functions, see Expressions.

Fields on the String maths utility form

Define the files to be processed

Specify the range of files to be processed by entering the Location and ID range.

Retain descriptions

If the description field on input files is to be manipulated or transferred to the output files, enter `Y'.

Define the files to be created

Define the Location code for the range of files to be created

Number of string ranges

For each of the operation groups specified enter the number of string ranges to which the operations are to be applied. Enter the range of strings to which the following operations are to be applied. Up to 100 ranges can be defined. You may have a number of different operations to perform on a particular range of strings such as:

swap Y and Z fields around to change file into section view.
multiply Y field by a constant to exaggerate the scale in this dimension.

Complete the String maths utility form and choose Apply to display the String maths - define required operations form for each string range nominated. This form also appears when you run GRAPHICS STRING MATHS, GRAPHICS SEGMENT MATHS, or GRAPHICS POINT MATHS.

Fields on the String maths - define required operations form

String range number

Display only. This is to help you keep track of the operations you are applying to the strings.

String range

Specify the range of strings to which the following operations are to be applied.

Opfield, Operator and Value

Enter the operations to be applied to the specified string range. Each operation is of the format [OPFIELD][OPERATOR] [VALUE(s)], for example:

Opfield X Operator = Value 14.5

When the desired operations have been entered for the current range, choose Apply. You will then be prompted for the next string range. The Opfields may be X, Y, Z, D1, D2 etc.

When the operations for all string ranges have been defined processing will commence.

Note: If the same string range is nominated more than once, the successive operations specified are performed on the values resulting from the previous operation. Thus although only one operation may be entered for each field for a given range specification, it is possible to perform complex operations by repeating the range and specifying different operations each time.

Allowed Operations

As illustrated above, the general format for specifying an operation is to enter a single character operator followed by one or two operands depending on the operator. If two operands are entered they are separated by a comma.

Operator	Operand(s)	Action
=	value	Set the field EQUAL to the 'value', for example: X = 157.5 D1 = 'Z'
+	value	Respectively add, subtract, multiply and divide the field by the 'value', for example: D1 + 10000 Y-50 X*2.5 X/1.8
-	value
*	value
/	value
C	value	Cut any value above 'value' down to 'value', for example: Z C 30
S	scale, fixed value	Scale value, by factor 'scale' around 'fixed value', for example: D3 S 2,400 The previous example scales all values by a factor of 2 around a fixed value of 400, i.e. 500 will be scaled to 600
D	ndec	Set the number of decimal places for a numeric value in the Description field only. The resultant field is left justified within the Description Field, for example: D1 D 2
F	width, ndec	Format a numeric value in the description field. Make it 'width' characters wide, including ndec' decimal places, for example: D4 F 10,2

Note that operands are generally numeric. The exceptions to this are:

A Description field may be set to a string of characters, for example
D4 = THIS IS A DESC
The operators = +, -, *, /, and C will also accept the operand entries 'X', 'Y', 'Z', 'Dn', 'ID', 'STR', 'PTNO' and 'SEG' which represented the X, Y, Z, nth Description Field, file ID, string number, point number and segment number respectively for the data point being processed. For example, the First Description field may be set to the value in the Z field with the command
D1 = 'Z'

Note: Operands must stribe enclosed in single quotes.

For the operators =, +, -, *, and /, the OPERAND may also be a special function from the following list.

Functions and their Actions

Function	Action
@LEN2D	Set the field to the 2D length of the string or segment to which this point belongs. The length is the sum of the distances between the (X, Y) points in the string.
@LEN3D	As for @LEN2D, but the length is the sum of the distances between the (X, Y, Z) points in the string.
@AREA	Set the field to the area of the closed segment and or string to which the point belongs. If the point belongs to an open string this value is zero.
@LOG	Convert the field to the natural logarithm of its current value.
@LOG10	Convert the field to the base 10 logarithm of its current value.
@EXP	Compute the current field value as exponent to base e.
@EXP10	Compute the current field value as exponent to base 10.
@CLEN2D	Calculate the 2D distance from the start of the current segment to the current point.
@CLEN3D	Calculate the 3D distance from the start of the current segment to the current point.
@SLEN2D	Calculate the 2D length of each of the line segments within a string, i.e. the distance from the current point to the previous point of the current string.
@SLEN3D	Calculate the 3D length of each of the line segments within a string.
@VDIST	Calculate the vertical distance (difference in Z values) between the previous point and the current point of the current string.
@AZ	Calculate the azimuth (bearing) from the previous point to the current point of the current string. The azimuth is expressed as shown below: If you have selected DEGREES as your Angle units, the azimuth is displayed in DDD.MMSS format. If you have selected GRADS as your Angle units, the azimuth is displayed in GRADS to four decimal places.
@DIP	Calculate the dip from the previous point to the current point of the current string. The dip is expressed as shown below: If you have selected DEGREES as your Angle units, the dip is displayed in DDD.MMSS format. If you have selected GRADS as your Angle units, the dip is displayed in GRADS to four decimal places. A negative dip indicates a downward direction, 0 indicates horizontal and a positive dip indicates an upward direction.
@SLOPE	Calculate the slope from the previous point to the current point of the current string. The slope is expressed as a percentage value.
@SIN @COS @TAN	Trigonometric functions which expect angles expressed in decimal degrees. e.g. D1 = @SIN
@ASIN ACOS @ATAN	Trigonometric functions which give answers as angles expressed in decimal degrees.
@JULIAN	Converts a text date in the format 'DD-Mon-YYYY' to a Julian Day Number e.g. D1=@JULIAN
TXTDATE	The inverse of @JULIAN. Takes a Julian Day Number (integer) and converts it to text date of the format 'DD-Mon-YYYY'.

The @MIN, @MAX and @AVE functions are applied to individual segments, so that each segment is treated separately. Because of the way these functions work, they are applied to the data after all other operations for a given string range, regardless of the order in which you define them.

Function	Action
@MIN	Calculate the minimum value for each segment of the opfield specified and store the result in that field.
@MAX	Calculate the maximum value for each segment of the opfield specified, and store the result in that field.
@AVE	Calculate the average value for each segment of the opfield specified and store the result in that field.

Result

A new string file is created which contains the modified string data.