Pivy/fr: Difference between revisions

From FreeCAD Documentation
(Created page with "[http://pivy.coin3d.org/ Pivy] est une bibliothèque de codes qui sert de passerelle entre Python et [http://www.coin3d.org Coin3d], la bibliothèque 3D de [[Scenegraph/fr|ren...")
No edit summary
 
(94 intermediate revisions by 6 users not shown)
Line 1: Line 1:
<languages/>
[http://pivy.coin3d.org/ Pivy] est une bibliothèque de codes qui sert de passerelle entre Python et [http://www.coin3d.org Coin3d], la bibliothèque 3D de [[Scenegraph/fr|rendu graphique]] utilisé par FreeCAD. Lors de l'importation dans l'interpréteur Python, Pivy permet de dialoguer immédiatement avec les procédures de Coin3d, tels que les vue3D, ou même d'en créer de nouvelles.<br />
Pivy est inclus d'origine dans l'installation FreeCAD.


{{Docnav/fr
The coin library is divided into several pieces, coin itself, for manipulating scenegraphs and bindings for several GUI systems, such as windows or, like in our case, qt. Those modules are available to pivy too, depending if they are present on the system. The coin module is always present, and it is what we will use anyway, since we won't need to care about anchoring our 3D display in any interface, it is already done by FreeCAD itself. All we need to do is this:
|[[Scenegraph/fr|Graphe de scène]]
<syntaxhighlight>
|[[PySide/fr|PySide]]
from pivy import coin
}}
</syntaxhighlight>
==Accessing and modifying the scenegraph==


{{TOCright}}
We saw in the [[Scenegraph]] page how a typical Coin scene is organized. Everything that appears in a FreeCAD 3D view is a coin scenegraph, organized the same way. We have one root node, and all objects on the screen are its children.


==Introduction==
FreeCAD has an easy way to access the root node of a 3D view scenegraph:
<syntaxhighlight>
sg = FreeCADGui.ActiveDocument.ActiveView.getSceneGraph()
print sg
</syntaxhighlight>
This will return the root node:
<syntaxhighlight>
<pivy.coin.SoSelection; proxy of <Swig Object of type 'SoSelection *' at 0x360cb60> >
</syntaxhighlight>
We can inspect the immediate children of our scene:
<syntaxhighlight>
for node in sg.getChildren():
print node
</syntaxhighlight>
Some of those nodes, such as SoSeparators or SoGroups, can have children themselves. The complete list of the available coin objects can be found in the [http://doc.coin3d.org/Coin/classes.html official coin documentation].


[[Pivy/fr|Pivy]] est une bibliothèque de liaison [[Python/fr|Python]] pour [https://github.com/coin3d Coin], la bibliothèque de rendu 3D utilisée dans FreeCAD pour afficher des éléments dans une [[3D_view/fr|3D vue]]. Coin est une implémentation open source de la spécification "Open Inventor" pour gérer les graphiques. Par conséquent, dans FreeCAD, les termes "Pivy", "Coin" ou "Open Inventor" se réfèrent essentiellement à la même chose.
Let's try to add something to our scenegraph now. We'll add a nice red cube:
<syntaxhighlight>
col = coin.SoBaseColor()
col.rgb=(1,0,0)
cub = coin.SoCube()
myCustomNode = coin.SoSeparator()
myCustomNode.addChild(col)
myCustomNode.addChild(cub)
sg.addChild(myCustomNode)
</syntaxhighlight>
and here is our (nice) red cube. Now, let's try this:
<syntaxhighlight>
col.rgb=(1,1,0)
</syntaxhighlight>
See? everything is still accessible and modifiable on-the-fly. No need to recompute or redraw anything, coin takes care of everything. You can add stuff to your scenegraph, change properties, hide stuff, show temporary objects, anything. Of course, this only concerns the display in the 3D view. That display gets recomputed by FreeCAD on file open, and when an object needs recomputing. So, if you change the aspect of an existing FreeCAD object, those changes will be lost if the object gets recomputed or when you reopen the file.


Lorsqu'il est importé dans un interpréteur Python en cours d'exécution, Pivy nous permet de communiquer directement avec n'importe quel Coin [[Scenegraph/fr|Graphe de scène]], tel que la [[3D_view/fr|vue 3D]], ou même d'en créer de nouveaux. Pivy n'est pas nécessaire pour compiler FreeCAD, mais il est requis lors de l'exécution lors de l'exécution d'établis basés sur Python qui créent des formes à l'écran, comme [[Draft_Workbench/fr|Draft]] et [[Arch_Workbench/fr|Arch]]. Pour cette raison, Pivy est normalement installé lors de l'installation d'une distribution de FreeCAD.
A key to work with scenegraphs in your scripts is to be able to access certain properties of the nodes you added when needed. For example, if we wanted to move our cube, we would have added a SoTranslation node to our custom node, and it would have looked like this:
<syntaxhighlight>
col = coin.SoBaseColor()
col.rgb=(1,0,0)
trans = coin.SoTranslation()
trans.translation.setValue([0,0,0])
cub = coin.SoCube()
myCustomNode = coin.SoSeparator()
myCustomNode.addChild(col)
mtCustomNode.addChild(trans)
myCustomNode.addChild(cub)
sg.addChild(myCustomNode)
</syntaxhighlight>
Remember that in an openInventor scenegraph, the order is important. A node affects what comes next, so you can say something like: color red, cube, color yellow, sphere, and you will get a red cube and a yellow sphere. If we added the translation now to our existing custom node, it would come after the cube, and not affect it. If we had inserted it when creating it, like here above, we could now do:
<syntaxhighlight>
trans.translation.setValue([2,0,0])
</syntaxhighlight>
And our cube would jump 2 units to the right.
Finally, removing something is done with:
<syntaxhighlight>
sg.removeChild(myCustomNode)
</syntaxhighlight>
==Using callback mechanisms==


La bibliothèque Coin est divisée en plusieurs éléments, Coin lui-même pour manipuler les graphes de scènes et les liaisons pour plusieurs systèmes d'interface graphique, tels que Windows et Qt. S'ils sont présents sur le système, ces modules sont également disponibles pour Pivy. Le module Coin est toujours présent, et c'est ce que nous utiliserons de toute façon, car nous n'aurons pas besoin de nous soucier d'ancrer notre affichage 3D dans aucune interface, ce qui est déjà fait par FreeCAD. Tout ce que nous devons faire est ceci:
A [http://en.wikipedia.org/wiki/Callback_%28computer_science%29 callback mechanism] is a system that permits a library that you are using, such as our coin library, to call you back, that is, to call a certain function from your currently running python object. This is extremely useful, because that way coin can notify you if some specific event occurs in the scene. Coin can watch very different things, such as mouse position, clicks of a mouse button, keyboard keys being pressed, and many other things.


{{Code|code=
FreeCAD features an easy way to use such callbacks:
from pivy import coin
<syntaxhighlight>
}}
class ButtonTest:
def __init__(self):
self.view = FreeCADGui.ActiveDocument.ActiveView
self.callback = self.view.addEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(),self.getMouseClick)
def getMouseClick(self,event_cb):
event = event_cb.getEvent()
if event.getState() == SoMouseButtonEvent.DOWN:
print "Alert!!! A mouse button has been improperly clicked!!!"
self.view.removeEventCallbackSWIG(SoMouseButtonEvent.getClassTypeId(),self.callback)
ButtonTest()
</syntaxhighlight>
The callback has to be initiated from an object, because that object must still be running when the callback will occur.
See also a [[Code_snippets#Observing_mouse_events_in_the_3D_viewer_via_Python|complete list]] of possible events and their parameters, or the [http://doc.coin3d.org/Coin/classes.html official coin documentation].


==Graphe de scène==
== Documentation ==


Nous avons vu dans la page [[Scenegraph/fr|Graphe de scène]] comment une scène Coin typique est organisée. Tout ce qui apparaît dans une [[3D_view/fr|vue 3D]] est un Graphe de scène Coin organisée de la même manière. Nous avons un nœud racine et tous les objets à l'écran sont ses enfants.
Unfortunately pivy itself still doesn't have a proper documentation, but since it is an accurate translation of coin, you can safely use the coin documentation as reference, and use python style instead of c++ style (for example SoFile::getClassTypeId() would in pivy be SoFile.getClassId())


FreeCAD a un moyen facile d'accéder a la racine d'une scène 3D:
{{docnav|Scenegraph|PyQt}}


{{Code|code=
[[Category:Poweruser Documentation]]
sg = FreeCADGui.ActiveDocument.ActiveView.getSceneGraph()
print(sg)
}}


La racine de la scène 3D sera:
{{clear}}

<languages/>
{{Code|code=
<pivy.coin.SoSelection; proxy of <Swig Object of type 'SoSelection *' at 0x360cb60> >
}}

Vous pouvez inspecter immédiatement les enfants (branches) de la scène 3D:

{{Code|code=
for node in sg.getChildren():
print(node)
}}

Certains de ces nœuds, tels que {{incode|SoSeparator}} ou {{incode|SoGroup}}, peuvent avoir eux-mêmes des enfants. La liste complète des objets Coin est disponible dans la documentation officielle des Coin.

Maintenant essayons d'ajouter quelque chose à notre scène (projet).<br />
Nous allons ajouter un beau cube rouge:

{{Code|code=
col = coin.SoBaseColor()
col.rgb = (1, 0, 0)
cub = coin.SoCube()
myCustomNode = coin.SoSeparator()
myCustomNode.addChild(col)
myCustomNode.addChild(cub)
sg.addChild(myCustomNode)
}}

Maintenant, nous allons essayer ceci:

{{Code|code=
col.rgb = (1, 1, 0)
}}

Comme vous pouvez le voir, tout est toujours accessible et modifiable à la volée. Pas besoin de recalculer ou de redessiner quoi que ce soit, Coin s'occupe de tout. Vous pouvez ajouter des éléments à votre graphe de scène, modifier les propriétés, masquer des éléments, afficher des objets temporaires, n'importe quoi. Bien entendu, cela ne concerne que l'affichage dans la vue 3D. Cet affichage est recalculé par FreeCAD lors de l'ouverture d'un fichier et lorsqu'un objet doit être recalculé. Ainsi, si vous modifiez l'aspect d'un objet FreeCAD existant, ces modifications seront perdues si l'objet est recalculé ou lorsque vous rouvrez le fichier.

Comme déjà mentionné, dans un graphe de scène openInventor, l'ordre est important. Un nœud affecte ce qui vient ensuite. Par exemple, si nous voulons avoir la possibilité de déplacer notre cube, nous devrons ajouter un nœud {{incode|SoTranslation}} {{Emphasis|avant}} le cube:

{{Code|code=
col = coin.SoBaseColor()
col.rgb = (1, 0, 0)
trans = coin.SoTranslation()
trans.translation.setValue([0, 0, 0])
cub = coin.SoCube()
myCustomNode = coin.SoSeparator()
myCustomNode.addChild(col)
myCustomNode.addChild(trans)
myCustomNode.addChild(cub)
sg.addChild(myCustomNode)
}}

Pour déplacer notre cube, nous pouvons maintenant faire:

{{Code|code=
trans.translation.setValue([2, 0, 0])
}}

Enfin, supprimer quelque chose se fait avec:

{{Code|code=
sg.removeChild(myCustomNode)
}}
{{Top}}
==Rappels (callback)==

Un [https://fr.wikipedia.org/wiki/Fonction_de_rappel mécanisme de rappel] est un système qui permet à une bibliothèque, telle que notre bibliothèque Coin, de vous rappeler, c'est-à-dire d'appeler une certaine fonction depuis votre objet Python en cours d'exécution. De cette façon, Coin peut vous informer qu'un événement spécifique s'est produit dans la scène. Coin peut regarder des choses très différentes, telles que la position de la souris, les clics sur les boutons de la souris, les touches du clavier enfoncées et bien d'autres.

FreeCAD dispose d'un moyen facile pour utiliser ces rappels:

{{Code|code=
from pivy import coin

class ButtonTest:
def __init__(self):
self.view = FreeCADGui.ActiveDocument.ActiveView
self.callback = self.view.addEventCallbackPivy(coin.SoMouseButtonEvent.getClassTypeId(), self.getMouseClick)

def getMouseClick(self, event_cb):
event = event_cb.getEvent()
if event.getState() == coin.SoMouseButtonEvent.DOWN:
print("Alert!!! A mouse button has been improperly clicked!!!")
self.view.removeEventCallbackPivy(coin.SoMouseButtonEvent.getClassTypeId(), self.callback)

ButtonTest()
}}

Le rappel doit être initié à partir d'un objet, car cet objet doit toujours être en cours d'exécution lorsque le rappel se produit. Voir aussi une [[Code_snippets/fr#Observer_des_.C3.A9v.C3.A8nements_de_la_souris_dans_la_vue_3D_via_Python|liste complète des événements possibles et leurs paramètres]] ou dans la documentation officielle de Coin.
{{Top}}
==Documentation==

Malheureusement, Pivy n’a pas sa propre documentation. Cependant, puisqu'il s'agit d'un wrapper de la bibliothèque Coin, vous pouvez lire la référence C++ pour plus d'informations. Dans ce cas, vous devez traduire le style de nommage de la classe C++ comme vous la liriez en Python.

En C++:

{{Code|code=
SoFile::getClassTypeId()
}}

Dans Pivy:

{{Code|code=
SoFile.getClassId()
}}

* Page d'accueil de [https://github.com/coin3d Coin3D].
* Page d'accueil de [https://github.com/coin3d/pivy Pivy].
* Le [https://github.com/coin3d/coin/wiki wikiCoin3D], sur GitHub.
* La [https://github.com/coin3d/coin/wiki/Documentation documentation du wiki Coin3D], sur GitHub.
* La [https://coin3d.github.io/Coin/html/ Documentation Coin3D], dernière documentation Doxygen générée automatiquement.
* [https://webdocs.cs.ualberta.ca/~graphics/books/mentor.pdf (Open)Inventor Mentor] - recommandé.

=== Plus ancien ===

Ces liens fournissent une documentation de référence pour Coin v3.x. Les différences avec la v4.x sont minimes, elles peuvent donc toujours être utiles.

* [https://coin3d.bitbucket.io/Coin/index.html Documentation Coin3D], sur BitBucket.
* [https://grey.colorado.edu/coin3d/index.html Coin3D Documentation], à l'Université du Colorado.
* [https://mevislabdownloads.mevis.de/docs/current/MeVis/ThirdParty/Documentation/Publish/OpenInventorReference/index.html Ouvrir la documentation de référence Inventor], par MeVisLab.
{{Top}}

{{Docnav/fr
|[[Scenegraph/fr|Graphe de scène]]
|[[PySide/fr|PySide]]
}}

{{Powerdocnavi{{#translation:}}}}
[[Category:Developer Documentation{{#translation:}}]]
[[Category:Python Code{{#translation:}}]]

Latest revision as of 09:40, 30 December 2022

Introduction

Pivy est une bibliothèque de liaison Python pour Coin, la bibliothèque de rendu 3D utilisée dans FreeCAD pour afficher des éléments dans une 3D vue. Coin est une implémentation open source de la spécification "Open Inventor" pour gérer les graphiques. Par conséquent, dans FreeCAD, les termes "Pivy", "Coin" ou "Open Inventor" se réfèrent essentiellement à la même chose.

Lorsqu'il est importé dans un interpréteur Python en cours d'exécution, Pivy nous permet de communiquer directement avec n'importe quel Coin Graphe de scène, tel que la vue 3D, ou même d'en créer de nouveaux. Pivy n'est pas nécessaire pour compiler FreeCAD, mais il est requis lors de l'exécution lors de l'exécution d'établis basés sur Python qui créent des formes à l'écran, comme Draft et Arch. Pour cette raison, Pivy est normalement installé lors de l'installation d'une distribution de FreeCAD.

La bibliothèque Coin est divisée en plusieurs éléments, Coin lui-même pour manipuler les graphes de scènes et les liaisons pour plusieurs systèmes d'interface graphique, tels que Windows et Qt. S'ils sont présents sur le système, ces modules sont également disponibles pour Pivy. Le module Coin est toujours présent, et c'est ce que nous utiliserons de toute façon, car nous n'aurons pas besoin de nous soucier d'ancrer notre affichage 3D dans aucune interface, ce qui est déjà fait par FreeCAD. Tout ce que nous devons faire est ceci:

from pivy import coin

Graphe de scène

Nous avons vu dans la page Graphe de scène comment une scène Coin typique est organisée. Tout ce qui apparaît dans une vue 3D est un Graphe de scène Coin organisée de la même manière. Nous avons un nœud racine et tous les objets à l'écran sont ses enfants.

FreeCAD a un moyen facile d'accéder a la racine d'une scène 3D:

sg = FreeCADGui.ActiveDocument.ActiveView.getSceneGraph()
print(sg)

La racine de la scène 3D sera:

<pivy.coin.SoSelection; proxy of <Swig Object of type 'SoSelection *' at 0x360cb60> >

Vous pouvez inspecter immédiatement les enfants (branches) de la scène 3D:

for node in sg.getChildren():
    print(node)

Certains de ces nœuds, tels que SoSeparator ou SoGroup, peuvent avoir eux-mêmes des enfants. La liste complète des objets Coin est disponible dans la documentation officielle des Coin.

Maintenant essayons d'ajouter quelque chose à notre scène (projet).
Nous allons ajouter un beau cube rouge:

col = coin.SoBaseColor()
col.rgb = (1, 0, 0)
cub = coin.SoCube()
myCustomNode = coin.SoSeparator()
myCustomNode.addChild(col)
myCustomNode.addChild(cub)
sg.addChild(myCustomNode)

Maintenant, nous allons essayer ceci:

col.rgb = (1, 1, 0)

Comme vous pouvez le voir, tout est toujours accessible et modifiable à la volée. Pas besoin de recalculer ou de redessiner quoi que ce soit, Coin s'occupe de tout. Vous pouvez ajouter des éléments à votre graphe de scène, modifier les propriétés, masquer des éléments, afficher des objets temporaires, n'importe quoi. Bien entendu, cela ne concerne que l'affichage dans la vue 3D. Cet affichage est recalculé par FreeCAD lors de l'ouverture d'un fichier et lorsqu'un objet doit être recalculé. Ainsi, si vous modifiez l'aspect d'un objet FreeCAD existant, ces modifications seront perdues si l'objet est recalculé ou lorsque vous rouvrez le fichier.

Comme déjà mentionné, dans un graphe de scène openInventor, l'ordre est important. Un nœud affecte ce qui vient ensuite. Par exemple, si nous voulons avoir la possibilité de déplacer notre cube, nous devrons ajouter un nœud SoTranslation avant le cube:

col = coin.SoBaseColor()
col.rgb = (1, 0, 0)
trans = coin.SoTranslation()
trans.translation.setValue([0, 0, 0])
cub = coin.SoCube()
myCustomNode = coin.SoSeparator()
myCustomNode.addChild(col)
myCustomNode.addChild(trans)
myCustomNode.addChild(cub)
sg.addChild(myCustomNode)

Pour déplacer notre cube, nous pouvons maintenant faire:

trans.translation.setValue([2, 0, 0])

Enfin, supprimer quelque chose se fait avec:

sg.removeChild(myCustomNode)

En haut

Rappels (callback)

Un mécanisme de rappel est un système qui permet à une bibliothèque, telle que notre bibliothèque Coin, de vous rappeler, c'est-à-dire d'appeler une certaine fonction depuis votre objet Python en cours d'exécution. De cette façon, Coin peut vous informer qu'un événement spécifique s'est produit dans la scène. Coin peut regarder des choses très différentes, telles que la position de la souris, les clics sur les boutons de la souris, les touches du clavier enfoncées et bien d'autres.

FreeCAD dispose d'un moyen facile pour utiliser ces rappels:

from pivy import coin

class ButtonTest:
    def __init__(self):
        self.view = FreeCADGui.ActiveDocument.ActiveView
        self.callback = self.view.addEventCallbackPivy(coin.SoMouseButtonEvent.getClassTypeId(), self.getMouseClick) 

    def getMouseClick(self, event_cb):
        event = event_cb.getEvent()
        if event.getState() == coin.SoMouseButtonEvent.DOWN:
            print("Alert!!! A mouse button has been improperly clicked!!!")
            self.view.removeEventCallbackPivy(coin.SoMouseButtonEvent.getClassTypeId(), self.callback)

ButtonTest()

Le rappel doit être initié à partir d'un objet, car cet objet doit toujours être en cours d'exécution lorsque le rappel se produit. Voir aussi une liste complète des événements possibles et leurs paramètres ou dans la documentation officielle de Coin.

En haut

Documentation

Malheureusement, Pivy n’a pas sa propre documentation. Cependant, puisqu'il s'agit d'un wrapper de la bibliothèque Coin, vous pouvez lire la référence C++ pour plus d'informations. Dans ce cas, vous devez traduire le style de nommage de la classe C++ comme vous la liriez en Python.

En C++:

SoFile::getClassTypeId()

Dans Pivy:

SoFile.getClassId()

Plus ancien

Ces liens fournissent une documentation de référence pour Coin v3.x. Les différences avec la v4.x sont minimes, elles peuvent donc toujours être utiles.

En haut