python-materialsdb is an unofficial python library for materialsdb.org an open format and database for building materials.

Features :

Package

• serialiser.py :
  • from xml : deserialise from materialsdb*.xsd compliant xml file
  • to xml : serealise classes to a materialsdb*.xsd compliant xml file
• classes.py : generated classes corresponding to XML elements
• cache.py : cache latest materials data from producers
• config.py : set and get user config as language and country
• ifc/project_library.py : convert deserialised source into IFC (IfcProjectLibrary)
• gui/server.py : stdlib-only web application to browse and export cached materials (materialsdb-gui)

devutils

• classes_generator.py : generate classes (dataclasses except for simple type) for materialsdb*.xsd elements

config

Materials data are often localized. You can set your language and country this way:

from materialsdb import config

config.set_lang("fr")
config.set_country("CH")

Note: in materialsdb standard languages are ISO 639-1 codes and countries are ISO_3166-1_alpha-2 codes.

Usage examples :

Check out some examples:

• Convert latest materials data to ifc
• Create your own materialsdb.org compliant XML

Querying materials :

The library keeps an sqlite index of the cached materials data for fast filtering and single-material access:

from materialsdb import query

query.refresh()                                   # incremental update from cached xml
rows = query.search("isolant", sort="lambda")     # filtered, sorted summaries
material = query.get_material(rows[0].id)         # full material dataclass

Create a single material in IFC :

Append one material into an existing ifcopenshell file (idempotent), or build a minimal standalone file.

from materialsdb import query
from materialsdb.ifc.material_builder import add_material, create_material_file

material = query.get_material("<materialsdb-id>")

add_material(existing_ifc_file, material, company="Producer")   # idempotent append
file = create_material_file("<materialsdb-id>")                 # standalone .ifc
file.write("single_material.ifc")

Material picker GUI :

Launch the local web application (stdlib only, no extra dependencies):

materialsdb-gui            # opens http://127.0.0.1:8619 in your browser

Or run straight from a source checkout without installing:

PYTHONPATH=src python3 -m materialsdb.gui

The materials index uses schema v2: the first launch after upgrading rebuilds it automatically (previous index is discarded — source of truth is your cached XML). Refresh cache downloads any newer producer files from materialsdb.org and re-ingests them — on a fresh machine it fills the empty list after one click, behind a progress dialog (cancellable). The app shows a notice when updates are available on materialsdb.org.

Browse, sort and filter all cached materials; multi-select then either export a standalone .ifc, or open one of your own .ifc files and append the selected materials into it. The same HTTP API powers future BIM software plugins (all mutating calls require a per-launch token).

Construction maker :

Compose thermal constructions from materialsdb materials and compute their U-value (ISO 6946 / SIA 180 surface resistance presets):

PYTHONPATH=src python3 -m materialsdb.gui   # then open constructions.html

Create a construction, add materials from the catalog, adjust layer thicknesses in millimetres and read the resulting U-value live. Save constructions as JSON in your cache directory, export them as standalone .ifc files containing an IfcMaterialLayerSet, or append them into an already-open session file.

You can also push the construction straight into the IFC model open in Bonsai (same target picker as the materials page): it is created or updated as an IfcWallType/IfcSlabType/IfcRoofType (per the design usage, generic creating all three) with its IfcMaterialLayerSet — undoable with Ctrl+Z.

Bonsai integration :

Push materials straight from the picker into the IFC model open in Bonsai. Install it from the extension repository: in Blender, Preferences ▸ Get Extensions ▸ ⌄ ▸ Add Remote Repository and add https://cyrilwaechter.github.io/python-materialsdb/index.json, then install materialsdb listener (updates appear in the same panel). Manual install stays available: build dist/materialsdb_listener.zip with python3 dev_utils/build_bonsai_addon.py and use Extensions ▸ Install from Disk. Start the listener from the materialsdb panel in the 3D-view sidebar. The panel can also start the GUI server itself (Start server & open picker) — it needs pip install python-materialsdb in a system Python (set the interpreter in the add-on preferences if autodiscovery picks the wrong one). Then run materialsdb-gui as usual and hit send to: (picking the target instance) in the picker or the construction maker. Materials are registered into the model's material library (identity + per-layer psets included); assigning them to objects stays a normal Bonsai action. Pushed constructions become typed elements (IfcWallType/IfcSlabType/ IfcRoofType per the design usage) with their IfcMaterialLayerSet, visible in the outliner and revertible with Ctrl+Z. Each pushed type also carries its computed U-value as ThermalTransmittance in Pset_WallCommon/Pset_SlabCommon/Pset_RoofCommon (per the element type). Round-trip: select the wall (or its type) in Bonsai and hit Send type to composer in the materialsdb panel — the construction appears under incoming from model on the constructions page for editing. Any layer's material can be replaced from the catalog with the pencil button or a double-click on the material row. Layers whose material is not a materialsdb material are kept as "model material" placeholders (λ read from the model) and re-attach to the same material on push-back.

How to install

Using pip

pip install python-materialsdb

Dependencies

• lxml (BSD) : xml parser (tested with version 6.1.1)
• ifcopenshell (LGPL) : ifc read/write (tested with version 0.8.5)

Third parties :

• materialsdb.org (GPL) : materials schema