Voir la source de Introduction à l'utilisation de la connexion Archicad-Python

(tutoriel initialement rédigé par [https://www.archi-cadlink.fr/memberlist.php?mode=viewprofile&u=70 MathiasJ] sur le forum [https://www.archi-cadlink.fr/ Archi-cadlink] puis remis en forme ici.)
== Introduction ==
=== Qu'est ce que python? ===
C'est un langage de programmation particulièrement utilisé pour l’automatisation de tâches simples mais fastidieuses. Il a été créé en 1991 et en est aujourd'hui à la version 3.12 (date du post). De manière générale, on parle de version 3 pour la version actuelle. C'est celle qui est utilisée pour archicad.

Pour utiliser python, il faut l'installer (voir le site officiel https://www.python.org/).

=== Comment travailler avec python sur archicad ? ===

* Installer la dernière version du langage python sur le site officiel (Dernière version 3.XX)
* Activer Python dans les options expérimentales (Options > Environnement de travail > Autres options & cocher la case « Activer palette Python Palette»)
* Afficher la palette python maintenant accessible.
* Suivre les indications de la palette pour finaliser l'installation.

<gallery>
Fichier:Python1.png
Fichier:Python2.png
</gallery>

=== Comment marche la connexion? ===
La connexion marche en utilisant la palette python.

Cette palette est composée de deux parties: une partie où l'on sélectionne ses scripts (en haut) et on lance le script voulu , et une partie nommée "console" ou l'ordinateur va vous donner des informations.

==== La Partie script ====
On sélectionne l'icone dossier et on indique où se trouvent les scripts à utiliser. Un bouton permet de supprimer le dossier, et un autre sert à actualiser la liste.

[[Fichier:Python3.png|thumb|left]]
<br clear=all>

Pour lancer un script, il suffit de sélectionner le script choisi (1), et de cliquer sur lancer (2). On peut aussi double cliquer sur le nom du script pour le lancer. 

[[Fichier:Python4.png|thumb|left]]
<br clear=all>

==== La Partie console ====
C'est une partie très importante pour l'utilisateur du script et indispensable pour le 'codeur'.

On peut y retrouver une indication de lancement du script (1) les informations liées à l'activation du script (Par exemple des informations souhaitées comme des quantités, ou subies comme des rapports d'erreurs)(2), et si le script a bien fini son travail (3).

[[Fichier:Python5.png|thumb|left]]
<br clear=all>

=== Comment créer/modifier un script? ===

Pour cela, tout éditeur de texte suffit (Bloc note sur PC par exemple). Sous Mac, on peut en double cliquant sur le script ouvrir un éditeur de code dédié qui donne des outils rudimentaires pour modifier le script (voir capture d'écran ci-dessous), comme la coloration selon le type, le numéro de la ligne sélectionnée, la possibilité de "lancer" le script.

[[Fichier:Python6.png|thumb|left]]
<br clear=all>

Toutefois, il est recommandé de travailler sur un éditeur de code dédié.
Je vous recommande Visual Studio Code qui marche sur Mac et PC et qui possède une extension permettant de travailler aussi sur du GDL.
Les avantages pour ce type d'outil sont nombreux.

[[Fichier:Python7.png|thumb|left]]
<br clear=all>

Certains pour coder en général, d'autres spécifiques à la connexion python/archicad.
Par exemple:
* L'ensemble des lignes sont numérotés (les bugs indiquent souvent à quelle ligne le script a buggé, ce qui aide à le corriger),
* Lors d'erreurs "grossières" (une parenthèse oubliée, un retour à la ligne manquant...), le logiciel alerte et aide à éviter les erreurs bêtes.
* Après avoir installé le package dédié (https://pypi.org/project/archicad/#description), le logiciel reconnait l'ensemble des commandes disponibles, avec des informations complémentaires qui aident à les utiliser (sur les besoins de la commande, et ce qui résultera de l'utilisation de cette commande).

[[Fichier:Python8.png|thumb|left]]
<br clear=all>

Par exemple, sur Get2DBOundingBoxes, on apprends que c'est une commande, qu'il lui faut les identifiants des éléments à récupérer sous la forme ElementArrayItem et qu'elle donnera en retour une liste contenant les contours 2D des éléments ou des erreurs s'il n'y en a pas.


=== HTTP & JSON ===

Une des première chose à savoir, c'est que python n'agit pas directement sur archicad, mais passe via Http en utilisant des messages au format JSON (https://fr.wikipedia.org/wiki/JavaScript_Object_Notation) .

Graphisoft propose un package pour python qui "cache" la communication en JSON.

Par exemple, si on utilise la commande GetAllPropertyIds qui permet de récupérer l'ensemble des identifiant des propriétés d'un fichier archicad, il faudra écrire en python:

<pre>
acc.GetAllPropertyIds("UserDefined")
</pre>

Ce qui sera traduit par le "package" en JSON sous cette forme:

<pre>
{
    "command": "API.GetAllPropertyIds",
    "parameters": {
        "propertyType": "UserDefined"
    }
}
</pre>

Et le résultat donnera quelque chose qui ressemblera à ça (une liste d'identifiant unique - Les GUID - correspondant pour chacun à une propriété d'archicad):

<pre>
{
    "succeeded": true,
    "result": {
        "propertyIds": [
            {
                "propertyId": {
                    "guid": "E480E81E-EDE3-43FC-9C52-B55A4CA1A85C"
                }
            },
            {
                "propertyId": {
                    "guid": "13A61253-66A9-4494-9393-9E8F2E19D55E"
                }
            },
            {
                "propertyId": {
                    "guid": "BCB5813F-2115-4B8B-A12F-16CFE37C7B7F"
                }
            },
            {
                "propertyId": {
                    "guid": "6F4A46AC-AE91-47E6-BF4A-9F9AB01A4986"
                }
            },
            {
                "propertyId": {
                    "guid": "F6F67733-1DC1-442A-8CF4-ACD2DF7E62C6"
                }
            },
            {
                "propertyId": {
                    "guid": "52D7923A-E5D7-47DF-9319-834B2CB68A6C"
                }
            },
            {
                "propertyId": {
                    "guid": "331D26A3-8168-460C-B7F5-0FA11B596B60"
                }
            },
            {
                "propertyId": {
                    "guid": "78B73923-1B87-460B-8D9E-6E3041CF38D6"
                }
            },
            {
                "propertyId": {
                    "guid": "2FAB57AB-40D6-4B7B-A7F7-31FAE42BCFBD"
                }
            },
            {
                "propertyId": {
                    "guid": "3D9EF415-8D5E-42C3-999F-3CE138DF341F"
                }
            },
            {
                "propertyId": {
                    "guid": "9CC16F4D-9754-B744-B3F8-20BA074A3B2D"
                }
            }
        ]
    }
}
</pre>

Le résultat peux paraitre un peu indigeste, mais cette forme de code en JSON permet de conserver une structure hiérarchique.
Par exemple si on copie colle la partie "résultat" et qu'on la colle dans un "viewer JSON" trouvable sur internet, les lignes de codes donnent çà:

[[Fichier:Python9.png|thumb|left]]
<br clear=all>

Conclusion: les résultat qu'on reçoit peuvent apparaitre au premier abord peu clairs, mais on peut en extraire les données qui nous interessent!
De même, avant de donner des valeurs au script, il faut les "empaqueter" de manière adéquate.

==== Pourquoi ne pas avoir créé une passerelle directe sans utiliser JSON? ====

Lors de la première bêta, la connexion se faisait directement par python, sans intermédiaire.
Le choix s'est finalement porté sur HTTP/JSON pour laisser l'opportunité de développer ultérieurement des passerelles avec n'importe quel langage informatique. Il "suffirait" de créer un nouvel package qui permet de produire du code en JSON.

== Comment apprendre python? ==
Je n'ai pas un "gros niveau", j'ai essayé plusieurs fois de m'y mettre, et j'ai trouvé enfin une source assez efficace en anglais qui s’appelle ''Automate the Boring Stuff with Python''. C'est un livre (en anglais) qui a la particularité d'être disponible gratuitement et légalement sur un site internet : https://automatetheboringstuff.com/

Pour (re)créer le script sur le total des surfaces de zones, je n'ai eu besoin d'apprendre que finalement peu de concepts propre à python. Ci-dessous les chapitres que j'ai lu (et dont j'ai suivi les petits exercices).
Vous pouvez surement trouver de la documentation/tuto en Français, surtout depuis que Python peut être enseigné (une option si j'ai bien compris?) au Lycée.

=== Les basiques ===
https://automatetheboringstuff.com/2e/chapter1/

* Les types de données (entiers, décimaux, chaîne ce qui donne en entier integers, Floating point numbers, strings)
* La création et l'utilisation de variable en utilisant le signe =
* La création de commentaires avec le symbole #
* Des fonctions importantes comme len() pour mesurer un nombre d'éléments et surtout la fonction print() qui va être la base de l'élaboration du script sous python. C'est la fonctions print() qui va permettre d'afficher des informations dans la console d'archicad

=== Les instructions conditionnelles ===
https://automatetheboringstuff.com/2e/chapter2/

* Les opérateurs de comparaison, en particulier la différence entre == (vérification d'égalité) et = (attribution de valeur)
* Les différentes conditions de type "If" "else" "elif" "while" "break" les boucles basées sur "for"...
* L'import de modules (des fonctions complémentaires à python) qu'il faut "appeler" pour pouvoir utiliser

=== Les fonctions ===
https://automatetheboringstuff.com/2e/chapter3/

=== Les listes ===
https://automatetheboringstuff.com/2e/chapter4/
Les listes sont une façon de stocker des données. Chaque donnée à un index et une valeur. Les index sont des entiers et la première valeur d'une liste a pour index 0 (et pas 1).

Il faut apprendre comment récupérer une valeur à partir d'un (ou de plusieurs) index, l'ajout ou la suppression de valeurs dans cette liste.

=== Les dictionnaires ===
https://automatetheboringstuff.com/2e/chapter5/

Les dictionnaires sont une autre façon de stocker des données. au lieu d'avoir index sous forme de nombre entier, chaque valeur est associée à une "clé". Cette clé peut être de n'importe quel type.

=== La modification des "chaines" ===
https://automatetheboringstuff.com/2e/chapter6/

== Ou en est la connexion python/archicad ==

Les possibilités sont (encore) limitées.
La connexion archicad/python est apparue en archicad 24, quelques fonctions sont apparues en 25 (accès aux informations porteur/non porteur; interieur/extérieur...) et en 26 (Possibilité de récupérer les identifiant des éléments sélectionnés par l'utilisateur, accès aux classifications des éléments...)

De manière générale, les utilisateurs de cette connexion trouvent que le développement de cette partie d'archicad est très lente.
Le développeur qui a mis en place cette connexion est partie depuis de chez Graphisoft.

Il y'a quand même un indice sur la poursuite du développement de ce côté, c'est la RoadMap présentée par graphisoft qui indique de l'automatisation pour 2025.

[[Fichier:Python10.jpeg|thumb|left]]
<br clear=all>

=== Que peut-on faire exactement? ===

Pour savoir ce qu'il est possible de faire, il faut regarder:

* le site dédié à l'interface JSON (voir précédent post) : https://archicadapi.graphisoft.com/JSONInterfaceDocumentation/#Introduction
* le site dédié à l'"empaqueteur" python (voir précédent post) : https://archicadapi.graphisoft.com/archicadPythonPackage/archicad.html

Le site pour JSON est un peu plus digeste et donne un bon aperçu.
La majorité des commandes commencent par "Get" suivi d'un texte. Ce sont des commandes pour récupérer des informations. Par exemple récupérer le nom d'un calque, d'une propriété, la valeur de cette propriétén etc...

Les commandes qui vont réellement agir dans archicad sont beaucoup moins nombreuses.

La majorité de ces commandes permettent de modifier les vues et les mises en pages:

<pre>
DeleteNavigatorItems
RenameNavigatorItem
MoveNavigatorItem
CloneProjectMapItemToViewMap
CreateViewMapFolder
CreateLayoutSubset
CreateLayout
SetLayoutSettings
</pre>

Et pour le reste, seulement deux commandes:

<pre>
SetClassificationsOfElements
SetPropertyValuesOfElements
</pre>

L'une pour modifier des paramètres d'un élément archicad (propriété personnalisée ou paramètre intégré (BuiltIn) comme les calques...) l'autre (et seulement depuis archicad 26) les classification des éléments.

Ca reste peu!

=== Tapir ===
https://www.archicad-api.com/

Des utilisateur d'archicad ont décidé de développer en opensource un plugin permettant d'utiliser dans Grasshopper ( Outil du logiciel Rhinoceros) les possibilités offertes par le plugin python.

Pour augmenter les capacité de ce plugin, ils ont décidé d'améliorer le plugin python en offrant d'autres commandes au logiciel.

Par exemple, ils ont ajouté la possibilité de récupérer les informations projet (ce qui n'est pas possible dans la version de base).

Le développement se reposant sur des bénévole, ce n'est pas très rapide, mais il semblerait que pour des développeur s'y connaissant en C++, la possibilité de créer de nouvelles fonctionnalités ne soit pas très compliqué, et un ancien développeur de graphisoft a partagé un tutoriel à ce sujet dans le discord du projet.

== La suite... ==
[[Premier script en python, un exemple expliqué de A à Z]]