Using FilterCategoryRule in the Revit API

[CaptainDan]

Hi,

I have three questions regarding the filter rule represented by the class FilterCategoryRule:

1) What does this rule correspond to in the Revit user interface?

2) If this filters by category, then what is the relationship between the set of categories assigned to this rule and the set of categories passed to ParameterFilterElement.Create(...) ?

3) How do I successfully create a filter based on this filter rule? I keep getting an "

Autodesk.Revit.Exceptions.InternalException: An internal error has occurred" exception whenever I try to create a filter using this filter rule. I've tried the same code in Revit 2017 and 2018 with the same exception occurring.

Regards

Dan

[jeremytammik]

Dear Dan,

Thank you for your query.

All I can find about this is from The Building Coder on What's New in the Revit 2014 API:

FilterCategoryRule

The new class FilterCategoryRule can be used in the definition of a ParameterFilterElement.   It represents a filter rule that matches elements of a set of categories.

The related method:

  ParameterFilterElement.AllCategoriesFilterable()

has been replaced by

  FilterCategoryRule.AllCategoriesFilterable()

I also checked the SDK samples for you, and cannot find any example usage there, nor searching the Internet.

Consequently, I have asked the development team for further information and a sample for you.

I hope this helps.

Best regards,

Jeremy

[BenoitE&A]

Hey,

I use the simplified version of the filter :

FilteredElementCollector collector2 = new FilteredElementCollector(documentLie).OfCategory(BuiltInCategory.OST_Rooms);

This filter is especially usefull for elements which you can't reach using the Class filter, such as Rooms or RevitLinks.

Cheers

Benoit

[CaptainDan]

Hi @BenoitE&A

Thanks but the FilterCategoryRule is class is a part of the Revit Filter API, not the element filter / collector.

@jeremytammik Thanks Jeremy. I too searched the internet and SDK and couldn't find much mention of it. Thanks for letting the dev team know.

[jeremytammik]

Dear Dan,

Thank you for your patience.

I heard back from the development team, and they say:

Q1. What does `FilterCategoryRule` correspond to in the Revit user interface?

A1. There is no direct correspondence in Revit UI, this is the FilterRule to be used in API.

Q2. If this filters by category, then what is the relationship between the set of categories assigned to this rule and the set of categories passed to `ParameterFilterElement.Create()`?

A2. There is no relation to ParameterFilterElement.Create();

Q3. How do I successfully create a filter based on this filter rule?

A3. You cannot create a `ParameterFilterElement` based on this `FilterCategoryRule`, but you can create an `ElementParameterFilter`, an API construct, based on it.

Here is an example:

  FilteredElementCollector collector  = new FilteredElementCollector( doc );
  // Find all walls and windows in the document
  IList<ElementId> categories = new List<ElementId>();
  categories.Add(BuiltInCategory.OST_Walls);
  categories.Add(BuiltInCategory.OST_Windows);
  FilterCategoryRule fRule = new FilterCategoryRule(categories);
  ElementParameterFilter wallsAndWindows  = new ElementParameterFilter( fRule, true );
  IList<Element> wallAndWindowFounds = collector.WherePasses( wallsAndWindows  );

I hope this helps.

Best regards,

Jeremy

[CaptainDan]

@jeremytammik 

Thanks for getting the feedback from the dev team. I think the documentation is confusing on this because it states in the Revit 2014 API updates (at http://thebuildingcoder.typepad.com/blog/2013/04/whats-new-in-the-revit-2014-api.html😞

FilterCategoryRule

The new class FilterCategoryRule can be used in the definition of a ParameterFilterElement. 

Also the fact that FilterCategoryRule derives from FilterRule whose other subclasses form a part of creating parameter filters (for views, i.e. those that are accessible in the Revit UI). There is a function on ParameterFilterElement that accepts a list of FilterRule which adds to the confusion:

public static ParameterFilterElement Create(
	Document aDocument,
	string name,
	ICollection<ElementId> categories,
	IList<FilterRule> rules
)

 
Perhaps the Revit API documentation on subclasses of FilterRule should be made more clear where each subclass can and can't be used. (Or at least have it raise a more specific exception than InternalException when a FilterCategoryRule is passed as an argument).

Are you able to relay this information back to the dev team?

Regards

Dan

[jeremytammik]

Yes, I find this confusing too!

I'll point it out and ask for further clarification.

Thank you!

Cheers,

Jeremy

[jeremytammik · Accepted solution]

Dear Dan,

The development team agree and explain:

You are correct. The Revit API docs are not entirely correct, especially this statement: "The new class FilterCategoryRule can be used in the definition of a ParameterFilterElement". the ParameterFilterElement.Create() method could potentially take a FilterCategoryRule object instead of a set of category ids, but this flavour of the Create method was never introduced. I'll file a development task to either correct the docs or add the method. Additional confusion also comes from these two names in the API: ParameterFilterElement and ElementParameterFilter :slightly_smiling_face: ... Anyway, the summary in your blog post draft is correct: "... this can be seen as an extension of the ElementCategoryFilter and the associated quick filter shortcut methods OfCategory and OfCategoryId."

In fact, Benoit was absolutely correct.

It seems to me that the FilterCategoryRule is completely equivalent to a logical or of a bunch of ElementCategoryFilter instances, such as I used in the examples to retrieve MEP and structural elements:

• http://thebuildingcoder.typepad.com/blog/2010/06/retrieve-mep-elements-and-connectors.html
• http://thebuildingcoder.typepad.com/blog/2010/07/retrieve-structural-elements.html

I hope this helps.

Best regards,

Jeremy

[jeremytammik]

Dear Dan,

I summarised the results of our illuminating discussion on The Building Coder:

http://thebuildingcoder.typepad.com/blog/2018/05/how-to-use-filtercategoryrule.html

I hope this helps.

Thank you for raising this.

Cheers,

Jeremy