Scripted objects/fr

Outre les types d'objets standards tels que les annotations, les mailles et les objets Parts, FreeCAD offre également la possibilité incroyable d'écrire des scripts d'objets  100% Python. Ces "objets" se comporteront exactement comme n'importe quels autres objets dans FreeCAD, et sont, sauvegardés et restaurés automatiquement dans le répertoire de chargement/sauvegarde.

Une particularité doit être comprise, ces objets sont enregistrés dans des fichiers FreeCAD FcStd avec le module Python json '. Ce module transforme un objet (code) Python en une chaîne de caractères (texte), lui permettant d'être ajouté au fichier sauvegardé. Une fois chargé, le module json utilise cette chaîne pour recréer l'objet d'origine, à condition qu'il ait accès au code source qui l'a créé. Cela signifie que si vous enregistrez un tel objet personnalisé et l'ouvrez sur une machine où le code source Python qui a créé l'objet n'est pas présent, l'objet ne sera pas recréé.

Si vous distribuez ces scripts à d'autres, vous devrez aussi distribuer l'ensemble du script Python qui l'a créé.

Les fonctionnalités de Python suivent les mêmes règles que toutes les fonctionnalités de FreeCAD: ils sont séparés en plusieurs parties celle App (application) et GUI parts (interface graphique).

La partie Object App (application), définit la forme géométrique de notre objet, tandis que la partie graphique (GUI), définit la façon dont l'objet sera affiché à l'écran.

L'outil View Provider Object (créateur de vue), comme toutes les fonctions FreeCAD, n'est disponible que lorsque vous exécutez FreeCAD dans son interface (GUI).

Il ya plusieurs manières et méthodes disponibles pour créer votre projet. Les méthodes utilisées doivent êtres une des méthodes prédéfinies que vous fourni FreeCAD, et apparaîtra dans la fenêtre Propriété, afin qu'ils puissent être modifiés par l'utilisateur (onglet Données).

De cette manière, les objets sont FeaturePython (ont toutes les propriétés de Python) et sont totalements paramétriques.

Vous pouvez paramétrer les propriétés et l'affichage ViewObject de l'objet séparément.

 Astuce: dans les versions antérieures, nous avons utilisé le module Python cPickle. Cependant, ce module exécute du code arbitrairement et provoque ainsi des problèmes de sécurité. Alors, nous avons opté pour le module Python json.

Exemples de base
L'exemple suivant (portion) peut être trouvé sur la page, src/Mod/TemplatePyMod/FeaturePython.py qui inclus beaucoup d'autres exemples:

Things to note
If your object relies on being recomputed as soon as it is created, you must do this manually in the function as it is not called automatically. This example does not require it because the method of the  class has the same effect as the  function, but the examples below rely on being recomputed before anything is displayed in the 3D view. In the examples, this is done manually with but in more complex scenarios you need to decide where to recompute either the whole document or the FeaturePython object.

This example produces a number of exception stack traces in the report view window. This is because the method of the  class is called each time a property is added in. When the first one is added, the Width and Height properties don't exist yet and so the attempt to access them fails.

Une explication de et  se trouve dans le fil de discussion du forum obj.Proxy.Type is a dict, not a string.

Propriétés disponibles
Les propriétés sont les bases des FeaturePython objets. Grâce à elles, l'utilisateur est en mesure d'interagir et de modifier son objet. Après avoir créé un nouveau ObjetPython dans votre document ( obj = FreeCAD.ActiveDocument.addObject ("App :: FeaturePython", "Box") ), ses propriétés sont directement accessibles, vous pouvez obtenir la liste,

en faisant:

Et voici, la liste des propriétés disponibles:

Lors de l'ajout de propriétés à vos objets, prenez soin de ceci:
 * Ne pas utiliser de caractères "<" ou ">" dans les descriptions des propriétés (qui coupent des portions de code dans le fichier xml.Fcstd)
 * Les propriétés sont stockées dans un fichier texte .Fcstd.
 * Toutes les propriétés dont le nom vient après "Shape" sont triés dans l'ordre alphabétique, donc, si vous avez une forme dans vos propriétés, et comme les propriétés sont chargées après la forme, il peut y avoir des comportements inattendus!

Une liste complète des attributs de propriété est disponible dans le fichier d’en-tête PropertyStandard C++. Par exemple, si vous souhaitez autoriser l'utilisateur à saisir uniquement une plage de valeurs limitée (par exemple, à l'aide de PropertyIntegerConstraint), vous affecterez à Python un tuple contenant non seulement la valeur de la propriété, mais également les limites inférieure et supérieure, ainsi que l'incrément, comme ci-dessous :

Property Type
Par défaut, les propriétés peuvent être actualisées. Il est possible de rendre les propriétés en lecture seule, par exemple dans le cas ou l'on veut montrer le résultat d'une méthode. Il est également possible de cacher la propriété. Le type de propriété peut être définie à l'aide

Mode est un int court qui peut avoir la valeur: 0 -- mode par défaut, lecture et écriture 1 -- lecture seule 2 -- caché

Les EditorModes ne sont pas fixés dans le fichier reload de FreeCAD. Cela pourrait être fait par la fonction __setstate__. Voir http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=10#p108072 En utilisant les propriétés de setEditorMode vous ne savez que lire dans PropertyEditor. Les propriétés pourraient encore être modifiées à partir d'une commande Python. Pour faire une lecture seul le réglage doit être transmis directement à la fonction d'ajout de propriété. Voir le topic http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=20#p109709 pour voir un exemple.

En utilisant le paramètre direct dans la fonction addProperty, vous avez également plus de possibilités. En particulier, un point intéressant est de marquer une propriété en tant que propriété en sortie. De cette façon, FreeCAD ne marquera pas la fonctionnalité comme étant touchée lors de la modification (inutile donc de recalculer).

Exemple de sortie de property (see also https://forum.freecadweb.org/viewtopic.php?t=24928):

Les types de propriétés pouvant être définis au dernier paramètre de la fonction addProperty sont les suivants: 0 - Prop_None, pas de type de propriété spécial 1 - Prop_ReadOnly, la propriété est en lecture seule dans l'éditeur 2 - Prop_Transient, la propriété ne sera pas sauvegardée dans un fichier 4 - Prop_Hidden, la propriété n'apparaîtra pas dans l'éditeur 8 - Prop_Output, modifier la propriété ne touche pas son conteneur parent 16 - Prop_NoRecompute, modifier la propriété ne touche pas son conteneur pour le recalcul

Vous pouvez trouver ces différents types de propriétés définis dans source code C++ header for PropertyContainer

Autres exemples plus complexes
Cet exemple utilise le module Atelier Part pour créer un octaèdre, puis crée sa représentation coin avec pivy

En premier, c'est l'objet document lui-même:

Puis, nous avons view provider object, qui est responsable d'afficher l'objet dans la scène 3D (votre projet à l'écran):

Enfin, une fois que notre objet et son viewobject sont définis, nous n'avons qu'a les appeler:

Création d'objets sélectionnables
Si vous voulez travailler sur un objet sélectionné, ou du moins une partie de celui-ci, vous cliquez sur l'objet dans la fenêtre, vous devez inclure la forme géométrique à l'intérieur d'un noeud SoFCSelection node.

Si votre objet a une représentation complexe, avec des widgets, des annotations, etc, vous pouvez n'inclure qu'une partie de celui-ci dans un SoFCSelection.

Tout ce qui est SoFCSelection est constamment "scanné" par FreeCAD pour voir s'il est sélectionné/présélectionné, il est donc logique de ne rien surcharger avec des scans inutiles.

Voici un exemple de ce que vous devrez faire pour inclure un self.face:

Vous créez Simplement un SoFCSelection node (noeud), puis vous lui ajoutez vos noeuds géométriques, alors seulement vous l'ajoutez à votre noeud principal, au lieu d'ajouter vos noeuds géométriques directement.

Travailler avec des formes simples
Si votre objet paramétrique renvoie simplement une forme, vous n'avez pas besoin d'utiliser un objet créateur de vue (view provider object).

La forme sera affichée à l'aide du module standard de représentation des formes de FreeCAD:

Même code en utilisant ViewProviderLine

Plus d'informations
Quelques discussions intéressantes sur le forum à propos des objets scriptés:

- Python object attributes lost at load

- New FeaturePython is grey

- Eigenmode frequency always 0?

- how to implement python feature's setEdit properly?

En plus de ces exemples, vous pouvez voir dans le code source de FreeCAD src/Mod/TemplatePyMod/FeaturePython.py pour plus d'exemples.