Anatomy of a node

One of the simplest nodes in the VI-Suite is the location node. The location node defines the location of the building to be analysed in terms of latitude and longitude, and is a required node for Sun Path, Shadow Study, Wind Rose, LiVi and EnVi analyses.

The image below shows the Python code listing for the location node.

Basic node Python code

A node in Blender is an instance of a Python class and so the code begins with a class definition that locates the node within the ‘VINodes’ node tree.   Lines 2 to 5 identifies the name, label and icon of the node.

Lines 7 to 13 define some parameters associated with the node. Parameters are important as they not only hold values, but also create user interface elements to allow the user to alter their values. Parameters for the location node include the latitude and longitude values.

A Blender node has a number of built-in functions, but as a node is an instance of a class we call these built-in functions methods, that are called during the ‘life’ of the node. When a node is created by the user the ‘init’ method is executed and lines 15 to 21 defines what happens when this occurs. In this method a property is associated with the node called ‘nodeid’ which contains the name of the node and the name of nodetree that the node sits in. An external function is run called ‘nodeinit’ which creates some platform specific parameters the VI-Suite uses, and finally an output socket is created.

Whenever the user changes the socket connections of this node the method ‘update’ is executed, which is defined on lines 23 & 24. When the update method is executed it in turn executes an external function called socklink that checks if the socket on the other node we are connecting the output socket of this node to is the same colour. If so the connection is made, if not the connection is not made. This helps make sure the user does not construct node connections that would result in an error.

The final method we use here is the draw_buttons method where we can define the user-interface presented by the node. In this function some of the parameters of the node defined earlier are presented. For example the ‘loc’ parameter is defined as a Blender EnumProperty. An EnumProperty in Blender basically represents a list, and the loc parameter has two entries in its list: A ‘Manual’ entry and an ‘EPW’ entry. When we include the ‘loc’ parameter in the draw_buttons method Blender automatically creates a drop-down menu interface for this parameter. Similarly, the latitude and longitude parameters are defined as FloatProperties, which represent regular numbers. When these are included in the draw_buttons function, Blender creates boxes that allow the user to manipulate these numbers.

If ‘EPW’ is selected in the ‘loc’ menu then an EnumProperty drop-down menu is displayed to select the desired EnergyPlus weather file. Weather files with an .epw or .EPW extension should be placed within the vi-suite/EPFiles/Weather directory. After adding a weather file Blender needs to be restarted to see the new file.

The short video shows how the location node functions.

VI-Suite location node from Ryan Southall on Vimeo.

Installing the VI-Suite

First get hold of a copy of the most recent version of Blender (2.69 at the time of writing) from and install it. If this is the first time you have used Blender open it and select the ‘File – User Preferences’ menu item. The settings window will appear and for now simply click the ‘Save User Settings’ button in the bottom left corner. This makes sure that the Blender configuration directory is created on your system.

On a Windows 7 PC this directory can be found at  C:\Users\your_username\AppData\Roaming\Blender Foundation\Blender\blender_version

On a Mac it can be found at /Users/your_username/Library/Application Support/Blender/blender_version

And on an Arch Linux machine can be found at /home/your_username/.config/blender/blender_version

Other operating systems may vary but this directory should be created somewhere similar.

Within this folder create a directory called ‘scripts’ and within this a directory called ‘addons’.

For those comfortable with the command-line navigate to the ‘addons’ directory above and checkout, with Mercurial, the VI-Suite code from the Google Code repository with the command:

hg clone

This should place a ‘vi-suite’ directory within the addons directory.

Alternatively, a zip file containing the VI-Suite code can be downloaded from by clicking the download zip button just above the list of code changes. The directory within the zip file should be renamed to ‘vi-suite’ and moved to the ‘addons’ directory.

Upon starting Blender the VI-Suite should be registered as an available add-on. The video below shows how to activate this add-on within Blender.

Activating the VI-Suite from Ryan Southall on Vimeo.

Introducing the VI-Suite

The VI-Suite is a set of environmental analysis tools presented to the user as a set of connectible ‘nodes’ within the 3D content creation suite Blender. Blender nodes have traditionally been used for the application of a sequence of post-production tasks on rendered images. More recently they have been used to define materials for Blender’s new physically based rendering system, and very recently nodes, and the nodetrees that they sit in, have become user programmable with Blender’s scripting language Python. It is this latter development that is leveraged here.

I have previously written two Blender based interfaces for environmental analysis: LiVi, for lighting simulation with Radiance, and EnVi for energy simulation with EnergyPlus. As these interfaces became more advanced it became increasingly difficult to see how I could easily manage communication between these types of analyses e.g. using accurate solar radiation data from LiVi in the temperature calculations of EnVi. It also became difficult to envisage how the data generated by these analyses could be used to flexibly manipulate geometric form for environmental parametric and generative design studies. This is where a node based system comes in very handy. By having analyses broken down in to a set of modular nodes, the user can connect these nodes as they wish, for example modifying window size according to solar radiation or light levels and density of parametrically generated shading forms.

When combined with ancillary nodes like sun path and wind rose generators, shadow study node and glare analysis nodes the VI-Suite becomes a powerful holistic tool to explore interconnections between building form and performance.