Interface FilterItemInterface

The FilterItemInterface interface is the base interface used to filter part instances.

NO FilterItemInterface are created per se. Instead, interfaces that inherit FilterItemInterface are created. The FilterItemInterface is a kind of "abstract interface".

The FilterItemInterface serves to elect a list of part instances based on a criterion (or a list of criteria), for example (others can be found in Filters examples):

• Find all part instances whose size is lower than 3 cms
• Find all part instances that overlaps a given 3D cube
• Find all part instances that have a metadata "type" equal to "electrical" (electrical part instances)
• Find all part instances that have a metadata "mounted" to true (mounted part instances).

Each example is made possible by the creation of a specific interface that inherits FilterItemInterface.

A FilterItemInterface is not usable as is, it must be included in a "solver" object : the FilterSolverInterface. The FilterSolverInterface interface allows the computation of the FilterItemInterfaces, and allows grouping them with set operators (intersection, union, exclusion). See FilterSolverInterface for more details, but keep in mind that FilterSolverInterfaces rely on filtering contexts to work : VisibilityContextInterface (see Filtering Context).

When a FilterItemInterface is modified, there is no automatic update of the content of a FilterSolverInterface : indeed, you may want to modify a lot of FilterItemInterface, ConfContextInterfaces, VisibilityContextInterfaces before getting the expected result. Moreover, VisibilityContextInterfaces may depend on FilterSolverInterfaces that could lead to massive dependency graphs. For this reason, VisibilityContextInterfaces, FilterSolverInterfaces and FilterItemInterfaces are not updated through a dedicated function on each interface but with the update function.
The dependency graph of ConfContextInterfaces, VisibilityContextInterfaces and FilterItemInterfaces is handled by the DataSessionInterface, this also prevent too many requests to be sent to the server for nothing.
To sum up : modify your FilterItemInterfaces, ConfContextInterfaces, VisibilityContextInterfaces and FilterSolverInterfaces without taking into account any dependency that may have between them, and when you want the server to compute the result, remember to call update.

DO NOT create interfaces that inherits FilterItemInterface before the DMU is loaded, such filters will be silently discarded.

Discard existing interfaces that inherits FilterItemInterface before loading a new DataSessionInterface (dispose).

The same FilterItemInterface cannot be used at the same time in multiple FilterSolverInterface, FilterSetInterface, FilterCompoundInterface : calling insertFilter, insertFilter or insertFilter on a FilterItemInterface that is already included will return false.
Warning : only FilterAttributeInterface, FilterRangeInterface, FilterHasFieldInterface and FilterBooleanInterface can be included in a FilterCompoundInterface.

Each FilterItemInterface is assigned a unique identifier upon creation.

The combination of the FilterItemInterfaces in a FilterSolverInterface, FilterSetInterface, FilterCompoundInterface may be a union, intersection, or exclusion (FilterOperator). Each FilterItemInterface stores a combination mode that tells its way to combine itself with the first enabled FORMER FilterItemInterface in the parent list.
The FilterItemInterface operator of the first enabled FilterItemInterface in a parent list (FilterSolverInterface, FilterSetInterface, FilterCompoundInterface) is always ignored, but a warning is outputted in the console when the FilterOperator is different that FO_UNION.
The FilterSetInterface allows to gather filters together and to create an operator precedence with FilterOperator. It is a sort of "parenthesis" FilterItemInterface.

A FilterItemInterface may be :

• enabled/disabled : tells if this FilterItemInterface contributes to the filtering of the enclosing [FilterSolverInterface]], FilterSetInterface, FilterCompoundInterface. Warning, changing the enabled status of a FilterItemInterface without knowing its successor may result in unexpected results, since the successor FilterOperator will be used with the first enabled FilterItemInterface that precedes the disabled one.
• normal/inverted : tells if the result of the FilterItemInterface may be "inverted". When "inverted", a FilterItemInterface "elects" all other part instances leaves minus the one in the "normal" FilterItemInterface (in a FilterCompoundInterface, the meaning of the "inverted" state is different).

The content of a FilterItemInterface is provided by getFilterData and can be restored by setFilterData.

Each filter has a depth contribution. For implementation reasons, the depth contribution of each FilterItemInterface included inside a FilterSolverInterface is limited. The depth contribution is available through getDepthContribution.

This depth contribution cannot be more than

Max Depth Contribution

Please see Available Filters for a list of available FilterItemInterfaces.

/** 
 * Sample to illustrate the use of an intersection of 
 * FilterAABBInterface and FilterAttributeInterface.
 */
import {
    AABB, AttributesDictionaryInterface, AttributeInfoInterface, AttributeType, DataSessionInterface,
    ConfContextInterface, VisibilityContextInterface, FilterSolverInterface,
    FilterAABBInterface, FilterAttributeInterface, FilterOperator,
} from 'generated/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;

// MAKE SURE the attributes "CompletionStatus"
const lAttributeDictionary : AttributesDictionaryInterface = lDataSession.getAttributesDictionary();
const lAttributeInfo : AttributeInfoInterface | undefined = lAttributeDictionary.getAttributeInfo('CompletionStatus');
// make sure the attribute is a string one
console.assert((lAttributeInfo !== undefined) && (lAttributeInfo.getAttributeType() === AttributeType.ATTR_STRING));

// create the resolution chain : 
// create a filtering context "unconfigured"
// first create ConfContextInterface "unconfigured"
const lConfCtx : ConfContextInterface = lDataSession.createConfContext();
// and create the filtering context and bind it to the unconfigured ConfContextInterface
const lConfVisibilityCtx: VisibilityContextInterface = lDataSession.createVisibilityContext();
lConfVisibilityCtx.setConfContext(lConfCtx);

// the AABB to use
const lABB : AABB = new AABB();
lABB.mCenter.x = 3.0;
lABB.mCenter.y = 3.0;
lABB.mCenter.z = 3.0;

lABB.mHalfExtent.x = 10.0;
lABB.mHalfExtent.y = 10.0;
lABB.mHalfExtent.z = 10.0;

// create a Filter Solver
const lFilterSolver : FilterSolverInterface = lDataSession.createFilterSolver();

// create a box filter
const lFilterAABB : FilterAABBInterface = lDataSession.createFilterAABB();
// useless, FilterOperator.FO_UNION is the default operator when creating a new filter
// lFilterAABB.setFilterOperator(FilterOperator.FO_UNION);

lFilterAABB.setAABB(lABB);

// create an FilterAttributeInterface
const lFilterAttributes : FilterAttributeInterface = lDataSession.createFilterAttribute();
// completion status to done
lFilterAttributes.setAttributeName('CompletionStatus');
lFilterAttributes.setExactValues(['done']);
// no n/a
lFilterAttributes.setNaValueChecked(false);

// intersection is the way to go since intersection of box and instances that have the field "CompletionStatus"
// to "done"
// only change the operator of the filters except the first
lFilterAttributes.setFilterOperator(FilterOperator.FO_INTERSECTION);

// and add the filters
// push back (-1) the AABB filter
lFilterSolver.insertFilter(-1, lFilterAABB);
// push back (-1) the FilterAttributeInterface, as it is the second one, its operator is used and therefore
// intersection is used
lFilterSolver.insertFilter(-1, lFilterAttributes);

// set the conf context to use => unconfigured for this example
lFilterSolver.setVisibilityContext(lConfVisibilityCtx);
// and tell the DataSessionInterface to update the modified ConfContextInterface, VisibilityContextInterface and FilterSolverInterfaces
lDataSession.update();

See

• FilterItemInterfaceSignal
• FilterType
• FilterOperator