NewFamilyInstance(Face,Line,FamilySymbol), ArgumentsInconsistentException

[RPTHOMAS108]

Please refer to attached solution files which provides minimum reproducible case for the unexpected API behaviour I am experiencing. There is a Revit project file within the solution called SampleProject.
Whilst using the following NewFamilyInstance overloads:

ItemFactoryBase.NewFamilyInstance(Reference, Line, FamilySymbol)
ItemFactoryBase.NewFamilyInstance(Face, Line, FamilySymbol)

I am getting the exception ArgumentsInconsistentException with message “Family cannot be placed on this line as it does not coincide with the input face.”

I know that the line is coincident with the input face to a reasonable degree by comparison of coords and it is a curve resulting from the intersection of the input face with another face (so must be coincident with the input face).
I believe the error is occurring because the test for compatibility is being conducted between a curve in instance space and a face is the symbol space of the originating geometry. I surmise this due to the fact that an uncut family instance (which inherently has solids transformed to instance space) throws the exception whilst a cut family instance (which inherently has solids in the instance position without transformation) does not.

It can be further demonstrated that if the curve is transformed into symbol space then the exception is not thrown (since presumably comparison occurs between curve and face both in symbol space). However, when doing this the created hosted instance is not in a position that would be permissible in the UI i.e. it is in symbol space remote from the host element.

Obviously if there is a better approach or I’m doing something wrong let me know. I don’t think I’m expected to add the instance in the wrong place and then move it to the right place etc. I believe this is an issue that has to be rectified in the API. Since it will currently work one way for walls, floors etc where solids are at the top level in the geometry tree but will fail for uncut family instances.

[jeremytammik]

Dear Richard,

Thank you for your report and reproducible case.

Sorry to hear about this.

I logged the issue REVIT-159855 [NewFamilyInstance ArgumentsInconsistentException line does not coincide with input face] with our development team for this on your behalf as it requires further exploration and possibly a modification to our software. Please make a note of this number for future reference.

You are welcome to request an update on the status of this issue or to provide additional information on it at any time quoting this change request number.

This issue is important to me. What can I do to help?

This issue needs to be assessed by our engineering team and prioritised against all other outstanding change requests. Any information that you can provide to influence this assessment will help. Please provide the following where possible:

• Impact on your application and/or your development.
• The number of users affected.
• The potential revenue impact to you.
• The potential revenue impact to Autodesk.
• Realistic timescale over which a fix would help you.
• In the case of a request for a new feature or a feature enhancement, please also provide detailed Use cases for the workflows that this change would address.

This information is extremely important. Our engineering team have limited resources, and so must focus their efforts on the highest impact items. We do understand that this will cause you delays and affect your development planning, and we appreciate your cooperation and patience.

Best regards,

Jeremy

[RPTHOMAS108]

Hello Jeremy,

Thanks for raising a case for this.

I wouldn't state it has had a large impact on me in terms of affected users or revenue (since my numbers would be 1 and 0 respectively). However my concern would be for those that have incorporated this function and are not aware of the issue (since it would work some of the time as expected). Worse still may be the tendency to make downstream allowances for such a quirk found to exist. As an example I've become aware of a core dynamo node 'FamilyInstance.ByFace' that uses this overload at it's interface with the API. 

Realistic timescale would be less than a month. If the error is what I believe then it's just a case of correctly comparing the coordinates within the checking function that throws the exception. Everything needed to verify the line is coincident with the face is already supplied to the function in a common coordinate space.

[jeremytammik]

Dear Richard,

Thank you for your appreciation, business case and thoughts on this.

I added them to the development ticket.

Cheers,

Jeremy

[jeremytammik]

Dear Richard,

Thank you for your patience.

The development team analysed the ticket REVIT-159855 [NewFamilyInstance ArgumentsInconsistentException line does not coincide with input face] and made some internal observations. Not sure whether they will help illuminate or understand the issue, and whether you have any possibility of making use of them in the external API, but I'll share them with you anyway:

Yes, so in short, SF_F.Reference ends up supplying a Pick to the Face inside the FamSym directly, not going through the FamilyInstance. The validator correctly throws, as the Curve/Line is nowhere near the un-transformed Face.

The next question: Is there a proper way to generate a reference/pick that includes the FamilyInstance at the top, so that the PickFinder would return a Trf? If there is one, what is it?

Looking at the supplied sample code in MinRepCase.vb ... aaagh! I think I see what is happening. Maybe.

In this chunk of code near the end:

  Private Shared Function GetSolids(geomElem As Autodesk.Revit.DB.GeometryElement) As List(Of Solid)
  ...
    For Each item As GeometryInstance In S_L2
      Dim transformedGeomElem As Autodesk.Revit.DB.GeometryElement = item.GetInstanceGeometry()
      Dim SOLs As List(Of Solid) = GetSolids(transformedGeomElem)
      If SOLs.Count > 0 Then
        SolidsFromThis.AddRange(SOLs)
      End If
    Next
  
    Return SolidsFromThis
  End Function

We are dealing with the GeometryInstance and likely correctly transforming the geometry, I assume. But later in life the code is just using a Face of that Geometry, which Face might be in the correct location indeed, but we are saying:

  Fi = IntDoc.Create.NewFamilyInstance(SF_F.Reference, Crv, FS)

i.e. just taking a Reference to that Face. But the transformed Face that does not belong to any Element or, at least if it is really transformed, it just cannot possibly belong to the original Element. So what is SF_F.Reference supposed to produce here anyway? I am not sure. Looks like it produces a ref to the GeometryElement/GRep from which the original Face came, i.e. the GRep of the FamilySymbol in this case.

Can you make any use of these observations with the existing API in its current state?

Cheers,

Jeremy

[RPTHOMAS108]

Hello Jeremy,

Thanks for the update and taking the time to review personally.

I’m not sure I can make any adjustments my end and if I did what would happen down the line? I can probably just avoid this overload and use a different form of family to achieve what I need. The idea was to add a shelf angle to the side of a beam/wall to pick up floor slab (bottom of floor intersects with web of beam or wall face). I can do this with level based structural framing and end offsets given the curve ends. Although it has the disadvantage of when the beam/wall is moved the angle is left behind. Ideally, I want to achieve the aforementioned hosted behaviour.

I don’t know if it has been concluded by the development team that this is acceptable internal behaviour or not i.e. can they suggest a workaround or correct alternative approach I should be using? Alternatively, do they believe the internal code needs adjustment and are planning to do so?

I think it seems straightforward in the sense that I get the curve by intersecting two faces. If I then supply one of those faces and the curve to the family instance constructor it shouldn’t tell me they don’t coincide. It’s a bit confusing otherwise and leads to contradictions in approach between elements with top-level solids and those with solids within the top-level geometry instance.

In the below image I've drawn on red lines in paintbrush to show where the instance is placed compared to where it should be placed (when we supply the curve transformed to symbol space). As can be seen the element is hosted to the face of the beam. You would be hard pressed to achieve this using the UI (so as a minimum I should not be able to do this).

I note the view cube which shows that the orientation of the hosted family matches how the host family would be located in it's family document (symbol space). I mention this because I've often used a transform from instance space to symbol space to identify the top face of the family (or other faces etc.). Regardless of the slope of the beam represented by the instance (where face normal is not 0,0,1) we can always transform it to symbol space where it will be. I note this because I believe it is a useful trick in identifying faces of instances with any orientation.

Regards

Richard

[jeremytammik]

Dear Richard,

Thank you for your update and explanation.

I added them to the issue REVIT-159855 [NewFamilyInstance ArgumentsInconsistentException line does not coincide with input face] as well.

Cheers,

Jeremy

[jeremytammik]

Dear Richard,

Good news!

An answer to and resolution of the issue REVIT-159855 [NewFamilyInstance ArgumentsInconsistentException line does not coincide with input face] has been provided by Revit API guru Scott Conover:

I can make the original code work in both cases described.

The problem with the original code provided is the use of GeometryInstance.GetInstanceGeometry() when extracting solids from family instances.  What’s wrong with that?  Since this face will be used as a Reference for another instance placement, it is required to take the Reference from the faces/edges of that Solid.  GetInstanceGeometry() (as well as GetSymbolGeometry(Transform) and GetInstanceGeometry(Transform) ) have remarks that say:

The geometry will be in the coordinate system of the model that owns this instance. The context of the instance object (such as effective material) will be applied to the symbol. Note that this method involves extensive parsing or Revit's data structures, so try to minimise calls if performance is critical. Geometry will be parsed with the same options as those used when this object was retrieved. This method returns a copy of the Revit geometry. It is suitable for use in a tool which extracts geometry to another format or carries out a geometric analysis; however, because it returns a copy the references found in the geometry objects contained in this element are not suitable for creating new Revit elements referencing the original element (for example, dimensioning). Only the geometry returned by GetSymbolGeometry() with no transform can be used for that purpose.

This is basically the problem; the Picks (References in API) generated by Geometry parsing are not correct when we apply transforms and get the geometry in a modified form.  They can’t be used by routines that create elements from the input References (dimensions, tags, and other model elements creation).

So, the fix is to make use of GetSymbolGeometry() to get the reference to the family instance face.

The complication lies in the logic for this particular workflow.  The line used for placement is calculated with the intersection of the instance face and the floor face.  So, we can’t get that line from the intersection of the symbol geometry and the floor face.  Thus, to make this work, I needed to also get the instance geometry for the family instance and use heuristics (comparing area and the transformed normal vector) to determine I’d found a matching face.  I believe in the next major release of Revit, we may be able to compare Tag values instead, though I didn’t test this.

I also eliminated some of these steps for family instances which have their own unique geometry (by using the routine FamilyInstance.HasModifiedGeometry()).  This is probably better than trying to take that geometry through the full logic with transforms and inverse transforms when not necessary.

I can’t guarantee that the logic in the modified add-in code is bulletproof for all situations they may encounter.  There are lots of ways Revit does things or allows users to do things.  But I would recommend starting from this.

I will close this issue as "By Design".

Many thanks to Scott for the clarification with the detailed precise explanation and solution.

An updated modified VB file demonstrating the exact code steps is coming soon... can't access the database system right now.

I hope this helps.

Cheers,

Jeremy

[RPTHOMAS108]

Hello Jeremy,

Thanks for explaining this workaround approach. I'm not fully following so I'll await your solution file. I still believe there is a flaw somewhere in the sense that I can achieve non-ui behaviour with the API. 

Perhaps also the Exception raised itself is a bit vague and misleading. Since from what you describe it is not about the final co-ordinate relationship between the face and the line but instead where the face came from.

Regards

Richard

[jeremytammik · Accepted solution]

Dear Richard,

Thank you for your update and patience.

Sorry it took me so long to dig out the updated sample VB code for and from your issue REVIT-159855 [NewFamilyInstance ArgumentsInconsistentException line does not coincide with input face], provided by Scott Conover.

Here it is now, attached to this message, in MinRepCase_modified.vb.txt.

I hope this helps.

Cheers,

Jeremy

[RPTHOMAS108]

Hello Jeremy,

Thanks for the solution to this issue it appears to be a very robust.  I've adjusted slightly to aid my understanding and updated to include non-family instances (since I need to find intersections between slabs and walls also).

I believe it still follows the same principles you set out.

Regards

Richard

[jeremytammik]

Thanks again for raising this tricky issue, and to Scott for his illuminating solution. Preserved for posterity here:

https://thebuildingcoder.typepad.com/blog/2020/04/references-in-symbol-versus-instance-geometry.html

[哀家爆]

What if the familyinstance doesn't have symbolGeometry?

[RPTHOMAS108]

Then it is probably not a family instance you get either:

Objects that have only geometry without a GeometryInstance object (e.g. modified FamilyInstance, walls/floors other system families)

Objects that have both instance and symbol geometry within a GeometryInstance object (e.g. non-modified FamilyInstance)

Objects that have no geometry (they may have geometry but not made of objects exposed to the API).

[哀家爆]

In fact, I also met this problem when I try to locate a familyinstance which is based on a line. If I locate the instance manual, I have to choose a sketch plane or just a plane, then I need

 to pick up two points before finish this operation. So in my code,I choose the function: NewFamilyInstance(face,line,familysymbol). And of course Revit throw the same exception.

But my familyinstance’s SymbolGeometry is null. Or is there a workaround to solve my problem?

[RPTHOMAS108]

You have to probably elaborate but if you are you talking about a FamilyInstance that is modified by cuts vs one that isn't then the solution provided above seemed to resolve both those situations. If it doesn't have GeometryInstance to use then use the solids directly.

If you are talking about some other situation then I've not encountered that.

[RPTHOMAS108]

This is a situation with a cut family instance:

This is one that is not cut:

They both have geometry you can use, either top level or nested within the GeometryInstance. Also note GeometryInstance still has a transform, refer to the code for the implications of this (in terms of using it).

Also I should note that the two solids you see above are what exists in the family for different 'Detail Levels' the one that is empty is the one not appropriate to the geometry options. These empty solids appear even when you don't include non-visible objects via the geometry options (at least that seems to be the case in RevitLookup).