Sketcher scripting

Construction Mode

Coincident

Sketcher

Creating a constraint using Python

A geometric constraint and the special InternalAlignment constraints 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 constraint Snell's law 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')))

1. 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:

• 'Coincident', see Coincident for the possible combinations of arguments
• 'PointOnObject', see Point On Object for the possible combinations of arguments
• 'Vertical', see Vertical for the possible combinations of arguments
• 'Horizontal', see Horizontal for the possible combinations of arguments
• 'Parallel', see Parallel for the possible combinations of arguments
• 'Perpendicular', see Perpendicular for the possible combinations of arguments
• 'Tangent', see Tangent for the possible combinations of arguments
• 'Equal', see Equal for the possible combinations of arguments
• 'Symmetric', see Symmetric for the possible combinations of arguments
• 'Block', see Block for the possible combinations of arguments

The InternalAlignment constraints behave like geometric constraints for the purposes of scripting.

• 'InternalAlignment:EllipseMajorDiameter', see InternalAlignment for the possible combinations of arguments
• 'InternalAlignment:EllipseMinorDiameter', see Internal alignment for the possible combinations of arguments
• 'InternalAlignment:EllipseFocus1', see Internal alignment for the possible combinations of arguments
• 'InternalAlignment:EllipseFocus2', see Internal alignment for the possible combinations of arguments

For dimensional constraints, the first argument is one of the following:

• 'DistanceX', see Horizontal distance for the possible combinations of arguments
• 'DistanceY', see Vertical distance for the possible combinations of arguments
• 'Distance', see Distance for the possible combinations of arguments
• 'Radius', see Radius for the possible combinations of arguments
• 'Diameter', see Diameter for the possible combinations of arguments
• 'Angle', see Angle for the possible combinations of arguments
• 'AngleViaPoint', see Angle for the possible combinations of arguments

The Snell's law constraints behave like dimensional for the purposes of scripting.

• 'SnellsLaw', see Snell's law for the possible combinations of arguments

The Lock constraint is a GUI command which creates a Horizontal distance and a Vertical distance 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:

• -1 denotes the horizontal x axis
• -2 denotes the vertical y axis
• -n denotes the external geometry element number n-3 (e.g. the external geometry element with index 0 in the flattened list App.ActiveDocument.Sketch.ExternalGeometry would 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:

• 0 to indicate that the constraint affects the entire edge.
• 1 to indicate that the constraint affects the starting point of the edge (a full circle has no starting point).
• 2 to indicate that the constraint affects the end point of the edge.
• 3 to indicate that the constraint affects the center point of the edge. For Circles and Conics (ellipses), this is the center of the circle or center (intersection of major and minor axes) of the ellipse. For straight Lines, 3 cannot be used to indicate the center point.
• n to 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 command Sketch.addConstraint(Sketcher.Constraint('Coincident',0,2,2,2)) yields following result:

Construction Mode

Coincident

Sketcher

Sketcher

• General: Create sketch, Edit sketch, Map sketch to face, Reorient sketch, Validate sketch, Merge sketches, Mirror sketch, Leave sketch, View sketch, View section, Toggle grid, Toggle snap, Configure rendering order, Stop operation

---

• Sketcher geometries: Point, Line, Arc, Arc by 3 points, Circle, Circle by 3 points, Ellipse, Ellipse by 3 points, Arc of ellipse, Arc of hyperbola, Arc of parabola, B-spline by control points, Periodic B-spline by control points, B-spline by knots, Periodic B-spline by knots, Polyline, Rectangle, Centered rectangle, Rounded rectangle, Triangle, Square, Pentagon, Hexagon, Heptagon, Octagon, Regular polygon, Slot, Fillet, Corner-preserving fillet, Trim, Extend, Split, External geometry, Carbon copy, Toggle construction geometry

---

• Sketcher constraints:
  • Geometric constraints: Coincident, Point on object, Vertical, Horizontal, Parallel, Perpendicular, Tangent, Equal, Symmetric, Block
  • Dimensional constraints: Lock, Horizontal distance, Vertical distance, Distance, Radius or weight, Diameter, Auto radius/diameter, Angle, Refraction (Snell's law)
  • Constraint tools: Toggle driving/reference constraint, Activate/deactivate constraint

---

• Sketcher tools: Select unconstrained DoF, Select associated constraints, Select associated geometry, Select redundant constraints, Select conflicting constraints, Show/hide internal geometry, Select origin, Select horizontal axis, Select vertical axis, Symmetry, Clone, Copy, Move, Rectangular array, Remove axes alignment, Delete all geometry, Delete all constraints

---

• Sketcher B-spline tools: Show/hide B-spline degree, Show/hide B-spline control polygon, Show/hide B-spline curvature comb, Show/hide B-spline knot multiplicity, Show/hide B-spline control point weight, Convert geometry to B-spline, Increase B-spline degree, Decrease B-spline degree, Increase knot multiplicity, Decrease knot multiplicity, Insert knot, Join curves

---

• Sketcher virtual space: Switch virtual space

---

• Additional: Sketcher Dialog, Preferences, Sketcher scripting

User documentation

• 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, Arch, Assembly, CAM, Draft, FEM, Inspection, Mesh, OpenSCAD, Part, PartDesign, Points, Reverse Engineering, Robot, Sketcher, Spreadsheet, Start, Surface, TechDraw, Test Framework, Web

---

• Addons: Addon Manager, External workbenches, Scripting and macros

---

• Hubs: User hub, Power users hub, Developer hub