Python Connection in Archicad

[Minh Nguyen]

If you've ever spent hours doing repetitive tasks - like assigning numbers to parking spaces one-by-one, finding any unused items in the View Map, or editing each element ID due to multiplying - you know how tedious and error-prone these tasks can be. What if we could have those tasks automatically done?

In Archicad 24, we release the Archicad - Python connection add-on to the public as an experimental feature. With Python, such tasks can be done fast, automatically, and precisely. Python offers excellent readability and approachable syntax, similar to plain English.

If you do not know the Python language, fear not! You will still be able to enjoy the benefits of Python. At the moment, there are some example scripts available at https://graphisoft.com/downloads/python.

Setting up the Python environment

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

There are various methods to install Python. The easiest way is to download the latest Python version directly from here and run the installer. We recommend installing with the default options.

On Windows 10

• Double click the executable file.
• Click Install Now to let Python install with the default options.
  
• Alternatively, choose Customize installation if you want to select which features to install and where to install.
  
  For advanced users: we recommend adding Python to the PATH environment variable, installing py launcher, and associating script files with Python. These options can be found in the Optional Features and Advanced Options section of the Python installer. With these options running a Python script becomes easier.
• Once it is finished, click Close and the Python environment is installed.

On macOS

• Double click the downloaded installer file.
• Click Continue. The installer will walk you through the Important Information and Python's License Agreement.
• In the next step, it will ask for the location where you want to install Python. Please leave it at the internal drive for future compatibility.
  
• To customize which elements to install, click Customize at Installation Type; or leave it at Standard Install.
  
  
• The installation process will start after clicking Install. Once it is finished, click Close to close the installer. You may choose to delete the installer if it is no longer needed.

Using Python inside Archicad

Although we can run a Python script without Archicad, the Python Palette will provide a more user-friendly way to manage and run the scripts. To open it, the Python Palette Experimental Feature must be enabled via the Work Environment dialog.

Enable Python Palette

1. Go to Options > Work Environment > More Options
2. Under Experimental Features, tick the Enable Python Palette checkbox
   
3. Open the Python Palette from Window > Palettes > Python Palette

	The Python Palette will notify you if something is missing from your computer. If Python is not installed, then the Install Python button will open Python's official web page for downloading the latest version of Python.
	If the Archicad - Python connection is not yet installed, the Install Connection button automatically installs the missing package.

Once the connection with Python is made, we are ready to run some scripts via the Python Palette.

To know which version of the Python environment is being used, click the  button. The  button will let us choose different versions if we have more than one installed.

NOTE: currently, the Python Palette needs to check for updates whenever it is opened after Archicad restarts. Therefore internet connection is a requirement to open the palette.

Managing script in the Palette

The Python Palette contains some basic functions to manage and run Python scripts.

It can show the scripts stored in multiple places on your computer. Click the  button to add a folder. The palette will list all runnable scripts inside the main folder (it cannot look into any sub-folder).

The  button will refresh the list: the palette will check if there is any new script in the added folders, or if a script is moved/deleted.

While a folder is selected, clicking  will remove it from the palette. A dialog appears to confirm the action. 

Run script via Python Palette

To run a script in the Python Palette, you can either

• Double-click the script in the list
  
• Select the script and click the Run button
  

The events will be shown one by one at the Console field of the palette. Once the process is finished, the palette will present the result with notification of whether the script ran successfully or not. 

NOTE: 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 reset all property values to their original states.

If the script makes changes that are not undoable in Archicad (for example, moving or renaming items on View Map of the Navigator), we will not be able to undo those changes.

Examples

Chair numbering

We usually use the Multiply tool to arrange the chairs inside an area (i.e., auditorium). However, when the chairs are multiplied, the original object's element ID is also transferred to all new objects. To quickly re-number them by changing the element ID, we created a demo script called Chair numbering.

When the script is executed, the IDs of all objects classified as Chair placed in all stories will be modified. Hidden objects are not affected by this.

Execution

1. Download the script here.
2. Extract the downloaded ZIP package into a folder.
3. Open the example project file or your own project.
4. Open the Python Palette by navigating to Windows > Palettes > Python Palette
5. Add the script to the palette by browsing the folder where the script is placed in.
6. Run the script by selecting it and press Run, or double-clicking the script.
   
   
7. The element IDs of the chairs will be set automatically. The labels in the example project display the value of element ID on the floor plan view.

Requirements

The following requirements must be met to execute the script successfully without any customization:

• A classification system named Archicad Classification must be available in the project
• The chairs must be classified as Chair in the Archicad Classification 
• Archicad version must be 24 build 3008 or above
• Archicad - Python Connection version 24.2310 or above

The script uses the Z coordinates of the objects to identify the rows. By default, chairs are grouped into rows if the maximum difference between the Z coordinates of the chairs in the same row is less than 0.25m.

To learn more about customization options, please follow the attached PDF guide inside the downloaded package.

Move unused items in View Map

This script will find any unused items in the View Map and move to a new folder. An item is considered unused if it is not placed on any layout and is not referenced by any Publisher Sets.

NOTE: moving a navigator item is not undoable. Thus, modifications made by this script are not undoable.

Execution

1. Download the script here.
2. Extract the ZIP package.
3. Open the example project file or your own project.
4. Open the Python Palette by navigating to Windows > Palettes > Python Palette
5. Add the script to the palette by browsing the folder where the script is placed in.
6. Run the script by selecting it and press Run, or double-clicking the script.
   
7. The unused items will be moved to a new folder called -- UnusedViews -- in the View Map of the Navigator.

Requirements

The following requirements must be met to execute the script successfully without any customization:

• Archicad 24 3008 or above
• Archicad - Python Connection version 24.2310 or above

This script does not require anything from the currently opened Archicad project.

Please note that we can use the Archicad Python API without the Python Palette. If you already have the Archicad pypi package (Python Wrapper) installed, then you can execute your python script anywhere (in Terminal or in your favorite integrated development environment, for example, in Visual Studio Code).