Part JoinConnect: Difference between revisions

From FreeCAD Documentation
m (→‎GuiCommand: menu item)
(Corrected Part_Fuse link.)
(21 intermediate revisions by 6 users not shown)
Line 1: Line 1:
<languages/>
<translate>
<translate>
<!--T:29-->
{{Docnav
|[[Part_CompJoinFeatures|CompJoinFeatures]]
|[[Part_JoinEmbed|JoinEmbed]]
|[[Part_Module|Part]]
|IconL=Part_JoinConnect.svg
|IconR=Part_JoinEmbed.svg
|IconC=Workbench_Part.svg
}}

<!--T:1-->
<!--T:1-->
{{GuiCommand
{{GuiCommand|Name=Part JoinConnect|MenuLocation=Part → Join → Connect objects|Workbenches=[[Part Module|Part]]|SeeAlso=[[Part_JoinConnect|Connect]], [[Part_JoinEmbed|Embed]], [[Part_JoinCutout|Cutout]], [[Part Booleans|Part Booleans]], [[Part Thickness|Part Thickness]]}}
|Name=Part JoinConnect
|MenuLocation=Part → Join → Connect objects
|Workbenches=[[Part_Module|Part]]
|Version=0.16
|SeeAlso=[[Part_JoinEmbed|Part JoinEmbed]], [[Part_JoinCutout|Part JoinCutout]], [[Part_Boolean|Part Boolean]], [[Part_Thickness|Part Thickness]]
}}

==Description== <!--T:33-->


==Description== <!--T:2-->
<!--T:2-->
Connect tool connects interiors of two walled objects (e.g., pipes).
Connect tool connects interiors of two walled objects (e.g., pipes). It can also join shells and wires.


<!--T:3-->
<!--T:3-->
[[image:JoinFeatures_Connect.png|600px]]
[[image:JoinFeatures_Connect.png|600px]]


==How to use== <!--T:4-->
==Usage== <!--T:34-->

# Select two objects to be connected. <br /> The order of selection is not important, since the action of the tool is symmetric. It is enough to select one sub-shape of each object (e.g., faces).
<!--T:4-->
# Invoke the Part JoinConnect command.
# Select objects to be connected. <br /> The order of selection is not important, since the action of the tool is symmetric. It is enough to select one sub-shape of each object (e.g., faces). You can also select a compound containing all the shapes to be connected, e.g. [[Draft Array]].
# Invoke the Part JoinConnect command using several ways:
#* Press the [[Image:Part_JoinConnect.svg|24px]] [[Part_JoinConnect]] button in the Part toolbar
#* Use the {{MenuCommand|Part → Join → Connect objects}} entry in the Part menu


<!--T:5-->
<!--T:5-->
A Part JoinFeature object is created, with Mode set to 'Connect'. Original objects are hidden, and the result of conecting is shown in 3D view.
A Connect parametric object is created. Original objects are hidden, and the result of connecting is shown in [[3D view]].

==Properties== <!--T:35-->

<!--T:6-->
{{TitleProperty|Connect}}
* {{PropertyData|Objects}}: List of objects to be connected. Generally, at least two objects are needed, but a single compound containing the shapes to connect will do as well. (as of FreeCAD v0.17.8053, this property is not displayed in [[Property editor]], and can only be accessed via [[#Scripting|Python]]).
* {{PropertyData|Refine}}: Sets whether to apply [[Part RefineShape|Refine]] operation or not, to the final shape. The default value is determined by a 'Automatically refine shape after boolean operation' checkbox in [[PartDesign Preferences]].
* {{PropertyData|Tolerance}}: "fuzziness" value. This is an extra tolerance to apply when searching for intersections, in addition to tolerances stored in the input shapes.


==Properties== <!--T:6-->
==Example== <!--T:36-->
{{TitleProperty|Base}}
* {{PropertyData|Base}}: Reference to base object (one of the objects to be connected). The object should be a single solid.
* {{PropertyData|Tool}}: Reference to tool object (the other of the objects to be connected). The object should be a single solid.
* {{PropertyData|Mode}}: The mode of operation, equals 'Connect' (Changing that will transform the tool into another Part_JoinXXX). The value of 'bypass' can be used to temporarily disable the long computations (a compound of Base and Tool will be created, which is a fast operation).
* {{PropertyData|Refine}}: Sets whether to apply [[Part RefineShape|Refine]] operation or not, to the final shape. The default value is determined by a 'Automatically refine shape after boolean operation' checkbox in PartDesign preferences. When Mode property is 'bypass', Refine is ignored (never applied).


==Example== <!--T:7-->
<!--T:7-->
# Create a pipe by applying [[Part_Thickness|thickness]] to a [[Part_Cylinder|cylinder]]: <br />[[image:JoinFeatures_Example_step1.png|320px]]
# Create a pipe by applying [[Part_Thickness|thickness]] to a [[Part_Cylinder|cylinder]]: <br />[[image:JoinFeatures_Example_step1.png|320px]]
# Create another, smaller diameter pipe, and [[Placement|place]] it so that it pierces the wall of the first pipe: <br />[[image:JoinFeatures_Example_step2.png|320px]]
# Create another, smaller diameter pipe, and [[Placement|place]] it so that it pierces the wall of the first pipe: <br />[[image:JoinFeatures_Example_step2.png|320px]]
# Select the first pipe and the second pipe, and click the 'Connect objects' option from the Join tools dropdown toolbar button. <br />[[image:JoinFeatures_Example_step3_Connect.png|320px]]
# Select the first pipe and the second pipe, and click the 'Connect objects' option from the Join tools dropdown toolbar button. <br />[[image:JoinFeatures_Example_step3_Connect.png|320px]]
# Use some cross-section tool ([[Std_ClippingPlane|Clipping plane]], [[Arch_SectionPlane|Arch Section Plane]], [[Arch_CutPlane|Arch Cut Plane]]) to reveal internals. On the picture below, Arch Section Plane is used.<br />[[image:JoinFeatures_Example_step4_Connect.png|320px]]
# Use some cross-section tool ([[Std_ToggleClipPlane|Clipping plane]], [[Arch_SectionPlane|Arch Section Plane]], [[Arch_CutPlane|Arch Cut Plane]]) to reveal internals. In the picture below, Arch Section Plane is used.<br />[[image:JoinFeatures_Example_step4_Connect.png|320px]]


==Algorithm== <!--T:8-->
==Algorithm== <!--T:8-->
The algorithms behind Join tools are quite simple, and understanding them is important to use the tools correctly. The algorithm of Connect, in particular, is quite a bit more complex than others, but it's generally enough to think of it as a symmetric variant of [[Part_JoinEmbed#Algorithm|Embed algorithm]]
The algorithms behind Join tools are quite simple, and understanding them is important to use the tools correctly. The algorithm of Connect, in particular, is quite a bit more complex than others, but it's generally enough to think of it as a symmetric variant of [[Part_JoinEmbed#Algorithm|Embed algorithm]]


<!--T:9-->
<!--T:23-->
1. Each object is split into pieces by intersections with other objects. (see [[Part BooleanFragments]])
1. Base object is [[Part Cut|boolean-cut]] with Tool object. The resulting shape is a set ([[Part MakeCompound|compound]]) of non-intersecting solids (typically, two).


<!--T:10-->
<!--T:24-->
2. The resulting compound is filtered: only the largest solid is kept.
2. From the pieces of an object, only the largest one is kept; all the rest are thrown away.


<!--T:11-->
<!--T:25-->
3. Intersection pieces that touch at least two objects are added to result. Then, the pieces are joined together to form the result of Connect.
3. Tool object is boolean-cut with Base object.


<!--T:12-->
===Notes=== <!--T:37-->
4. The resulting compound is filtered: only the largest solid is kept.


<!--T:13-->
<!--T:16-->
* If at step 1 each object remains in one piece, the result of Connect will be equivalent to [[Part_Fuse|union]] of Objects.
5. [[Part_Common|Boolean-common]] is computed between Base and Tool
* Now, all compounds supplied are exploded prior to connecting. This means that self-intersecting compounds, which are invalid for all other Boolean operations, are valid for Connect. (This may be changed in the future.)

* The "largest" piece is the one that has largest mass. That is, for solids, volumes are compared; for shells and faces, areas are compared, and so on.
<!--T:14-->
* Since FreeCAD v0.17.8053, and if OCC version is 6.9.0 and above, Connect is almost as fast as all other Boolean operations. For older versions, Connect is approximately 5 times slower than a regular Boolean operation, and works only on solids.
6. Results of 2, 4 and 5 are fused together.

<!--T:15-->
7. If Refine property is true, the resulting shape is [[Part RefineShape|refined]].
<br /><br />[[image:JoinFeatures-Algo-Connect.png|800px]]

===Notes=== <!--T:16-->
* If at steps 1 and 3, the objects remains in one piece, the result of Connect will be equivalent to [[Part Fuse|fusion]] of Base and Tool, but taking much longer to compute.
* Now, the tool will produce unexpected result, if a compounds are supplied. This may be changed in the future.
* Because the largest piece is determined by comparing volumes of pieces, the tool can only work with solids. This may be changed in the future.
* As of now, Connect does 5 boolean operations in a row, which makes it about 5 times slower than a regular boolean operation.


==Scripting== <!--T:17-->
==Scripting== <!--T:17-->
Line 65: Line 80:
The Join tools can by used in [[macros]] and from the python console by using the following function:
The Join tools can by used in [[macros]] and from the python console by using the following function:
</translate>
</translate>
'''JoinFeatures.makePartJoinFeature(name = 'Connect', mode = 'Connect')'''
'''BOPTools.JoinFeatures.makeConnect(name)'''
<translate>
<translate>
<!--T:19-->
<!--T:19-->
* Creates an empty Connect feature (or other Join feature, depending on mode passed). The properties Base and Tool must be assigned explicitly, afterwards.
* Creates an empty Connect feature. The 'Objects' property must be assigned explicitly, afterwards.
* Returns the newly created object.
* Returns the newly created object.

<!--T:26-->
Connect can also be applied to plain shapes, without the need to have a document object, via:
</translate>
'''Part.BOPTools.JoinAPI.connect(list_of_shapes, tolerance = 0.0)'''
<translate>
<!--T:27-->
This can be useful for making custom Python scripted features.


<!--T:20-->
<!--T:20-->
Line 75: Line 98:
</translate>
</translate>
{{code|code=
{{code|code=
import JoinFeatures
import Part
j = JoinFeatures.makePartJoinFeature(name = 'Connect', mode = 'Connect' )
j = Part.BOPTools.JoinFeatures.makeConnect(name= 'Connect')
j.Base = FreeCADGui.Selection.getSelection()[0]
j.Objects = FreeCADGui.Selection.getSelection()
j.Tool = FreeCADGui.Selection.getSelection()[1]
}}
}}
<translate>
<translate>
<!--T:21-->
<!--T:21-->
The tool itself is implemented in Python, see /Mod/Part/JoinFeatures.py under where FreeCAD is installed.
The tool itself is implemented in Python, see {{FileName|/Mod/Part/BOPTools/JoinFeatures.py}} ([https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/BOPTools/JoinFeatures.py Github link]) under where FreeCAD is installed.


==Version== <!--T:22-->
==History== <!--T:22-->
The tool was introduced in FreeCAD v0.16.5069
* The tool was introduced in FreeCAD v0.16.5069

<!--T:28-->
* The tool was re-implemented to work via generalFuse in FreeCAD v0.17.8053


<!--T:30-->
{{Docnav
|[[Part_CompJoinFeatures|CompJoinFeatures]]
|[[Part_JoinEmbed|JoinEmbed]]
|[[Part_Module|Part]]
|IconL=Part_JoinConnect.svg
|IconR=Part_JoinEmbed.svg
|IconC=Workbench_Part.svg
}}


</translate>
</translate>
{{Part Tools navi{{#translation:}}}}
{{Userdocnavi{{#translation:}}}}
{{clear}}
{{clear}}
<languages/>

Revision as of 20:22, 8 December 2020

Part JoinConnect

Menu location
Part → Join → Connect objects
Workbenches
Part
Default shortcut
None
Introduced in version
0.16
See also
Part JoinEmbed, Part JoinCutout, Part Boolean, Part Thickness

Description

Connect tool connects interiors of two walled objects (e.g., pipes). It can also join shells and wires.

Usage

  1. Select objects to be connected.
    The order of selection is not important, since the action of the tool is symmetric. It is enough to select one sub-shape of each object (e.g., faces). You can also select a compound containing all the shapes to be connected, e.g. Draft Array.
  2. Invoke the Part JoinConnect command using several ways:
    • Press the Part_JoinConnect button in the Part toolbar
    • Use the Part → Join → Connect objects entry in the Part menu

A Connect parametric object is created. Original objects are hidden, and the result of connecting is shown in 3D view.

Properties

Connect

  • DataObjects: List of objects to be connected. Generally, at least two objects are needed, but a single compound containing the shapes to connect will do as well. (as of FreeCAD v0.17.8053, this property is not displayed in Property editor, and can only be accessed via Python).
  • DataRefine: Sets whether to apply Refine operation or not, to the final shape. The default value is determined by a 'Automatically refine shape after boolean operation' checkbox in PartDesign Preferences.
  • DataTolerance: "fuzziness" value. This is an extra tolerance to apply when searching for intersections, in addition to tolerances stored in the input shapes.

Example

  1. Create a pipe by applying thickness to a cylinder:
  2. Create another, smaller diameter pipe, and place it so that it pierces the wall of the first pipe:
  3. Select the first pipe and the second pipe, and click the 'Connect objects' option from the Join tools dropdown toolbar button.
  4. Use some cross-section tool (Clipping plane, Arch Section Plane, Arch Cut Plane) to reveal internals. In the picture below, Arch Section Plane is used.

Algorithm

The algorithms behind Join tools are quite simple, and understanding them is important to use the tools correctly. The algorithm of Connect, in particular, is quite a bit more complex than others, but it's generally enough to think of it as a symmetric variant of Embed algorithm

1. Each object is split into pieces by intersections with other objects. (see Part BooleanFragments)

2. From the pieces of an object, only the largest one is kept; all the rest are thrown away.

3. Intersection pieces that touch at least two objects are added to result. Then, the pieces are joined together to form the result of Connect.

Notes

  • If at step 1 each object remains in one piece, the result of Connect will be equivalent to union of Objects.
  • Now, all compounds supplied are exploded prior to connecting. This means that self-intersecting compounds, which are invalid for all other Boolean operations, are valid for Connect. (This may be changed in the future.)
  • The "largest" piece is the one that has largest mass. That is, for solids, volumes are compared; for shells and faces, areas are compared, and so on.
  • Since FreeCAD v0.17.8053, and if OCC version is 6.9.0 and above, Connect is almost as fast as all other Boolean operations. For older versions, Connect is approximately 5 times slower than a regular Boolean operation, and works only on solids.

Scripting

The Join tools can by used in macros and from the python console by using the following function:

BOPTools.JoinFeatures.makeConnect(name)
  • Creates an empty Connect feature. The 'Objects' property must be assigned explicitly, afterwards.
  • Returns the newly created object.

Connect can also be applied to plain shapes, without the need to have a document object, via:

Part.BOPTools.JoinAPI.connect(list_of_shapes, tolerance = 0.0)

This can be useful for making custom Python scripted features.

Example:

import Part
j = Part.BOPTools.JoinFeatures.makeConnect(name= 'Connect')
j.Objects = FreeCADGui.Selection.getSelection()

The tool itself is implemented in Python, see /Mod/Part/BOPTools/JoinFeatures.py (Github link) under where FreeCAD is installed.

History

  • The tool was introduced in FreeCAD v0.16.5069
  • The tool was re-implemented to work via generalFuse in FreeCAD v0.17.8053