Filtering

A filter is an object that derives from EntityFilter<TEntity>. There are two provided implementations:

• AccessEntityFilter<TEntity> - filters based on the results of an AccessQuery.

• DelegateEntityFilter<TEntity> - filters based on a provided delegate, which is useful for very simple filters on specific criteria, such as Force == Friendly.

While a filter provides the criteria for selection, an EntityFilterChain<TEntity> is used to actually process groups of filters.

The following code sample creates an EntityFilterChain<TEntity> containing two DelegateEntityFilter<TEntity> objects that separate entities into friendly and hostile categories based on the value of the Affiliation property. The EntityFilterChain<TEntity> constructor takes two parameters: the EntitySet<TEntity> to filter and the MatchingStrategy, which indicates whether an entity should be placed in multiple filters, or only in the first filter it matches.

DelegateEntityFilter<ExampleEntity> friendlyFilter =
    new DelegateEntityFilter<ExampleEntity>(inputEntities.Context,
                                            (transaction, entity) => entity.Affiliation.GetValue(transaction) == Force.Friendly);

DelegateEntityFilter<ExampleEntity> hostileFilter =
    new DelegateEntityFilter<ExampleEntity>(inputEntities.Context,
                                            (transaction, entity) => entity.Affiliation.GetValue(transaction) == Force.Hostile);

EntityFilterChain<ExampleEntity> filterChain = new EntityFilterChain<ExampleEntity>(inputEntities, MatchingStrategy.First);
filterChain.Filters.Add(friendlyFilter);
filterChain.Filters.Add(hostileFilter);
filterChain.ApplyChanges();

EntitySet<ExampleEntity> friendlyEntities = friendlyFilter.MatchingEntities;
EntitySet<ExampleEntity> hostileEntities = hostileFilter.MatchingEntities;
EntitySet<ExampleEntity> unknownEntities = filterChain.HomelessEntities;

After configuring the EntityFilterChain<TEntity>, the three entity sets will remain empty until the RedistributeEntities method is called to process the filters, as shown in the code sample below:

context.DoTransactionally(filterChain.RedistributeEntities);

Once this method returns, each of the entity sets will contain the entities that correspond to the value of their Affiliation property, and all entities that match neither filter are placed in the HomelessEntities entity set. The entity set used as the input is never modified by the filter chain, and is expected to be managed by an outside source. Furthermore, the Changed event is raised whenever entities are added to or removed from an entity set managed by a filter.

As mentioned above, MatchingStrategy indicates if an EntityFilterChain<TEntity> will place each entity in only the first EntityFilter<TEntity> it matches or all matching filters. MatchingStrategy.First is recommended unless there is a specific reason for an entity to be in multiple filters. This will not only improve performance, but is ideal when using a filter chain for visualization, since the resulting entity sets will not overlap.

Filters can make use of Evaluator Parameterization to filter entities based on complex analysis. The following code sample shows the use of an AccessQuery to create a filter that only contains entities with line of sight to the surface of the Earth at zero latitude and longitude.

var earth = CentralBodiesFacet.GetFromContext().Earth;

var entityParameter = new EntityParameter<ExampleEntity>();
var transactionParameter = new TransactionParameter();

var transmitter = new Platform
{
    LocationPoint = new EntityPoint<ExampleEntity>(entityParameter, transactionParameter),
    OrientationAxes = new EntityAxes<ExampleEntity>(entityParameter, transactionParameter)
};

var receiver = new Platform
{
    LocationPoint = new PointCartographic(earth, new Cartographic(0.0, 0.0, 0.0)),
    OrientationAxes = earth.FixedFrame.Axes
};

var link = new LinkInstantaneous(transmitter, receiver);
var constraint = new CentralBodyObstructionConstraint(link, earth);

var group = new EvaluatorGroup();
var filterByAccess = new AccessEntityFilter<ExampleEntity>(context, entityParameter, transactionParameter, constraint, group);

The above is a very simple AccessQuery, but the same concept can be extended to use any of the analysis capabilities of DME Component Libraries.

Since filtering makes use of the transaction system, the filtering can be done on a separate thread, taking advantage of modern multi-core processors. One approach to achieve this is to call RedistributeEntities repeatedly in the background at a predetermined interval. RecurringTaskScheduler facilitates running a requested task as fairly as possible across all available threads. Each task has an associated frequency and all attempts are made to run the task at the desired interval.

The following code sample runs RedistributeEntities in a background thread every tenth of a second:

RecurringTaskScheduler recurringTasks = new RecurringTaskScheduler();
recurringTasks.AddTask(Duration.FromSeconds(0.1), filterChain.RedistributeEntities);
recurringTasks.Start();

The same approach can also be achieved using other task scheduling systems, either built-in to .NET, or available as third-party libraries. RecurringTaskScheduler does not have any special capabilities specific to DME Component Libraries.