How to Manage Part Hierarchies in FreeCAD Assembly4

Managing part hierarchies in the FreeCAD Assembly4 workbench allows you to organize complex mechanical assemblies into logical, maintainable sub-assemblies and individual components. This article explains how Assembly4 handles hierarchical structures using App::Part containers, how to establish parent-child relationships through Local Coordinate Systems (LCS), and the best practices for inserting, updating, and structuring nested assemblies within your FreeCAD document tree.

Understanding Assembly4 Architecture

Assembly4 does not use a traditional physics-based constraint solver. Instead, it positions parts geometrically by mapping a Local Coordinate System (LCS) on a child part directly to an LCS on a parent part or assembly.

In this structure:

  • Root Assembly (Model): The primary container that holds the global coordinate system and top-level sub-assemblies or parts.
  • App::Part Containers: Standard FreeCAD Part containers used to encapsulate solid bodies, sketches, and their associated coordinate systems.
  • Sub-Assemblies: Standalone Assembly4 Model containers that can be nested inside a parent Model to create multi-tiered hierarchies.

Step 1: Create Independent Sub-Assemblies

To build a clean hierarchy, start from the bottom up by creating self-contained sub-assemblies in their own FreeCAD document files:

  1. Create a new document and switch to the Assembly4 workbench.
  2. Click New Model to insert the root Model container.
  3. Import or model individual parts within this document, placing each distinct solid in an App::Part container.
  4. Add a designated attachment LCS to the root of the sub-assembly (Model) or directly to the constituent parts using the New Coordinate System tool.
  5. Save the document with a descriptive name (e.g., Gearbox_SubAssembly.FCStd).

Step 2: Establish Attachment Points (LCS)

Proper hierarchy management relies entirely on defining intentional datum points:

  1. Select the target face, vertex, or datum plane where components will connect.
  2. Click the New Coordinate System button in Assembly4.
  3. Use the coordinate system properties dialog to orient the LCS axes (X, Y, Z) so they align with your intended mating orientation.
  4. Name the LCS clearly (e.g., LCS_Mounting_Hole or LCS_Base_Connection) to avoid confusion when mapping links later.

Step 3: Insert Sub-Assemblies into the Main Assembly

Once sub-assemblies are prepared, create the top-level assembly:

  1. Create a new FreeCAD document and insert a New Model container.
  2. Save this document in the same working directory as your sub-assemblies.
  3. Click Insert a Part from an external file.
  4. Browse to your sub-assembly file and select the primary Model container to import.
  5. In the placement dialogue that appears:
    • Under Attachment Engine, choose Asm4EE.
    • Under Attach to, select the parent LCS (such as the default LCS_0 of the main assembly).
    • Under Attachment LCS, select the corresponding LCS from your inserted sub-assembly.
  6. Click OK. The sub-assembly will now appear nested under the main assembly tree.

Step 4: Nesting and Deep Hierarchies

To add further depth to your hierarchy:

  • Part within Sub-Assembly: You can insert parts directly inside a nested sub-assembly by opening the sub-assembly's native file, modifying the hierarchy there, and saving.
  • Sub-Assembly within Sub-Assembly: Assembly4 supports importing sub-assemblies into other sub-assemblies before inserting that entire unit into the top-level model.
  • Document Tree Organization: Expand the Model tree view in the FreeCAD Combo View. You will see linked containers (App::Link). Expanding these links exposes the internal hierarchy of coordinate systems and bodies without cluttering the top-level workspace.

When modifying parts within a hierarchy:

  • Propagating Changes: If you edit a part in a sub-assembly, return to the master assembly and click Recompute assembly (or use the shortcut Ctrl+R) to refresh the links.
  • Changing Attachments: To change where a nested component attaches, right-click the component link in the tree, select Edit Placement, and pick a new target LCS from the parent.
  • Managing File Paths: Assembly4 uses FreeCAD's App::Link mechanism. Keep all related files in the same directory or a structured sub-folder structure to ensure relative file paths remain intact across different machines.