Occurences and Transformations

---

Updated : 03 December 2024

Overview

---

An assembly document can include one or more inclusions, which may originate from various documents. Each inclusion can be positioned differently depending on the operations it has undergone.

Note

It is possible to retrieve the definition document of an occurrence present in an assembly document from its inclusion operation:

DocumentId inclusionDefDocument = TopSolidDesignHost.Assemblies.GetInclusionDefinitionDocument(operation);

This diagram illustrates the relational logic between "source" and "definition" occurrences:

The "source" represents the previous occurrence, while the "definition" represents the first occurrence.

It is also possible to access the transformations associated with the final positioning of the resulting entity from an inclusion operation in the current document, both from the "source" and "definition" occurrences:

ElementId child = TopSolidDesignHost.Assemblies.GetInclusionChildOccurrence(operation);
Transform3D transformDefinition = TopSolidHost.Geometries3D.GetOccurrenceDefinitionTransform(child);
Transform3D transformSource = TopSolidHost.Geometries3D.GetOccurrenceSourceTransform(child);

This transformation can then be used for purposes such as identifying notable geometric elements.

Code example with comments :

---

The following method searches for sketches present in the inclusions of an assembly document and generates the associated points in the said document using the associated transformation. Two behaviors are highlighted: the inclusion of a part-type document and the inclusion of an assembly-type document. In the latter case, two transformations are applied successively. Naturally, in a similar scenario, a recursive method should be coded to process all potential assembly levels.

This example has been built on such a scenario:

In this case, it is necessary to navigate to the part document containing the sketch and apply the required transformations to accurately retrieve and integrate it into the top-level assembly document.

1. Verify if a document is opened and confirm it is of the assembly type::

   DocumentId currentDoc = TopSolidHost.Documents.EditedDocument;
   if (currentDoc.IsEmpty) return;
   
   if (!TopSolidHost.Documents.GetTypeFullName(currentDoc).Contains("AssemblyDocument")) return;
   

2. Retrieve all operations from the document and filter by inclusion type:

   List<ElementId> operations = TopSolidHost.Operations.GetOperations(currentDoc);
   foreach (ElementId operation in operations)
   {
   	if (!TopSolidHost.Elements.GetTypeFullName(operation).Contains("InclusionOperation")) continue;
   

3. Extract the child occurrence, definition document, and associated transformation:

   ElementId child = TopSolidDesignHost.Assemblies.GetInclusionChildOccurrence(operation);
   Transform3D transform = TopSolidHost.Geometries3D.GetOccurrenceDefinitionTransform(child);
   DocumentId inclusionDefDocument = TopSolidDesignHost.Assemblies.GetInclusionDefinitionDocument(operation);
   

4. If the inclusion is an occurrence of another assembly, retrieve the additional transformation:

   Transform3D transformAdditional = Transform3D.Identity;
   if (TopSolidDesignHost.Assemblies.IsAssemblyOccurrence(child))
   {
     List<ElementId> parts = TopSolidDesignHost.Assemblies.GetParts(inclusionDefDocument);
     foreach (ElementId part in parts)
     {
       ElementId parentOpe = TopSolidHost.Elements.GetParent(part);
       if (TopSolidHost.Elements.GetParent(part) != ElementId.Empty)
       {
         if (TopSolidDesignHost.Assemblies.IsInclusion(parentOpe))
         {
           inclusionDefDocument = TopSolidDesignHost.Assemblies.GetInclusionDefinitionDocument(parentOpe);
           transformAdditional = TopSolidHost.Geometries3D.GetOccurrenceDefinitionTransform(part);
         }
       }
     }
   }
   

5. Initiate modifications to the current documen:

   try
   {
     TopSolidHost.Application.StartModification("sketch to points", false);
     TopSolidHost.Documents.EnsureIsDirty(ref currentDoc);
   

6. Retrieve sketch points from the inclusion's definition document:

   //gets sketch points from inclusion definition document
   ElementId sketch = TopSolidHost.Sketches2D.GetSketches(inclusionDefDocument).FirstOrDefault();
   if (!sketch.IsEmpty)
   {
     List<ElementItemId> vertices = TopSolidHost.Sketches2D.GetVertices(sketch);
     int indexPoint = 0;
     foreach (ElementItemId vertex in vertices)
     {
       Point2D point2D = TopSolidHost.Sketches2D.GetVertexPoint(vertex);
   
       Point3D point3D = new Point3D(point2D.X, point2D.Y, 0);
       SmartDirection3D dirX = new SmartDirection3D(Direction3D.DX, point3D);
       SmartDirection3D dirY = new SmartDirection3D(Direction3D.DY, point3D);
   

7. For each sketch point, create the corresponding point in the current document and assign it a name:

   ElementId pointCreated = TopSolidHost.Geometries3D.CreatePoint(currentDoc, point3D);
   if (pointCreated.IsEmpty) continue;
   TopSolidHost.Elements.SetName(pointCreated, "Point_" + indexPoint);
   

8. Create a corresponding offset point (with a value of zero) to generate an actual transformation operation:

   ElementId pointCreated = TopSolidHost.Geometries3D.CreatePoint(currentDoc, point3D);
   if (pointCreated.IsEmpty) continue;
   TopSolidHost.Elements.SetName(pointCreated, "Point_" + indexPoint);
   

9. Apply the transformation to the result point, distinguishing between two cases:

   • Assembly occurence

   if (TopSolidDesignHost.Assemblies.IsAssemblyOccurrence(child))
   {
     ElementId pointCreatedTransformed1 = TopSolidHost.Entities.Transform(offsetPoint, transformAdditional);
     if (pointCreatedTransformed1.IsEmpty) continue;
     TopSolidHost.Elements.SetName(pointCreatedTransformed1, "SketchPointTransformed1_" + indexPoint);
     ElementId pointCreatedTransformed = TopSolidHost.Entities.Transform(offsetPoint, transform);
     TopSolidHost.Elements.SetName(offsetPoint, "SketchPointTransformed2_" + indexPoint);
   }
   

   • Part occurence

   else
   {
     ElementId pointCreatedTransformed1 = TopSolidHost.Entities.Transform(offsetPoint, transform);
     if (pointCreatedTransformed1.IsEmpty) continue;
     TopSolidHost.Elements.SetName(pointCreatedTransformed1, "SketchPointTransformed1_" + indexPoint);
   }
   

10. Finalize the modification and complete the iteration over the loop:

            indexPoint++;
          }
        }
        TopSolidHost.Application.EndModification(true, true);
      }
      catch (Exception ee)
      {
        TopSolidHost.Application.EndModification(false, false);
      }
    }