The FreeCAD interface

Before being able to use the Raytracing Workbench in FreeCAD, one of these two rendering applications needs to be installed on your system. This is usually very straightforward, both provide installers for many platforms or are usually included in the software repositories of most Linux distributions.

Once POV-Ray or Luxrender is installed, we need to set the path to their main executable in the FreeCAD preferences. This is usually only required on Windows and Mac. On Linux FreeCAD will pick it from the standard locations. The location of the povray or luxrender executables can be found by simply searching your system for files named povray (or povray.exe on Windows) and luxrender (or luxrender.exe on Windows).

In this preferences screen we can also set the desired image size we want to produce.

Rendering with PovRay

We will use the table we have been modeling in the tradtional modeling chapter to produce renderings with PovRay and Luxrender.

Start by loading the table.FCStd file that we modeled earlier or from the link at the bottom of this chapter.

Press the small down arrow next to the New Povray project button, and choose the RadiosityNormal template

A warning message might appear telling you that the current 3D view is not in perspective mode and the rendering will therefore differ. Correct this by choosing No, choosing menu View->Perspective view and choosing the RadiosityNormal template again.

You might also try other templates after you created a new project, simply by editing its Template property.

A new project has now been created:

The new project has adopted the point of view of the 3D view as it was at the moment we pressed the button. We can change the view, and update the view position stored in the povray project anytime, by pressing the Reset camera button.

The Raytracing Workbench works the same way as the Drawing Workbench: Once a project folder is created, we must add Views of our objects to it. We can now do that by selecting all the objects that compose the table, and press the Insert part button:

The views have taken the color and transparency values from their original parts, but you can change that in the properties of each individual view if you wish.

We are now ready to produce our first povray render. Press the Render button.

You will be asked to give a file name and path for the .png image that will be saved by povray.

The povray will then open and calculate the image.

When this is done, simply click the image to close the povray window. The resulting image will be loaded in FreeCAD:

Rendering with LuxRender

Rendering with Luxrender works almost the same way. We can leave our file open and create a new Luxrender project in the same file, or reload it to start from scratch.

Press the little down arrow next to the New Luxrender project button and choose the LuxOutdoor template.

Select all the components of the table. If you still have the povray project in your document, be sure to also select the lux project itself, so the views created in the next step won't go in the wrong project by mistake.

Press the Insert part button.

Select the luxrender project, and press the Render button.

Luxrender works differently than povray. When you start the render, the luxrender application will open and immediately start rendering:

If you leave that window open,Luxrender will continue calculating and rendering forever, progressively refining the image. It is up to you to decide when the image has reach a sufficient quality for your needs, and stop the render.

There are also many controls to play with, on the left panel. All these controls will change the aspect of the image being rendered on the fly, without stopping the rendering.

When you feel the quality is good enough, simply press Render->stop, and then File->Export to image->Tonemapped low dynamic range to save the rendered image to a png file.

You can extend greatly the render possibilities of FreeCAD by creating new templates for povray or luxrender. This is explained in the Raytracing Workbench documentation.

Downloads

The table model: https://github.com/yorikvanhavre/FreeCAD-manual/blob/master/files/table.FCStd

The file produced during this exercise: https://github.com/yorikvanhavre/FreeCAD-manual/blob/master/files/render.FCStd

Read more

The Raytracing Workbench: http://www.freecadweb.org/wiki/index.php?title=Raytracing_Module

Blender: http://www.blender.org

POV-Ray: http://www.povray.org

Luxrender: http://www.luxrender.net

Python scripting

A gentle introduction

Python is a widely popular, open-source programming language, very often used as a scripting language, embedded in applications, as this is the case with FreeCAD. It also has a series of features that makes it specially interesting for us FreeCAD users: It is very easy to learn, specially for people who had never programmed before, and it is embedded in many other applications, which makes it a very valuable tool to learn, as you will be able to use it in many other applications, such as Blender, Inkscape or GRASS.

FreeCAD makes an extensive use of Python. With it, you can access and control almost any feature of FreeCAD. You can for example create new objects, modify their geometry, analyze their contents, or even create new interface controls, tools and panels. Some workbenches of FreeCAD and most of the addon workbenches are fully programmed in python. FreeCAD has an advanced python console, available from menu View->Panels->Python console. It is often useful to perform operations for which there is no toolbar button yet, or to check shapes for problems, or to perform repetitive tasks:

But the python console also has another very important use: Everytime you press a toolbar button, or perform other operations in FreeCAD, some python code is printed in the console and executed. By leaving the Python console open, you can litterally see the python code unfold as you work, and in no time, almost without knowing it, you will be learning some python language.

FreeCAD also has a macros system, which allows you to record actions to be replayed later. This system also uses the Python console, by simply recording everything that is done in it.

In this chapter, we will discover very generally the Python language. If you are interested in learning more, the FreeCAD documentation wiki has an extensive section related to python programming.

Writing python code

There are two easy ways to write python code in FreeCAD: From the python console (menu View -> Panels -> Python Console), or from the Macro editor (menu Tools -> Macros -> New). In the console, you write python commands one by one, which are executed when you press return, while the macros can contain a more complex script made of several lines, which is executed only when the macro is launched from the same Macros window.

In this chapter, you will be able to use both methods, but it is highly recommended to use the Python Console, since it will immediately inform you of any error you could do while typing.

If this is the first time you are doing Python coding, consider reading this short introduction to Python programming before going further, it will make the basic concepts of Python clearer.

Manipulating FreeCAD objects

Let's start by creating a new empty document:

doc = FreeCAD.newDocument()

If you type this in the FreeCAD python console, you will notice that as soon as you type "FreeCAD." (the word FreeCAD followed by a dot), a windows pops up, allowing to quickly autocomplete the rest of your line. Even better, each entry in the autocomplete list has a tooltip explaining what it does. This makes it very easy to explore the functionality available. Before choosing "newDocument", have a look at the other options available.

As soon as you press Enter our new document will be created. This is similar to pressing the "new document" button on the toolbar. In Python, the dot is used to indicate something that is contained inside something else (newDocument is a function that is inside the FreeCAD module). The window that pops up therefore shows you everything that is contained inside "FreeCAD". If you would add a dot after newDocument, instead of the parentheses, it would show you everything that is contained inside the newDocument function. The parentheses are mandatory when you are calling a Python function, such as this one. We will illustrate that better below.

Now let's get back to our document. Let's see what we can do with it:

doc.

Explore the available options. Usually names that begin with a capital letter are attributes, they contain a value, while names that begin with small letter are functions (also called methods), they "do something". Names that begin with an underscore are usually there for the internal working of the module, and you shouldn't care about them. Let's use one of the methods to add a new object to our document:

box = doc.addObject("Part::Box","myBox")

Our box is added in the tree view, but nothing happens in the 3D view yet, because when working from Python, the document is never recomputed automatically. We must do that manually, whenever we need:

doc.recompute()

Now our box appeared in the 3D view. Many of the toolbar buttons that add objects in FreeCAD actually do two things: add the object, and recompute. If you turned on the "show script commands in python console" option above, try now adding a sphere with the appropriate button in the Part Workbench, and you will see the two lines of python code being executed one after the other.

You can get a list of all possible object types like Part::Box:

doc.supportedTypes()

Now let's explore the contents of our box:

box.

You'll immediately see a couple of very interesting things such as:

box.Height

This will print the current height of our box. Now let's try to change that:

box.Height = 5

If you select your box with the mouse, you will see that in the properties panel, under the Data tab, our Height property appears with the new value. All properties of a FreeCAD object that appear in the Data and View tabs are directly accessible by python too, by their names, like we did with the Height property. Data properties are accessed directly from the object itself, for example:

box.Length

View properties are stored inside a ViewObject. Each FreeCAd object possesses a ViewObject, which stores the vieual properties of the object. When running FreeCAD without its Graphical Interface (for example when launching it from a terminal with the -c command line option, or using it from another Python script), the ViewObject is not available, since there is no visual at all.

For example, to access the line color of our box:

box.ViewObject.LineColor

Vectors and Placements

Vectors are a very fundamental concept in any 3D application. It is a list of 3 numbers (x, y and z), describing a point or position in the 3D space. A lot of things can be done with vectors, such as additions, subtractions, projections and much more. In FreeCAD vectors work like this:

myvec = FreeCAD.Vector(2,0,0) print(myvec) prnimarkdownt(myvec.x) print(myvec.y) othervec = FreeCAD.Vector(0,3,0) sumvec = myvec.add(othervec)

Another common feature of FreeCAD objects is their Placement. As we saw in earlier chapters, each object has a Placement property, which contains the position (Base) and orientation (Rotation) of the object. It is easy to manipulate from Python, for example to move our object:

print(box.Placement) print(box.Placement.Base) box.Placement.Base = sumvec otherpla = FreeCAD.Placement() otherpla.Base = FreeCAD.Vector(5,5,0) box.Placement = otherpla

Read more

Python: https://www.python.org/

Working with Macros: http://www.freecadweb.org/wiki/index.php?title=Macros

Introduction to Python scripting: http://www.freecadweb.org/wiki/index.php?title=Introduction_to_Python

Using Python in FreeCAD: http://www.freecadweb.org/wiki/index.php?title=Python_scripting_tutorial

The Python scripting wiki hub: http://www.freecadweb.org/wiki/index.php?title=Power_users_hub

Creating and manipulating geometry

In the previous chapters, we learned about the different workbenches of FreeCAD, and that each of them implements its own tools and geometry types. The same concepts applies when working from Python code.

We also saw that the big majority of the FreeCAD workbenches depend on a very fundamental one: the Part Workbench. In fact, may other workbenches, such as Draft or Arch, do exactly what we will do in this chapter: They use Python code to create and manipulate Part geometry.

So the first thing we need to do to work with Part geometry, is to do the Python equivalent to switching to the Part Workbench: import the Part module:

import Part

Take a minute to explore the contents of the Part module, by typing Part. and browsing through the different methods offered there. The Part module offers several convenience fuctions such as makeBox, makeCircle, etc... which will instantly build an object for you. Try this, for example:

Part.makeBox(3,5,7)

When you press Enter after typing the line above, nothing will appear in the 3D view, but something like this will be printed on the Python Console:

<Solid object at 0x5f43600>

This is where an important concept takes place. What we created here is a Part Shape. It is not a FreeCAD document object (yet). In FreeCAD, objects and their geometry are independent. Think of a FreeCAD document object as a container, that will host a shape. Parametric objects will also have properties such as Length and Width, and will recalculate their Shape on-the-fly, whenever one of the properties changes.What we did here is calculate a shape manually.

We can now easily create a "generic" document object in the current document (make sure you have at least one new document open), and give it a box shape like we just made:

boxShape = Part.makeBox(3,5,7) myObj = FreeCAD.ActiveDocument.addObject("Part::Feature","MyNewBox") myObj.Shape = boxShape FreeCAD.ActiveDocument.recompute()

Note how we handled myObj.Shape, see that it is done exactly like we did in the previous chapter, when we changed other properties of an object, such as box.Height = 5. In fact, Shape is also a property, just like Height. Only it takes a Part Shape, not a number. In next chapter we will have a deeper look at how those parametric objects are constructed.

For now, let's explore our Part Shapes more in detail. At the end of the chapter about traditional modeling with the Part Workbench we showed a table that explains how Part Shapes are constructed, and their different components (Vertices, edges, faces, etc). The exact same components exist here and can be retrieved from Python. All Part Shape always have the following attributes:Vertexes, Edges, Wires, Faces, Shells and Solids. All of them are lists, that can contain any number of elements or be empty: