A number of commands use a filter expression to control the data included in the output of a process. Some commands provide controls for building an expression directly in their dialog box, while others provide a field to launch the Expression Builder dialog box, which contains the expression building controls.
Regardless of the tool used, filter expressions can be built using operator buttons in a dialog box and/or values entered through the keyboard. The supported operators are listed below.
Operator | Type | Function | Example |
|---|---|---|---|
( ) | Grouping | bracketed operation | (Depth+1) |
+ | Mathematical | addition | Depth + 4 |
* | Mathematical | multiplication | Depth * 4 |
– | Mathematical | subtraction | Depth - 4 |
/ | Mathematical | division | Depth / 4 |
^ | Mathematical | exponentiation (Depthx) | Depth ^ 4 |
< | Mathematical | less than | Depth < 4 |
> | Mathematical | greater than | Depth > 4 |
= | Mathematical | equal to | Depth = 4 |
<= | Mathematical | less than or equal to | Depth <= 4 |
>= | Mathematical | greater than or equal to | Depth >= 4 |
!= | Mathematical | not equal to | Depth != 4 |
ROUND | Mathematical | round the input to the nearest integer, rounding half upwards round to a non-integer value by applying a factor | Integer: ROUND(0.1) = 0 ROUND(0.9) = 1 Non-integer: ROUND(X/0.5)*0.5 |
ABS | Mathematical | calculate the absolute value of the input with no rounding applied | ABS(-1.2) = 1.2 ABS(2.3) = 2.3 |
PI | Mathematical | include in expressions to apply the mathematical constant of PI | SINR(Slope * PI/180) |
SIN | Mathematical | calculate sine values with the angles specified in degrees | SIN(Slope) |
SIND | Mathematical | calculate sine values with the angles specified in degrees | SIND(Aspect) |
SINR | Mathematical | calculate sine values with the angles specified in radians | SINR(0.34) |
SING | Mathematical | calculate sine values with the angles specified in gradians | SING(Slope / 0.9) |
COS | Mathematical | calculate cosine values with the angles specified in degrees | COS(Aspect) |
COSD | Mathematical | calculate cosine values with the angles specified in degrees | COSD(45) |
COSR | Mathematical | calculate cosine values with the angles specified in radians | COSR(Slope * PI/180) |
COSG | Mathematical | calculate cosine values with the angles specified in gradians | COSG(Aspect / 0.9) |
TAN | Mathematical | calculate tangent values with the angles specified in degrees | TAN(29) |
TAND | Mathematical | calculate tangent values with the angles specified in degrees | TAND(Slope) |
TANR | Mathematical | calculate tangent values with the angles specified in radians | TANR(Aspect * PI/180) |
TANG | Mathematical | calculate tangent values with the angles specified in gradians | TANG(65) |
AND | Logical | conditional relation | Depth > 4 AND Uncertainty < 0.5 |
OR | Logical | conditional relation | Depth > 4 OR Density > 5 |
NOT | Logical | inversion | NOT (Depth < 4) |
IN | Set | is contained in | ‘Designated’ IN Status |
Multiple expressions can be combined to build conditional expressions in the form below, where each bolded part can be a full expression in itself:
If Expression then ResultA else ResultB
Conditional expressions provide the added ability to have no‑data values in the results. When no‑data values are assigned to nodes in the output, those nodes will not be displayed and cannot be selected or exported.
Conditional expressions also allow mathematical expressions in the results. This allows the attribute values to be altered differently for each result or additional expressions to be run based on the results of the first expression.
Examples of both are shown below:
If expression Then (Density+12) Else (Depth+10)
If (Intensity> -46 AND Intensity< -25.4) Then 1 Else If (Intensity> -24.399 AND Intensity< -19.2) Then 2 Else If (Intensity> -19.199 AND Intensity< -14.5) Then 3 Else If (Intensity> -14.5 AND Slope > 8.51) Then 4 Else If (Intensity> -14.5 AND Slope < 8.51) Then 5 Else NO_DATA
If using the AND operator, both relations must be true for the complex expression to be true. If using the OR operator, only one of the relations must be true for the expression to be true.
To correctly enter an expression, the following rules must be followed:
• When defining conditions, if, then and else must always be entered in the order that they are specified here.
• When a part of the expression (Expression, ResultA, ResultB) contains multiple parts, each part of the expression must be surrounded by brackets.
• The correct case must be used when specifying names of 'Available attributes', for example Deep and Density.
• Always use NO_DATA to set no-data values for a node.
• When filtering a coverage based on a contributor band, and the contributor band values include file paths, the expression must be entered as the full URI.
Examples of expressions are provided below.
Scenario | Expression | Result |
|---|---|---|
Checking the depth and uncertainty values of all data on a surface. | If (Depth > 10 AND Uncertainty < 0.2) Then Depth Else NO_DATA | Each node that is deeper than 10 and has uncertainty less than 0.2 passes the filter criteria. All nodes that do not meet the criteria will be added to the new layer with the NO_DATA value. |
Testing a variable resolution surface against IHO Order 1a. | If (Density >= 5 AND ((Depth<=40 AND Resolution<=1) OR (Depth>=40 AND Resolution <= (0.1 * Depth)))) Then NO_DATA Else 1 | Each node that meets the criteria is added to the new layer with the NO_DATA value. All nodes that do not meet the criteria will be added to the new layer with a value of 1. |
Identifying all data in a coverage that originated from a specific contributor dataset. | Contributor='file:///C:/Surfaces/CUBE_05m_Final.csar' | All data that originated from the CUBE_05m_Final.csar coverage is saved to a new coverage. |
Creating a filtered point cloud using LAS classification data. | Classification = 'Ground' OR Classification = 'Low Vegetation' OR Classification = 'Medium Vegetation' OR Classification = 'High Vegetation' | All data classified as ground or vegetation is included in the new point cloud. |
Identifying all nodes in a point cloud that are not flagged as Rejected or Designated in order to identify all accepted nodes. | NOT ('Rejected' IN Status) OR (‘Designated’ IN Status) | All accepted nodes in the point cloud will meet the filter criteria. |
Interface
The Expression Builder is accessible through the dialog box of various commands.
The Expression Builder dialog box is used to create a filter expression by typing in the expression field or selecting options from the Bands list and the operator buttons. The Bands list displays all bands present in the data source and their data types. If the list contains string table bands, such as Status and Classification, these can be expanded to build the expression using one of the attributes in the band.
The expression field also provides the following functionality to assist in expression creation:
• Auto-complete options are displayed as you type in the expression field, based on the attributes in the source data. The arrow keys and/or the <Enter> key are used to select an auto-complete option. Entries added using auto-complete will be enclosed in quotation marks to ensure spaces and special characters in the band names do not cause the expression to be invalid.
• Values that are specific to the source data, such as band names, are coloured differently from the rest of the expression.
• If the expression contains parentheses, selecting a parenthesis causes that character and the matching parenthesis to be highlighted, making it easier to distinguish between different levels of parentheses.
If filtering a string table band (Source_Name, Contributor, Classification, etc.), string values must be enclosed in single quotes in the expression. For example, to filter Classification data with the value of "Water", the expression would be Classification = ’Water’. |
Once an expression has been defined, the Save As button can be used to save the expression to a .txt file for future use. The Load button is used to load existing expression files.