Std Part: Difference between revisions

From FreeCAD Documentation
m (Changed "most if not any" to "most, if not all,".)
(New caption for a new image "Document with two Std Parts, of which the second one is active.")
(18 intermediate revisions by 2 users not shown)
Line 23: Line 23:


<!--T:3-->
<!--T:3-->
'''Part''' is a general purpose container that keeps together a group of objects so that they can be moved as a unit. Part can contain most, if not all, FreeCAD objects such as PartDesign Bodies, Part workbench objects, Mesh objects, etc.
[[Std_Part|Std Part]] (internally called [[App_Part|App Part]]) is a general purpose container that keeps together a group of objects so that they can be moved together as a unit in the [[3D_view|3D view]].


<!--T:4-->
<!--T:4-->
The Std Part element was developed to be the basic building block to create mechanical assemblies. In particular, it is meant to arrange objects that have a [[Part_TopoShape|Part TopoShape]], like [[Part_Primitives|Part Primitives]], [[PartDesign_Body|PartDesign Bodies]], and other [[Part_Feature|Part Features]]. The Std Part provides an [[App_Origin|Origin object]] with local X, Y, and Z axes, and standard planes; this Origin is used as reference to position and attach those other objects. In addition, Std Parts may be nested inside other Std Parts to create a full assembly from smaller sub-assemblies.
Part provides a local coordinate system to which sketches and other objects can be attached.

<!--T:54-->
Although it is primarily intended for solid bodies, the Std Part can be used to manage any object that has a [[Placement|Placement]] property, so it can also contain [[Mesh_Feature|Mesh Features]], [[Sketch|sketches]], and other objects derived from [[App_GeoFeature|App GeoFeature]].


<!--T:5-->
<!--T:5-->
Part is found in the Structure toolbar that is displayed in all workbenches.
The Std Part tool is not defined by a particular workbench, but by the base system, thus it is found in the {{MenuCommand|structure toolbar}} that is available in all [[Workbenches|workbenches]].


</translate>
</translate>
[[File:Std Part-tree.png|top]][[File:Std Part example.png]]
[[File:Std Part-tree.png]][[File:Std Part example.png]]
<translate>
<translate>


<!--T:21-->
<!--T:21-->
{{Caption|Left: elements inside a Std Part in the [[tree_view|tree view]]. Right: objects positioned in space, referred to the Origin of the Std Part.}}
{{Caption|Local coordinate system defined by a Part}}


===Example uses=== <!--T:7-->
==How to use== <!--T:11-->

* As an assembly container that groups objects to be manufactured separately then glued or screwed together, like a wooden table.
<!--T:12-->
* When importing a STEP assembly in FreeCAD, the main assembly and its sub-assemblies are Part containers.
# Press the {{Button|[[File:Std_Part.svg|16px]] [[Std_Part|Std Part]]}} button. An empty Part is created and automatically becomes ''[[Std_Part#Active_status|active]]''.
* A part that is composed of multiple non-fused components, like a ball bearing.
# To add objects to a Part, select them in [[tree_view|tree view]], and then drag and drop them over the Part.
# To remove objects from a Part, drag them out of the Part, and onto the document label at the top of the [[tree_view|tree view]].

=== Notes === <!--T:55-->

<!--T:56-->
* As of v0.19, a given object can only belong to a single Part.
* Double-click the Part in the [[tree view|tree view]] or open the context menu (right-click) and select {{MenuCommand|Toggle active part}} to activate or deactivate the Part. If another Part is active, it will be deactivated. See [[Std_Part#Active_status|active status]] for more information.

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

<!--T:57-->
A [[Std_Part|Std Part]] is internally called [[App_Part|App Part]] ({{incode|App::Part}} class), and is derived from an [[App_GeoFeature|App GeoFeature]] ({{incode|App::GeoFeature}} class), therefore it shares most of the latter's properties.

<!--T:58-->
In addition to the properties described in [[App_GeoFeature|App GeoFeature]], the App Part class has some properties that help it manage information in the context of an assembly, for example, {{PropertyData|Type}}, {{PropertyData|Id}}, {{PropertyData|License}}, {{PropertyData|LicenseURL}}, {{PropertyData|Color}}, and {{PropertyData|Group}}.

<!--T:59-->
These are the properties available in the [[property editor|property editor]]. Hidden properties can be shown by using the {{MenuCommand|Show all}} command in the context menu of the [[property editor|property editor]].

=== Data === <!--T:60-->

<!--T:61-->
{{TitleProperty|Base}}

<!--T:14-->
* {{PropertyData|Type|String}}: a description for this object. By default, it is an empty string {{value|""}}.
* {{PropertyData|Id|String}}: an identification or part number for this object. By default, it is an empty string {{value|""}}.
* {{PropertyData|License|String}}: a field to specify the license for this object. By default, it is an empty string {{value|""}}.
* {{PropertyData|LicenseURL|String}}: a field to specify the web address to the license or contract for this object. By default, it is an empty string {{value|""}}.
* {{PropertyData|Color|Color}}: a tuple of four floating point RGBA values {{value|(r,g,b,a)}} to define the color of the object; by default it is {{value|(1.0, 1.0, 1.0, 1.0)}}, which is displayed as {{value|[255,255,255]}} on base 255, <span style="background-color:#fff; color:#000; border: 1px solid #888888; width:3em; height:12pt; padding: 2px 1em 2px;">white color</span>.
* {{PropertyData|Placement|Placement}}: the position of the object in the [[3D view|3D view]]. The placement is defined by a {{incode|Base}} point (vector), and a {{incode|Rotation}} (axis and angle). See [[Placement|Placement]].
** {{PropertyData|Angle}}: the angle of rotation around the {{PropertyData|Axis}}. By default, it is {{value|0°}} (zero degrees).
** {{PropertyData|Axis}}: the unit vector that defines the axis of rotation for the placement. Each component is a floating point value between {{value|0}} and {{value|1}}. If any value is above {{value|1}}, the vector is normalized so that the magnitude of the vector is {{value|1}}. By default, it is the positive Z axis, {{value|(0, 0, 1)}}.
** {{PropertyData|Position}}: a vector with the 3D coordinates of the base point. By default, it is the origin {{value|(0, 0, 0)}}.
* {{PropertyData|Label|String}}: the user editable name of this object, it is an arbitrary UTF8 string.
* {{PropertyData|Group|LinkList}}: a list of referenced objects. By default, it is empty {{value|[]}}.

==== Hidden properties Data ==== <!--T:62-->

<!--T:63-->
* {{PropertyData|Material|Map}}: map with material properties. By default, it is empty <code>{}</code>.
* {{PropertyData|Meta|Map}}: map with additional meta information. By default, it is empty <code>{}</code>.
* {{PropertyData|Uid|UUID}}: the [https://en.wikipedia.org/wiki/Universally_unique_identifier universally unique identifier] (UUID) (128-bit number) of the object. This is assigned at creation time.
* {{PropertyData|Label2|String}}: a longer, user editable description of this object, it is an arbitrary UTF8 string that may include newlines. By default, it is an empty string {{value|""}}.
* {{PropertyData|Expression Engine|ExpressionEngine}}: a list of expressions. By default, it is empty {{value|[]}}.
* {{PropertyData|Visibility|Bool}}: whether to display the object or not.
* {{PropertyData|Origin|Link}}: the [[App_Origin|App Origin]] object that is the positional reference for all elements listed in {{PropertyData|Group}}.
* {{PropertyData|_ Group Touched|Bool}}: whether the group is touched or not.

=== View === <!--T:64-->

<!--T:65-->
The App Part only has five of the properties of the basic [[App_GeoFeature|App GeoFeature]], and it does not have hidden properties.

<!--T:66-->
{{TitleProperty|Base}}

<!--T:67-->
* {{PropertyView|Display Mode|Enumeration}}: {{value|Group}}.
* {{PropertyView|On Top When Selected|Enumeration}}: {{value|Disabled}} (default), {{value|Enabled}}, {{value|Object}}, {{value|Element}}.
* {{PropertyView|Selection Style|Enumeration}}: {{value|Shape}} (default), {{value|BoundBox}}. If the option is {{value|Shape}}, the entire shape (vertices, edges, and faces) will be highlighted in the [[3D view|3D view]]; if it is {{value|BoundBox}} only the bounding box will be highlighted.
* {{PropertyView|Show In Tree|Bool}}: if it is {{TRUE}}, the object appears in the [[tree view|tree view]]. Otherwise, it is set as invisible.
* {{PropertyView|Visibility|Bool}}: if it is {{TRUE}}, the object appears in the [[3D view|3D view]]; otherwise it is invisible. By default this property can be toggled on and off by pressing the {{KEY|Space}} bar in the keyboard.

== Assembly concept == <!--T:7-->

<!--T:68-->
The Std Part is intended to be the basic building block to create assemblies. Unlike a [[PartDesign_Body|PartDesign Body]], an assembly is meant to be a collection of separate, distinguishable elements which are connected in some way in the physical world, for example, through pressure, screws, or glue.

<!--T:69-->
Examples that could be Parts:
* A wooden table that consists of individual wooden pieces (legs, top), which are put together by glue or metal screws.
* A ball bearing that is composed of multiple steel balls, an inner ring, a retainer, a seal, and an outer ring.
* An assembly of a screw with a washer, and a matching nut.


===Active Status=== <!--T:8-->
A FreeCAD document can contain multiple Parts. Only one Part can be active at a time. An active Part will be displayed in the tree with a light blue background color.
</translate>
</translate>
[[File:PartDesign_Body_contiguous_separate.png|x200px]] [[File:PartDesign_Body_contiguous_assembly.png|x200px]]
[[File:Std Part-tree-active.png|none]]
<translate>
<translate>
===Origin=== <!--T:9-->
<!--T:53-->
{{Caption|Left: three individual contiguous solids, each of them modelled by a [[PartDesign_Body|PartDesign Body]]. Right: the individual Bodies put together inside a Std Part to create an assembly.}}
The Origin consists of the three standard axes (X, Y, Z) and three standard planes (XY, XZ and YZ). Sketches can be attached to these planes. All elements inside the Part are referenced to the Part's Origin; which means that the Part can be moved and rotated in reference to the global coordinate system without affecting the placement of elements inside it.

In general terms, when importing a STEP file into the program, the main assembly and its sub-assemblies will be imported as Part containers, each of them containing a simple [[Part_Feature|Part Feature]].

== Detailed explanation == <!--T:70-->

===Active status=== <!--T:8-->

<!--T:71-->
An open document can contain multiple Parts. An active Part will be displayed in the [[tree view|tree view]] with the background color specified by the {{MenuCommand|Active container}} value in the [[Preferences_Editor#Colors|preferences editor]] (by default, light blue). An active part will also be shown in bold text.

To activate or de-activate a Part:
* Double click on it on the [[tree view|tree view]], or
* Open the context menu (right click) and select {{MenuCommand|Toggle active part}}.

<!--T:72-->
{{Emphasis|Notes:}}
* The {{emphasis|active status}} of Parts was developed in v0.17 in parallel with the {{emphasis|active status}} of [[PartDesign_Body|PartDesign Bodies]]; however, as of v0.19 this status does not serve a real purpose for Parts.
* Even when a Part is active, newly created objects are not placed inside of it automatically. In this case, simply drag these new objects, and drop them onto the desired Part.
* Only a single Part can be active at a time.

</translate>
</translate>
[[File:PartDesign_Body_tree-02.png|none]]
[[File:Std Part-tree-active.png]]
<translate>
<translate>
===Visibility Management=== <!--T:10-->
The Part's visibility supersedes the visibility of any object it contains. If the Part is hidden, the objects it contains will be hidden as well, even if their visibility is set to true. Multiple objects inside a Part can be visible at a time.


{{Caption|Document with two Std Parts, of which the second one is active.}}
==How to use== <!--T:11-->


<!--T:12-->
===Origin=== <!--T:9-->
* Press the {{KEY|[[Image:Std Part.png|24px]] '''Create part'''}} button in the toolbar. The Part automatically becomes active.
* Double-click the Part in the Model tree to activate or deactivate it.
* To add objects to a Part, drag & drop them over the Part in the Model tree.
* To remove objects from a Part, drag & drop them out of the Part and on the document label at the top of the Model tree.


==Properties== <!--T:13-->
<!--T:74-->
The Origin consists of the three standard axes (X, Y, Z) and three standard planes (XY, XZ and YZ). Sketches can be attached to these planes. All elements inside the Part are referenced to the Part's Origin; which means that the Part can be moved and rotated in reference to the global coordinate system without affecting the placement of elements inside it.


</translate>
<!--T:14-->
[[File:PartDesign_Body_tree-02.png]]
* {{PropertyData|Id}}: ID (Part number) of the item. This field is optional.
<translate>
* {{PropertyData|License}}: the license under which the part is released.

* {{PropertyData|License URL}}: the Web address where the terms license can be found.
===Visibility Management=== <!--T:10-->
* {{PropertyData|Placement}}: specifies the orientation and position of the Part in the 3D space. See [[Placement|Placement]].

* {{PropertyData|Label}}: the Label is the name given to the operation. This name can be changed at your convenience.
<!--T:75-->
* {{PropertyData|Group}}: lists the referenced objects.
The Part's visibility supersedes the visibility of any object it contains. If the Part is hidden, the objects it contains will be hidden as well, even if their visibility is set to true. Multiple objects inside a Part can be visible at a time.


==Limitations== <!--T:15-->
===Limitations=== <!--T:15-->


<!--T:16-->
<!--T:16-->
* At this time, [[Draft Snap|Draft Snaps]] do not work on selected Part containers or on the objects inside of it.
* Even when a Part is active, newly created objects are not placed inside the Part, but at the bottom of the tree. Simply drag and drop them over the Part.
* A Part has no shape. It is therefore not possible to apply most 3D operations on a Part, such as Part Booleans.
* A Part has no [[Part_TopoShape|topological shape]], therefore, it is not possible to apply most 3D operations such as [[Part_Booleans|Part Booleans]] on a Part itself, only on its contained objects.
* At this time, [[Draft Snap|Draft Snaps]] do not work on selected Part containers or on objects inside a Part container.
* ''Redactor's note: at this time, it is unclear whether the Part's active status serves a purpose.''


== Inheritance == <!--T:22-->
=== Inheritance === <!--T:22-->


<!--T:23-->
<!--T:23-->
Line 91: Line 181:


<!--T:25-->
<!--T:25-->
{{Caption|Simplified diagram of the relationships between the core objects in the program. The {{incode|App::Part}} class is a simple group that has a position in 3D space, and controls the placement of other objects it contains.}}
{{Caption|Simplified diagram of the relationships between the core objects in the program. The {{incode|App::Part}} class is a simple container that has a position in 3D space, and has an Origin to control the placement of the objects grouped under it.}}


== Scripting == <!--T:26-->
== Scripting == <!--T:26-->


<!--T:27-->
<!--T:76-->
{{Emphasis|See also:}} [[FreeCAD Scripting Basics|FreeCAD Scripting Basics]], and [[scripted objects|scripted objects]].
Following command adds new group to the active document:


<!--T:77-->
See [[Part_Feature|Part Feature]] for the general information on adding objects to the program.

<!--T:27-->
A Std Part ([[App_Part|App Part]]) is created with the {{incode|addObject()}} method of the document. Once a Part exists, other objects can be added to it with the {{incode|addObject()}} or {{incode|addObjects()}} methods of this Part.
</translate>
</translate>
{{Code|code=
{{Code|code=
import FreeCAD as App
App.ActiveDocument.addObject("App::Part", "Part")

doc = App.newDocument()
obj = App.ActiveDocument.addObject("App::Part", "Part")

bod1 = App.ActiveDocument.addObject("PartDesign::Body", "Body")
bod2 = App.ActiveDocument.addObject("Part::Box", "Box")

obj.addObjects([bod1, bod2])
App.ActiveDocument.recompute()
}}
}}
<translate>
<translate>

Revision as of 22:06, 12 January 2020

Std Part

Menu location
None
Workbenches
All
Default shortcut
None
Introduced in version
0.17
See also
Std Group, PartDesign Body

Description

Std Part (internally called App Part) is a general purpose container that keeps together a group of objects so that they can be moved together as a unit in the 3D view.

The Std Part element was developed to be the basic building block to create mechanical assemblies. In particular, it is meant to arrange objects that have a Part TopoShape, like Part Primitives, PartDesign Bodies, and other Part Features. The Std Part provides an Origin object with local X, Y, and Z axes, and standard planes; this Origin is used as reference to position and attach those other objects. In addition, Std Parts may be nested inside other Std Parts to create a full assembly from smaller sub-assemblies.

Although it is primarily intended for solid bodies, the Std Part can be used to manage any object that has a Placement property, so it can also contain Mesh Features, sketches, and other objects derived from App GeoFeature.

The Std Part tool is not defined by a particular workbench, but by the base system, thus it is found in the structure toolbar that is available in all workbenches.

Left: elements inside a Std Part in the tree view. Right: objects positioned in space, referred to the Origin of the Std Part.

How to use

  1. Press the Std Part button. An empty Part is created and automatically becomes active.
  2. To add objects to a Part, select them in tree view, and then drag and drop them over the Part.
  3. To remove objects from a Part, drag them out of the Part, and onto the document label at the top of the tree view.

Notes

  • As of v0.19, a given object can only belong to a single Part.
  • Double-click the Part in the tree view or open the context menu (right-click) and select Toggle active part to activate or deactivate the Part. If another Part is active, it will be deactivated. See active status for more information.

Properties

A Std Part is internally called App Part (App::Part class), and is derived from an App GeoFeature (App::GeoFeature class), therefore it shares most of the latter's properties.

In addition to the properties described in App GeoFeature, the App Part class has some properties that help it manage information in the context of an assembly, for example, DataType, DataId, DataLicense, DataLicenseURL, DataColor, and DataGroup.

These are the properties available in the property editor. Hidden properties can be shown by using the Show all command in the context menu of the property editor.

Data

Base

  • DataType (String): a description for this object. By default, it is an empty string "".
  • DataId (String): an identification or part number for this object. By default, it is an empty string "".
  • DataLicense (String): a field to specify the license for this object. By default, it is an empty string "".
  • DataLicenseURL (String): a field to specify the web address to the license or contract for this object. By default, it is an empty string "".
  • DataColor (Color): a tuple of four floating point RGBA values (r,g,b,a) to define the color of the object; by default it is (1.0, 1.0, 1.0, 1.0), which is displayed as [255,255,255] on base 255, white color.
  • DataPlacement (Placement): the position of the object in the 3D view. The placement is defined by a Base point (vector), and a Rotation (axis and angle). See Placement.
    • DataAngle: the angle of rotation around the DataAxis. By default, it is (zero degrees).
    • DataAxis: the unit vector that defines the axis of rotation for the placement. Each component is a floating point value between 0 and 1. If any value is above 1, the vector is normalized so that the magnitude of the vector is 1. By default, it is the positive Z axis, (0, 0, 1).
    • DataPosition: a vector with the 3D coordinates of the base point. By default, it is the origin (0, 0, 0).
  • DataLabel (String): the user editable name of this object, it is an arbitrary UTF8 string.
  • DataGroup (LinkList): a list of referenced objects. By default, it is empty [].

Hidden properties Data

  • DataMaterial (Map): map with material properties. By default, it is empty {}.
  • DataMeta (Map): map with additional meta information. By default, it is empty {}.
  • DataUid (UUID): the universally unique identifier (UUID) (128-bit number) of the object. This is assigned at creation time.
  • DataLabel2 (String): a longer, user editable description of this object, it is an arbitrary UTF8 string that may include newlines. By default, it is an empty string "".
  • DataExpression Engine (ExpressionEngine): a list of expressions. By default, it is empty [].
  • DataVisibility (Bool): whether to display the object or not.
  • DataOrigin (Link): the App Origin object that is the positional reference for all elements listed in DataGroup.
  • Data_ Group Touched (Bool): whether the group is touched or not.

View

The App Part only has five of the properties of the basic App GeoFeature, and it does not have hidden properties.

Base

  • ViewDisplay Mode (Enumeration): Group.
  • ViewOn Top When Selected (Enumeration): Disabled (default), Enabled, Object, Element.
  • ViewSelection Style (Enumeration): Shape (default), BoundBox. If the option is Shape, the entire shape (vertices, edges, and faces) will be highlighted in the 3D view; if it is BoundBox only the bounding box will be highlighted.
  • ViewShow In Tree (Bool): if it is true, the object appears in the tree view. Otherwise, it is set as invisible.
  • ViewVisibility (Bool): if it is true, the object appears in the 3D view; otherwise it is invisible. By default this property can be toggled on and off by pressing the Space bar in the keyboard.

Assembly concept

The Std Part is intended to be the basic building block to create assemblies. Unlike a PartDesign Body, an assembly is meant to be a collection of separate, distinguishable elements which are connected in some way in the physical world, for example, through pressure, screws, or glue.

Examples that could be Parts:

  • A wooden table that consists of individual wooden pieces (legs, top), which are put together by glue or metal screws.
  • A ball bearing that is composed of multiple steel balls, an inner ring, a retainer, a seal, and an outer ring.
  • An assembly of a screw with a washer, and a matching nut.

Left: three individual contiguous solids, each of them modelled by a PartDesign Body. Right: the individual Bodies put together inside a Std Part to create an assembly.

In general terms, when importing a STEP file into the program, the main assembly and its sub-assemblies will be imported as Part containers, each of them containing a simple Part Feature.

Detailed explanation

Active status

An open document can contain multiple Parts. An active Part will be displayed in the tree view with the background color specified by the Active container value in the preferences editor (by default, light blue). An active part will also be shown in bold text.

To activate or de-activate a Part:

  • Double click on it on the tree view, or
  • Open the context menu (right click) and select Toggle active part.

Notes:

  • The active status of Parts was developed in v0.17 in parallel with the active status of PartDesign Bodies; however, as of v0.19 this status does not serve a real purpose for Parts.
  • Even when a Part is active, newly created objects are not placed inside of it automatically. In this case, simply drag these new objects, and drop them onto the desired Part.
  • Only a single Part can be active at a time.

File:Std Part-tree-active.png

Document with two Std Parts, of which the second one is active.

Origin

The Origin consists of the three standard axes (X, Y, Z) and three standard planes (XY, XZ and YZ). Sketches can be attached to these planes. All elements inside the Part are referenced to the Part's Origin; which means that the Part can be moved and rotated in reference to the global coordinate system without affecting the placement of elements inside it.

File:PartDesign Body tree-02.png

Visibility Management

The Part's visibility supersedes the visibility of any object it contains. If the Part is hidden, the objects it contains will be hidden as well, even if their visibility is set to true. Multiple objects inside a Part can be visible at a time.

Limitations

  • At this time, Draft Snaps do not work on selected Part containers or on the objects inside of it.
  • A Part has no topological shape, therefore, it is not possible to apply most 3D operations such as Part Booleans on a Part itself, only on its contained objects.

Inheritance

A Std Part is formally an instance of the class App::Part, whose parent is the basic App GeoFeature (App::GeoFeature class).

Simplified diagram of the relationships between the core objects in the program. The App::Part class is a simple container that has a position in 3D space, and has an Origin to control the placement of the objects grouped under it.

Scripting

See also: FreeCAD Scripting Basics, and scripted objects.

See Part Feature for the general information on adding objects to the program.

A Std Part (App Part) is created with the addObject() method of the document. Once a Part exists, other objects can be added to it with the addObject() or addObjects() methods of this Part.

import FreeCAD as App

doc = App.newDocument()
obj = App.ActiveDocument.addObject("App::Part", "Part")

bod1 = App.ActiveDocument.addObject("PartDesign::Body", "Body")
bod2 = App.ActiveDocument.addObject("Part::Box", "Box")

obj.addObjects([bod1, bod2])
App.ActiveDocument.recompute()