[WIP] Tutorial: FreeCAD console mode (-c or --console) Tips and Tricks

[Kunda1]

Starting a thread to accumulate interesting tips and tricks to run FreeCAD without the GUI. Please share you favorite tips/tricks in this thread.

To start FreeCAD in console mode (this will drop you in to a python shell)
Linux/MacOS

Code: Select all

freecadcmd
or 
freecad -c

Windows

Code: Select all

freecadcmd.exe
or 
freecad.exe -c

AppImage
The AppImage may not find certain modules, so it's possible to use the -M <path-to-system-python-modules> flag which directs it to use the system modules.

Code: Select all

# swap out for the correct path on your system
./FreeCAD.AppImage -c -M /usr/lib/python3.7/site-packages

Unpacked Appimage (link)

Code: Select all

FreeCAD.AppImage --appimage-extract
cd squashfs-root/
# swap out for the correct path on your system
./AppRun -c -M /usr/lib/python3.7/site-packages 

----------------------------------------
What version of python is the shell running?

Code: Select all

import sys
print(sys.version)

On some systems using the delete key in the shell doesn't work. The solution for this is to import the readline module

Code: Select all

import readline

The FreeCAD python API is pretty awesome, lets access it:

Code: Select all

import FreeCAD

Note: you can be more efficient and concatenate imports all on one line

Code: Select all

import readline, FreeCAD

Print FreeCAD's version

Code: Select all

print(FreeCAD.Version())

The output above is a little hard to read. Lets make it more discernible using the prettyprint module

Code: Select all

import pprint
pprint.pprint(FreeCAD.Version())

Print your FreeCAD's User AppData directory. This is where FreeCAD saves configurations and addons among other things

Code: Select all

FreeCAD.getUserAppDataDir()

or save the AppData path to a variable to use later

Code: Select all

appdata = FreeCAD.getUserAppDataDir()
print(appdata)

Lets list all available functions for FreeCAD class. We'll use the builtin function dir()

Code: Select all

dir(FreeCAD)

The output above is a little hard to read. Lets make it more discernible again using the prettyprint

Code: Select all

pprint.pprint(dir(FreeCAD))

Lets choose a function available to FreeCAD class and learn what it does using the builtin python help() function. For example: ConfigDump

Code: Select all

help(FreeCAD.ConfigDump)

Lets print the contents of ConfigDump() shall we?

Code: Select all

print(FreeCAD.ConfigDump())
# aaaand lets use pprint again
pprint.pprint(FreeCAD.ConfigDump())

We can also drill down in to each of these functions available to FreeCAD class. For example we can take the ConfigDump function

Code: Select all

pprint.pprint(dir(FreeCAD.ConfigDump))

Lets make life easier and introduce a very powerful feature, command completion. We do this through the fancycompleter module

Code: Select all

import fancycompleter
fancycompleter.interact(persist_history=True)

Now instead of using the dir() function like we did above, we can type the command we want to explore and press <TAB> to list available commands

Code: Select all

FreeCAD.<TAB>

--------------------------------

We can import pretty much any workbench (Note: not all of them or their total functionalities are exposed to python)

Code: Select all

import Arch
import Draft
import Fem
import Part
import PartDesign
import Path
import Sketcher
import Spreadsheet
import TechDraw

Lets read more about how to access these workbenches

Code: Select all

help(FreeCAD)

ToDo:

• Print the contents of user.cfg (openBrain's script)
• How to print the About FreeCAD version info to console? <-- anyone know how to do this?
• How to print all the python api functions for each workbench? help(FreeCAD)
• How to import external workbenches and some examples
• more...

[vocx]

Code: Select all

freecadcmd

is equivalent to

Code: Select all

freecad -c

You don't need to add the -c option to the first executable, only to the second one, to start in console mode.

There's no point in "printing all functions of each workbench". What we need is documentation generated by Doxygen or Sphinx. Then the interested user can refer to it offline whenever he or she wishes.

[Kunda1]

You don't need to add the -c option to the first executable, only to the second one, to start in console mode.

Thx, fixed

There's no point in "printing all functions of each workbench". What we need is documentation generated by Doxygen or Sphinx. Then the interested user can refer to it offline whenever he or she wishes.

Is there a way to identify what functions we can run without the gui?

[vocx]

...
Is there a way to identify what functions we can run without the gui?

I don't think it's really possible in general, because a function in Python could be defined in any way.

Essentially, any function that doesn't manage the view provider of an object (something.ViewObject), or that doesn't operate the Coin3D scenegraph (FreeCADGui.ActiveDocument.ActiveView) can be used without the GUI.

What should probably exist is a standardized way, basically a programming convention among developers, to completely separate their non-GUI code from their GUI code. This is done in Draft, Arch, FEM, and others, but it is not perfectly done in all cases, and also documentation is missing on which functions work with and without the GUI. Essentially, workbench developers have complete freedom to implement their code how they want.

Precisely the long post I made in [Discussion] Splitting Draft tools into their own modules talks about separating the code into GUI and non-GUI parts. Then we can say that functions Draft/draftobjects/ will work always, while Draft/draftguitools, Draft/draftviewproviders, Draft/drafttaskpanels/, etc. will require the interface to work.

[Kunda1]

What should probably exist is a standardized way, basically a programming convention among developers, to completely separate their non-GUI code from their GUI code. This is done in Draft, Arch, FEM, and others, but it is not perfectly done in all cases, and also documentation is missing on which functions work with and without the GUI. Essentially, workbench developers have complete freedom to implement their code how they want.

Precisely the long post I made in [Discussion] Splitting Draft tools into their own modules talks about separating the code into GUI and non-GUI parts. Then we can say that functions Draft/draftobjects/ will work always, while Draft/draftguitools, Draft/draftviewproviders, Draft/drafttaskpanels/, etc. will require the interface to work.

Thanks for this elaborate reply and idea. We can make the Draft workbench a proof of concept of this moving forward.

[Kunda1]

Any tips/tricks you can share ?

[Joel_graff]

Any tips/tricks you can share ?

Nope. I never run FC headless, I'm afraid...

@vocx brings up a good point for better defining modules that do / don't require a GUI. Most of that is up to the dev to do for themselves, though. We can probably come up with a standardized way to encourage that (loosely enforce MVC, for example), but we'd need to get more rigorous about defining how to "design" code for FreeCAD... Which is a pretty big segue from what this topic is really all about.

[Kunda1]

Learned a crucial tip today.

Code: Select all

import fancycompleter
fancycompleter.interact(persist_history=True)

Now we have command completion!

[ezzieyguywuf]

Nope. I never run FC headless, I'm afraid...

@vocx brings up a good point for better defining modules that do / don't require a GUI. Most of that is up to the dev to do for themselves, though. We can probably come up with a standardized way to encourage that (loosely enforce MVC, for example), but we'd need to get more rigorous about defining how to "design" code for FreeCAD... Which is a pretty big segue from what this topic is really all about.

This should be generally solvable using Init.py vs InitGui.py.

In other words, a dev should prefer to import/define things in Init.py until the can't (since it requires Gui), at which point they move that import/definition to InitGui.py

For example, let's say you were re-writing the Part workbench in pure Python - all of the Features (PartFeature, FeatureBox, FeatureCylinder, etc...) would be described in Init.py, since they don't need a Gui to be useful.

All the view provider stuff, and indeed the "Workbench" definition itself (which describes to toolbars, context menu, icons, etc) would be defered until InitGui.py

[Joel_graff]

For example, let's say you were re-writing the Part workbench in pure Python - all of the Features (PartFeature, FeatureBox, FeatureCylinder, etc...) would be described in Init.py, since they don't need a Gui to be useful.

That's a good point, though I debate how effective it would be. Until you mentioned it, I had no idea about using init.py rather than init_gui.py.

I suppose it should be a recommended best practice with some good examples. I would certainly incorporate that into what I'm doing with Workbench-Starterkit.