My first Bonsai

This is a quick beginners guide for anybody adopting Bonsai. Links to more comprehensive information, such as the Bonsai documentation, are given wherever possible. If you have not got it yet, start with the installation guide.

Bonsai turns Blender into an editor for IFC files. It runs on GNU/Linux, macOS and Windows, and it is Free Software.

IFC is the open standard file format for BIM: the building modelled as data rather than drawn. The objects in the file know what they are and carry their own properties and their relationships to each other, and the drawings, schedules and quantities are generated out of that rather than drawn by hand and kept in step by you.

You should consider Bonsai when you need to:

keep your model in an open standard format that outlives the software that made it.
work on a building model with ordinary files, folders and version control.
fine-tune anything to do with the data in your model.
own the tools of your trade, rather than work with a licence somebody else holds.

What is Bonsai?

Simply put, Bonsai is an editor for IFC files. The .ifc file is the document, and Blender is the window you edit it through, much as a text editor is a window onto a text file. When you save, you write IFC. There is no separate project format that IFC is exported from, and no import step to get back in.

This one fact explains most of what follows. Because the model is an ordinary file, other programs can read and write the same file, version control can track its history, and nothing you do is locked inside a vendor’s database.

Bonsai bundles what you need for ordinary work. Modelling, drawings, schedules, quantities and model checking are all part of the one add-on. You do not have to assemble a toolchain before you can begin, and what else is in the box has a page to itself.

Bonsai is a mod, not a panel

Bonsai is distributed as a Blender add-on, but calling it an add-on undersells it. It replaces large parts of Blender’s interface, adds tools and panels of its own, and changes what a good many familiar operations mean. With Bonsai enabled and a project open, you are working in what is substantially a different program.

This has two practical consequences. Blender tutorials will often not match what is on your screen, and advice written for stock Blender may not apply or may quietly damage your model. And you cannot treat Bonsai as an optional extra tucked away in a corner - once a project is open, Bonsai is the program you are using.

What remains underneath is still worth knowing, because you will use it constantly: navigating the viewport, selecting objects, and editing meshes are Blender’s, and they work as they always did. Which of your habits survive and which do not is the subject of a page of its own.

Bonsai and IfcOpenShell

Bonsai is the graphical part of a larger project called IfcOpenShell. IfcOpenShell is the library that actually understands IFC; Bonsai is one program built on top of it, and there are a couple of dozen others, most of which run from a command line.

You do not need any of them to use Bonsai, and you should not go looking for them yet. They matter later, when you want to automate something, process many files at once, or script a job that would be tedious by hand. The last few pages of this guide cover the ones worth knowing about.

Bonsai is a mutual aid project

Bonsai is made by the people who use it. Somebody meets a problem on a real job, solves it, and the solution is in the box for whoever meets it next - by people, for people. Nobody is selling it to you.

That is also what makes it yours. Your tools go with you between jobs and employers, the way a tradesman’s own tools do, rather than being a licence that somebody else holds on your behalf and that stops working on your last day.

The file is the document: Bonsai saves IFC. There is no separate project format, so there is no import and no export.
Bonsai is a mod, not a panel: Bonsai replaces large parts of Blender's interface. Which of your Blender habits still apply, and which do not.
The model is a graph of standard objects: IFC describes objects and the relationships between them, in a vocabulary Bonsai did not invent. Most of it is not geometry.
Containment - the spatial tree: Project, site, building, storey, space. Everything physical is assigned somewhere, or it is not really in the model.
Definition - types and occurrences: How a wall type differs from a wall, where the Revit family analogy holds, and why there is no vendor content library.
Description - properties, materials and classifications: Property sets, quantities, material layers and classification systems. The data that is not geometry.
Representations - one object, several geometries: An object may have no geometry, one, or several. A plan symbol is a stored representation, not a picture generated on the fly.
What is parametric and what is not: Bonsai maintains some relationships and regenerates some geometry, but it is not a general constraint solver.
Finding things: Selecting and filtering by data rather than by clicking, which is how you reach the parts of the model the viewport does not show.
What comes out: Drawings, schedules and quantities are generated from the model, and the annotation lives in the IFC.
Checking the model: Two different questions - is this a valid IFC file, and does it contain what somebody asked for.
Other people's models: Linking and federating models, and BCF. Several models at one moment, and why there is no central model to check out of.
Revisions: The model is a file, so Git can track its history. One model across time, and several people working on it at once.
What else is in the box: Clash detection, model checking, CSV and patching are already part of the add-on. When you would want the command line versions instead.
Who makes Bonsai: Bonsai is built by the people who use it, and the distance between using it and changing it is shorter than you expect.
About this guide: How this guide came about, how it is maintained, and how to send corrections.