Introduction to the use of the Archicad-Python connection
((tutorial originally written by MathiasJ on the Archi-cadlink forum and then re-formatted here).
Sommaire
Introduction
What is python?
It is a programming language particularly used for the automation of simple but tedious tasks. It was created in 1991 and is now at version 3.12 (date of the post). In general, we speak of version 3 for the current version. It is the one used for archicad.
To use python, you need to install it (voir le site officiel https://www.python.org/).
How to work with python in archicad?
- Install the latest version of the python language on the official website (Latest version 3.XX)
- Activate Python in the experimental options (Options > Working environment > Other options & check the box " Activate Python Palette")
- Display the Python palette now available.
- Follow the indications of the palette to finalize the installation.
How does the connection work?
The connection works by using the python palette.
This palette is composed of two parts: a part where you select your scripts (on top) and launch the desired script, and a part named "console" where the computer will give you information.
The script section
We select the folder icon and indicate where the scripts to be used are located. A button is used to delete the folder, and another one is used to update the list.
To launch a script, just select the chosen script (1), and click on launch (2). You can also double click on the script name to launch it.
The console section
This is a very important part for the user of the script and indispensable for the coder.
You can find here an indication of the launch of the script (1), the information related to the activation of the script (for example, desired information such as quantities, or informations such as error reports)(2), and if the script has finished its work (3).
How to create/modify a script?
For this, any text editor is needed (Notepad on PC for example). On Mac, you can double click on the script to open a dedicated code editor that gives you rudimentary tools to modify the script (see screenshot below), such as coloring according to the type, the number of the selected line, the possibility to "launch" the script.
However, it is recommended to work on a dedicated code editor. I recommend Visual Studio Code which works on Mac and PC (which has an extension allowing to work on GDL.) The advantages of this type of tool are numerous.
Some for coding in general, some specific to the python/archicad connection. For example:
- All lines are numbered (bugs often indicate which line the script bugged, which helps to fix it),
- In case of "big" errors (a forgotten parenthesis, a missing line break...), the software alerts and helps to avoid stupid mistakes.
- After installing the dedicated package (https://pypi.org/project/archicad/#description), the software recognizes all the available commands, with additional information that helps to use them (on the needs of the command, and what will result from using this command).
For example, on Get2DBOundingBoxes, we learn that it is a command, that it needs the identifiers of the elements to be retrieved in the form ElementArrayItem and that it will give in return a list containing the 2D outlines of the elements or errors if there is none.
HTTP & JSON
archicad, but passes via Http using messages in JSON format (https://fr.wikipedia.org/wiki/JavaScript_Object_Notation).
Graphisoft offers a package for python that "hides" the communication in JSON.
For example, if you use the GetAllPropertyIds command which allows you to retrieve all the property identifiers of an archicad file, you will have to write in python:
acc.GetAllPropertyIds("UserDefined")
This will be translated by the "package" into JSON in this form:
{
"command": "API.GetAllPropertyIds",
"parameters": {
"propertyType": "UserDefined"
}
}
And the result will look like this (a list of unique identifiers - GUIDs - each corresponding to an archicad property):
{
"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"
}
}
]
}
}
The result may look a bit cumbersome, but this form of JSON code allows to keep a hierarchical structure. For example, if you copy and paste the "result" part into a JSON viewer that you can find on the internet, the lines of code look like this:
Conclusion: the results we receive may seem unclear at first, but we can extract the data we are interested in! Also, before giving values to the script, we have to "package" them properly.
Why didn't they create a direct connection without using JSON?
During the first beta, the connection was made via python, without any intermediary. The choice was finally made to use HTTP/JSON in order to leave the opportunity to develop bridges with any computer language later on. It would be "enough" to create a new package that allows to produce code in JSON.
How do I learn python?
I don't have a "high level", I tried several times to get into it, and I finally found a quite effective resource in English called Automate the Boring Stuff with Python. It's a book that has the particularity to be available for free and legally on a website : https://automatetheboringstuff.com/
Here are the chapters I read (and followed the small exercises)
The basics
https://automatetheboringstuff.com/2e/chapter1/
- Data types (integers, floats, strings )
- The creation and use of variables using the = sign
- The creation of comments with the # symbol
- Important functions like len() to measure a number of elements and especially the print() function which is going to be the basis of the script development under python. It's the print() function that will allow to display information in the archicad console
Conditional instructions
https://automatetheboringstuff.com/2e/chapter2/
- Comparison operators, in particular the difference between == (equality check) and = (value assignment)
- The different conditions of type "If" "else" "elif" "while" "break" loops based on "for"...
- Import of modules (additional functions to python) that must be called.
Functions
https://automatetheboringstuff.com/2e/chapter3/
Lists
https://automatetheboringstuff.com/2e/chapter4/ Lists are a way to store data. Each data has an index and a value. Indexes are integers and the first value of a list has index 0 (not 1).
You have to learn how to retrieve a value from one (or more) indexes, adding or deleting values in this list.
Dictionnary
https://automatetheboringstuff.com/2e/chapter5/
Dictionaries are another way of storing data. Instead of having indexes in integer form, each value is associated with a "key". This key can be of any type.
Strings modifications
https://automatetheboringstuff.com/2e/chapter6/
What is the status of the python/archicad connection ?
The possibilities are (still) limited. The archicad/python connection appeared in archicad 24, some functions appeared in 25 (access to bearer/non-bearer information; interior/exterior...) and in 26 (Possibility to retrieve the identifiers of the elements selected by the user...)
In general, the users of this connection find that the development of this part of archicad is very slow.
There is however a clue on the continuation of the development on this side, it is the RoadMap presented by Graphisoft which indicates automation for 2025.
What exactly can we do?
To know what is possible, you have to look at:
- the site dedicated to the JSON interface : https://archicadapi.graphisoft.com/JSONInterfaceDocumentation/#Introduction
- the site dedicated to the python "packer" : https://archicadapi.graphisoft.com/archicadPythonPackage/archicad.html
The site for JSON is a bit more easily understandable and gives a good overview. Most of the commands start with "Get" followed by a text. These are commands to get information. For example get the name of : a layer, a property, the value of this property etc...
The commands that will really act in Archicad are much less numerous.
The majority of these commands allow you to modify views and layouts:
DeleteNavigatorItems RenameNavigatorItem MoveNavigatorItem CloneProjectMapItemToViewMap CreateViewMapFolder CreateLayoutSubset CreateLayout SetLayoutSettings
And for the rest, only two commands:
SetClassificationsOfElements SetPropertyValuesOfElements
One to modify parameters of an archicad element (custom property or built-in parameter (BuiltIn) like layers...) the other is the classification of elements.
It's not much!
Tapir
Some archicad users decided to develop an opensource plugin to use in Grasshopper (Rhinoceros software tool) the possibilities offered by the python plugin.
To increase the capabilities of this plugin, they decided to improve the python plugin by offering other commands to the software.
For example, they added the possibility to retrieve project informations (which is not possible in the basic version).
Since the development is based on volunteers, it is not very fast, but it seems that for developers who know C++, the possibility to create new features is not very complicated, and a former developer of graphisoft shared a tutorial about it in the project discord.
