Porting guide from Level of Details to Model states.

by Chandra shekar Gopal,

Introduction to Model states

Model States were introduced in Inventor 2022 and even though the product documentation has good details, our ADN team has provided much support around the issues to move to the model states feature. Now that Inventor 2023 has come out last week, it’s a good time to review the porting requirements in your code for Model States and discuss some of the known issues.

Let’s start by reviewing the documentation. These links are provided for the 2023 product, but also present in 2022:

Feature Aspects:
Introducing Model States (What's New in 2022)
About Model States

Adding my own perspective to the “introduction” topic, I would also like to add that “Design Options” and “varying configurations” are important aspects of this new Models States feature.

As you can see, there is already detailed information in the product documentation. When comparing this to the old Level of details representation (LOD) feature, there is much improvement to how you can work with different representations of the model, but this can also present some migration problems. When discussing this internally, we realized that Inventor developers have actually had a fairly easy migration path in the past (when compared to AutoCAD or 3ds Max for example).  The Model States feature seems to be the most disruptive so far. We would be happy to hear your ideas about how we can better support you in future when such major features are coming in Inventor, Please feel free to leave comments below.

Conversion of Level of Detail into model state

One topic that you will need to fully understand to handle model migration is how the LOD is converted to Model States. This is explained in the docs here: About Level of Detail Migration

API aspects

The API documentation as also updated to help support developers. See here: Working with Model States. In the next sections, I will discuss application specific issues.

The Legacy way of accessing Level of Detail Representation (LOD) API in Inventor 2021

Let’s start with looking at how to access the legacy Level of detail representation items, they are accessible through ReprenstationManager object of AssemblyComponentDefinition

Sub GetLods()

    Dim sFileName As String

    sFileName = "C:\Temp\Assembly1.iam"

    Dim oDoc As AssemblyDocument

    Set oDoc = ThisApplication.Documents.Open(sFileName)

    Dim oAssemblyCompDef As AssemblyComponentDefinition

    Set oAssemblyCompDef = oDoc.ComponentDefinition

    ' Get Level of Detail Representations collection object.

    Dim oLODs As LevelOfDetailRepresentations

    Set oLODs = oAssemblyCompDef.RepresentationsManager.LevelOfDetailRepresentations

    ' Get all Level of Detail Representation names from Level of Detail Representations object.

    Dim oLOD As LevelOfDetailRepresentation

    For Each oLOD In oLODs

        Debug.Print oLOD.Name

    Next

    oDoc.Close True

End Sub

Different types of documents with respect to Model State  

Part or Assembly can be categorized as three types, 

• Plain Document 
• Model State Document 
• iComponent (iPart or iAssembly) Document 

When a new part or assembly is created, usually we can only see Master model state there. At this moment, such part or assembly is called a Plain Document. Plain document is not model state document and not iComponent document. A master model state document is basically a document without any model states in it. The reason why we design this way is providing user a visible way to create Model State. 

If user starts to create at least one additional Model State (end up with Master and another new created Model State), this document becomes Model State document. The user cannot create any iComponent there.  

User cannot create any Model State inside it. iComponent document also has two types (factory and member). 

We plan this way is truly connected with how clients utilize Model State and iComponent to tackle issues. They are totally unrelated

If you look from bigger picture, plain document is just like legacy normal document. Model State and iComponent both are table driven document. When a document becomes table driven document, these Booleans start

After understanding the design, let me list these Boolean in a table (together with some legacy booleans). The empty cells means False. 

Member document v/s Factory document

Essentially, Factory document is the document for user to create model states or design modeling recipe (feature, component). You can think of it as (in general) all edits user do need be Factory document environment. For example, user creates 3 model states in Factory Document (ms1, ms2, ms3).

Member document represents one result document from one of model states (e.g., ms1). This is only elaborated when placing ms1 into other assembly, or derived into another part, or place into drawing view. It is for consumption purpose. This document usually cannot be modified. Member document update is always driven by Factory Document. Please note, these documents are only elaborated on demand. If we do not consume, there might be no member document there.   

Model State Factory Document

• Full editing document with Model States
• Drive variations in members
• Presented with UI Frame
• Floating document, no storage on disk
• Generated from one of member document storage on the fly

Model State Member Document

• Represent Model State Member
• Non-modifiable when Factory document is available
• Usually no UI Frame except in-place-edit
• Each physical file might have multiple member

Facts about accessing the iProperties of Model State via Apprentice Server 2022 API

The ApprenticeServerDocument.PropertySets currently just return the iProperty of the active model state, and the model state level iProperty is regarded as the model data so Apprentice can’t edit at present.  

A new API ApprenticeServerDocument.FilePropertySets is exposed in Inventor 2022.1 release, and this FilePropertySets is File level iProperty, and it will return the same property values as the iProperty of master model state, and you can also change the property values in FilePropertySet.  If you want to edit the iProperty of a custom model state, it is recommended to use Inventor Server or Inventor instead.

Behavior of IsModifiable value after adding custom model state in Inventor 2022

Any Inventor 2022 part with an added model state causes IsModifiable value to be true and prevents any updates of iproperties with apprentice server. Removing the model state then allows updates as IsModifiable is then set to false. When there are two parts (one with model state and one without) can be used to demonstrate the issue. Open a part and try to update a property, it works on the part without a model state but fails on the same part with model state added.

The legacy ApprenticeServerDocument.PropertySets does not work in ApprenticeServer anymore when there is custom model state, and in Inventor 2022.1 we introduced a new ApprenticeServerDocument.FilePropertySets instead, so you should make use of the new API to update the file level iProperties. 

Behavior of DocumentDescriptor object with model state in Inventor 2022

In a situation in Inventor 2022, a custom model state is added to an assembly. In that custom model state, suppress the few occurrence and activate the custom model state. On retrieving the count of ReferencedDocumentDescriptor using below VBA code, it gives wrong number count (lesser than the actual count). Few suppressed occurrences were not included in the count of ReferencedDocumentDescriptor.

ThisApplication.ActiveDocument.ReferencedDocumentDescriptors.Count

This behavior has been rectified and fixed in Inventor 2023. Open the same assembly and activate custom model state (few occurrences were suppressed). On counting the number of DocumentDescriptor using same above VBA code, it gives exact number of DocumentDescriptor which are participated in an assembly. Even though, few occurrences are suppressed in custom model state of an assembly.

Checking Dirty states of Model state member Document

As we know that each model state (including master/model state/substitute) could have its own member document, and there could also have different dirty states. Normally we cannot use the dirty state of master document to represent all the member docs. 
 
So one work around for the developers could be check the dirty state for each model state or only substitute without activating them: 

Dim doc As AssemblyDocument  
Set doc = ThisApplication.ActiveDocument  
 
Dim oMs As ModelState  
For Each oMs In doc.ComponentDefinition.modelStates 

If oMs.ModelStateType = kSubstituteModelStateType Then  
            Dim oMsDoc As AssemblyDocument  
            Set oMsDoc = oMs.Document 
 
            If Not oMsDoc Is Nothing Then  
                        Debug.Print oMs.Document.Dirty  
            End If  
End If

Next 

Another solution could be getting the substitute document only and checking its dirty state if the developer only cares about the substitute: 
 
Dim oSub As AssemblyDocument 
 
Set oSub = ThisApplication.Documents.ItemByName("D: \Temp\Assembly1.iam<Substitute1>") 
 
Debug.Print oSub.Dirty

Checking iProperty value for substitute LOD saved which is saved in lower than Inventor 2022 version.

In a scenario, an assembly which is saved Inventor version lower than 2022. It means that Level of Detail (LOD) is available in assembly files instead of model state. When the same assembly is opened in Inventor 2022, substitute LOD becomes substitute model state. In doing this upgrade, iProperty value (Part Number) of assembly after activating substitute model state is unable to retrieve through Inventor API using VBA code.

Sub GetPartNumber()
    Dim doc As Document
    Set doc = ThisApplication.ActiveDocument
    Debug.Print doc.FullDocumentName
    Dim propSet As PropertySet
    Set propSet = doc.PropertySets.Item("{32853F0F-3444-11D1-9E93-0060B03C1CA6}")
    Dim prop As Property
    Set prop = propSet.Item("Part Number")
    Debug.Print "PartNumber=" & prop.Value
End Sub

This behavior has been addressed in Inventor 2022.3 and 2023. Now, iProperty value for substitute LOD which is saved in lower than Inventor 2022 version can be retrieved through Inventor API.