Development

Building Tools Development Guide

1. Getting Started

A basic understanding of Python, GitHub, Git and Blender API is required.

• Make sure you have the following:

  1. Blender.
  2. Git.
  3. Text Editor / IDE ( Sublime Text, Visual Studio code, Pycharm )
  4. Github account.

• Navigate to this project's repository.

• Fork the project.

• Navigate to the newly created fork in your GitHub account.

• Clone the project into your local machine.

2. Project Structure

The source code for building tool is laid out as follows.

assets/
docs/
tests/
btools/
    __init__.py
    .building/
        .window/
            __init__.py
            window.py
            window_ops.py
            window_props.py
            window_types.py

        ...
        __init__.py
        generic.py
        ...
    .utils/
        util_common.py
        util_geometry.py
        util_material.py
        util_mesh.py
        ...

The main add-on folder is named btools.

At the root of the btools folder, __init__.py can be found which serves as the add-on initialization. You can expect to find:

• The add-on bl_info used by Blender's Python API for add-on metadata.
• UI definition for the add-on's main panels.
• register and unregister functions.

Also in the btools folder is a utils folder. This contains a collection of useful, reusable modules and functions. Great effort has been taken to keep related functionality in common files.

Finally, the guts of the add-on are in the folders building and road. These folders contain collections of packages alongside some python files. The files include:

• __init__.py
• generic.py - contains all properties that are used by more than one package.

The packages include:

• window
• door
• roof
• floorplan
• floors
• balcony
• stairs
• road

with more to be added.

Each of these packages contains at least 5 python files:

• __init__.py
• foo.py - contains a class to build geometry and validate the blender context.
• foo_ops.py - contains blender operators.
• foo_props.py - contains blender properties.
• foo_types.py - contains helper functions used by the operators.

where foo is the name of the package.

The root of the project also contains a tests folder.

The tests folder contains test files for packages contained in the building and road folders e.g tests for the floors package will be found in the test module called test_floors.py.

Also in the tests folder is a __main__.py file that should be run from within blender. A command to run the test can look as follows:

blender --window-geometry 0 0 1 1 --no-window-focus -P tests/__main__.py

This command will run the tests in an unfocused blender window. Tests must be run from within blender to provide the proper context and extra modules such as bpy.

3. Environment Setup

To start contributing to the development of Building Tool you need to have the appropriate environment setup. Developing blender add-ons can be somewhat tricky especially when using an external editor. I will provide a short overview of my setup for developing Building Tool.

1. You will need to get ScriptWatcher.

A very handy blender add-on I stumbled across that watches your project files in Blender and runs your add-on when you make changes.

2. Once ScriptWatcher is installed in Blender, locate the ScriptWacher panel which should be in the Properties editor under the Scene tab.

3. Point ScriptWacher to the __init__.py file at the root of your local Building Tool development sources. Click Watch Script to run Building Tool in the current blender workspace.

To avoid having to repeat these steps every time, you can save the current blender workspace as a file, say building_tool_dev.blend. Then in the SciptWatcher settings, enable the Watch on startup checkbox. Now every time you open the .blend file, everything will already be setup.

4. Making Changes

At this point, making changes to the building tools source code should not be a scary endeavor. You should be able to fix issues, add new features and refactor appropriately.

It is advisable of course to take the time to understand the portions of code you would like to change. Be sure to maintain a style consistent with the rest of the source code. I personally use black to handle python style, but occasionally prefer the freedom of deciding on my own.

In general, the following hints apply:-

• Run Blender from a terminal. This allows you to watch all output from the add-on including errors when testing functionality.

• Make small changes and test often.

• If adding/removing new classes, ensure you register/unregister them. Errors relating to this issue are usually vague and not helpful.

• When adding new properties, caution should be taken when defining update functions. Blenders documentation warns users about Infinite Recursion, but errors relating to this issue can be vague and seem unrelated to recursion.

• If you feel that a piece of code is used often or that it could be useful in other areas of the add-on, consider adding it in the utils module.

• As part of a consistent style, I have made great effort to keep the length of functions reasonable. Less than 40 lines is preferred.

5. Submitting Pull Requests

Once you are happy with the changes you have made, push them to your fork and create a pull request.