FreeCAD external editor with Code – OSS

I’m not a big fan of M$ but Code – OSS is quite good and is the one I managed to set up with FreeCAD with a working debugger. I am very open to try another documented way if you have one to suggest !

Set up

To allow auto-completion and your linter like pylint to work partially you need to reference FreeCAD libraries. Examples below shows path for Arch/Manjaro with freecad-git installed. To get better auto-completion you can also add reference to freecad-stubs folder below I cloned it in my home git folder with git clone https://github.com/CyrilWaechter/freecad-stubs.git.

Open your working folder in Code – OSS eg. :
- macro folder : ~/.FreeCAD/Macro
- your in progress workbench folder
Create an .env file referencing FreeCAD lib folder and optionally your stubs folder :
FREECAD_LIB=/usr/lib/freecad/lib
FREECAD_STUBS=/home/<user>/git/freecad-stubs/out
PYTHONPATH=${FREECAD_MOD}:${FREECAD_LIB}:${PYTHONPATH}
(Note that on windows you need to replace : by ;)
If you use git, add .vscode and .env to gitignore to avoid dirtyness

.env file concept is explained in Code – OSS help : Environment variable definitions file.

~~Unfortunately auto-completion and linter do not work for everything eg. Part. Shall we generate stubs like Gui Talarico did for Revit API or is there a better way ?~~

Update: I have generated stubs with mypy stubgen. Still unperfect but far better than before. You might want to keep an eye on Vanuan freecad-python-stubs.

Use

Once set up you have multiple options :

Embedding FreeCAD
Use your script as a macro or as a full workbench

Embedding FreeCAD

As explained on the wiki page FreeCAD can be embedded in another application sharing the host event loop. Let’s take a very basic example of application with PySide2 on their website :

import sys

from PySide2.QtWidgets import QApplication, QLabel
                                                    
if __name__ == "__main__":
    app = QApplication(sys.argv)
    label = QLabel("Hello World")
    label.show()
    sys.exit(app.exec_())

Let’s replace the hello world label with the two lines from FreeCAD wiki and create a box :

import FreeCAD
import FreeCADGui
import Part

import sys

from PySide2.QtWidgets import QApplication


if __name__ == "__main__":

    app = QApplication(sys.argv)

    FreeCADGui.showMainWindow()
    
    doc = FreeCAD.newDocument()
    box = Part.makeBox(100, 100, 100)
    Part.show(box)

    sys.exit(app.exec_())

That’s it, nothing more. The sad thing is that I don’t know yet how to interact with an already running application like you do with eg. Libre Office. Maybe with QProcess ? I saw multiple reference to this on Stackoverflow : Read output from python script in C++ Qt app, Communicating with QProcess Python program). I saw on FreeCAD forum that some people are doing it using a webserver : Re: Remote editor possible ?, Animate – Server. But for good reason or not it seems weird to me to use a webserver to communicate between 2 local applications.

Macro / workbench

Nothing much to say here. As you modify you macro or workbench you can then use it in FreeCAD as usual.

Debugging

Embedding FreeCAD

As you embed FreeCAD in your own application you can use your usual debugger.

Macro / workbench

To debug a script running from FreeCAD check Debugging wiki page. I described the process for Code – OSS at Visual Studio Code (VS Code) paragraph. You need ptvsd installed :

pip install ptvsd

Add a piece of code to your script :

import ptvsd
print("Waiting for debugger attach")
# 5678 is the default attach port in the VS Code debug configurations
ptvsd.enable_attach(address=('localhost', 5678), redirect_output=True)
ptvsd.wait_for_attach()

And add a new debug configuration : Debug → Add Configurations…

    "configurations": [
        {
            "name": "Python: Attacher",
            "type": "python",
            "request": "attach",
            "port": 5678,
            "host": "localhost",
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "."
                }
            ]
        },

Then start your script from FreeCAD which freeze waiting for the debugger to start.

Video demo

23 comments

Jérôme Puttemans says:

15 February 2021 at 22 h 42 min

Hi,
as lots of people in the freecad forum use Windows, maybe you should add a note telling them to use ; instead of : for the PYTHONPATH like this to help them:

PYTHONPATH=${FREECAD_MOD};${FREECAD_LIB};${PYTHONPATH}

Reply
1. Cyril Waechter says:
  
  15 February 2021 at 22 h 50 min
  
  Hi,
  True. Thanks for noticing it.
  
  Reply
j.M. Cornil says:

16 February 2021 at 16 h 57 min

Hello

I tried the second method and installed ptvsd with pip, but when I launch a macro within FreeCAD, I get the message on the import line :
No module named ‘ptvsd’

I get not this message if I start a script from VS-Code, which proves that ptvsd exists !

May be a problem of path for FreeCAD but where ?

Thanks in advance

Reply
1. Cyril Waechter says:
  
  16 February 2021 at 17 h 21 min
  
  Hello,
  I assume FreeCAD uses its own python interpreter. ptvsd installed from pip is in system_python_folder/site-packages while FreeCAD is looking in its own FreeCAD_python_folder/site-packages. You can copy / link ptvsd folder into freecad python folder if python version is compatible. I think pip is also somewhere in packaged FreeCAD you can use this pip instead of system one to install ptvsd again.
  
  Reply
Juan says:

1 March 2021 at 20 h 06 min

Hi, first thank you for your time! Then sorry for me being so noob… to the point..
Regarding the .env file in Windows? I did the clone for the freecad stubs, but Im not sure if Im inserting correctly the path. I tried different ways with no luck. Also, the freecad lib path, does it has to point to freecad instalation? or do I need the download the source code?

Thank you! traing to get started with Macros and I was just looking how to use VS Code + QT Designer, so this document is just what I needed.

Reply
Juan says:

1 March 2021 at 20 h 07 min

sorry, forgot to paste my .env file

FREECAD_LIB=”C:/Program Files/FreeCAD_0.19.23546-Win-Conda_vc14.x-x86_64/lib”
FREECAD_STUBS=”C:/Users/jmmartin/Documents/JM/Python/freecad-stubs”
PYTHONPATH=${FREECAD_MOD};${FREECAD_LIB};${PYTHONPATH}

Reply
1. Cyril Waechter says:
  
  5 March 2021 at 14 h 21 min
  
  Hi Juan,
  On windows, my env path looks like this :
  FREECAD="C:\\tools\\FreeCAD_0.19.22894_Win-LPv12.1.6_vc14.x-x86-64\\bin" FREECADMOD="C:\\tools\\FreeCAD_0.19.22894_Win-LPv12.1.6_vc14.x-x86-64\\Mod" FREECADSTUBS="C:\\git\\freecad-stubs\\out" PYTHONPATH=${FREECADSTUBS};${FREECADMOD};${FREECAD};${PYTHONPATH}
  The subfolder out is missing in your .env file. It might solve your issue.
  
  Reply
  1. Juan Manuel Martin says:
    
    7 March 2021 at 21 h 31 min
    
    Thank Cyril,
    
    Now it looks like this:
    
    FREECAD_LIB=”C:\\Program Files\\FreeCAD_0.19.23546-Win-Conda_vc14.x-x86_64\\lib”
    FREECAD_MOD=”C:\\Program Files\\FreeCAD_0.19.23546-Win-Conda_vc14.x-x86_64\\Mod”
    FREECAD_STUBS=”C:\\Users\\jmmartin\\Documents\\JM\\Python\\freecad-stubs\\out”
    PYTHONPATH=${FREECADSTUBS};${FREECADMOD};${FREECAD};${PYTHONPATH}
    
    But Im not sure if its working. Im not having any auto complete from FreeCAD commands. Which could be a simple test to know if its working. Again sorry for being so noob. (both python and macros in FreeCAD).
    
    Reply
Pingback: python-materialsdb – Python HVAC
Abbas says:

3 July 2021 at 18 h 11 min

I really need to use an external editor and I have read this article over and over. It looks like that the key point is to set correct addresses in the .env file…
I have installed FreeCAD 0.19 on my windows10 with the installer exe file. I have these folders:
C:\Program Files\FreeCAD 0.19\lib and C:\Program Files\FreeCAD 0.19\bin\Lib
C:\Program Files\FreeCAD 0.19\Mod
there is no stubs folder!

I’ve tried many combinations of LIB, MOD and STUBS addresses… I don’t know “/” is correct or “\\”…
PLEASE HELP ME!

Reply
1. Cyril Waechter says:
  
  4 July 2021 at 11 h 44 min
  
  As explained in the article in Set up part stubs are not part of FreeCAD. You need to clone it from https://github.com/CyrilWaechter/freecad-stubs.git
  Also check previous comments which show an example of paths to put in `.env`
  
  Reply
Abbas says:

4 July 2021 at 16 h 27 min

Sir, You are a expert in programming. I’m just a mechanical engineer who is trying to use python in FreeCAD. I know Very little compared to you!
This is a complicated subject for me But I need it badly. 🙁

I copied stubs folder as below and used instruction and comments. still, is not working! here is my .env file:

FREECAD_LIB=”C:\\Program Files\\FreeCAD 0.19\\lib”
FREECAD_MOD=”C:\\Program Files\\FreeCAD 0.19\\Mod”
FREECAD_STUBS=”C:\\Program Files\\FreeCAD 0.19\\freecad-stubs-master”
PYTHONPATH=${FREECAD_STUBS};${FREECAD_MOD};${FREECAD_LIB};${PYTHONPATH}

what is wrong with it? Please Help me!

Reply
1. Cyril Waechter says:
  
  5 July 2021 at 10 h 25 min
  
  Sir, I am just an just an HVAC / thermal and energy engineering specialist. Take a look at my first script on this blog you will see that I started with very simple ones.
  Your freecad stubs folder is wrong. You need to target the `out` subfolder. Try replacing FREECAD_STUBS= C:\\Program Files\\FreeCAD 0.19\\freecad-stubs-master by FREECAD_STUBS= C:\\Program Files\\FreeCAD 0.19\\freecad-stubs-master\out.
  Why is there a » before C:\\ ?
  
  Reply
Abbas says:

5 July 2021 at 19 h 58 min

I searched for library folders and put the addresses in the .env file. This is how It solved the freaky yellow underline errors.

FREECAD_LIB=C:\Program Files\FreeCAD 0.19\bin
FREECAD_LIB_two=C:\Program Files\FreeCAD 0.19\lib
FREECAD_LIB_three=C:\Program Files\FreeCAD 0.19\Ext
FREECAD_MOD=C:\Program Files\FreeCAD 0.19\Mod
FREECAD_MOD_two=C:\Users\Abbas\AppData\Roaming\FreeCAD\Mod\A2plus
FREECAD_STUBS=C:\Program Files\FreeCAD 0.19\freecad-stubs-master\out
PYTHONPATH=${FREECAD_LIB};${FREECAD_LIB_two};${FREECAD_LIB_three};${FREECAD_MOD};${FREECAD_MOD_two};${FREECAD_STUBS};${PYTHONPATH}

Now I get this error:
Exception has occurred: ImportError
Module use of python38.dll conflicts with this version of Python.
File “E:\Saved Files\FreeCAD\Macro\Four_Link.py”, line 11, in
import FreeCAD

Should I use Python 3.8 to solve this problem?

Reply
1. Cyril Waechter says:
  
  5 July 2021 at 20 h 01 min
  
  Yes, you need to use same version of python packaged with FreeCAD. You can set your interpreter in VSCode to the one in freecad\bin folder.
  
  Reply
  1. Wolfgang Spang says:
    
    8 July 2021 at 8 h 09 min
    
    Ich habe auch Problem den vs-Code Editor mit FreeCad0.19 zu verbinden.
    OS: Windows 10 Version 2009
    Word size of OS: 64-bit
    Word size of FreeCAD: 64-bit
    Version: 0.19.24291 (Git)
    Build type: Release
    Branch: releases/FreeCAD-0-19
    Hash: 7b5e18a0759de778b74d3a5c17eba9cb815035ac
    Python version: 3.8.6+
    Qt version: 5.15.2
    Coin version: 4.0.1
    OCC version: 7.5.0
    Locale: German/Germany (de_DE)
    
    FreeCad Python 3.8.6+ 64bit Version. Einstellung in vs-Editor Python 3.8.6 64-bit (FreeCad 0.19)
    ***
    .env Datei –FC.env –Inhalt
    FREECAD_BIN=”C:\\Program Files\\FreeCAD 0.19\\bin”
    FREECAD_MOD= “C:\\Program Files\\FreeCAD 0.19\\Mod”
    FREECAD_STUBS= “C:\\Users\\wrs53\\AppData\Roaming\\FreeCAD\\freecad-stubs\\out”
    PYTHONPATH= ${env:FREECAD_STUBS}; ${env:FREECAD_MOD}; ${env:FREECAD_BIN}; ${env:PYTHONPATH}
    ***
    setting.json — Inhalt: {“Python.envFile”: “${workspaceFolder}/FC.env”}
    ***
    launch.json — Inhalt:
    {
    “configurations”: [
    {
    “name”: “Python: Aktuelle Datei”,
    “type”: “python”,
    “request”: “launch”,
    “program”: “${file}”,
    “console”: “integratedTerminal”
    }
    ]
    }
    ***
    beim import FreeCAD — Fehlermeldung
    Ich weis nicht was noch fehlt.
    
    Reply
    1. Cyril Waechter says:
      
      8 July 2021 at 9 h 02 min
      
      My German is not good enough. Why do you add a env: before every name in PYTHONPATH ?
      
      Reply
      1. Spang says:
        
        9 July 2021 at 10 h 13 min
        
        Das mit dem env: habe ich wo gelesen.
        
        PYTHONPATH= ${FREECAD_STUBS}; ${FREECAD_MOD}; ${FREECAD_BIN}; ${PYTHONPATH}
        Aber bei dem Zeichen $ bekomme ich einen SyntaxError: invalid syntax.
  2. Abbas says:
    
    11 July 2021 at 17 h 45 min
    
    Hi,
    Thank 10^6 for your help.
    Since then I have yellow underline error again for PySide2!!! it says:
    
    PySide2 is not accessed Pylance
    import “Pyside2.QtWidgets” could not be resolved Pylance(reportMissingImports)
    
    I’ve added these to .env file:
    FREECAD_LIB_four=C:\Program Files\FreeCAD 0.19\bin\Lib\site-packages
    FREECAD_LIB_five=C:\Users\Abbas\AppData\Local\Programs\Python\Python38\Lib\site-packages
    
    But it’s not helping!
    What I’m missing now?
    
    Reply
    1. Abbas says:
      
      11 July 2021 at 19 h 17 min
      
      Solved! very stupid of me… it was “S” in “PySide”…
      
      Reply
Wolfgang Spang says:

9 July 2021 at 10 h 59 min

Das mit dem env: habe ich gelesen, hat aber nix gebracht.

PYTHONPATH= ${FREECAD_STUBS}; ${FREECAD_MOD}; ${FREECAD_BIN}; ${PYTHONPATH}
^
SyntaxError: invalid syntax für $

Reply
Naresh says:

11 January 2022 at 17 h 16 min

Hi Cyril, thank you very much for your article, it is very useful. I am attempting to implement the embedding method on a Mac running Monterey 12.0.1 and my FreeCAd version is 0.19. When I am attempting to run the embedding.py file in VSCode I encounter this error:

“ModuleNotFoundError: No module named ‘FreeCAD'”

Do you have any advice on what may be causing this? I have double-checked my paths in the .env file which are shown below but I suspect that there must be an error:

FREECAD_LIB=/Applications/FreeCAD.app/Contents/Resources/lib
FREECAD_MOD=/Applications/FreeCAD.app/Contents/Resources/Mod

Any reccomendations would be appreciated!

Reply
1. Cyril Waechter says:
  
  14 January 2022 at 15 h 58 min
  
  I am not familiar with macOS. Is there a `FreeCAD.so` or `FreeCAD.dylib` in your `/Applications/FreeCAD.app/Contents/Resources/lib`? As a workaround and to check if there is an issue in your `.env` file you can add the folder to python path inside your script:
  “`python
  import sys
  sys.path.append(r”/Applications/FreeCAD.app/Contents/Resources/lib”)
  “`
  
  Reply

Set up

Use

Embedding FreeCAD

Macro / workbench

Debugging

Embedding FreeCAD

Macro / workbench

Video demo

23 comments

Leave a Reply Cancel reply