Highlight elements from a linked document

[Moustafa_K]

The past 2 days I was scratching my head of how to highlight an element from a linked document. I tried many API statement and I also found out there are many posts requesting the same.

https://forums.autodesk.com/t5/revit-api-forum/how-to-select-linked-element-by-element-id/m-p/824563...
https://forums.autodesk.com/t5/revit-api-forum/highlight-and-tag-linked-elements/m-p/5294217
https://forums.autodesk.com/t5/revit-api-forum/how-to-highlight-element-in-linked-model-by-api/m-p/9...
https://forums.autodesk.com/t5/revit-api-forum/high-light-link-element/m-p/11111305
https://forums.autodesk.com/t5/revit-api-forum/can-t-select-elements-in-a-linked-model/m-p/12681983
https://forums.autodesk.com/t5/revit-ideas/highlight-element-selection-in-linked-files/idi-p/7619701

I also realized that this has been a wish since 2017, which was some how disappointing. The good news, after some readings over the Revit API Doc, it seems this wish have been granted since Revit 2023.

A new Selection function called SetReferences has been added, allowing elements to be highlighted via set of references. We don't (at least for me) often use references to highlight elements, but rather to set hosts, like placing hosted families or extracting element IDs from a ReferenceIntersector or when selecting by picking.

So, if we provide the SetReferences function with references from a linked document, will it work? In theory, yes, it should work. However, some extra work is required to capture such element references. Firstly, we need to understand that this function operates on the currently active document. This means that the references we provide must be in a format that the current document can recognize to highlight them in the current view.

Let's attempt to highlight a face from an element in a linked document in the following steps:

1. Click on a point over one of the faces in a linked document.

2. Then, pass this reference to SetReferences, and it will highlight the face from the linked document.

3. Similarly, if you press Tab to cycle through line, face, and object, once you reach the object, select it to get the object reference.

var linkedFaceReference = UiDoc.Selection.PickObject(
    Autodesk.Revit.UI.Selection.ObjectType.PointOnElement
);
UiDoc.Selection.SetReferences([linkedFaceReference]);

Now, this only happens when a user interacts with the UI. But what if I have an element ID from a linked document that I want to highlight? The real question then becomes, how can I extract a reference from an ElementId that belongs to a linked document?

This is achievable, but not directly from the ElementId; we need to work with the element itself. First, we need to get the element from the linked document, then create a reference for this element. However, we can't use this reference as it's only meaningful to the linked document, not the current one. Therefore, we must convert this reference to the current document using CreateLinkReference and RevitLinkInstance. It might sound confusing, but I've included the code below to demonstrate how it functions clearly. So if you have the linked ElementId, you can directly start from line 10, without the need for selection.

See the example code below for easy reference.

var pickedReference = UiDoc.Selection.PickObject(
    Autodesk.Revit.UI.Selection.ObjectType.PointOnElement
);

// get Revit link Instance and its document
var linkedRvtInstance = Doc.GetElement(pickedReference) as RevitLinkInstance;
var linkedDoc = linkedRvtInstance.GetLinkDocument();

//get the Linked element from the linked document
var linkedElement = linkedDoc.GetElement(pickedReference.LinkedElementId);

// now create a reference from this element [ this is a reference inside the linked document]
var reference = new Reference(linkedElement);

// convert the reference to be readable from the current document
reference = reference.CreateLinkReference(linkedRvtInstance);

// now the linked element is highlighted
UiDoc.Selection.SetReferences([reference]);

[longt61]

I used to work with a similar task in the past to highlight elements from a linked document without success, so I have to compromise that once I have gather all linked element data that I need, I will open the linked document to highlight those elements. In doing so, it will unload the linked document and open it in a new Revit tab, quite inconvenient.
To be honest, I never think of using references as you have proposed. Very interesting idea. I can still learn from something I have worked on like 3 years ago. 
Just out of curiosity, have you succeeded with this idea yet? And may be it should be posted somewhere else so people can see this as an proposed idea instead of a question without mark of resolution. Thank you for sharing, I will try this sometime soon.

[Moustafa_K]

Thanks! I have placed it on my fresh starting blog, that I will usually journal my findings there as well as placing it here.

https://sharpbim.hashnode.dev/highlight-elements-from-a-linked-document

and yes the proposed solution is tested and works for me... I will be glad to know if there is any exception to this methodology.

[jeremy_tammik]

Thank you for researching and documenting this approach. I am sure many will find it very useful. I shared it on The Building Coder blog:

• https://thebuildingcoder.typepad.com/blog/2024/05/lengthen-ducts-and-highlight-links.html#2

Now I see that you also started your own blog. Congratulations! I wish you lots of luck and much success with that!

[Moustafa_K]

Thanks @jeremy_tammik , so glad to read this topic on your blog 🙂 

[GaryOrrMBI]

@Moustafa_K , @jeremy_tammik 

Since the ability to properly highlight selected link elements is newer than the ability to programmatically select them you may also want to include references to, or info from, this post about highlighting those elements:

https://forums.autodesk.com/t5/revit-api-forum/selection-of-linked-elements-does-not-look-correct/m-... 

-G