String maths
The String Maths functions allow you to modify the data in a string file (or several string files) replacing the fields associated with each point (x, y, z, or the description fields D1, …) with values calculated using generic expressions.
To run this function: Choose Edit > Layer > Maths, Edit > String > Maths, Edit > Segment > Maths, File tools > String maths, or...
- In the Function Chooser, type one of the following function names, and press ENTER.
The GRAPHICS Maths functions work on the current active layer, or the selected portions of the current active layer. You can launch these functions by right-clicking in Graphics or the Layer Manager. All these functions also use generic expressions.
Note: These functions are enhanced versions of the older, redundant functions. The older functions are still available so that any existing macros which use them will still run correctly although the menu options run the new functions instead of the old ones. The old functions that relate to these new functions are:
Fields on the String maths form
Define the files to be processed
Specify the range of files to be processed by entering the Location and ID Range. This field has no bearing on the GRAPHICS functions and so does not exist on the form.
Define the files to be created
Define the Location code for the range of files to be created. This Location can be the same as the Location given above if you desire the output files to have the same names as the input files.
This field has no bearing on the GRAPHICS functions and so does not exist on the form.
A scrolling region exists for defining the expressions to be assigned to fields. The columns in this scrolling region are:
String Range
The range of strings to apply this assignment and the assignments in subsequent rows up to the next non-blank String Range. The special value of "all" can be used to indicate that the range applies to all strings in the file.
The string range field only applies to the STR MATHS and GRAPHICS LAYER MATHS functions, all others do not display this field.
Each block of assignments for a particular string range is completely processed before the next string range is considered. In this way it is possible to calculate the average grade for each segment and assign it to a _segment_Dn field and then use that average grade value in a block of assignments for a later string range.
Inappropriate use of non-blank string ranges, especially all, can cause very different results to what might be expected. Results of an operation are committed as soon as a the next non-blank range is encountered, or the last operation is processed. Inappropriate placing of non-blank string ranges may cause operations to produce unexpected results.
This approach is necessary as it would be impossible to swap the contents of fields otherwise. This is best demonstrated by example:
Example of correct usage to swap fields
This example swaps the contents of the X and Y fields by first assigning the X field to the Y field. Recall that this operation is not committed at this time because if it were then both the X and Y fields would contain the value of the X field. The Y field is then assigned to X field. As this is the last operation the results are now committed to the target fields.
| String Range | Constraint | Field | Expression |
|---|---|---|---|
| all | y | x | |
| x | y |
Example of incorrect usage to swap fields
This example attempts to swap the contents of the X and Y fields as in the above example. The result though is not as expected because the presence of a non-blank range for the second operation causes the first operation to be committed. The outcome is that the X and Y fields both contain the same value, that of the original X field.
| String Range | Constraint | Field | Expression |
|---|---|---|---|
| all | y | x | |
| all | x | y |
Constraint
An extra constraint to limit which points will be updated using this assignment. This is a generic expression which must have a boolean value. As an example the Constraint can be used to limit the assignment to the first point in each segment, or to only apply the assignment to closed segments.
Field
The field to be assigned with the result of the following expression. The field can be one of X, Y, Z, or Dn where n is an integer greater than or equal to one. Dn represents the nth description field. As well as these values for the fields of a point they can be prefixed by _segment_ , _string_, or _file_ to update the field for all the points in the segment, string, or file respectively. When these special prefixed fields are used the expression is calculated at the end of processing for the respective segment, string or file and then the field in all the associated points is update. That is rows assigning explicit point fields are completed for each point of the segment, string or file before the expression for segment, string, or file fields is evaluated. Within the assignments for a given string range it is also possible to use temporary variables known as _tmp1, _tmp2, … to store intermediate values.
Expression
The expression whose result will be assigned to the indicated field. You can use the generic expression syntax, and also the following variables that are relevant to strings.
| Variable | Description |
|---|---|
| X | The value of the X coordinate of the point |
| Y | The value of the Y coordinate of the point |
| Z | The value of the Z coordinate of the point |
| Dn | The value of the nth description field for the point |
| _tmpn | The value of the nth temporary variable for this string range grouping |
| An aggregate value of the form:
_<entity>_<aggregate>_<field> where: <entity> is one of file, segment, or string, <aggregate> is one of min, max, sum, ave, or num and <field> is one of x, y, z, or Dn For example, the minimum x value in a string is given by: _string_min_x |
Return an aggregate value calculated from the points in a segment, string or file depending on the first part of the variable name. Only numeric values are included in the aggregate, so that, for example, averages do not included blank values. The second part indicates if the value is the minimum value, maximum value, sum, the average, or the count of numeric values of the field indicated in the third part of the variable name. The aggregate value is calculate before any points are updated for this string range block. |
| _file_string_no | Get the position of the string within the file. The first string in the file is considered to have a position of one. |
| _file_segment_no | Get the position of the segment within the file. The first segment in the file is considered to have a position of one. |
| _file_point_no | Get the position of the point within the file. The first point in the file is considered to have a position of one. |
| _string_segment_no | Get the position of the segment within the string. |
| _string_point_no | Get the position of the point within the string. |
| _segment_point_no | Get the position of a point within the segment. |
| _file_location | The location of the current input file. |
| _file_id | The ID of the current input file. |
| _string_id | The ID of the current string. |
| A calculated value of the form:
_<entity>_<value> <entity> is one of file, segment, or string, and <value> is one of area, 2dlen, 3dlen, or closed. For example, the area of a segment is given by: _segment_area |
Return a calculated value for the current file, string, or segment. The values which can be returned are the total area, 2d length, 3d length, or a true/false value depending on whether or not all the segments are closed. |
| _first_file_string | Return true for the first string within a file. |
| _first_file_segment | Return true for the first segment within a file. |
| _first_file_point | Return true for the first point within a file. |
| _first_string_segment | Return true for the first segment within a string. |
| _last_string_segment | Return true for the last segment within a string. |
| _first_string_point | Return true for the first point within a string. |
| _last_string_point | Return true for the last point within a string. |
| _first_segment_point | Return true for the first point within a segment. |
| _ last_segment_point | Return true for the last point within a segment. |
| _prev_<field>
where: <field> is one of x, y, z, or Dn. For example, the x coordinate for the previous point is given by: _prev_x |
Return the value of the field for the previous point in the segment. This value is before any assignments to the previous point. If one of these values is used for the first point of a closed segment it returns the value for the last point in the segment (excluding the final closing point). If one of these values is used for the first point in an open segment it returns zero. |
| _next_<field>
where: <field> is one of x, y, z, or Dn. For example, the x coordinate for the next point is given by: _next_x |
Return the value of the field for the next point in the segment. If one of these values is used for the last point of a closed segment (excluding the final closing point) it returns the value for the first point in the segment before any assignments were made to the first point. If one of these values is used for the last point in an open segment it returns zero. |
| A derived value of the form:
_prev_<value> where: <value> is one of az, dip, slope, vdist, 2dlen, or 3dlen. For example, the azimuth from the previous point to this point is given by: _prev_az |
Calculate a value dependent on the previous point in the segment and the current point. The values which can be returned are the azimuth, dip, slope, vertical distance, 2d length (or horizontal distance), and 3d length from the previous point to the current point. The previous point behaves as for _prev_<field> above for the first point of an open or closed segment. |
| A derived value of the form:
_next_<value> where: <value> is one of az, dip, slope, vdist, 2dlen, or 3dlen. For example, the azimuth from this point to the next point is given by: _next_az |
Calculate a value dependent on the current point and the next point in the segment. The values which can be returned are the azimuth, dip, slope, vertical distance, 2d length (or horizontal distance), and 3d length from the current point to the next point. The next point behaves as for _next_<field> above for the last point of an open or closed segment. |
| _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. |
Note: The last point for closed segments is a repeat of the first point. This point is not processed like the other points in a segment and is set to
have the same x, y, z and description fields as the first point in the segment. This allows expressions used to accumulate values to ignore any
special processing for the last closing point in a closed segment. Thus it is not possible to change a closed segment to an open segment or vice-versa
using string maths.
Examples
- To place the accumulated 2d distance along a string in the D1 field,
and the complete distance along the string in the D2 field the following
can be used:
String Range Constraint Field Expression all _first_string_point _tmp1 0 D1 _tmp1 _tmp1 _tmp1 + _next_2dlen _string_D2 _tmp1 - If string 1 has the grade for each point in D1 with missing values
being set to -1 then the average grade for each segment can be calculated
to D2 using the first block of expressions below. The second block places
the grade as a percentage of the average grade for the segment in D3 with
missing values set to nothing. Note that the second block is started by
a non-blank string range value and is not processed until after all the
points have been processed with the first block.
String Range Constraint Field Expression 1 _first_segment_point _tmp1 0 _first_segment_point _tmp2 0 D1 >= 0.0 _tmp1 _tmp1 + D1 D1 >= 0.0 _tmp2 _tmp2 + 1 _segment_D2 IIF(_tmp2 > 0, _tmp1/_tmp2, 0.0) 1 D1 >= 0 D3 IIF(D2 != 0.0, D1/D2*100.0, 0.0) D1 < 0 D3 "" - To swap the x and y fields:
String Range Constraint Field Expression all X Y Y X Note that since the fields for a point are not assigned until after all expressions for the point are calculate it is not necessary to use a temporary when swapping values.
Examples comparing the old STRING MATHS and the new STR MATHS functions
- Assign the value 14.5 to the X field
Old String Maths
Opfield Operator Value X = 14.5 New String Maths
String Range Constraint Field ExpressionField all Z 14.5 - Cut any values in the D1 field that are greater than 30 back to 30.
Old String Maths
Opfield Operator Value D1 C 30 New String Maths
String Range Constraint Field Expression all D1 IIF(D1 > 30, 30,D1) - Make the field D1 equal to the value contained in the Z field.
Old String Maths
Opfield Operator Value D1 = 'Z' New String Maths
String Range Constraint Field Expression all D1 Z - Calculate the dip from the previous point to the current point of the current string.
Old String Maths
Opfield Operator Value D1 = @DIP New String Maths
String Range Constraint Field Expression all D1 _prev_dip - Set the field to the 2D length of the segment to which this point belongs.
The length is the sum of the distances between the (X, Y) points in the string.
Old String Maths
Opfield Operator Value D2 = @LEN2D New String Maths
String Range Constraint Field Expression all D2 _segment_2dlen - Calculate the average value for each segment of the opfield specified and store the result in that field.
Old String Maths
Opfield Operator Value D4 = @AVE New String Maths
String Range Constraint Field Expression all D4 _segment_ave_d4 - Get the string number into the D1 field.
Old String Maths
Opfield Operator Value D1 = 'STR' New String Maths
String Range Constraint Field Expression all D1 _file_string_no - Calculate the 2D distance from the start of the current segment to the current point.
Old String Maths
Opfield Operator Value D1 = @CLEN2D New String Maths
String Range Constraint Field Expression all D1 _clen2d - Calculate the 3D distance from the start of the current segment to the current point.
Old String Maths
Opfield Operator Value D1 = @CLEN3D New String Maths
String Range Constraint Field Expression all D1 _clen3d