Part scripting/en: Difference between revisions
(Updating to match new version of source page) |
(Updating to match new version of source page) |
||
(2 intermediate revisions by the same user not shown) | |||
Line 10: | Line 10: | ||
==Introduction== |
==Introduction== |
||
The main data structure used in the Part module is the [http://en.wikipedia.org/wiki/Boundary_representation BRep] data type from [[OpenCASCADE|OpenCASCADE]]. Almost all contents and object types of the Part module are available in [[Python|Python]] scripting. This includes geometric primitives, such as Lines, Circles and Arcs, and the whole range of TopoShapes, like Vertexes, Edges, Wires, Faces, Solids and Compounds. For each of those objects, several creation methods exist, and for some of them, especially the TopoShapes, advanced operations like boolean union/difference/intersection are also available. Explore the contents of the Part module, as described in the [[FreeCAD_Scripting_Basics|FreeCAD Scripting Basics]] page, to know more. |
|||
The main data structure used in the Part module is the [http://en.wikipedia.org/wiki/Boundary_representation BRep] data type from OpenCascade. |
|||
Almost all contents and object types of the Part module are available by [[Python|Python]] scripting. This includes geometric primitives, such as Line and Circle (or Arc), and the whole range of TopoShapes, like Vertexes, Edges, Wires, Faces, Solids and Compounds. For each of those objects, several creation methods exist, and for some of them, especially the TopoShapes, advanced operations like boolean union/difference/intersection are also available. Explore the contents of the Part module, as described in the [[FreeCAD Scripting Basics|FreeCAD Scripting Basics]] page, to know more. |
|||
The most basic object that can be created is a [[ |
The most basic object that can be created is a [[Part_Feature|Part Feature]], which has a simple {{PropertyData|Placement}} property, and basic properties to define its color and appearance. |
||
Another simple object used in 2D geometrical objects is [[ |
Another simple object used in 2D geometrical objects is the [[Part_Part2DObject|Part Part2DObject]], which is the base of the [[Sketcher_SketchObject|Sketcher SketchObject]] and most [[Draft_Workbench|Draft elements]]. |
||
===See also=== |
===See also=== |
||
Line 24: | Line 23: | ||
==Test script== |
==Test script== |
||
Test the creation of [[Part_Primitives|Part Primitives]] with a script. |
Test the creation of [[Part_Primitives|Part Primitives]] with a script. |
||
{{Code|code= |
{{Code|code= |
||
Line 32: | Line 31: | ||
This script is located in the installation directory of the program, and can be examined to see how the basic primitives are built. |
This script is located in the installation directory of the program, and can be examined to see how the basic primitives are built. |
||
{{Code|code= |
{{Code|code= |
||
$INSTALL_DIR/Mod/Part/parttests/part_test_objects.py |
$INSTALL_DIR/Mod/Part/parttests/part_test_objects.py |
||
Line 38: | Line 38: | ||
==Examples== |
==Examples== |
||
===Line=== |
|||
To create a line element switch to the Python console and type in: |
|||
To create a line element switch to the [[Python_console|Python console]] and enter: |
|||
{{Code|code= |
{{Code|code= |
||
import |
import FreeCAD as App |
||
import Part |
|||
doc=App.newDocument() |
|||
l=Part.LineSegment() |
|||
doc = App.newDocument() |
|||
l.StartPoint=(0.0,0.0,0.0) |
|||
l.EndPoint=(1.0,1.0,1.0) |
|||
line = Part.LineSegment() |
|||
doc.addObject("Part::Feature","Line").Shape=l.toShape() |
|||
line.StartPoint = (0.0, 0.0, 0.0) |
|||
line.EndPoint = (1.0, 1.0, 1.0) |
|||
obj = doc.addObject("Part::Feature", "Line") |
|||
obj.Shape= line.toShape() |
|||
doc.recompute() |
doc.recompute() |
||
}} |
}} |
||
Let's go through the above |
Let's go through the above Python example step by step: |
||
{{Code|code= |
{{Code|code= |
||
import |
import FreeCAD as App |
||
import Part |
|||
doc=App.newDocument() |
|||
doc = App.newDocument() |
|||
}} |
}} |
||
loads the Part |
This loads the FreeCAD and Part modules and creates a new document. |
||
{{Code|code= |
{{Code|code= |
||
line = Part.LineSegment() |
|||
line.StartPoint = (0.0, 0.0, 0.0) |
|||
line.EndPoint = (1.0, 1.0, 1.0) |
|||
}} |
}} |
||
Line 68: | Line 76: | ||
{{Code|code= |
{{Code|code= |
||
doc.addObject("Part::Feature","Line" |
obj = doc.addObject("Part::Feature", "Line") |
||
obj.Shape= line.toShape() |
|||
}} |
}} |
||
This adds a Part object type to the document and assigns the shape representation of the line segment to the |
This adds a Part object type to the document and assigns the shape representation of the line segment to the {{Incode|Shape}} property of the added object. It is important to understand here that we use a geometric primitive (the {{Incode|Part.LineSegment}}) to create a TopoShape out of it (with the {{Incode|toShape()}} method). Only shapes can be added to the document. In FreeCAD geometric primitives are used as "building structures" for shapes. |
||
{{Code|code= |
{{Code|code= |
||
Line 77: | Line 86: | ||
}} |
}} |
||
Updates the document. This also prepares the visual representation of the new |
Updates the document. This also prepares the visual representation of the new Part object. |
||
Note that a |
Note that a line segment can also be created by specifying its start and endpoint directly in the constructor, for example {{Incode|Part.LineSegment(point1, point2)}}, or we can create a default line and set its properties afterwards, as we did here. |
||
A Line can be created |
A Line can also be created using: |
||
{{Code|code= |
{{Code|code= |
||
import FreeCAD |
import FreeCAD as App |
||
import Part |
import Part |
||
DOC = FreeCAD.newDocument() |
|||
def |
def my_create_line(pt1, pt2, obj_name): |
||
obj = |
obj = App.ActiveDocument.addObject("Part::Line", obj_name) |
||
obj.X1 = pt1[0] |
obj.X1 = pt1[0] |
||
obj.Y1 = pt1[1] |
obj.Y1 = pt1[1] |
||
Line 98: | Line 106: | ||
obj.Z2 = pt2[2] |
obj.Z2 = pt2[2] |
||
App.ActiveDocument.recompute() |
|||
return obj |
return obj |
||
line = |
line = my_create_line((0, 0, 0), (0, 10, 0), "LineName") |
||
}} |
}} |
||
===Circle=== |
|||
A circle can be created in a similar way: |
A circle can be created in a similar way: |
||
{{Code|code= |
{{Code|code= |
||
import FreeCAD as App |
|||
import Part |
import Part |
||
doc = App.activeDocument() |
doc = App.activeDocument() |
||
c = Part.Circle() |
|||
circle = Part.Circle() |
|||
c.Radius=10.0 |
|||
circle.Radius = 10.0 |
|||
f = doc.addObject("Part::Feature", "Circle") |
|||
obj = doc.addObject("Part::Feature", "Circle") |
|||
f.Shape = c.toShape() |
|||
obj.Shape = circle.toShape() |
|||
doc.recompute() |
doc.recompute() |
||
}} |
}} |
||
Or using: |
|||
{{Code|code= |
{{Code|code= |
||
import FreeCAD |
import FreeCAD as App |
||
import Part |
import Part |
||
DOC = FreeCAD.newDocument() |
|||
def |
def my_create_circle(rad, obj_name): |
||
obj = |
obj = App.ActiveDocument.addObject("Part::Circle", obj_name) |
||
obj.Radius = rad |
obj.Radius = rad |
||
App.ActiveDocument.recompute() |
|||
return obj |
return obj |
||
circle = |
circle = my_create_circle(5.0, "CircleName") |
||
}} |
}} |
||
Alternatively we can create a circle by defining its center, axis and radius: |
|||
{{Code|code= |
{{Code|code= |
||
import FreeCAD as App |
|||
import Part |
import Part |
||
doc = App.activeDocument() |
doc = App.activeDocument() |
||
center = App.Vector(1,2,3) |
|||
center = App.Vector(1, 2, 3) |
|||
axis = App.Vector(1, 1, 1) |
|||
radius = 10 |
radius = 10 |
||
circle = Part.Circle(center, axis, radius) |
|||
obj = doc.addObject("Part::Feature", "Circle") |
|||
obj.Shape = circle.toShape() |
|||
doc.recompute() |
doc.recompute() |
||
}} |
}} |
||
Or by defining three points on its circumference: |
|||
or create a circle defined by three points using: |
|||
{{Code|code= |
{{Code|code= |
||
import FreeCAD as App |
|||
import Part |
import Part |
||
doc = App.activeDocument() |
doc = App.activeDocument() |
||
p1 = App.Vector(10,0,0) |
|||
p1 = App.Vector(10, 0, 0) |
|||
p2 = App.Vector(0, 10, 0) |
|||
p3 = App.Vector(0, 0, 10) |
|||
circle = Part.Circle(p1, p2, p3) |
|||
f = doc.addObject("Part::Feature", "Circle") |
|||
obj = doc.addObject("Part::Feature", "Circle") |
|||
f.Shape = c.toShape() |
|||
obj.Shape = circle.toShape() |
|||
doc.recompute() |
doc.recompute() |
||
}} |
}} |
||
Note again, we used the circle ( |
Note again, we used the circle (geometric primitive) to construct a shape. We can of course still access our construction geometry afterwards, by doing: |
||
{{Code|code= |
{{Code|code= |
||
shape = obj.Shape |
|||
edge = shape.Edges[0] |
|||
curve = edge.Curve |
|||
}} |
}} |
||
Here we take the |
Here we take the {{Incode|Shape}} of our object {{Incode|obj}} and then its list of {{Incode|Edges}}. In this case there will be only one edge because we made the shape out of a single circle. So we take only the first item in the {{Incode|Edges}} list, and then take its curve. Every edge has a {{Incode|Curve}}, which is the geometric primitive it is based on. |
||
===Arc=== |
|||
An arc can be created like this: |
|||
{{Code|code= |
|||
import FreeCAD as App |
|||
import Part |
|||
doc = App.activeDocument() |
|||
p1 = App.Vector(10, 0, 0) |
|||
p2 = App.Vector(0, 10, 0) |
|||
p3 = App.Vector(-10, 0, 0) |
|||
arc = Part.Arc(p1, p2, p3) |
|||
obj = doc.addObject("Part::Feature", "Arc") |
|||
obj.Shape = arc.toShape() |
|||
doc.recompute() |
|||
}} |
|||
This draws a half circle. The center is at (0, 0, 0). The radius is 10. P1 is the start point on +X axis. P2 is the middle point on +Y axis and P3 is the end point on -X axis. |
|||
We can also create an arc from a circle: |
|||
{{Code|code= |
|||
import FreeCAD as App |
|||
import Part |
|||
doc = App.activeDocument() |
|||
p1 = App.Vector(10, 0, 0) |
|||
p2 = App.Vector(0, 10, 0) |
|||
p3 = App.Vector(-10, 0, 0) |
|||
circle = Part.Circle(p1, p2, p3) |
|||
arc = Part.ArcOfCircle(circle, 0.0, 0.7854) |
|||
obj = doc.addObject("Part::Feature", "Arc") |
|||
obj.Shape = arc.toShape() |
|||
doc.recompute() |
|||
}} |
|||
It needs a circle, and a start angle and end angle in radians. |
|||
Head to the [[Topological data scripting|Topological data scripting]] page if you would like to know more. |
|||
Latest revision as of 16:13, 20 May 2023
Introduction
The main data structure used in the Part module is the BRep data type from OpenCASCADE. Almost all contents and object types of the Part module are available in Python scripting. This includes geometric primitives, such as Lines, Circles and Arcs, and the whole range of TopoShapes, like Vertexes, Edges, Wires, Faces, Solids and Compounds. For each of those objects, several creation methods exist, and for some of them, especially the TopoShapes, advanced operations like boolean union/difference/intersection are also available. Explore the contents of the Part module, as described in the FreeCAD Scripting Basics page, to know more.
The most basic object that can be created is a Part Feature, which has a simple DataPlacement property, and basic properties to define its color and appearance.
Another simple object used in 2D geometrical objects is the Part Part2DObject, which is the base of the Sketcher SketchObject and most Draft elements.
See also
Test script
Test the creation of Part Primitives with a script.
import parttests.part_test_objects as pto
pto.create_test_file("example_file")
This script is located in the installation directory of the program, and can be examined to see how the basic primitives are built.
$INSTALL_DIR/Mod/Part/parttests/part_test_objects.py
Examples
Line
To create a line element switch to the Python console and enter:
import FreeCAD as App
import Part
doc = App.newDocument()
line = Part.LineSegment()
line.StartPoint = (0.0, 0.0, 0.0)
line.EndPoint = (1.0, 1.0, 1.0)
obj = doc.addObject("Part::Feature", "Line")
obj.Shape= line.toShape()
doc.recompute()
Let's go through the above Python example step by step:
import FreeCAD as App
import Part
doc = App.newDocument()
This loads the FreeCAD and Part modules and creates a new document.
line = Part.LineSegment()
line.StartPoint = (0.0, 0.0, 0.0)
line.EndPoint = (1.0, 1.0, 1.0)
Line is actually a line segment, hence the start and endpoint.
obj = doc.addObject("Part::Feature", "Line")
obj.Shape= line.toShape()
This adds a Part object type to the document and assigns the shape representation of the line segment to the Shape
property of the added object. It is important to understand here that we use a geometric primitive (the Part.LineSegment
) to create a TopoShape out of it (with the toShape()
method). Only shapes can be added to the document. In FreeCAD geometric primitives are used as "building structures" for shapes.
doc.recompute()
Updates the document. This also prepares the visual representation of the new Part object.
Note that a line segment can also be created by specifying its start and endpoint directly in the constructor, for example Part.LineSegment(point1, point2)
, or we can create a default line and set its properties afterwards, as we did here.
A Line can also be created using:
import FreeCAD as App
import Part
def my_create_line(pt1, pt2, obj_name):
obj = App.ActiveDocument.addObject("Part::Line", obj_name)
obj.X1 = pt1[0]
obj.Y1 = pt1[1]
obj.Z1 = pt1[2]
obj.X2 = pt2[0]
obj.Y2 = pt2[1]
obj.Z2 = pt2[2]
App.ActiveDocument.recompute()
return obj
line = my_create_line((0, 0, 0), (0, 10, 0), "LineName")
Circle
A circle can be created in a similar way:
import FreeCAD as App
import Part
doc = App.activeDocument()
circle = Part.Circle()
circle.Radius = 10.0
obj = doc.addObject("Part::Feature", "Circle")
obj.Shape = circle.toShape()
doc.recompute()
Or using:
import FreeCAD as App
import Part
def my_create_circle(rad, obj_name):
obj = App.ActiveDocument.addObject("Part::Circle", obj_name)
obj.Radius = rad
App.ActiveDocument.recompute()
return obj
circle = my_create_circle(5.0, "CircleName")
Alternatively we can create a circle by defining its center, axis and radius:
import FreeCAD as App
import Part
doc = App.activeDocument()
center = App.Vector(1, 2, 3)
axis = App.Vector(1, 1, 1)
radius = 10
circle = Part.Circle(center, axis, radius)
obj = doc.addObject("Part::Feature", "Circle")
obj.Shape = circle.toShape()
doc.recompute()
Or by defining three points on its circumference:
import FreeCAD as App
import Part
doc = App.activeDocument()
p1 = App.Vector(10, 0, 0)
p2 = App.Vector(0, 10, 0)
p3 = App.Vector(0, 0, 10)
circle = Part.Circle(p1, p2, p3)
obj = doc.addObject("Part::Feature", "Circle")
obj.Shape = circle.toShape()
doc.recompute()
Note again, we used the circle (geometric primitive) to construct a shape. We can of course still access our construction geometry afterwards, by doing:
shape = obj.Shape
edge = shape.Edges[0]
curve = edge.Curve
Here we take the Shape
of our object obj
and then its list of Edges
. In this case there will be only one edge because we made the shape out of a single circle. So we take only the first item in the Edges
list, and then take its curve. Every edge has a Curve
, which is the geometric primitive it is based on.
Arc
An arc can be created like this:
import FreeCAD as App
import Part
doc = App.activeDocument()
p1 = App.Vector(10, 0, 0)
p2 = App.Vector(0, 10, 0)
p3 = App.Vector(-10, 0, 0)
arc = Part.Arc(p1, p2, p3)
obj = doc.addObject("Part::Feature", "Arc")
obj.Shape = arc.toShape()
doc.recompute()
This draws a half circle. The center is at (0, 0, 0). The radius is 10. P1 is the start point on +X axis. P2 is the middle point on +Y axis and P3 is the end point on -X axis.
We can also create an arc from a circle:
import FreeCAD as App
import Part
doc = App.activeDocument()
p1 = App.Vector(10, 0, 0)
p2 = App.Vector(0, 10, 0)
p3 = App.Vector(-10, 0, 0)
circle = Part.Circle(p1, p2, p3)
arc = Part.ArcOfCircle(circle, 0.0, 0.7854)
obj = doc.addObject("Part::Feature", "Arc")
obj.Shape = arc.toShape()
doc.recompute()
It needs a circle, and a start angle and end angle in radians.
- FreeCAD scripting: Python, Introduction to Python, Python scripting tutorial, FreeCAD Scripting Basics
- Modules: Builtin modules, Units, Quantity
- Workbenches: Workbench creation, Gui Commands, Commands, Installing more workbenches
- Meshes and Parts: Mesh Scripting, Topological data scripting, Mesh to Part, PythonOCC
- Parametric objects: Scripted objects, Viewproviders (Custom icon in tree view)
- Scenegraph: Coin (Inventor) scenegraph, Pivy
- Graphical interface: Interface creation, Interface creation completely in Python (1, 2, 3, 4, 5), PySide, PySide examples beginner, intermediate, advanced
- Macros: Macros, How to install macros
- Embedding: Embedding FreeCAD, Embedding FreeCADGui
- Other: Expressions, Code snippets, Line drawing function, FreeCAD vector math library (deprecated)
- Hubs: User hub, Power users hub, Developer hub
- Primitives: Box, Cylinder, Sphere, Cone, Torus, Tube, Create primitives, Shape builder
- Creation and modification: Extrude, Revolve, Mirror, Fillet, Chamfer, Make face from wires, Ruled Surface, Loft, Sweep, Section, Cross sections, 3D Offset, 2D Offset, Thickness, Projection on surface, Attachment
- Boolean: Make compound, Explode Compound, Compound Filter, Boolean, Cut, Fuse, Common, Connect, Embed, Cutout, Boolean fragments, Slice apart, Slice, XOR
- Measure: Measure Linear, Measure Angular, Measure Refresh, Clear All, Toggle All, Toggle 3D, Toggle Delta