Power users hub: Difference between revisions

From FreeCAD Documentation
(Scripted objects migration: how to migrate old scripted objects to a new class.)
mNo edit summary
(32 intermediate revisions by 11 users not shown)
Line 1: Line 1:
<languages/>
<languages/>
{{TOCright}}
[[Image:Power_user_hub.png|64px]]
----
<translate>
<translate>

<!--T:1-->
[[Image:Crystal_Clear_app_terminal.png|right|150]]


<!--T:2-->
<!--T:2-->
This is the place to come if you want to have a deeper insight into FreeCAD. Here you can learn about customizing FreeCAD for your needs.
This is the place to come if you are an experienced user and want to learn more about customizing and extending FreeCAD.

<!--T:4-->
FreeCAD is extensible by [[Python|Python]] code that is run directly in the [[Python_console|Python console]], or that is loaded from modules at startup. This means that you can modify FreeCAD without needing to recompile the program. For example, you can:
* '''Create and modify geometry''': you can create a new object type, either from scratch or by adapting an existing type.
* '''Create custom tools and commands''': add your own set of tools that run your code.
* '''Modify the interface''': create toolbars to put your tools, create special windows, panels, or interfaces for interacting with your tools.
*'''Modify the scenegraph representation''': FreeCAD has separate processes for building up the geometry and displaying that geometry on screen. You have full access to the way the scene contents are displayed on screen, therefore you can modify that representation, interact with it, or add custom behaviour to it. You can also add custom screen widgets, like information, draggers, anchors or temporary entities.


<!--T:3-->
<!--T:3-->
If you'd like to contribute content to these pages, request a wiki account with editor permissions [https://forum.freecadweb.org/viewtopic.php?f=21&t=6830 in the forum], and read the [[WikiPages|WikiPages]] for the general guidelines that you should follow. For other ways to contribute with the project, see the [[Help_FreeCAD|Help FreeCAD]] page.
These pages are in early stage of development. If you can't find the information you are looking for, or have found useful information somewhere we have not linked to, then please leave a comment on the [http://forum.freecadweb.org/ forum], or, why not? [[Help_FreeCAD| Add some more content here yourself!]]

<!--T:4-->
One of the nicest features of FreeCAD is that you can script and extend it extremely far without the need to compile anything or touch the source code. All the scripting part is done in [http://en.wikipedia.org/wiki/Python_(programming_language) Python], a very powerful but simple programming language. With simple Python scripts, you have total access to about any part of FreeCAD. For example, you can:
* '''Create and modify geometry''': Is there a special object you need that's not present in the default FreeCAD installation? You can easily create a new object type, either from scratch or by adapting an existing type.
* '''Create custom tools and commands''': At the moment, FreeCAD already has extensive functionality, but there aren't many convenient tools and commands for the final user yet. But it is already easy to create your own sets of tools.
* '''Modify the interface''': The FreeCAD user interface is still very basic at this stage. But everything is there for you to extend it to your needs. You can, for example, create toolbars to put your own tools, create special panels for interacting with your tools, etc.
*'''Modify the scene representation''': FreeCAD has separate processes for building up and computing the geometry and displaying that geometry on your screen. You have full access to the way the scene contents are displayed on screen, therefore you can modify that representation, interact with it, or add all kinds of custom behaviours and screen widgets, like information, draggers, anchors or temporary entities.


== Customizing FreeCAD == <!--T:5-->
== Customizing FreeCAD == <!--T:5-->
Line 26: Line 26:
* [[Customize_Toolbars|Customize Toolbars]]
* [[Customize_Toolbars|Customize Toolbars]]
* [[Installing_more_workbenches|Installing more workbenches]]
* [[Installing_more_workbenches|Installing more workbenches]]
* [http://forum.freecadweb.org/viewtopic.php?t=10556 Plugin Loader]
* [https://github.com/FreeCAD/FreeCAD-addons Addons installer.FCMacro]


== Scripting in FreeCAD == <!--T:7-->
== Scripting in FreeCAD == <!--T:7-->


===General=== <!--T:8-->
===General=== <!--T:39-->

* [[Introduction to Python|Introduction to Python]] - See also other Python tutorials at the bottom of this page
<!--T:8-->
* [[Python scripting tutorial|FreeCAD scripting tutorial]] - A general look at python scripting in FreeCAD
* [[FreeCAD Scripting Basics|FreeCAD Scripting Basics]]: Well, the basics...
* [[Scripting_and_macros|Scripting and Macros]] - A list of relevant wiki pages
* [[Introduction_to_Python|Introduction to Python]] - See also other Python tutorials at the bottom of this page
* [[Gui Command|Gui Command]] : Adding custom commands to the GUI
* [[Python_scripting_tutorial|FreeCAD scripting tutorial]] - A general look at Python scripting in FreeCAD
* [[FreeCAD_Scripting_Basics|FreeCAD Scripting Basics]]: Well, the basics
* [[Manual:A_gentle_introduction|FreeCAD Manual - Section Python Scripting]]: Multi-chapter introduction to Python Scripting in FreeCAD
* [[Gui_Command|Gui Command]]: Adding custom commands to the GUI
* Using mixed [[Units|Units]] in FreeCAD
* Using mixed [[Units|Units]] in FreeCAD
* [[Profiling|Profiling]] the Python code
* [[Debugging#Python Debugging|Debugging]] the Python code
*[[Python_Development_Environment|Python Development Environment]] - A simplistic development environment for Python within FreeCAD


=== Modules === <!--T:28-->
=== Modules === <!--T:28-->
Line 47: Line 52:
* [[Workbench creation|Workbench creation]] shows you how to create your own workbench
* [[Workbench creation|Workbench creation]] shows you how to create your own workbench


====Working with Meshes==== <!--T:9-->
====Working with Meshes==== <!--T:40-->
* [[Mesh Scripting|Mesh Scripting]]: How to interact with the [[Mesh Module|Mesh Module]]


====Working with Parts==== <!--T:10-->
<!--T:9-->
* [[Mesh Scripting|Mesh Scripting]]: How to interact with the [[Mesh_Workbench|Mesh Workbench]]
* [[Part Module|The Part Module]]: How [http://en.wikipedia.org/wiki/Open_CASCADE Open CASCADE Technology] tools and structure is used in FreeCAD

====Working with Parts==== <!--T:41-->

<!--T:10-->
* [[Part_Workbench|The Part Workbench]]: How [http://en.wikipedia.org/wiki/Open_CASCADE Open CASCADE Technology] tools and structure is used in FreeCAD
* [[Topological data scripting|Topological data scripting]]: How to interact with the Part Module
* [[Topological data scripting|Topological data scripting]]: How to interact with the Part Module
* [[PythonOCC|PythonOCC]]: How to unleash the whole Open CASCADE power
* [[PythonOCC|PythonOCC]]: How to unleash the whole Open CASCADE power
* [[Mesh to Part|Mesh to Part]]: Converting between object types
* [[Mesh to Part|Mesh to Part]]: Converting between object types


====Accessing the Coin scenegraph==== <!--T:11-->
====Accessing the Coin scenegraph==== <!--T:42-->

<!--T:11-->
* [[Scenegraph|The Coin/Inventor scenegraph]]: How the FreeCAD scene representation works
* [[Scenegraph|The Coin/Inventor scenegraph]]: How the FreeCAD scene representation works
* [[Pivy|Pivy]]: How to access and modify the scenegraph
* [[Pivy|Pivy]]: How to access and modify the scenegraph


===Controlling the Qt interface=== <!--T:12-->
===Controlling the Qt interface=== <!--T:43-->

<!--T:12-->
* [[PySide|PySide]]: How to access the interface, and modify its contents
* [[PySide|PySide]]: How to access the interface, and modify its contents
* [[Embedding FreeCADGui|Using the FreeCAD GUI]] in another Qt application with PyQt
* [[Embedding FreeCADGui|Using the FreeCAD GUI]] in another Qt application with PyQt
Line 66: Line 79:
===Working with parametric objects=== <!--T:13-->
===Working with parametric objects=== <!--T:13-->


<!--T:35-->
* [[Scripted_objects|Scripted objects]]: how to make 100% Python-scripted objects.
* [[Scripted_objects|Scripted objects]]: how to make 100% Python-scripted objects.
** [[Scripted_objects_with_attachment|Scripted objects with attachment]]: how to make scripted objects attachable to other objects.
** [[Scripted_objects_with_attachment|Scripted objects with attachment]]: how to make scripted objects attachable to other objects.
** [[Scripted_objects_saving_attributes|Scripted objects saving attributes]]: how to save and restore attributes of the proxy class with {{incode|__getstate__}} and {{incode|__setstate__}}.
** [[Scripted_objects_migration|Scripted objects migration]]: how to migrate old scripted objects to a new class.
** [[Scripted_objects_migration|Scripted objects migration]]: how to migrate old scripted objects to a new class.
* [[Drawing Module|Drawing Module]]: Automating the 3D-to-2D process


===Examples=== <!--T:14-->
===Examples=== <!--T:44-->

<!--T:14-->
* [[Code snippets|Code snippets]] : A collection of pieces of FreeCAD Python code, to serve as ingredients in your scripts...
* [[Code snippets|Code snippets]] : A collection of pieces of FreeCAD Python code, to serve as ingredients in your scripts...
* [[Line drawing function|Line drawing function]]: How to build a simple tool to draw lines
* [[Line drawing function|Line drawing function]]: How to build a simple tool to draw lines
* [[Dialog creation|Dialog creation]]: How to construct dialogs with Qt designer, and use them in FreeCAD
* [[Dialog creation|Dialog creation]]: How to construct dialogs with Qt designer, and use them in FreeCAD
* [[Embedding FreeCAD|Embedding FreeCAD]]: How to import FreeCAD as a Python module in other applications
* [[Embedding FreeCAD|Embedding FreeCAD]]: How to import FreeCAD as a Python module in other applications
* The [[Draft Module|Draft Module]] adds basic 2d drawing functions to freecad. It is written entirely in Python, so it can be a good example if you want to write your own modules.
* The [[Draft_Workbench|Draft Workbench]] adds basic 2d drawing functions to freecad. It is written entirely in Python, so it can be a good example if you want to write your own modules.
* [[FreeCAD vector math library|FreeCAD vector math library]] : A couple of handy functions to manipulate FreeCAD vectors. This library is also included in the Draft module.
* [[FreeCAD vector math library|FreeCAD vector math library]] : A couple of handy functions to manipulate FreeCAD vectors. This library is also included in the Draft module.


Line 90: Line 106:


<!--T:18-->
<!--T:18-->
* [[Start up and Configuration|Start up and Configuration]]: Startup and command line options
* [[Start_up_and_Configuration|Start up and Configuration]]: Startup and command line options
* [[Install on Windows|Install on Windows]]: Using the windows installer
* [[Installing_on_Windows|Installing on Windows]]: Using the windows installer
* [[Compile_on_Windows|Compiling FreeCAD on Windows]] and [[Compile on Linux/Unix|Compiling FreeCAD on Linux]]
* [[Compile_on_Windows|Compiling FreeCAD on Windows]] and [[Compile_on_Linux|Compiling FreeCAD on Linux]]
* [[Branding|Branding]]: Simple modifications you can do to the source code to change some aspects of FreeCAD
* [[Branding|Branding]]: Simple modifications you can do to the source code to change some aspects of FreeCAD
* [[Extra python modules|Extra python modules]] : Extend the FreeCAD python interpreter with these powerful modules!
* [[Extra_python_modules|Extra python modules]] : Extend the FreeCAD python interpreter with these powerful modules!


== Python tutorials == <!--T:19-->
== Python tutorials == <!--T:19-->
Line 103: Line 119:
<!--T:21-->
<!--T:21-->
'''Python'''
'''Python'''
* [https://docs.python.org/2.7/tutorial/index.html Official python tutorial] - A very complete tutorial for discovering python
* [https://docs.python.org/3/tutorial/index.html Official python tutorial] - A very complete tutorial for discovering python
* [http://en.wikibooks.org/wiki/Non-Programmer%27s_Tutorial_for_Python Non-programmer tutorial for python] - an excellent wikibook
* [https://en.wikibooks.org/wiki/Non-Programmer%27s_Tutorial_for_Python_3 Non-programmer tutorial for python] - an excellent wikibook
* [http://npt.cc.rsu.ru/user/wanderer/ODP/Python_for_Newbies.htm Python for newbies] - one big tutorial covering all the basics
* [http://npt.cc.rsu.ru/user/wanderer/ODP/Python_for_Newbies.htm Python for newbies] - one big tutorial covering all the basics


Line 119: Line 135:
The following two references are PyQt specific (not PySide) but may offer some information of use:
The following two references are PyQt specific (not PySide) but may offer some information of use:
* [http://www.cs.usfca.edu/~afedosov/qttut/ Basic PyQt tutorial] : A simple and short linux-based tutorial that will explain how to work with PyQt and Qt Designer
* [http://www.cs.usfca.edu/~afedosov/qttut/ Basic PyQt tutorial] : A simple and short linux-based tutorial that will explain how to work with PyQt and Qt Designer
* [http://vizzzion.org/?id=pyqt Programming Qt applications in python] : A more in-depth tutorial covering all the process of working with qt and python.
* [http://vizzzion.org/?id=pyqt Programming Qt applications in python] : A more in-depth tutorial covering all the process of working with qt and python


<!--T:23-->
<!--T:23-->
'''Pivy''' - How to interact with FreeCAD's 3D scenes
'''Pivy''' - How to interact with FreeCAD's 3D scenes
* [http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.108.947&rep=rep1&type=pdf Pivy - Embedding a Dynamic Scripting Language into a Scene Graph Library] : Thesis that explains Pivy in detail
* [http://pivy.coin3d.org/documentation/pycon Basic Pivy tutorial] : A very simple tutorial from the official Pivy site
* [http://ftp.ntua.gr/mirror/python/pycon/dc2004/papers/47/ High Level 3D Graphics Programming in Python] : Pivy example from Pycon 2004
* [http://www.google.com.br/url?sa=U&start=3&q=http://studierstube.icg.tu-graz.ac.at/doc/pdf/PivyStudierstubeTutorial.pdf&ei=XyC1Sc2wOeCKmQem_eHnBQ&usg=AFQjCNEYhb-0DcUc6OxFVijAe1epBb-4aA Introducing Pivy into studierstube] : A document that is not really a tutorial, but that illustrates well how Pivy works
* [https://www.semanticscholar.org/paper/Integrating-Pivy-into-Studierstube-4.2-Gruber/08c9a89c8326c87f81c2d83428029fbfb6c2ae64 Introducing Pivy into studierstube] [https://www.researchgate.net/publication/228737136_Integrating_Pivy_into_Studierstube_42 (Mirror)] : A paper that is not really a tutorial, but that illustrates well how Pivy works (requires an academic account)


== Community projects == <!--T:24-->
== Community projects == <!--T:24-->
Line 131: Line 148:
On the [[FreeCAD Community Portal|Community portal]], you can find other FreeCAD-based projects run by the FreeCAD users community. If you are starting a new FreeCAD project, be sure to list it there! We also have a page with things you can do if you would like to [[Help FreeCAD|Help FreeCAD]].
On the [[FreeCAD Community Portal|Community portal]], you can find other FreeCAD-based projects run by the FreeCAD users community. If you are starting a new FreeCAD project, be sure to list it there! We also have a page with things you can do if you would like to [[Help FreeCAD|Help FreeCAD]].


<!--T:32-->
<!--T:38-->
* [[Scientific_literature|Scientific literature]]: articles that reference or use the FreeCAD system in different ways.
{{Userdocnavi}}

<!--T:27-->
[[Category:Hubs]]


<!--T:33-->
[[Category:Poweruser Documentation]]


</translate>
</translate>
{{Powerdocnavi{{#translation:}}}}
[[Category:Hubs{{#translation:}}]]

Revision as of 07:03, 2 September 2022


This is the place to come if you are an experienced user and want to learn more about customizing and extending FreeCAD.

FreeCAD is extensible by Python code that is run directly in the Python console, or that is loaded from modules at startup. This means that you can modify FreeCAD without needing to recompile the program. For example, you can:

  • Create and modify geometry: you can create a new object type, either from scratch or by adapting an existing type.
  • Create custom tools and commands: add your own set of tools that run your code.
  • Modify the interface: create toolbars to put your tools, create special windows, panels, or interfaces for interacting with your tools.
  • Modify the scenegraph representation: FreeCAD has separate processes for building up the geometry and displaying that geometry on screen. You have full access to the way the scene contents are displayed on screen, therefore you can modify that representation, interact with it, or add custom behaviour to it. You can also add custom screen widgets, like information, draggers, anchors or temporary entities.

If you'd like to contribute content to these pages, request a wiki account with editor permissions in the forum, and read the WikiPages for the general guidelines that you should follow. For other ways to contribute with the project, see the Help FreeCAD page.

Customizing FreeCAD

Scripting in FreeCAD

General

Modules

The functionality of FreeCAD is separated in Modules which deal with special data types and applications. FreeCAD has built-in modules and Extension Modules (plug-ins). Once plugin modules are installed, they become availible to you as easily as the built-in modules. The modules described below are the default modules, includeed in every FreeCAD installation.

  • The Builtin modules are the principal FreeCAD modules. They contain tools for manipulating general FreeCAD configurations, documents and their contents.
  • Workbench creation shows you how to create your own workbench

Working with Meshes

Working with Parts

Accessing the Coin scenegraph

Controlling the Qt interface

Working with parametric objects

Examples

  • Code snippets : A collection of pieces of FreeCAD Python code, to serve as ingredients in your scripts...
  • Line drawing function: How to build a simple tool to draw lines
  • Dialog creation: How to construct dialogs with Qt designer, and use them in FreeCAD
  • Embedding FreeCAD: How to import FreeCAD as a Python module in other applications
  • The Draft Workbench adds basic 2d drawing functions to freecad. It is written entirely in Python, so it can be a good example if you want to write your own modules.
  • FreeCAD vector math library : A couple of handy functions to manipulate FreeCAD vectors. This library is also included in the Draft module.

API Functions

The complete API documentation of FreeCAD is located at http://www.freecadweb.org/api/ . It contains both C++ and Python APIs, and is not totally well formatted yet, which can be confusing when looking for python-only code. An easier to browse version can be found here. Note that it can be incomplete, since it is updated manually. For more accurate information, browse the modules directly from FreeCAD's Python console.

Related: Exposing C++ to Python

Advanced modification

Python tutorials

These are good generic tutorials, not specific to FreeCAD, that might interest you if you are totally new to python.

Python

PySide - How to create and manage FreeCAD's Qt UI interface from python

The following two references are PyQt specific (not PySide) but may offer some information of use:

Pivy - How to interact with FreeCAD's 3D scenes

Community projects

On the Community portal, you can find other FreeCAD-based projects run by the FreeCAD users community. If you are starting a new FreeCAD project, be sure to list it there! We also have a page with things you can do if you would like to Help FreeCAD.