December 14, 2020
by Tibor Lorántfy

Getting started with Archicad-Python Connection

This tutorial shows you how to write a Python script from scratch based on the Archicad Automation API.

Archicad Automation API Basics

The goal of the Automation API is to support workflow automation. A Python wrapper is provided by Graphisoft, but you can use any programming language to access this API.

The communication between Archicad and Python happens via HTTP using JSON messages. The Python package helps to establish the connection and hides the JSON communication layer.

What will You Need?

First, you will have to set up your development environment:

  • Archicad – Version 24 or above is required. The demo version is perfectly fine for experimenting with the API.
  • Python – For executing Python scripts (version 3.7+).
  • archicad Python Package – This official archicad PyPI package helps to establish the connection and send commands to Archicad.
  • Development Environment – You can use your preferred Python IDE or even a simple text editor can do the job.

The best way to make sure that your development environment is set up is to open the Python Palette. It warns you if something is missing from your computer and guides you through the installation process. Read further for more details.

Installation guide of the Python Palette

Structure of the archicad Python Package

ACConnection is the main class in archicad Python Package. That class represents a live connection to an existing Archicad instance. The most important parts of the class are the followings:

  • connect: Use this static method to acquire an ACConnection instance. It automatically finds the running Archicad instance.
  • commands: Collection of the available commands for the currently attached Archicad instance. The collection may vary by Archicad versions.
  • types: Types required for the API.
  • utilities: Utility functions to simplify the usage of the API.

Let’s write your first Python script

Your very first Python script for Archicad will print the number of walls in the currently opened project.

The first part is for the connection, you can use that as a template for your Python scripts for Archicad. The last two lines implement the simple logic of this tutorial script.

Save it as a text file with .py extension.

from archicad import ACConnection

conn = ACConnection.connect()
assert conn

acc = conn.commands
act = conn.types
acu = conn.utilities

walls = acc.GetElementsByType('Wall')

print(f'Number of Walls: {len(walls)}')

How to run Python scripts

The Python Palette

For beginners the embedded Python Palette inside Archicad helps to run Python scripts. At first you have to switch on the Python Palette feature inside your Work Environment, to do this navigate to the Options/Work Environment/More Options menu. You will find the Python Palette inside the Window/Palettes menu.

Enabling Python Palette feature in Work Environment

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.

The Python Palette

Running script without the Python Palette

The professional Python developers can run their scripts from command line or by using their preferred IDE.

We recommend to use Visual Studio Code with Python Extension. It’s free and runs on both platforms. The built-in IntelliSense supports many useful code editing features including code completion and showing the documentation of the Archicad Automation API commands. Debugging is also pretty straightforward in Visual Studio Code.

Executing script in Visual Studio Code
Debugging in Visual Studio Code

Resources

This tutorial covered only the basics, but there are much more.