Catalogue of Metadata, Syntax and Functions

This catalogue details each of the items in the pinnable Insert list for Calculations and Filters. Each item includes an intentionally trivial example to illustrate the use of the item, along with an explanation of the effect of the expression.

The catalogue is organised as follows:

• Existing Items
  • Metadata
  • Evaluations
  • Variables, Calculations and Filters
• Syntax and Functions
  • Statements
  • Basic Operators
  • Complex Comparisons
  • Invalid Values
  • Mathematics
  • Trigonometric Functions
  • Limits and Rounding
  • Text
  • Date/Time
  • Unit Conversion
  • Colour
  • Random Number Generators

Existing Items

This section covers the items listed in the left-hand side of the pinnable Insert list:

To pin these lists to the Calculations tab, enable the Pin Window option:

Metadata

id

This metadata item is available for imported points objects. It is the row ID from the points table.

x, y and z

These three metadata items are the variables for locating each point in a points object in X, Y and Z coordinates. Select an item to add it to the expression at the insertion point. Note that whenever one of these metadata items is added to an expression, it is wrapped in square brackets. This is not available for block objects; use xc, xy and xz instead.

xc, yc and zc

These three metadata items are the variables for locating the centroid of each block, in X, Y and Z coordinates. Select an item to add it to the expression at the insertion point. Note that whenever one of these metadata items is added to an expression, it is wrapped in square brackets. This is not available for points objects; use x, y and z instead.

dx, dy and dz

These three metadata items are the variables for the block dimensions in X, Y and Z coordinates. Select an item to add it to the expression at the insertion point. Note that whenever one of these metadata items is added to an expression, it is wrapped in square brackets. This is not available for points objects.

volume

This metadata item provides the volume for each block. Note that when this metadata item is added to an expression, it is wrapped in square brackets. This is not available for points objects.

xi, yi and zi

These three metadata items are the variables for locating each block by X, Y and Z index. Select an item to add it to the expression at the insertion point. Note that whenever one of these metadata items is added to an expression, it is wrapped in square brackets. This is not available for points objects.

Evaluations

Each of these items are automatically added to the list whenever an evaluation is added to the object. When added to an expression, the item represents a placeholder in the calculation for an estimated value, as the expression is evaluated for each of the locations in turn.

Note you can expand each evaluation in the list to see the attributes for the estimation evaluation that may also be selected instead of or in addition to the estimated value.

Variables, Calculations and Filters

Each time you create a new variable, numeric calculation, category calculation, or filter in Calculations, it will also be added to the Existing items list. You can select them from this list and they will be inserted into your new expression at the insertion point. Note that whenever one of these named items is added to an expression, it is wrapped in square brackets.

Syntax and Functions

This section covers the items listed in the right-hand side of the pinnable Insert list.

To pin these lists to the Calculations tab, enable the Pin Window option:

Statements

(…) Brackets

Brackets are used to enclose an expression so the operations on the values within the brackets take precedence over operations outside the brackets.

if(::) If block

The If block is used for conditional logic. This allows multiple pathways to results depending on selected conditions, or categorisation based on values.

An If block will be evaluated by each test → result, row by row, separately and in order downwards by row. . Each test has an output that can be ‘true’, ‘false’, or an invalid value, either ‘error’ or ‘blank’. Block models can also have the invalid values‘without_value’ or ‘outside’ . The result output is produced by the execution of the result expression. The If block output follows these rules:

• If a test output is ‘error’, the If block output is ‘error’ and no further processing of subsequent rows is done.
• If a test output is ‘false’, the result expression is not executed, and the next row is considered.
• If a test is ‘true’, the result expression is executed and the result output is used for the If block output and no further processing of subsequent rows is done.
• If all the tests are ‘false’, the ‘otherwise’ result expression is executed and its output is used.
• If a test output is an invalid value (without_value, blank, outside) the result expression is not executed and the test output’s invalid value is remembered. The subsequent rows are then run.
• If a subsequent test output is ‘true’ after an earlier one produced an invalid value, the previous test output is discarded and the new row’s result expression output is used as the output for the If block.
• If all test outputs are invalid status values, the highest priority status of all the remembered invalid statuses is used as the output result. The priority of non-error invalid status values is: outside > without_value > blank.

Additionally, it is possible to choose to produce invalid values as the output of result expressions.

Basic Operators

+ Add

An arithmetic addition operation.

- Subtract

An arithmetic subtraction operation.

* Multiply

An arithmetic multiplication operation. Note that implied multiplication, putting factors adjacent to one another, is not supported. The * operator must be explicitly used.

/ Divide

An arithmetic division operation.

% Modulo

An arithmetic modulo operation. This is an integer division operation that returns the remainder instead of the integer quotient.

^ Power

A mathematical exponentiation operation where a base is raised to the power of the exponent.

and Logical and

A logical and operation.

or Logical or

A logical or operation.

not Logical not

A logical not operation.

= Equal

A logical equality operator.

!= Not equal

A logical not-equal operator.

< Less than

A logical less-than operator.

< Less or equal

A logical less-than-or-equals operator.

< Greater than

A logical greater-than operator.

< Greater or equal

A logical greater-than-or-equals operator.

Complex Comparisons

Lower < n < upper

A pair of comparisons, with a logical result to indicate if the tested value n is between the lower value provided and the upper value provided.

Lower <= n < upper

A pair of comparisons, with a logical result to indicate if the tested value n is between the lower value provided and the upper value provided, or equal to the lower value.

Lower < n <= upper

A pair of comparisons, with a logical result to indicate if the tested value n is between the lower value provided and the upper value provided, or equal to the upper value.

Lower <= n <= upper

A pair of comparisons, with a logical result to indicate if the tested value n is between (or equal to either) the lower value provided and the upper value provided.

x in {a,b,...}

A logical inclusion expression. This will return true if x matches any element of the set of listed items.

x not in {a,b,...}

A logical exclusion expression. This will return true if x fails to match any element of the set of listed items.

Invalid Values

Invalid values are different types of results for “numeric” categorisation calculations that need special non-numeric results for certain category results. These have special meanings of their own without having to resort to interpreting negative numbers and zero as having special meaning.

blank means having no value, the value in the imported file is blank or has non-numeric data

without_value is often used to mean the estimator cannot produce a value (specific to blocks)

outside is used to indicate the block is outside the boundary of the domain (specific to blocks)

error generates an error, and provides an ‘error’ status value for the affected block or point

error(‘message’) is similar to error but includes a custom message.

is_normal(a)

A function that tests a to see if it is a normal value or an invalid value. If a is normal, it returns true. If a is invalid, it returns false.

is_blank(a)

A function that tests a to see if it is a blank invalid value. If a is blank, it returns true. If a is normal or another invalid value, it returns false.

is_without_value(a)

A function that tests a to see if it is a without_value invalid value. If a is without_value, it returns true. If a is normal or another invalid value, it returns false.

is_outside(a)

A function that tests a to see if it is an outside invalid value. If a is outside, it returns true. If a is normal or another invalid value, it returns false.

Mathematics

pi Constant

The constant pi is an existing item you do not need to define yourself. It is defined to 15 decimal places as 3.141592653589793.

e Constant

The constant e, the base of the natural logarithm, is an existing item you do not need to define yourself. It is defined to 15 decimal places as 2.718281828459045.

log(n) Base 10

The common logarithm, the logarithm with base 10, i.e. log₁₀(n) or lg(n). This function will calculate the common logarithm of the value provided as n.

log(n, base)

The logarithm of a number n to the base base.

ln(n) Natural log, base e

The natural logarithm, the logarithm with base e, i.e. log_e(n). This function will calculate the natural logarithm of the value provided as n.

exp(n) Natural exponent

The natural exponent. This function will provide the result of eⁿ.

sqrt(n) Square root

The principle square root of the provided number n.

abs(n) Absolute value

The absolute value of a number is it's value with the sign of the number disregarded. The absolute value of -42 is 42. The absolute value of 42 is also 42.

Trigonometric Functions

sin(x) Sine

The trigonometric sine function, expecting the parameter provided to be in degrees (not radians).

cos(x) Cosine

The trigonometric cosine function, expecting the parameter provided to be in degrees (not radians).

tan(x) Tangent

The trigonometric tangent function, expecting the parameter provided to be in degrees (not radians).

asin(x) Arcsine

The trigonometric arcsine (or inverse sine) function, returning a result in degrees (not radians).

acos(x) Arccosine

The trigonometric arccosine (or inverse cosine) function, returning a result in degrees (not radians).

atan(x) Arctangent

The trigonometric arctangent (or inverse tangent) function, returning a result in degrees (not radians).

Limits and Rounding

min (n, m, ...)

Returns the lowest of all the values in the set provided.

max (n, m, ...)

Returns the highest of all the values in the set provided.

clamp(n, lower)

This clamp function tests the value n against the threshold lower and if it is less than lower the result will be lower; otherwise the result will be n. The effect is to push all the values below the threshold up to the threshold.

clamp(n, lower, upper)

This clamp function tests the value n against the threshold lower and if it is less than lower the result will be lower; it tests the value n against the threshold upper and if it is more than upper the result will be upper; otherwise the result will be n. The effect is to squish all the values into a box between the lower and upper thresholds.

round(n)

This function rounds the input value n to the nearest whole number.

round(n, dp)

This function rounds the input value n to the number of decimal places specified by dp, a positive integer.

roundsf(n, sf)

This function rounds the input value n to the number of significant figures specified by sf, which must be a positive integer >= 1. Rounding to a given number of significant figures is often preferred in scientific applications over rounding to a given number of decimal places, as outputs can be rounded to the same amount of significance as the inputs.

floor(n)

This function removes the fractional part of a real number n and returns the integer number below the real number n. This remains true when n is a negative number.

ceiling(n)

This function removes the fractional part of a real number n and returns the integer number above the real number n. This remains true when n is a negative number.

truncate(n)

This function simply removes the fractional part of a real number n and returns the integer number without the fractional part. This means that for positive real numbers, the result will be the integer less than the real number n, but for negative real numbers, the result will be the integer greater than the real number n.

Text

'abc' Text value

Use this item to add a text sequence to an expression. Selecting the item will add two single quotation marks with the cursor between, ready for the text sequence to be typed. You can of course simply type the quote marks into the expression yourself. Double quotations marks also work identically to the single quotation marks used by this item. If you need to include a quote mark inside your text sequence, you need to "escape" the character so it is not interpreted as the end of the text sequence, by entering two quotation marks for each quotation mark you want inside the text sequence. Alternatively, you can use a different type of quotation mark as the sequence wrappers; for instance to write Seequent's Region with an internal apostrophe, you might wrap the sequence with double quotation marks: "Seequent's Region".

Enter text...

This selection opens a dialog box prompting you for text. After you enter it and click OK, the text will be entered at the cursor, wrapped with quotation marks. This is an easy way to resolve any issues about internal quotation marks, as the dialog box will convert the text into the necessary character sequence required to generate your desired text.

concat(t, u, ...)

This concatenates a series of text sequences together.

startswith(t, 'prefix')

This function returns true if the text sequence t starts with prefix, and false otherwise. This is case insensitive; 'prefix' will match 'PREFIX'.

endswith(t, 'suffix')

This function returns true if the text sequence t ends with suffix, and false otherwise. This is case insensitive; 'suffix' will match 'SUFFIX'.

contains(t, 'part')

This function returns true if the text sequence t contains part somewhere within, and false otherwise. This is case insensitive; 'part' will match 'PART'.

like(t, 'pattern')

This function returns true if the text sequence t matches pattern, where [pattern] is follows SQL-style LIKE matching rules. This is case insensitive, and pattern must match the whole of t, not just a portion of it. Use _ as a wildcard for a single character, and % as a wildcard for any number of characters (including no characters).

regexp(t, 'pattern')

This function returns true if the text sequence t matches pattern, where [pattern] is follows regular expression matching rules. This is case insensitive.

Date/Time

'now' Current timestamp

Use this item to add the current date-and-timestamp at the insertion point.

'today' Current date

Use this item to add the current datestamp at the insertion point.

dateonly(timestamp)

This function takes a date-and-timestamp and cuts off the timestamp to leave just the date.

Pick timestamp...

This selection opens a dialog box prompting you for a date and a time that will be entered at the insertion point when you click OK.

Pick date...

This selection opens a dialog box prompting you for a date that will be entered at the insertion point when you click OK.

Unit Conversion

Mass/weight...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

When you have selected the two units, the dialog box disappears and the conversion function you require will have been inserted into the expression at the cursor, and the cursor repositioned so you can enter the source of the value to be converted.

Distance...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

When you have selected the two units, the dialog box disappears and the conversion function you require will have been inserted into the expression at the cursor, and the cursor repositioned so you can enter the source of the value to be converted.

Area...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

When you have selected the two units, the dialog box disappears and the conversion function you require will have been inserted into the expression at the cursor, and the cursor repositioned so you can enter the source of the value to be converted.

Volume...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

When you have selected the two units, the dialog box disappears and the conversion function you require will have been inserted into the expression at the cursor, and the cursor repositioned so you can enter the source of the value to be converted.

Temperature...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

When you have selected the two units, the dialog box disappears and the conversion function you require will have been inserted into the expression at the cursor, and the cursor repositioned so you can enter the source of the value to be converted.

Pressure...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

When you have selected the two units, the dialog box disappears and the conversion function you require will have been inserted into the expression at the cursor, and the cursor repositioned so you can enter the source of the value to be converted.

Energy...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

When you have selected the two units, the dialog box disappears and the conversion function you require will have been inserted into the expression at the cursor, and the cursor repositioned so you can enter the source of the value to be converted.

Colour

rgb_to_hex(R, G, B)

This function returns an RGB hex sequence by combining three other values, interpreting them as R (red), G (green) and B (blue) values. It requires that the new item selected when creating a calculation is of type RGB to Hex Colour, not Numeric calculation or Category calculation. While this data could be combined into a hex value using Excel prior to import, point clouds from sources such as LIDAR data can be millions of rows in length, beyond the capacity of Excel. This function allows data collected as separate RGB values to be combined into a RGB hex value that can be used within Leapfrog Works.

Random Number Generators

random_float(start, end, seed)

This function returns a pseudo-random real number between the start and end values (inclusive). When the random_float function is added to a calculation, by default the seed value is set to a number that relates to the exact time the function was added. This seed value can be changed. Because the function is a pseudo-random number generator, the use of the same seed will result in the same series of random numbers. Use a different seed number to get a different series of randomised values.

random_integer(start, end, seed)

This function returns a pseudo-random whole number between the start and end values (inclusive). When the random_integer function is added to a calculation, by default the seed value is set to a number that relates to the exact time the function was added. This seed value can be changed. Because the function is a pseudo-random number generator, the use of the same seed will result in the same series of random numbers. Use a different seed number to get a different series of randomised values.

random_normal(mean, stddev, seed)

This function returns a pseudo-random real number conforming to a normal distribution centred around the mean with a standard deviation stddev. When the random_normal function is added to a calculation, by default the seed value is set to a number that relates to the exact time the function was added. This seed value can be changed. Because the function is a pseudo-random number generator, the use of the same seed will result in the same series of random numbers. Use a different seed number to get a different series of randomised values.