Deep Map™ Rule specification
Rules are style definitions which override the feature style definition of a named feature. See Deep Map™ Style Specification [v2 public release] for the Deep Map™ Style specifications. The criteria are checked for each possibly visible object on the map in realtime, and when the criteria within the rule's condition are met, the style definition in the rule's body overrides the feature style definition for the object. The style definitions within the rule are the same as the feature style definition. The rules are defined in the .mapRule file.
The rule syntax is defined as follows:
rule is the keyword to start a new rule
<ruleName> is a unique
name for the rule. The feature name is followed by a list of
feature names, enclosed by parentheses. Those are the features the
rule is applied to. All features must be of the same basic type
(point, icon, line,
the beginning and end of the rule condition.
<rule expression> is a boolean
expression which specifies if the rule should be applied or not. We
will take a closer look at the rule expression later. The rule
condition is optional. If left out, the rule is always applied. The
body of a rule is the same as the body of a feature, and the
properties must match the assigned feature type. Additionally, it
is possible to nest rules within another rule. The nested rule is
then only executed if the embracing rules conditions are met. More
on nested rules later.
The rule expression mimics closely a SQL-WHERE clause. There are two key differences: the SQL data fields are replaced by feature attributes, and the rule body is applied if something matches the clause, instead of returning a data set. All functions from SQL are usable, but there are some additional functions for querying the map state.
- Logical expressions:
- AND, OR
- Comparative expressions:
- <, <=, >, >=, =, !=, NOT, IS NULL, NOT NULL, IN (1,2,3, ..), BETWEEN x AND y
- Math operators:
- +, -, *, /
- distance(), isSelected(), isHighlighted(), "any SQLITE function"
- Data fields:
- feature type attributes, map attributes
The new function for querying the map are:
|sdk version requirement|
|distance()||double: 3D distance from object to the camera||point/icon/polygon: O(1), lines: O(lineSegments)||v2.0.0|
|isSelected()||int: 1 if object is selected, otherwise 0||std::set lookup: Ω(1), O(n)||v2.0.0|
|isHighlighted()||int: 1 if object is highlighted, otherwise 0||std::set lookup: Ω(1), O(n)||v2.0.0|
double: distance from the camera to the ground
|currentZoomlevel()||int: the current Zoomlevel||O(1)||v2.1.2|
Multiple rules can set the same property. In the above example, selectionColor and specialRoom modify both the fill-color of an object. If this happens, the first defined rule wins. In this case, a room with the attribute "iAmSpecial: yes" will be blue, but as soon as it is selected it turns red. If the two rules were switched, the room would always be blue, and selection would have no effect.
If one feature inherits from another, it inherits not only the properties, but the rules as well! This can be useful if multiple feature have a similar style and should share the same behaviour. For example:
In this case, all objects of the type "building" and "specialBuilding" will get a thick, white outline when they are highlighted. Inherited rules have a lower priority than rules directly defined for the feature type in question. The further up in the ancestry, the lower the priority of a rule.
It is possible to define rules inside the body of another rule:
A nested rule is conditionally depending on the outer rule. In this case "innerRule" is only evaluated if the condition of the "outerRule" if fulfilled. So all rooms of a building will now be hidden if the building is selected.
There are several limitations which need to be considered when nesting rules:
- The feature types of the nested rules are not allowed to be related to the feature types of the outer rules over the Deep Map™ Style definitions. This is because the behaviour of a rule can become undefined due to rule inheritance
- The map objects affected by the outer rule have to be ancestors of the map objects affected by the nested rule to take effect.
The following example shows valid and invalid nested rules:
Nested rules have the highest priority, since they are the most specific. The deeper a rule is nested, the higher is its priority. The following diagram illustrates again in which order style properties are evaluated:
Property Rules (Version 2.1)
In some scenarios a user might want to set many different values for a single property. Doing this with the normal rules would be cumbersome, because this would require one rule for each individual value. These cases are better handled by property rules.
A property rule is defined by setting a rule-clause instead of the normal property-value:
The selected value has to match the string-format of the value type. For example, a custom set color value could be set in the following way:
In this case, the value of customColor needs to be a string representing a hex-color value. The query is discarded if the return-type does not match the property-type.