Fonctionnement

Un wrapper représente un nœud Maya côté Python. Ses specs décrivent les attributs exposés sous forme de propriétés, en complément des propriétés et méthodes définies directement par la classe.

Wrappers de nœuds

Principe	Fonctionnement
Types de nœuds	Chaque wrapper concret correspond à un type Maya couvert. Les classes de base, comme Node, DGNode et DAGNode, forment les bases abstraites de l’architecture et regroupent les comportements communs. Elles restent utilisables pour représenter des nœuds existants.
Héritage	Une classe retrouve les propriétés, méthodes et specs de ses parents ; elle ajoute ou redéfinit ses propres membres.
Entrées acceptées	Un nom de nœud (str) offre un accès simple, notamment pour un snippet dans Maya. Un objet OM2 déjà résolu convient à un code qui manipule directement les objets de la scène. Chaque constructeur précise les types acceptés.
Résolution et réutilisation	Une str nécessite de retrouver l’objet Maya à partir du nom. Réutiliser un MObject déjà résolu évite cette recherche à l’entrée du wrapper ; cela ne supprime pas les contrôles d’identité ni toutes les conversions internes.
Objets Maya	Le wrapper donne aussi accès à ses objets natifs : node.mobject renvoie son MObject, utilisable directement dans un appel OM2.

Attributs et plugs

Un attribut définit une donnée : type, structure et caractéristiques. Un plug représente cet attribut sur un nœud précis, ou l’un de ses enfants ou éléments. Il porte l’accès à la valeur et aux connexions, même lorsqu’aucune connexion n’existe.

Classe	Rôle
Plug	Un accès à une valeur et à ses connexions, basé sur om.MPlug.
PlugArray	Une collection de plugs, basée sur om.MPlugArray. Ce conteneur n’est pas un attribut multi Maya.
Plugs	Le gestionnaire accessible par node.plugs : recherche de plugs, inspection et création ou gestion d’attributs.

Pour un Transform existant, avec node = Transform("name") :

Usage	Syntaxe et comportement
Plug	node.plugs["translateX"] — Renvoie le Plug correspondant ; le nom court "tx" est également accepté. L’indexation s’effectue sur node.plugs.
Lecture	plug.value — Interroge la valeur courante du plug.
Écriture	plug.value = value — Affecte une valeur au plug, selon son type et ses conditions d’écriture.
Connexion sortante	source_plug >> destination_plug — Connecte la source à la destination ; équivaut à source_plug.connect_to(destination_plug).
Plusieurs destinations	source_plug >> [plug_a, plug_b] — Connecte la même source à chaque destination de la liste.
Connexion entrante	destination_plug << source_plug — La même direction de connexion, écrite depuis la destination ; équivaut à destination_plug.connect_from(source_plug).

Pour >>, la source est un Plug weSkel. La destination peut être un Plug, un om.MPlug, un PlugArray, un om.MPlugArray, ou une liste / un tuple de plugs. Il s’agit d’une collection de destinations, pas d’un branchement automatique sur les éléments d’un attribut multi.

Pour <<, la destination est un Plug weSkel et la source est un seul Plug ou om.MPlug. Les deux opérateurs renvoient None et ne se chaînent pas. Ils conservent le comportement force=False des méthodes : une destination déjà pilotée n’est pas remplacée automatiquement.

Specs

Chaque attribut couvert par une spec devient une propriété du wrapper. Son nom Python suit snake_case, tandis que le nom Maya reste inchangé : translateX est ainsi accessible par translate_x. Les propriétés héritées fonctionnent de la même manière.

En posant node = Transform("name") pour un nœud existant :

Accès	Résultat
Lecture	node.translate_x — Accède à la propriété et renvoie son proxy.
Écriture	node.translate_x = 5 — Écrit la translation X, dans l’unité de distance UI courante, si le plug est modifiable.
Valeur Python	node.translate_x.value — Renvoie la valeur Python de cette propriété, ici un float.
Type Python	type(node.translate_x.value) — Interroge le type de la valeur. type(node.translate_x) donne le type du proxy, et non celui de la valeur.

Une spec décrit cette correspondance en six champs :

Champ	Rôle
public_name	Nom de la propriété Python.
plug_name	Nom ou chemin exact de l’attribut Maya.
cache_name	Nom de stockage interne déclaré par la spec.
kind	Type et forme de l’accès : scalaire, unité, matrice, compound, array…
default_value	Valeur par défaut déclarée, utilisée selon le mécanisme de résolution.
flags	Caractéristiques de l’attribut, notamment utilisées pour sélectionner les valeurs et connexions à capturer ou rejouer.

Les specs déclarées et héritées déterminent les propriétés disponibles. La déclaration d’une spec ne crée pas à elle seule un attribut Maya. Un attribut sans spec reste accessible par node.plugs. Les accès propres aux function sets ne sont pas des plugs.

Lecture et écriture

Les propriétés sont définies sur la classe ; leurs données sont résolues à la demande. L’initialisation du wrapper ne charge pas la valeur de chaque propriété.

Accès	Comportement
Lecture	Les propriétés déléguées relisent d’abord la valeur dans Maya. Si la lecture live est impossible, leur résolution peut utiliser une valeur mémorisée, puis le défaut déclaré. Une valeur de repli ne prouve donc pas qu’un plug existe.
Valeur ou proxy	Selon son kind, une propriété renvoie une valeur ou un proxy adapté. Les proxies de valeur exposent .value, .plug et .mplug ; chaque fiche précise le type réellement retourné.
Écriture	Une propriété dotée d’un setter transmet la valeur au mécanisme d’écriture correspondant. Pour les propriétés déléguées, une écriture impossible peut laisser une valeur préparée en cache : une affectation n’est pas, à elle seule, la preuve d’une modification de la scène.
Conditions d’accès	Le setter, le type d’attribut et son état Maya déterminent ce qui est modifiable. Une sortie calculée ou un plug piloté ne devient pas librement modifiable par la présence d’une spec.
Unités	Un accès par Plug.value peut renvoyer MDistance, MAngle ou MTime. Les propriétés de specs d’unités peuvent exposer un nombre converti ; leur fiche précise l’unité.

Arrays et compounds

Structure	Accès
Compound	Regroupe plusieurs enfants ; la propriété peut exposer une valeur composée ou un proxy permettant d’accéder à ces enfants.
Array / multi	Les éléments suivent les indices logiques Maya, qui peuvent être non contigus. La position dans une liste de valeurs ne remplace pas l’indice logique.
Array typé	Une donnée contenant un tableau, comme un doubleArray, n’est pas un multi composé de plugs indexés. Son kind définit l’accès adapté.
Structures imbriquées	Les chemins, proxies et possibilités d’écriture dépendent de la structure native. Les limites et les accès alternatifs figurent dans la référence de la classe.

La Référence API distingue les membres propres et hérités, les propriétés Python et celles issues des specs. Pour la capture et la restauration de leur état, voir SVD & snapshots.