Sketcher scripting
Creating a SketchObject using Python
We create a SketchObject like this:
import FreeCAD as App
import Part
import Sketcher
doc = App.newDocument()
sketch = doc.addObject("Sketcher::SketchObject", "Sketch")
sketch.addGeometry(Part.LineSegment(App.Vector(1.2, 1.8, 0),
App.Vector(5.2, 5.3, 0)), False)
sketch.addGeometry(Part.LineSegment(App.Vector(6.5, 1.5, 0),
App.Vector(10.2, 5.0, 0)), False)
sketch.addGeometry(Part.LineSegment(App.Vector(12.2, 1.0, 0),
App.Vector(15.4, 5.0, 0)), False)
doc.recompute()
It also adds three lines in the newly created Sketch.
Creating a constraint using Python
A geometric constraint
and
can be created from macros and from the Python console by using the following command:
sketch.addConstraint(Sketcher.Constraint(ConstraintType, EdgeOrPartOfEdge…))
A dimensional constraint
and the special
refraction constraint can be created from macros and from the Python console by using the following command:
sketch.addConstraint(Sketcher.Constraint(DimensionalConstraintType, EdgeOrPartOfEdge…, App.Units.Quantity("float_value unit")))
e.g.
sketch.addConstraint(Sketcher.Constraint(DimensionalConstraintType, EdgeOrPartOfEdge…, App.Units.Quantity("123.0 mm")))
The first argument ConstraintType is described below in Constraint types.
A constraint can take up to six arguments which are edges or indicate which sub-part of an edge is used by the constraint. See the documentation of individual constraints for details on what combinations of edges and sub-parts of edges can be passed as arguments. The main issue with this function is to identify correctly the line number and the vertex number of the lines you want to process. The sections below describe how to identify the numbering of a line, and how to Identify the numbering of the sub-parts of a line.
Constraint types
For geometric constraints, the first argument is one of the following. See the corresponding feature page for the possible combinations of arguments allowed for each constraint.
| Code | Icon | Feature |
|---|---|---|
"Coincident" |
Coincident Constraint | |
"PointOnObject" |
Point-On-Object Constraint | |
"Vertical" |
Vertical Constraint | |
"Horizontal" |
Horizontal Constraint | |
"Parallel" |
Parallel Constraint | |
"Perpendicular" |
Perpendicular Constraint | |
"Tangent" |
Tangent/Collinear Constraint | |
"Equal" |
Equal Constraint | |
"Symmetric" |
Symmetric Constraint | |
"Block" |
Block Constraint |
For dimensional constraints, the first argument is one of the following. See the corresponding feature page for the possible combinations of arguments allowed for each constraint.
| Code | Icon | Feature |
|---|---|---|
"DistanceX" |
Horizontal Dimension | |
"DistanceY" |
Vertical Dimension | |
"Distance" |
Distance Dimension | |
"Radius" |
Radius Dimension | |
"Diameter" |
Diameter Dimension | |
"Angle" |
Angle Dimension | |
"AngleViaPoint" |
Angle Dimension |
The refraction constraint behave like dimensional constraints for the purposes of scripting. Again, see the corresponding feature page for the possible combinations of arguments allowed for each constraint.
| Code | Icon | Feature |
|---|---|---|
"SnellsLaw" |
Refraction Constraint |
The lock position constraint is a GUI command which creates a
horizontal dimension and a
vertical dimension constraint, it is not a constraint of its own.
Identifying the numbering of a line
I have drawn three lines as shown in the following figure.
By moving the cursor of the mouse above the line you can see the line number at the bottom left of the FreeCAD windows, see next figure.
Unfortunately the numbering displayed on the FreeCAD windows start from 1 whereas the numbering of the line used to script start from 0: this means that you have to subtract one each time you want to refer to a line.
Positive numbers indicate sketch edges (straight lines, circles, conics, B-splines, and so on). The following values can be used to denote elements that are not sketch edges:
-1denotes the horizontal x axis-2denotes the vertical y axis-ndenotes the external geometry element numbern-3(e.g. the external geometry element with index 0 in the flattened listsketch.ExternalGeometrywould be denoted by -3, the following element in the flattened list would be -4 and so on).
Identifying the numbering of the sub-parts of a line
When qualifying which part of a line is affected by a constraint, the following values can be used:
0to indicate that the constraint affects the entire edge.1to indicate that the constraint affects the start point of the edge (a full circle has no starting point).2to indicate that the constraint affects the endpoint of the edge.3to indicate that the constraint affects the center point of the edge. Can only be used for circles, circular arcs, ellipses and elliptical arcs.nto indicate that the constraint affects the n-th pole of a B-spline.
The vertices indicated by 1 and 2 are numbered according to their order of creation. To find out the order of their creation (If you have a lot of lines, you cannot remember which vertex you have created first), you just have to move the cursor of your mouse above the two vertices of one line, see following figure.
If you read e.g. 4 and 5, it means that the vertex with the lower number (4 in this example) will be referenced by using the number 1 (first in the script command and the vertex with the higher number (5 in this example) will be referenced by using the number 2 in the script command.
Example
Let us take the previous example of the three lines. The subsequent figure indicates the numbering of each line and their vertices according to the convention for scripting.
blue text: numbering of line, black text: numbering of vertices
The command sketch.addConstraint(Sketcher.Constraint("Coincident", 1, 2, 2, 1)) yields following result:
The full code to draw the three lines and add a Coincident constraint on two points from two lines is like this:
import FreeCAD as App
import Part
import Sketcher
doc = App.newDocument()
sketch = doc.addObject("Sketcher::SketchObject", "Sketch")
sketch.addGeometry(Part.LineSegment(App.Vector(1.2, 1.8, 0),
App.Vector(5.2, 5.3, 0)), False)
sketch.addGeometry(Part.LineSegment(App.Vector(6.5, 1.5, 0),
App.Vector(10.2, 5.0, 0)), False)
sketch.addGeometry(Part.LineSegment(App.Vector(12.2, 1.0, 0),
App.Vector(15.4, 5.0, 0)), False)
sketch.addConstraint(Sketcher.Constraint("Coincident", 1, 2, 2, 1))
doc.recompute()
- General: New Sketch, Edit Sketch, Attach Sketch, Reorient Sketch, Validate Sketch, Merge Sketches, Mirror Sketch, Leave Sketch, Align View to Sketch, Toggle Section View, Stop Operation, Grid, Snap, Rendering Order
- Geometries: Point, Polyline, Line, Arc From Center, Arc From 3 Points, Elliptical Arc, Hyperbolic Arc, Parabolic Arc, Circle From Center, Circle From 3 Points, Ellipse From Center, Ellipse From 3 Points, Rectangle, Centered Rectangle, Rounded Rectangle, Triangle, Square, Pentagon, Hexagon, Heptagon, Octagon, Polygon, Slot, Arc Slot, B-Spline, Periodic B-Spline, B-Spline From Knots, Periodic B-Spline From Knots, Toggle Construction Geometry
- Constraints:
- Dimensional Constraints: Dimension, Horizontal Dimension, Vertical Dimension, Distance Dimension, Radius/Diameter Dimension, Radius Dimension, Diameter Dimension, Angle Dimension, Lock Position
- Geometric Constraints: Coincident Constraint (Unified), Coincident Constraint, Point-On-Object Constraint, Horizontal/Vertical Constraint, Horizontal Constraint, Vertical Constraint, Parallel Constraint, Perpendicular Constraint, Tangent/Collinear Constraint, Equal Constraint, Symmetric Constraint, Block Constraint, Refraction Constraint
- Constraint Tools: Toggle Driving/Reference Constraints, Toggle Constraints
- Sketcher Tools: Fillet, Chamfer, Trim Edge, Split Edge, Extend Edge, External Projection, External Intersection, Carbon Copy, Select Origin, Select Horizontal Axis, Select Vertical Axis, Move/Array Transform, Rotate/Polar Transform, Scale, Offset, Mirror, Remove Axes Alignment, Delete All Geometry, Delete All Constraints, Copy Elements, Cut Elements, Paste Elements
- B-Spline Tools: Geometry to B-Spline, Increase B-Spline Degree, Decrease B-Spline Degree, Increase Knot Multiplicity, Decrease Knot Multiplicity, Insert Knot, Join Curves
- Visual Helpers: Select Under-Constrained Elements, Select Associated Constraints, Select Associated Geometry, Select Redundant Constraints, Select Conflicting Constraints, Toggle Circular Helper for Arcs, Toggle B-Spline Degree, Toggle B-Spline Control Polygon, Toggle B-Spline Curvature Comb, Toggle B-Spline Knot Multiplicity, Toggle B-Spline Control Point Weight, Toggle Internal Geometry, Switch Virtual Space
- Additional: Sketcher Dialog, Preferences, Sketcher scripting
- Getting started
- Installation: Download, Windows, Linux, Mac, Additional components, Docker, AppImage, Ubuntu Snap
- Basics: About FreeCAD, Interface, Mouse navigation, Selection methods, Object name, Preferences, Workbenches, Document structure, Properties, Help FreeCAD, Donate
- Help: Tutorials, Video tutorials
- Workbenches: Std Base, Assembly, BIM, CAM, Draft, FEM, Inspection, Material, Mesh, OpenSCAD, Part, PartDesign, Points, Reverse Engineering, Robot, Sketcher, Spreadsheet, Surface, TechDraw, Test Framework
- Hubs: User hub, Power users hub, Developer hub

