Pivy/fr: Difference between revisions

From FreeCAD Documentation
(Created page with "Vous pouvez inspecter immédiatement les enfants (branches) de la scène 3D:")
mNo edit summary
(35 intermediate revisions by 5 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 />
{{docnav/fr|[[Scenegraph/fr|Graph de scène]]|[[PySide/fr|PySide]]}}

[https://bitbucket.org/Coin3D/pivy/src/default/ Pivy] est une bibliothèque de codes qui sert de passerelle entre Python et [https://bitbucket.org/Coin3D/coin/wiki/Home Coin3d], la bibliothèque 3D de [[Scenegraph/fr|rendu graphique]] utilisé dans 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.
Pivy est inclus d'origine dans l'installation FreeCAD.


Line 8: Line 11:
Le module '''coin''' est toujours présent, et de toute façon c'est lui que nous allons utiliser, nous n'aurons pas besoin de nous occuper de l'affichage 3D dans une interface, FreeCAD s'en occupe lui-même.<br />
Le module '''coin''' est toujours présent, et de toute façon c'est lui que nous allons utiliser, nous n'aurons pas besoin de nous occuper de l'affichage 3D dans une interface, FreeCAD s'en occupe lui-même.<br />
Tout ce que nous aurons à faire, c'est:
Tout ce que nous aurons à faire, c'est:
{{Code|code=
<syntaxhighlight>
from pivy import coin
from pivy import coin
}}
</syntaxhighlight>
==Accéder et modifier une scène graphique==
==Accéder et modifier une scène graphique==


Line 16: Line 19:


FreeCAD a un moyen facile d'accéder a la racine d'une scène 3D:
FreeCAD a un moyen facile d'accéder a la racine d'une scène 3D:
{{Code|code=
<syntaxhighlight>
sg = FreeCADGui.ActiveDocument.ActiveView.getSceneGraph()
sg = FreeCADGui.ActiveDocument.ActiveView.getSceneGraph()
print sg
print sg
}}
</syntaxhighlight>
La racine de la scène 3D sera:
La racine de la scène 3D sera:
{{Code|code=
<syntaxhighlight>
<pivy.coin.SoSelection; proxy of <Swig Object of type 'SoSelection *' at 0x360cb60> >
<pivy.coin.SoSelection; proxy of <Swig Object of type 'SoSelection *' at 0x360cb60> >
}}
</syntaxhighlight>
Vous pouvez inspecter immédiatement les enfants (branches) de la scène 3D:
Vous pouvez inspecter immédiatement les enfants (branches) de la scène 3D:
{{Code|code=
<syntaxhighlight>
for node in sg.getChildren():
for node in sg.getChildren():
print node
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].
Certains de ces nodes, comme '''SoSeparators''' ou '''SoGroups''', peuvent avoir des enfants eux-mêmes. La liste complète des '''coin objets''' disponibles peut être trouvée dans la documentation [https://coin3d.bitbucket.io/Coin/annotated.html official coin documentation].


Maintenant essayons d'ajouter quelque chose à notre scène (projet).<br />
Let's try to add something to our scenegraph now. We'll add a nice red cube:
Nous allons ajouter un beau cube rouge:
<syntaxhighlight>
{{Code|code=
col = coin.SoBaseColor()
col = coin.SoBaseColor()
col.rgb=(1,0,0)
col.rgb=(1,0,0)
cub = coin.SoCube()
myCustomNode = coin.SoSeparator()
cub = coin.SoCube()
myCustomNode.addChild(col)
myCustomNode = coin.SoSeparator()
myCustomNode.addChild(cub)
myCustomNode.addChild(col)
sg.addChild(myCustomNode)
myCustomNode.addChild(cub)
sg.addChild(myCustomNode)
</syntaxhighlight>
}}
and here is our (nice) red cube. Now, let's try this:
et voici notre (beau) cube rouge.<br />
<syntaxhighlight>
Maintenant, nous allons essayer ceci:
col.rgb=(1,1,0)
{{Code|code=
</syntaxhighlight>
col.rgb=(1,1,0)
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.
}}
Vu ? Tout est encore accessible et modifiable à la volée.<br />
Pas besoin de recalculer ou redessiner quoi que ce soit, '''coin''' s'occupe de tout. Vous pouvez ajouter ce que vous voulez à votre scène (projet), propriétés de changements, cacher des objets, montrer des objets temporairement, faire n'importe quoi.<br />
Bien sûr, cela ne concerne que l'affichage de la vue 3D. L'affichage du document ouvert est recalculé par FreeCAD, et recalcule un objet quand il a besoin de l'être.<br />
Donc, si vous changez l'aspect d'un objet existant dans FreeCAD, ces modifications seront perdues si l'objet est recalculé, ou lorsque vous rouvrez le fichier.


Un truc, pour travailler avec scenegraphs dans vos scripts, vous pouvez, lorsque c'est nécessaire accéder à certaines propriétés des nodes que vous avez ajoutés.<br />
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:
Par exemple, si nous voulions faire évoluer notre cube, nous aurions ajouté un '''node SoTranslation''' à notre node personnalisé et,<br />
<syntaxhighlight>
il aurait ressemblé à ceci:
col = coin.SoBaseColor()
{{Code|code=
col.rgb=(1,0,0)
trans = coin.SoTranslation()
col = coin.SoBaseColor()
col.rgb=(1,0,0)
trans.translation.setValue([0,0,0])
cub = coin.SoCube()
trans = coin.SoTranslation()
trans.translation.setValue([0,0,0])
myCustomNode = coin.SoSeparator()
cub = coin.SoCube()
myCustomNode.addChild(col)
myCustomNode = coin.SoSeparator()
mtCustomNode.addChild(trans)
myCustomNode.addChild(cub)
myCustomNode.addChild(col)
sg.addChild(myCustomNode)
myCustomNode.addChild(trans)
myCustomNode.addChild(cub)
</syntaxhighlight>
sg.addChild(myCustomNode)
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>
Souvenez-vous que dans une scène graphique '''OpenInventor''', l'ordre est très important. Un noeud affecte ce qui suit, de sorte que, si vous dites: couleur rouge, cube, couleur jaune, sphère ! vous obtiendrez un cube rouge et une sphère jaune.<br />
trans.translation.setValue([2,0,0])
Si nous traduisons maintenant notre noeud personnalisé, il vient après le cube, et ne l'affecte pas.<br />
</syntaxhighlight>
Si nous l'avions inséré lors de sa création, comme l'exemple ci-dessus,<br />
And our cube would jump 2 units to the right.
nous pourrions faire maintenant:
Finally, removing something is done with:
{{Code|code=
<syntaxhighlight>
trans.translation.setValue([2,0,0])
sg.removeChild(myCustomNode)
}}
</syntaxhighlight>
Et notre cube sauterait de 2 unités vers la droite.<br />
==Using callback mechanisms==
Enfin, pour supprimer quelque chose, nous ferons:
{{Code|code=
sg.removeChild(myCustomNode)
}}


==Utilisation des mécanismes de rappel (callback)==
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.


Un [http://fr.wikipedia.org/wiki/Fonction_de_rappel mécanisme de rappel] est un système qui permet à la bibliothèque que vous utilisez, comme notre bibliothèque '''coin''' de faire un rappel comme, rappeler une certaine fonction pour l'Objet Python en cours d'exécution.<br />
FreeCAD features an easy way to use such callbacks:
Cela est extrêmement utile, car, de cette manière coin peut vous avertir si un événement particulier survient dans la scène.<br />
<syntaxhighlight>
Coin peut voir des choses très différentes, comme, la position de la souris, les clics sur un bouton de la souris, les touches du clavier qui sont pressées, et bien d'autres choses.
class ButtonTest:

def __init__(self):
FreeCAD dispose d'un moyen facile pour utiliser ces rappels:
self.view = FreeCADGui.ActiveDocument.ActiveView
{{Code|code=
self.callback = self.view.addEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(),self.getMouseClick)
class ButtonTest:
def getMouseClick(self,event_cb):
def __init__(self):
event = event_cb.getEvent()
self.view = FreeCADGui.ActiveDocument.ActiveView
if event.getState() == SoMouseButtonEvent.DOWN:
self.callback = self.view.addEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(),self.getMouseClick)
print "Alert!!! A mouse button has been improperly clicked!!!"
def getMouseClick(self,event_cb):
self.view.removeEventCallbackSWIG(SoMouseButtonEvent.getClassTypeId(),self.callback)
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()
ButtonTest()
}}
</syntaxhighlight>
Le rappel doit être initiée à partir d'un objet, et, cet objet doit '''toujours''' être actif au moment du rappel.<br />
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].
Voir aussi une [[Code_snippets/fr|liste complète des événements possibles et leurs paramètres]] [[Code_snippets|(en)]], ou dans la [https://coin3d.bitbucket.io/Coin/index.html documentation officielle de coin].


== Documentation ==
== Documentation ==


Malheureusement, Pivy n’a pas sa propre documentation. Cependant, puisqu'il s'agit d'un wrapper de la bibliothèque Coin3d, 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.
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())


En C++:
{{docnav|Scenegraph|PyQt}}
{{Code|code=
SoFile::getClassTypeId()
}}
En Pivy
{{Code|code=
SoFile.getClassId()
}}
{{docnav/fr|[[Scenegraph/fr|Graph de scène]]|[[PySide/fr|PySide]]}}


{{Userdocnavi/fr}}
[[Category:Poweruser Documentation]]

[[Category:Poweruser Documentation/fr]]


{{clear}}
{{clear}}
<languages/>

Revision as of 08:19, 16 September 2019

Pivy est une bibliothèque de codes qui sert de passerelle entre Python et Coin3d, la bibliothèque 3D de rendu graphique utilisé dans 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.
Pivy est inclus d'origine dans l'installation FreeCAD.

La bibliothèque d'outils est divisée en plusieurs parties,

  • coin: pour manipuler formes graphiques (projet) et gérer le système graphique (GUI), tels que plusieurs fenêtres ou, dans notre cas,
  • qt  : pour les interfaces.

Ces modules sont aussi accessibles à pivy, s'ils sont présents sur le système bien sûr.
Le module coin est toujours présent, et de toute façon c'est lui que nous allons utiliser, nous n'aurons pas besoin de nous occuper de l'affichage 3D dans une interface, FreeCAD s'en occupe lui-même.
Tout ce que nous aurons à faire, c'est:

from pivy import coin

Accéder et modifier une scène graphique

Nous avons vu dans la page Scenegraph comment coin organise une scène. Tout ce qui est affiché en 3D dans FreeCAD est construit et géré par coin.
Nous avons une racine, et tous les objets sur l'écran sont ses enfants, reliés par des nodes (noeuds). Les enfants aussi peuvent avoir une descendance.

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 nodes, comme SoSeparators ou SoGroups, peuvent avoir des enfants eux-mêmes. La liste complète des coin objets disponibles peut être trouvée dans la documentation official coin documentation.

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)

et voici notre (beau) cube rouge.
Maintenant, nous allons essayer ceci:

col.rgb=(1,1,0)

Vu ? Tout est encore accessible et modifiable à la volée.
Pas besoin de recalculer ou redessiner quoi que ce soit, coin s'occupe de tout. Vous pouvez ajouter ce que vous voulez à votre scène (projet), propriétés de changements, cacher des objets, montrer des objets temporairement, faire n'importe quoi.
Bien sûr, cela ne concerne que l'affichage de la vue 3D. L'affichage du document ouvert est recalculé par FreeCAD, et recalcule un objet quand il a besoin de l'être.
Donc, si vous changez l'aspect d'un objet existant dans FreeCAD, ces modifications seront perdues si l'objet est recalculé, ou lorsque vous rouvrez le fichier.

Un truc, pour travailler avec scenegraphs dans vos scripts, vous pouvez, lorsque c'est nécessaire accéder à certaines propriétés des nodes que vous avez ajoutés.
Par exemple, si nous voulions faire évoluer notre cube, nous aurions ajouté un node SoTranslation à notre node personnalisé et,
il aurait ressemblé à ceci:

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)

Souvenez-vous que dans une scène graphique OpenInventor, l'ordre est très important. Un noeud affecte ce qui suit, de sorte que, si vous dites: couleur rouge, cube, couleur jaune, sphère ! vous obtiendrez un cube rouge et une sphère jaune.
Si nous traduisons maintenant notre noeud personnalisé, il vient après le cube, et ne l'affecte pas.
Si nous l'avions inséré lors de sa création, comme l'exemple ci-dessus,
nous pourrions faire maintenant:

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

Et notre cube sauterait de 2 unités vers la droite.
Enfin, pour supprimer quelque chose, nous ferons:

sg.removeChild(myCustomNode)

Utilisation des mécanismes de rappel (callback)

Un mécanisme de rappel est un système qui permet à la bibliothèque que vous utilisez, comme notre bibliothèque coin de faire un rappel comme, rappeler une certaine fonction pour l'Objet Python en cours d'exécution.
Cela est extrêmement utile, car, de cette manière coin peut vous avertir si un événement particulier survient dans la scène.
Coin peut voir des choses très différentes, comme, la position de la souris, les clics sur un bouton de la souris, les touches du clavier qui sont pressées, et bien d'autres choses.

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

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()

Le rappel doit être initiée à partir d'un objet, et, cet objet doit toujours être actif au moment du rappel.
Voir aussi une liste complète des événements possibles et leurs paramètres (en), ou dans la documentation officielle de coin.

Documentation

Malheureusement, Pivy n’a pas sa propre documentation. Cependant, puisqu'il s'agit d'un wrapper de la bibliothèque Coin3d, 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()

En Pivy

SoFile.getClassId()