Getting Started Documentation: Set Up Environment

The document provides instructions for setting up and using the ARCHICAD-Python Connection. It describes how to: 1. Open the Python Palette in ARCHICAD to enable the connection. The palette will check that Python is installed and guide the installation process. 2. Run Python scripts from the palette by browsing folders, selecting scripts, and clicking run. Output will display in the console. 3. Write a simple Python script to connect to ARCHICAD and retrieve element data using commands. Technical details are also provided for advanced users.

Uploaded by

Aleks

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

137 views

Getting Started Documentation: Set Up Environment

Uploaded by

Aleks

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 9

Getting Started Documentation

Set up environment
ARCHICAD-Python Connection requires only the installed Python environment (version 3.7 or above) and a running ARCHICAD instance (version 24 or above).

The interactive Python Palette in ARCHICAD helps you with the installation process:

How to open Python Palette

To use Python Palette, switch on the Python Palette Experimental Feature on the Work Environment dialog. The palette can be opened from the Palettes menu.

1. Launch ARCHICAD
2. Go to Options > Work Environment > More Options
3. Under Experimental Features, switch on "Enable Python Palette" checkbox
4. Open the Python Palette from Window > Palettes > Python Palette
The Python Palette warns you if something is missing from your computer. If Python is not installed, then the Install Python button navigates you to the official
webpage of python where you can download the latest version of Python. We recommend you installing the latest version of Python with default options (which
contains pip and tkinter support). The Install Connection button automatically installs the missing package in case the Python is installed but the ARCHICAD-
Python Connection package is missing.

The palette automatically detects the installed Python versions. Click on the Options button in the upper right corner of the palette to list the found Python
versions. If you have multiple Python versions installed, then you can select which one to be used. Here you can update the connection if it’s not up to date.
How to run Python scripts
You can download a bunch of scripts from our webpage at the downloads section.

For beginners the Python Palette helps to run Python scripts. Simply browse a folder and the palette will list the runnable scripts inside. By double clicking a
script in the list or pushing Run button the selected script will be executed. You can check the output of the script at the Console field of the Python Palette.
How to revert changes made by the executed script
All undoable modifications made by a Python script execution can be undone in one undo step. For example, if the script modified property values of multiple
elements, then only one undo step will be available which will undo all property values to the original state.

Note, that if the script made changes which are not undoable in ARCHICAD (for example moving or renaming items on View Map of the Navigator), then those
changes won’t be able to undo.

Tips for advanced users

We recommend you install py launcher, add Python to the PATH environment variable and associate script files with Python. Find these options in the Optional
Features and Advanced Options section of the Python installer (see images below). With these options running a python script become easier:

Open a File Explorer on Windows or a Finder on macOS platform and simply double click to any python script file. The script will be executed automatically. After
double clicking a python window will pop up and automatically close when the script finished running. In this case the output messages of the script will be lost,
but of course the modification made by the script in your currently opened ARCHICAD project will preserve.

Open a Command Prompt on Windows or a Terminal on macOS platform, drag-and-drop the python script file into it and push Enter button. This way the output
message of the script will be written into the opened Command Prompt or Terminal window and it won’t close after the execution.
How to write a new Python script
This short tutorial demonstrates how to write your own first Python script. Please note, that this guide is not intended to teach the Python language, there are
plenty of online tutorials available.

Open any text editor (or Python IDE) and save a text file with .py extension and the following content:
from archicad import ACConnection
conn = ACConnection.connect()

elements = conn.commands.GetAllElements()

for element in elements:

print(element.elementId.guid)

To use the ARCHICAD-Python Connection, import ACConnection from the archicad Python package. The first two lines establish the connection to a running
ARCHICAD instance.

You can reach the collection of available commands using the commands attribute of the ACConnection object. This script uses the GetAllElements command at
the third line, which returns all elements in the current plan from ARCHICAD. With a for loop the items in returned list of elements can be iterated and the
contained GUID identifiers are printed.

Browse the list of the available commands at the documentation of ARCHICAD JSON Interface:
https://archicadapi.graphisoft.com/JSONInterfaceDocumentation/#Introduction

See the reference manual of archicad python package for type descriptions and further details:
https://archicadapi.graphisoft.com/archicadPythonPackage/archicad.html

Technical Details for Professionals

The professional Python developers don't need the palette to be able to run scripts, because Python scripts can be run outside from ARCHICAD too. Feel free to
run your scripts from your favorite IDE (Integrated Development Environment) to speed up the development process.

ARCHICAD-Python Connection is a Python binding for the ARCHICAD JSON Interface. It’s a Python package available at the PyPI (Python Package Index):
https://pypi.org/project/archicad

The communication between ARCHICAD and Python happens via HTTP using JSON messages. JSON is a language-independent data format, so any programming
language can be used to send commands to ARCHICAD. This Python package helps to establish the connection and hides the JSON communication layer.

Please note, that ARCHICAD-Python Connection itself is not an experimental feature, it is embedded and always switched on in ARCHICAD. Only the interactive
palette which helps running python scripts is part of the experimental feature. So, if you would like to run scripts without using the palette, then you don’t have
to switch on the Python Palette experimental feature, it’s optional for using ARCHICAD-Python Connection.

The steps of installation process without using Python palette:

1. Install Python downloaded from the official Python webpage: https://www.python.org/downloads

Make sure to install pip and tkinter support (recommend using the default installation options).
2. Install archicad pip package.
To do that open a Command Prompt on Windows or a Terminal on macOS platform and execute the following two commands, please use the path of
your installed Python executable:
cd <path to the installed python>
python –m pip install archicad

(If the path to the installed Python executable is added to the PATH environment variable, then the first command can be omitted.)