Primitive Class Reference

Wrapper Classes for FreeCAD These classes provide a stable interface for 3d objects, independent of the FreeCAD interface.

Future work might include use of pythonOCC, OCC, or even another CAD kernel directly, so this interface layer is quite important.

Funny, in java this is one of those few areas where i’d actually spend the time to make an interface and an implementation, but for new these are just rolled together

This interface layer provides three distinct values:

  1. It allows us to avoid changing key api points if we change underlying implementations. It would be a disaster if script and plugin authors had to change models because we changed implmentations
  2. Allow better documentation. One of the reasons FreeCAD is no more popular is because its docs are terrible. This allows us to provie good documentation via docstrings for each wrapper
  3. Work around bugs. there are a quite a feb bugs in free this layer allows fixing them
  4. allows for enhanced functionality. Many objects are missing features we need. For example we need a ‘forConstruciton’ flag on the Wire object. this allows adding those kinds of things
  5. allow changing interfaces when we’d like. there are few cases where the freecad api is not very userfriendly: we like to change those when necesary. As an example, in the freecad api, all factory methods are on the ‘Part’ object, but it is very useful to know what kind of object each one returns, so these are better grouped by the type of object they return. (who would know that Part.makeCircle() returns an Edge, but Part.makePolygon() returns a Wire ?
Plane(origin, xDir, normal) A 2d coordinate system in space, with the x-y axes on the a plane, and a particular point as the origin.
Vector(*args) Create a 3-dimensional vector :param *args: a 3-d vector, with x-y-z parts.
Vertex(obj[, forConstruction])

Geometry Classes

class cadfile.cadutils.cad.Vector(*args)[source]

Create a 3-dimensional vector


a 3-d vector, with x-y-z parts.

you can either provide:
  • a FreeCAD vector
  • a vector ( in which case it is copied )
  • a 3-tuple
  • three float values, x, y, and z

FreeCAD’s vector implementation has a dumb implementation for multiply and add– they modify the existing value and return a copy as well.

This vector is immutable– all mutations return a copy!


The center of myself is myself. Provided so that vectors, vertexes, and other shapes all support a common interface, when Center() is requested for all objects on the stack


Return self multiplied by the provided scalar

Note: FreeCAD has a bug here, where the base is also modified


Return normalized version this vector.

Note: FreeCAD has a bug here, where the base is also modified

class cadfile.cadutils.cad.Plane(origin, xDir, normal)[source]

A 2d coordinate system in space, with the x-y axes on the a plane, and a particular point as the origin.

A plane allows the use of 2-d coordinates, which are later converted to global, 3d coordinates when the operations are complete.

Frequently, it is not necessary to create work planes, as they can be created automatically from faces.

isWireInside(baseWire, testWire)[source]

Determine if testWire is inside baseWire, after both wires are projected into the current plane

  • baseWire (a FreeCAD wire) – a reference wire
  • testWire (a FreeCAD wire) – another wire

True if testWire is inside baseWire, otherwise False

If either wire does not lie in the current plane, it is projected into the plane first.

WARNING: This method is not 100% reliable. It uses bounding box tests, but needs more work to check for cases when curves are complex.

Future Enhancements:
  • Discretizing points along each curve to provide a more reliable test
classmethod named(stdName, origin=(0, 0, 0))[source]

Create a predefined Plane based on the conventional names.

  • stdName (string) – one of (XY|YZ|XZ|front|back|left|right|top|bottom
  • origin (3-tuple of the origin of the new plane, in global coorindates.) – the desired origin, specified in global coordinates

Available named planes are as follows. Direction references refer to the global directions

Name xDir yDir zDir
XY +x +y +z
YZ +y +z +x
XZ +x +z -y
front +x +y +z
back -x +y -z
left +z +y -x
right -z +y +x
top +x -z +y
bottom +x +z -y
rotated(rotate=Vector (0, 0, 0))[source]

returns a copy of this plane, rotated about the specified axes, as measured from horizontal

Since the z axis is always normal the plane, rotating around Z will always produce a plane that is parallel to this one

the origin of the workplane is unaffected by the rotation.

rotations are done in order x,y,z. if you need a different order, manually chain together multiple .rotate() commands

Parameters:roate – Vector [xDegrees,yDegrees,zDegrees]
Returns:a copy of this plane rotated as requested
setOrigin2d(x, y)[source]

Set a new origin based of the plane. The plane’s orientation and xDrection are unaffected.

  • x (float) – offset in the x direction
  • y (float) – offset in the y direction


the new coordinates are specified in terms of the current 2-d system. As an example::
p = Plane.XY() p.setOrigin2d(2,2) p.setOrigin2d(2,2)

results in a plane with its origin at (x,y)=(4,4) in global coordinates. The both operations were relative to local coordinates of the plane.


Move the origin of the plane, leaving its orientation and xDirection unchanged. :param originVector: the new center of the plane, global coordinates :type originVector: a FreeCAD Vector. :return: void


Project the provided coordinates onto this plane.

Parameters:obj – an object or vector to convert
Returns:an object of the same type as the input, but converted to local coordinates

Most of the time, the z-coordinate returned will be zero, because most operations based on a plane are all 2-d. Occasionally, though, 3-d points outside of the current plane are transformed. One such example is, where 3-d corners of a box are transformed to orient the box in space correctly.


Convert a point in local coordinates to global coordinates.

Parameters:tuplePoint (a 2 or three tuple of float. the third value is taken to be zero if not supplied) – point in local coordinates to convert
Returns:a 3-tuple in global coordinates

Shape Base Class

All objects inherit from Shape, which as basic manipulation methods:

class cadfile.cadutils.cad.Shape(obj)[source]

Represents a shape in the system. Wrappers the FreeCAD api

classmethod cast(obj, forConstruction=False)[source]

Returns the right type of wrapper, given a FreeCAD object


Gets the underlying geometry type :return: a string according to the geometry type.

Implementations can return any values desired, but the values the user uses in type filters should correspond to these.

As an example, if a user does:


The expectation is that the geomType attribute will return ‘mytype’

The return values depend on the type of the shape:

Vertex: always ‘Vertex’ Edge: LINE, ARC, CIRCLE, SPLINE Face: PLANE, SPHERE, CONE Solid: ‘Solid’ Shell: ‘Shell’ Compound: ‘Compound’ Wire: ‘Wire’

isType(obj, strType)[source]

Returns True if the shape is the specified type, false otherwise

contrast with ShapeType, which will raise an exception if the provide object is not a shape at all

rotate(startVector, endVector, angleDegrees)[source]

Rotates a shape around an axis :param startVector: start point of rotation axis either a 3-tuple or a Vector :param endVector: end point of rotation axis, either a 3-tuple or a Vector :param angleDegrees: angle to rotate, in degrees :return: a copy of the shape, rotated


returns a copy of the object, but with geometry transformed insetad of just rotated.

WARNING: transformGeometry will sometimes convert lines and circles to splines, but it also has the ability to handle skew and stretching transformations.

If your transformation is only translation and rotation, it is safer to use transformShape, which doesnt change the underlying type of the geometry, but cannot handle skew transformations


returns a copy of the ojbect, transformed by the provided matrix, with all objects keeping their type

Primitive Classes

class cadfile.cadutils.cad.Solid(obj)[source]

Remove a solid from another one

classmethod extrudeLinear(outerWire, innerWires, vecNormal)[source]

Attempt to extrude the list of wires into a prismatic solid in the provided direction

  • outerWire – the outermost wire
  • innerWires – a list of inner wires
  • vecNormal – a vector along which to extrude the wires

a Solid object

The wires must not intersect

Extruding wires is very non-trivial. Nested wires imply very different geometry, and there are many geometries that are invalid. In general, the following conditions must be met:

  • all wires must be closed
  • there cannot be any intersecting or self-intersecting wires
  • wires must be listed from outside in
  • more than one levels of nesting is not supported reliably

This method will attempt to sort the wires, but there is much work remaining to make this method reliable.

classmethod extrudeLinearWithRotation(outerWire, innerWires, vecCenter, vecNormal, angleDegrees)

Creates a ‘twisted prism’ by extruding, while simultaneously rotating around the extrusion vector.

Though the signature may appear to be similar enough to extrudeLinear to merit combining them, the construction methods used here are different enough that they should be separate.

At a high level, the steps followed ar:
  1. accept a set of wires
  2. create another set of wires like this one, but which are transformed and rotated

(3) create a ruledSurface between the sets of wires (40 create a shell and compute the resulting object

  • outerWire – the outermost wire, a cad.Wire
  • innerWires – a list of inner wires, a list of cad.Wire
  • vecCenter – the center point about which to rotate. the axis of rotation is defined by vecNormal, located at vecCenter. ( a cad.Vector )
  • vecNormal – a vector along which to extrude the wires ( a cad.Vector )
  • angleDegrees – the angle to rotate through while extruding

a cad.Solid object

fillet(radius, edgeList)[source]

Fillets the specified edges of this solid. :param radius: float > 0, the radius of the fillet :param edgeList: a list of Edge objects, which must belong to this solid :return: Filleted solid


computes the intersection between this solid and the supplied one The result could be a face or a compound of faces

classmethod isSolid(obj)[source]

Returns true if the object is a FreeCAD solid, false otherwise

classmethod makeBox(length, width, height, pnt=Vector (0, 0, 0), dir=Vector (0, 0, 1))[source]

makeBox(length,width,height,[pnt,dir]) – Make a box located in pnt with the d

imensions (length,width,height)

By default pnt=Vector(0,0,0) and dir=Vector(0,0,1)’

classmethod makeCone(radius1, radius2, height, pnt=Vector (0, 0, 0), dir=Vector (0, 0, 1), angleDegrees=360)[source]
‘makeCone(radius1,radius2,height,[pnt,dir,angle]) –
Make a cone with given radii and height
By default pnt=Vector(0,0,0),
dir=Vector(0,0,1) and angle=360’
classmethod makeCylinder(radius, height, pnt=Vector (0, 0, 0), dir=Vector (0, 0, 1), angleDegrees=360)[source]

makeCylinder(radius,height,[pnt,dir,angle]) – Make a cylinder with a given radius and height By default pnt=Vector(0,0,0),dir=Vector(0,0,1) and angle=360’

classmethod makeLoft(listOfWire)[source]

makes a loft from a list of wires The wires will be converted into faces when possible– it is presumed that nobody ever actually wants to make an infinitely thin shell for a real part.

classmethod makeSphere(radius, pnt=None, angleDegrees1=None, angleDegrees2=None, angleDegrees3=None)[source]
‘makeSphere(radius,[pnt, dir, angle1,angle2,angle3]) –
Make a sphere with a giv en radius

By default pnt=Vector(0,0,0), dir=Vector(0,0,1), angle1=0, angle2=90 and angle3=360’

classmethod makeTorus(radius1, radius2, pnt=None, dir=None, angleDegrees1=None, angleDegrees2=None)[source]

makeTorus(radius1,radius2,[pnt,dir,angle1,angle2,angle]) – Make a torus with agiven radii and angles By default pnt=Vector(0,0,0),dir=Vector(0,0,1),angle1=0 ,angle1=360 and angle=360’

classmethod makeWedge(xmin, ymin, zmin, z2min, x2min, xmax, ymax, zmax, z2max, x2max, pnt=None, dir=None)[source]
‘makeWedge(xmin, ymin, zmin, z2min, x2min,
xmax, ymax, zmax, z2max, x2max,[pnt, dir])
Make a wedge located in pnt
By default pnt=Vector(0,0,0) and dir=Vec
shell(faceList, thickness, tolerance=0.0001)[source]

make a shelled solid of given by removing the list of faces

  • faceList – list of face objects, which must be part of the solid.
  • thickness – floating point thickness. positive shells outwards, negative shells inwards
  • tolerance – modelling tolerance of the method, default=0.0001

a shelled solid

WARNING The underlying FreeCAD implementation can very frequently have problems with shelling complex geometries!

classmethod sweep(profileWire, pathWire)[source]

make a solid by sweeping the profileWire along the specified path :param cls: :param profileWire: :param pathWire: :return:

class cadfile.cadutils.cad.Shell(wrapped)[source]
class cadfile.cadutils.cad.Wire(obj)[source]
classmethod assembleEdges(listOfEdges)[source]

Attempts to build a wire that consists of the edges in the provided list :param cls: :param listOfEdges: a list of Edge objects :return: a wire with the edges assembled

classmethod combine(listOfWires)[source]

Attempt to combine a list of wires into a new wire. the wires are returned in a list. :param cls: :param listOfWires: :return:

classmethod makeCircle(radius, center, normal)[source]

Makes a Circle centered at the provided point, having normal in the provided direction :param radius: floating point radius of the circle, must be > 0 :param center: vector representing the center of the circle :param normal: vector representing the direction of the plane the circle should lie in :return:

classmethod makeHelix(pitch, height, radius, angle=360.0)[source]

Make a helix with a given pitch, height and radius By default a cylindrical surface is used to create the helix. If the fourth parameter is set (the apex given in degree) a conical surface is used instead’

class cadfile.cadutils.cad.Edge(obj)[source]
Returns:a vector representing the end point of this edge.

Note, circles may have the start and end points the same

classmethod makeLine(v1, v2)[source]

Create a line between two points :param v1: Vector that represents the first point :param v2: Vector that represents the second point :return: A linear edge between the two provided points

classmethod makeSpline(listOfVector)[source]

Interpolate a spline through the provided points. :param cls: :param listOfVector: a list of Vectors that represent the points :return: an Edge

classmethod makeThreePointArc(v1, v2, v3)[source]

Makes a three point arc through the provided points :param cls: :param v1: start vector :param v2: middle vector :param v3: end vector :return: an edge object through the three points

Returns:a vector representing the start poing of this edge

Note, circles may have the start and end points the same


Compute tangent vector at the specified location. :param locationVector: location to use. Use the center point if None :return: tangent vector

class cadfile.cadutils.cad.Vertex(obj, forConstruction=False)[source]

The center of a vertex is itself!

Table Of Contents

Previous topic

CadQuery API Reference

Next topic

CadQuery String Selectors