Elements filter

Elements Filter is a tool for filtering elements by categories and/or parameters, consisting of filtering algorithms and a configuration interface (hereinafter referred to as the tool). The tool is used in many plugins, such as Worksets, Parametrization, Coloring Elements, and others.

The tool consists of two filters: a category filter and a parameter filter. Some plugins allow only one of these filters to be used. For example, the World Orientation plugin uses only the parameter filter.

In the plugin interface, the tool can have a horizontal layout:

or a vertical layout:

If both filters are used, an AND/OR logical operator is available between them. The AND operator means that an element satisfies the filtering conditions if it meets the conditions of both filters. The OR operator means that an element satisfies the filtering conditions if it meets the conditions of at least one of the two filters.

The category list from the category filter and the condition list from the parameter filter can be copied to and pasted from the clipboard using the right-click context menu.

Category Filter

The category filter is a tree-structured list of allowed categories. The category list is edited in a dialog box opened from the parent window (plugin window):

At the top of the dialog box is a category search field. The search is performed by both the displayed category name and its unique programmatic name. The buttons below allow you to display only specific groups of categories based on their type.

The buttons to the right of the list apply to the currently selected category group. They allow you to clear the selection of all categories , expand and collapse all categories , display only selected categories eye check outline , or select categories whose elements are present in the current view shape plus outline . Selected categories can be saved as sets for subsequent use both in the current plugin and in other plugins that use the category filter.

You can load a category set (select categories from the chosen set) using the button.

Parameter Filter

The parameter filter is a list of conditions separated by the logical operator AND or OR. In the filter field, conditions are written using a special syntax with the following comparison operator symbols:

=	– equal
<	– less than
<=	– less than or equal to
>	– greater than
>=	– greater than or equal to
<>	– not equal
~	– contains
!~	– does not contain

Conditions are edited in a separate window:

At the top of the window are the Simple condition and Group condition links, which allow you to add the corresponding conditions. Conditions can be reordered, duplicated, and deleted. The Clear link removes all conditions.

Rules for creating and evaluating conditions:

You can enter multiple allowed values in the "Values" field, separated by commas. A parameter is considered to satisfy the condition if its value matches at least one of the allowed values.
To prevent a comma from being interpreted as a separator, escape it with a backslash. For example, "value 1\,5".
The "Presence of parameter" condition means that an element will be processed if it has the specified parameter, regardless of its value.
The "Absence of parameter" condition means that an element will be processed if it does not have the specified parameter.
The "Read-only" condition with the value "No" means that an element will be processed if the parameter is editable. The "Read-only" condition with the value "Yes" means that an element will be processed if the parameter is not editable. A parameter may be unavailable for editing if it is a non-editable system parameter (for example, the "Volume" parameter), the element is in an inaccessible workset, or for other reasons.
String parameters are evaluated only using the "Equal", "Not equal", "Contains", and "Does not contain" conditions.
The "Contains" condition checks whether the element parameter contains at least one of the allowed values. The "Does not contain" condition checks whether the parameter does not contain at least one of the values.
To use the "Starts with" condition, select "Contains" and add an "*" character to the end of the value. For example, "Wall*".
To use the "Ends with" condition, select "Contains" and add an "*" character to the beginning of the value. For example, "*Wall".
To use the "Does not start with" condition, select "Does not contain" and add an "*" character to the end of the value. For example, "Wall*".
To use the "Does not end with" condition, select "Does not contain" and add an "*" character to the beginning of the value. For example, "*Wall".
String values are checked case-sensitively by default using the Aa option. For the "Equal", "Not equal", "Contains", and "Does not contain" conditions, you can select the aa option to perform a case-insensitive check. In the string representation of the filter, such a condition is marked with a "?" character after the parameter name, for example: Mark?=A-1.
Yes/No parameters are evaluated as integers: 0 – off, 1 – on.
When checking the special parameter "Group" (parent group), the "Presence of parameter" and "Absence of parameter" conditions determine whether an element belongs to a group. The "Presence of parameter" condition is interpreted as "Element must be in a group", while the "Absence of parameter" condition is interpreted as "Element must not be in a group". Any other condition, if the element belongs to a group, evaluates the group name according to the rules for strings.
When checking the special parameter "Assembly" (parent assembly), the "Presence of parameter" and "Absence of parameter" conditions determine whether an element belongs to an assembly. The "Presence of parameter" condition is interpreted as "Element must be in an assembly", while the "Absence of parameter" condition is interpreted as "Element must not be in an assembly". Any other condition, if the element belongs to an assembly, evaluates the assembly name according to the rules for strings.
When checking the special parameter "Curtain" (whether a wall is a curtain wall), the "Presence of parameter" and "Absence of parameter" conditions determine whether a wall is a curtain wall. The "Presence of parameter" condition is interpreted as "Wall must be a curtain wall", while the "Absence of parameter" condition is interpreted as "Wall must not be a curtain wall".
When checking the special parameter "Nested" (whether a family is nested), the "Presence of parameter" and "Absence of parameter" conditions determine whether a family is nested. The "Presence of parameter" condition is interpreted as "Family must be nested", while the "Absence of parameter" condition is interpreted as "Family must not be nested".
When checking the special parameter "Parent" (whether a family is a parent family), the "Presence of parameter" and "Absence of parameter" conditions determine whether a family is a parent family, meaning that it contains nested families. The "Presence of parameter" condition is interpreted as "Family must be a parent family", while the "Absence of parameter" condition is interpreted as "Family must not be a parent family".
When using the special parameters "BottomZ" and "TopZ", the lowest and highest elevations of an element's geometry are evaluated, respectively. The special parameters "BottomZ" and "TopZ" are considered numeric and are evaluated using the corresponding conditions. Elevation values are expressed in millimeters and rounded to three decimal places. You can specify level names in the "Value" field: if the specified level is found, its elevation in millimeters, rounded to three decimal places, will be used.
The special parameter "AreaScheme" returns the name of the area scheme to which an Area belongs. The value of the "AreaScheme" special parameter is evaluated according to the rules for strings. If the element is not an Area, the condition is ignored and always returns "true".
When checking the special parameter "InMEPSystem" (whether an element belongs to an MEP system), the "Presence of parameter" and "Absence of parameter" conditions determine whether an element is part of an MEP system. The "Presence of parameter" condition is interpreted as "Element is part of an MEP system", while the "Absence of parameter" condition is interpreted as "Element is not part of an MEP system".
When checking the special parameter "InRebarSystem" (whether rebar belongs to a rebar system), the "Presence of parameter" and "Absence of parameter" conditions determine whether rebar is part of a rebar system. The "Presence of parameter" condition is interpreted as "Rebar is part of a rebar system", while the "Absence of parameter" condition is interpreted as "Rebar is not part of a rebar system".
The special parameter "DocumentTitle" returns the name of the current document. The value of the "DocumentTitle" special parameter is evaluated according to the rules for strings. If the document has not been saved or is detached, the default value or an empty string is returned.
All nested simple conditions of a group condition are evaluated using the "AND" operator, meaning that all nested conditions must match.
Instead of a parameter name, you can specify the GUID of a shared parameter or the system name of a built-in parameter.

Created conditions can be saved as sets for later use. When saving a set, you must specify its name, optionally provide a description, and select its availability scope:

Save for plugin – the set will be available in the current plugin
Save globally – the set will be available in other plugins that use the parameter filter.

A previously saved condition set can be loaded using the button.

The parameter identifier field may contain a button that allows you to select a parameter from a list:

This button appears if categories are specified in the category filter. If the current document contains instances of elements belonging to these categories, two lists are available: Instance parameters and Type parameters. If there are no instances in the model but element types are present, only the type parameter list is displayed.

As a parameter identifier, you can specify a parameter name, the GUID of a shared parameter, or the system name of a built-in parameter.

In addition to parameters, conditions can use the element identifier (ID), the element type identifier (TypeID), and special parameters such as Group, Assembly, Curtain, Parent, Nested, BottomZ, TopZ, AreaScheme, InMEPSystem, InRebarSystem, DocumentTitle, and others, when available.

When the "Equal" and "Not equal" conditions are selected, a button for searching parameter values magnify (black) becomes available:

The search is performed across all elements and element types of the specified categories. The following search scopes are available in the search window:

Project – searches for parameter values throughout the current document
Current view – searches for parameter values among elements in the current view
Linked files – searches for parameter values in loaded linked files. You can select a specific linked file or choose All to search all loaded linked files.

A group condition is a list of simple conditions. All simple conditions within a group condition are evaluated using the logical operator AND. An element satisfies a group condition if it meets all its nested simple conditions. In the filter field, a group condition is enclosed in square brackets.

At the bottom of the window is the Element is suitable if drop-down list, which specifies the logical operator between conditions. The value all conditions match corresponds to the logical operator AND, while any of conditions match corresponds to the logical operator OR.

The example from the screenshot above will look as follows in the filter field:

This means that a wall matches if its "Mark" parameter has the value "W-1", or if its "Mark" parameter has the value "W-2" and its "Structural" parameter has the value "1".

The required parameters are searched for in the element being evaluated by parameter name. The parameter is first searched for among instance parameters and, if not found, among type parameters.