Metadata-Version: 2.4
Name: python-materialsdb
Version: 0.2.0
Summary: A library to work with materialsdb.org open standard for building materials.
Author-email: Cyril Waechter <cyrwae@hotmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/CyrilWaechter/python-materialsdb
Project-URL: Bug Tracker, https://github.com/CyrilWaechter/python-materialsdb/issues
Project-URL: Community, https://community.osarch.org/
Keywords: materials,BIM,ifcopenshell,IFC
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: lxml
Provides-Extra: ifc
Requires-Dist: ifcopenshell; extra == "ifc"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-benchmark; extra == "dev"
Requires-Dist: ruff==0.16.4; extra == "dev"
Requires-Dist: ty==0.0.74; extra == "dev"
Dynamic: license-file

python-materialsdb is an unofficial python library for [materialsdb.org][1] 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:
```python
from materialsdb import config

config.set_lang("fr")
config.set_country("CH")
```
Note: in materialsdb standard languages are [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) codes and countries are [ISO_3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) codes.

# Usage examples :
Check out some [examples](examples):
* [Convert latest materials data to ifc](examples/generate_ifc_project_libraries.py)
* [Create your own materialsdb.org compliant XML](examples/create_layers.py)

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

```python
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.

```python
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):

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

Or run straight from a source checkout without installing:

```bash
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). Click *refresh cache* once to repopulate.

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):

```bash
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](https://bonsai.ifcopenshell.org). Install it from the
extension repository: in Blender, *Preferences ▸ Get Extensions ▸ ⌄ ▸
Add Remote Repository* and add
`https://cyrilwaechter.github.io/python-materialsdb/`, 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. 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. 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
```bash
pip install python-materialsdb
```

# Dependencies
* [lxml][2] (BSD) : xml parser (tested with version 6.1.1)
* [ifcopenshell][3] (LGPL) : ifc read/write (tested with version 0.8.5)

# Third parties :
* [materialsdb.org][1] (GPL) : materials schema

[1]: http://www.materialsdb.org
[2]: https://lxml.de
[3]: ifcopenshell.org
