Assembly3 Workbench

Other languages:
Assembly3 workbench icon

Introduction

Assembly3 is an external workbench that is used to perform assembly of different bodies contained in a single file or in multiple documents. The workbench is based on several core function changes done for the version of FreeCAD 0.19 (e.g. App Link), so the Assembly3 Workbench can not be used with earlier versions.

The main features of the Assembly3 Workbench are

top

Toolbars

As of 2020 the Assembly3 workbench features the following toolbars.

Main Toolbar

The Main Toolbar contains tools that cover the most often used features of the workbench. The tooltips will give the keyboard short cuts.
  • Create assembly: Add an assembly folder
  • Group objects: Group objects
  • Create element: Create element.
  • Import from STEP. This has two settings
  • Resolve constraints: Resolve constraints
  • Quick solve: Quick resolve constraints
  • Move part: Move parts in 3D, this is specific to Assembly3
  • Axial move: Axial move parts in 3D, this is the classical tool available elsewhere in FreeCAD
  • Quick move: This will attach the part selected in the tree to the mouse cursor. It will change the position of the part when you click.
    Often added parts are stacked upon each other in the origin. Use this function to grab a part you can not see.
  • Lock mover: Lock mover for fixed part. Toggle Button. When this is un-selected you can move the parts that have a "Locked" constraint.
  • Toggle part visibility: This toggles the visiblity of the selected part on/off.
    Note that this differs from using space. Using space with selected items from a sub-assembly in the 3D view often does not behave as expected. Use this function in those cases (or shortcut A-Space)
  • Trace part move: Trace part move (TBD)
  • Auto recompute: Auto recompute. Usually enabled.
    May be un-selected when repairing constraints or fixing parts where the solver gives a "do not converge" message (e.g. by turning the part 180deg)
  • Smart recompute: Smart recompute. Usually enabled.
  • Auto fix element: Element Auto Fixing. Experimental feature in 0.19_pre
  • Element Style. This has two settings
  • Workplane and origin. Adds a workplane, placement or origin. A part must be selected. This has five settings
  • Move item up: Move selected tree item up
  • Move item down: Move selected tree item down
    Allows to sort Parts, Elements or Constraints in the tree. Element roll over (top to bottom and vice versa). Only works for a single selection.
  • Multiply constraint: Multiply Constraint. This can be selected if multiple parts and suitable Elements are present.
    It is used e.g. to assign multiple fasteners of the same type into multiple holes with one constraint.

Main Constraints Toolbar

Some tools are actually a menu for more tools.
  • Locked: Add a "Locked" constraint to fix one or more parts.
    You must select a geometry element of the part.
    If you fix a vertex or an edge the part is still free to rotate around the vertex or edge.
    Fixing a face will completely lock the part.
  • Plane Alignment: Add a "Plane alignment" constraint to align planar faces of two or more parts.
    The faces become coplanar or parallel with an optional distance.
  • Plane Coincidence: Add a "Plane coincidence" constraint to coincide planar faces of two or more parts.
    The faces are coincided at their centers with an optional distance.
  • Attachment. This has two settings
    • Attachment: Add an "Attachment" constraint to attach two parts with the selected geometry elements.
      This constraint completely fixes the parts relative to each other.
    • AttachmentOffset: Same as "Attachment" constraint, but maintaining the current relative placement of the involved parts by applying an element offset.
      This constraint completely fixes the parts relative to each other.
  • Axial Alignment: Add an "Axial alignment" constraint to align edges/faces of two or more parts.
    The constraint accepts
    linear edges, which become collinear,
    planar faces, which are aligned using their surface normal axis,
    and cylindrical face, which are aligned using the axial direction.
    Different types of geometry elements can be mixed.
  • Same orientation: Add a "Same orientation" constraint to align faces of two or more parts.
    The planes are aligned to have the same orientation (i.e. rotation)
  • Multi parallel: Add a "Multi parallel" constraint to make planar faces or linear edges of two or more parts parallel.
  • Angle: Add an "Angle" constraint to set the angle of planar faces or linear edges of two parts.
  • Perpendicular: Add a "Perpendicular" constraint to make planar faces or linear edges of two parts perpendicular.
  • Points coincident: Add a "Point coincident" constraint to coincide two points in 2D or 3D.
  • Point on plane: Add a "Point on plane" to constrain one or more point onto a plane.
  • Point on line: Add a "Point on line" to constrain a point onto a line in 2D or 3D.
  • Point on circle: Add a "Point on circle" to constrain one or more points on to a clyndrical surface defined by a cricle.
    Note that you must select a point (any geometry element can define a point), and then select the circle (or clyndrical surface),
    after which you can add more points to your selection if you want.
  • Points distance: Add a "Points distance" to constrain the distance of two or more points.
  • Point plane distance: Add a "Point plane distance" to constrain the distance between one or more points and a plane.
  • Point line distance: Add a "Point line distance" to constrain the distance between a point and a linear edge in 2D or 3D.
  • Symmetric: Add a "Symmetric" constraint to make geometry elements of two parts symmetric about a plane.
    The supported elements are linear edge and planar face.
  • More: Toggle toolbars for more constraints
    Not really a constraint but a toggle switch to show/hide the Additional Constraints Toolbars.

Additional Constraints Toolbars

(Assembly3 Constraints2)
(Assembly3 Sketch Constraints)
You can enable these by selecting the More button on the Main Constraints toolbar.
  • Point distance: Add a "Point distance" to constrain the distance of two points in 2D or 3D.
  • Equal angle: Add an "Equal angle" to equate the angles between two lines or normals.
  • Points symmetric: Add a "Points symmetric" constraint to make two points symmetric about a plane.
  • () Symmetric horizontal: Symmetric horizontal
  • () Symmetric vertical: Symmetric vertical
  • Symmetric line: Add a "Symmetric line" constraint to make two points symmetric about a line.
  • Points horizontal: Add a "Points horizontal" constraint to make two points horizontal with each other when projected onto a plane.
  • Points vertical: Add a "Points vertical" constraint to make two points vertical with each other when projected onto a plane.
  • Line horizontal:Add a "Line horizontal" constraint to make a line segment horizontal when projected onto a plane.
  • Line vertical: Add a "Line vertical" constraint to make a line segment vertical when projected onto a plane.
  • Arc line tangent: Add an "Arc line tangent" constraint to make a line tangent to an arc at the start or end point of the arc.
  • Sketch plane: Add a "Sketch plane" to define the work plane of any draft element inside or following this constraint.
    Add an empty "Sketch plane" to undefine the previous work plane.
  • Line length: Add a "Line length" constrain the length of a non-subdivided Draft.Wire.
  • Equal length: Add an "Equal length" constraint to make two lines of the same length.
  • Length ratio: Add a "Length ratio" to constrain the length ratio of two lines.
  • Length difference: Add a "Length difference" to constrain the length difference of two lines.
  • Length Equal Point Line Distance: Add a "Length Equal Point Line Distance" to constrain the distance
    between a point and a line to be the same as the length of a another line.
  • ( )Equal Line Arc Length: Add an "Equal Line Arc Length" constraint to make a line of the same length as an arc.
  • Mid point: Add a "Mid point" to constrain a point to the middle point of a line.
  • Diameter: Add a "Diameter" to constrain the diameter of a circle/arc.
  • Equal radius: Add an "Equal radius" constraint to make two circles/arcs of the same radius.
  • Points project distance: Add a "Points project distance" to constrain the distance of two points projected on a line.
  • Equal point line distance: Add an "Equal point line distance" to constrain the distance
    between a point and a line to be the same as the distance between another point and line.
  • Colinear: Add a "Colinear" constraint to make two lines collinear.
The Constraints Toolbars will be the main interface used when assembling parts.
They are greyed out by default but are activated once at least one face, line or point of a part is selected.
Generally you select the Elements that should be joined and then select the constraint type.
The different colored frames mark different characteristics of the constraints:
whether 2D/3D or if more than 2 Elements can be added.
A detailed description can be found in the GitHub wiki.

Navigation Toolbar

Theses functions are useful when working with an assembly with a hierarchy of linked external files

Measurement Toolbar

The Measurement toolbar adds functions to measure the distance or the angle between two objects
  • Measure points: Add a "Measure points" to measure the distance of two points in 2D or 3D.
  • Measure point to line: Add a "Measure point to line" to measure the distance between a point and a linear edge in 2D or 3D.
  • Measure point to plane: Add a "Measure point to plane" to measure the distance between a point and a plane.
  • Measure angle: Add a "Measure angle" to measure the angle of planar faces or linear edges of two parts.
There is no function to measure a radius or diameter.
The measurement tools survive part changes, e.g. the distance between edges of a cube when the cube is re-sized.
As the constraints the calculations are done in real time and updated upon any change. Behind the scenes, the function is very similar to the constraints. The distance or angle is calculated between Elements in the same way as for constraints. The display in the tree works in the same way.

As usual you can modify the tool bars and add or remove single tools. Be sure to check the menu Assembly3 for functions that may not be present in the tool bars.

top

Constraints

The designer uses constraints to achieve the desired result for the relation of two parts. The art is the selection of the right constraints best suited to deal with each problem. Each eliminated DOF should in theory only be eliminated once between two objects, but in practice with many CAD tools selected constraints cause over-constrained combinations, often compensated by complex algorithms, sometimes not. Assembly3 does use algorithms to detect and compensate over-constraints, but clearly they are not very matured yet. So in practice for Assembly3 constraints avoid trouble by being aware of how many degrees of freedom (DOF) have been used and which ones are still to be locked down by constraints. No part should have a connection by constraints using more than 6 DOF.

Note: If the solver meets a combination that can not be solved, it will give an error. It is very difficult for the solver to find out what caused the problem, so typically from this error given it will not be clear where the problem is. In larger assemblies this can lead to complex problem searches. Unfortunately there is no easy way to avoid this. However, it helps to be fully aware how the system works (.e.g see Elements below), use clear names for all components involved and only ever add additional constraints when the solver solves the current assembly. Very helpful to track down a problem is the "ContexMenu/Deactivate" function of each constraint.

Assembly3 Constraints define restrictions in the position or orientation between two Elements. Some constraints even work with more than two Elements. An Elements can be a face, a line or edge or a point of a part. Generally constraints are defined by selecting the desired Elements and then select the constraint from the Constraints toolbar.

Other

: Note: In the following list Tx,Ty,Tz and Rx,Ry,Rz are used to describe translations and rotations about the reference coordinate systems of the involved Element's. This is not always exact or fully defined, e.g. when a line is involved it is not defined if it runs in X, Y or any angle in betweeen. The system is used for bevity and easy comparison in favour of a correct but more complex definition. So Z is generally the normal direction of any faces involved. Please feel free to modify this with a better approach with improved readability.

top

Elements

Elements is a specific term used in the Assembly3 workbench and it is important to understand Elements for understanding how Assembly3 should be used.

It is helpul to think of an Element as a general word for a 'selectable item' of a part, i.e. a face, an edge, a circle or a corner or other point. The items you select to constrain them, are those Elements. In the tree an Assembly folder has three sub-folders. Beside 'Parts' and 'Constraints' there is a folder named 'Elements', which is emtpy as long as there are no constraints added. When adding a constraint the constraint itself gets two (or more) leafs, these are the selected 'Elements'. Also these get added in the 'Elements' folder which is just a list of all Elements used in the assembly. Its a good idea to change their names (with F2 key), especially in bigger assemblies.

Let's look at an example

Create a new file and add from the Part workbench a cube and a cylinder. We will stack the cylinder onto the cube. First we fix the base part, in out case the cube. Select the bottom face of the cube and select the "Locked" constraints (first icon in the Constraints toolbar). Select the top face of the cylinder and the top face of the cube. Then select the "Plane Coincident" constraint. Now the cylinder is moved into the cube and in the tree a new leaf with two childe nodes was added under 'Constraints'. Additionally the same two child nodes were added under 'Elements'. If your cylinder is inside the cube instead of on top of the cube, let's correct that first: select the child node under 'Constraints' that shows the cylinder face and with a right click in the context menu select 'Flip Part'. Now the cylinder is stacked onto the box.

The key thing to understand is that the constraint operates on links to Elements in the list in the 'Elements' tree folder. This allows keeping the constraint structure intact while changing the parts. This is very difficult to see without an example.

Let's get back to the example above

Note: make sure you added the "Locked" constraint to the cube or this will look confusing
In the CAD window select another face of the cube. Now we will only work in the tree view. Use your mouse in the tree view; make sure the cube is selected. Drag&Drop the cube to the 'Elements' folder. Drop it on the 'Elements' name, not anywhere else in the folder - we will see why later. You should see that another Element is added to the 'ELements' list. Now select in the 'Constraints' folder the child node of the cube face in the "Plane Coincident" constraint and delete it. The Constraint will show an exclamation mark since it is missing one Element. Note that by deleting the Element in the Constraint we did not delete it in the list. That is because in the constraint it was only a link to the Element in the list. Now take the newly added Element in the 'Elements' list and drag&drop it onto the "Plane Coincident" constraint. Now the cylider moves to the other face we selected. We might need to select 'context menu/flip part' again if the cylinder is again inside the cube.

The example showed that without removing the constraint we can change the Elements that are used for the constraint. In the same way we can move the cylinder to a totally different part. After playing around with this example a bit more, you will note some additional things such as:

top

Compatibility

Assembly3 was inspired by Assembly2, but it is not compatible with it. If you have older models made in Assembly2, you should stay with FreeCAD 0.16 and use Assembly2 there.

New models developed with Assembly3 should only be opened and edited with this workbench.

Although they may have similar tools, Assembly3 is not compatible with A2plus nor Assembly4. Models created with these workbenches should be opened only with their respective workbench.

top

Installation

The Assembly3 Workbench is available (as of March 2022) through the Addon Manager. Any Assembly3 3rd party dependencies should be managed automatically through the Addon Manager.

Alternate installations

There are 2 alternate ways to install Assembly3:

Since the AppImage only works for Linux, for Windows users (who want an alternate install of Assembly3) option to test Assembly3 is the first option (realthunder's fork).

top

HowTo

Get Started

There are many ways to create an assembly with Assembly3. Here is the most simple one you can do.

Final Result of the Getting Started Example. In the image the Assembly3 Workbench is selected, so its multiple toolbars are visible. Note that the vertical "TabBar" left of the tree view is an AddOn Workbench that is not contained in standard FreeCAD (but can be installed with the Addon-Manager).

The tree view should look like this (0.20.pre and Link Branch):

Now the parts should be joined into each other and your tree should look like this (0.20.pre and Link Branch):

Now the Cylinder should be on top of the Cube. If the whole thing is upside down, go back and select Flip Part on the other element.

We omitted one important step that should be done in larger assemblies: Locking a base part.
That means to define one part that should not be moved by constraints. In this example we use the Cube for that:

Done.

The finished assembly tree should look like (0.20.pre and Link Branch):

:

If you like you can move the Locked constraint upwards in the tree. Use the Move item up button on the Main toolbar for that.

Note: all new external files must be saved, closed and re-opened at least once, so that Assembly3 can find it.

Without doing that FreeCAD can not give a file handle to the Assembly3 Workbench and it can not find the new part.
When all parts are in the same file, you should save, close and re-open this file, too.

top

Add an Offset

Assembly3 does not offer Offset with the constaints in the way the A2plus Workbench or other CAD tools do. Instead it offers a more general and flexible system to add offsets translations but also angles.

Example:

  • Test with other axes or the angle/axis fields. Also verify that you get the same result when using the other Element.

This is the same approach for all other constraints.

top

Solve a Solver Failure

This often happens when parts are over-constrained, i.e. more than 6 DOF are locked.

The easiest way to find the problem is to click relevant constraints in the tree and select ContextMenu/Disable and re-calculate. It is helpful to know the last added constraints before the solver failed and just undo them.

Note: as Assembly3 tries to compensate for over-constraint parts behind the scenes, sometimes the problem is just triggered by a new constraint but the root cause is somewhere different. Before deleting all and starting again, remember that you can re-use Elements. If you named them you can identify the required elements and re-build the constraints without using the 3D view at all. See Elements seciton above.

top

Replace a part or rename a filename

When a part is removed or when a filename changes, the assembly breaks, it can not longer be solved and the solver will issue the message "Inconsistent constraints". The solver marks invalid Elements and Constrains with a question mark in the tree.

One way to solve this is to just delete all invalid constraints and elements, import the new part and redo everything. But there is a better way:

Notes

top

Tips & Tricks

top

Links


User documentation