README.md

python-mvdxml

An mvdXML parser, checker, and W3C SPARQL converter provided as an IfcOpenShell submodule.

Warning

While this package has useful building blocks for mvdXML and IFC, there are many mvdXML dialects and not all variants are fully supported.

Parsing

Parsed documents are immutable dataclasses. Templates and template references are resolved while parsing, so repeated access returns the same parsed object.

from ifcopenshell.mvd import parse

concept_roots = parse("mvd_examples/wall_extraction.mvdxml")
concept_root = concept_roots[0]

print(concept_root.name)
print(concept_root.entity)
print([concept.name for concept in concept_root.concepts()])

parse() returns a tuple of concept_root objects. A document containing only concept templates returns a tuple of template objects instead. Invalid XML and missing template references raise ValueError with the relevant document or template identifier. Recursive template branches are expanded once.

Graphviz concept templates

The lightweight concept graphs used by the buildingSMART IFC4.x documentation can be read directly into the same immutable template representation:

from ifcopenshell.mvd import template

source = """
This prose is ignored.

```
concept {
    IfcObject:ObjectType -> IfcLabel
    IfcObject:ObjectType[binding="UserDefinedType"]
}
```
"""

parsed_template = template.from_graphviz(
    source,
    name="Object Predefined Type",
)

Only concept {} declarations inside triple-backtick fences are read; the surrounding Markdown is not parsed. Edges, attribute bindings, constraint nodes, and named template references follow the syntax used by buildingSMART's templates_to_mvdxml.py. Referenced templates must already be parsed and provided by name:

parent = template.from_graphviz(
    parent_source,
    references={"Surface Color Style": surface_color_style},
)

Reference names are matched without spaces or underscores. Graph parsing uses networkx, available through IfcOpenShell's advanced optional dependencies.

Extraction

Extraction returns native Python containers and IFC values.

import ifcopenshell

from ifcopenshell.mvd import concept_root, parse

parsed = parse("mvd_examples/wall_extraction.mvdxml")
root = parsed[0]
assert isinstance(root, concept_root)
ifc_file = ifcopenshell.open("Duplex_A_20110505.ifc")

all_data, verification = root.get_data(ifc_file)
non_respecting = root.get_non_respecting_entities(ifc_file, verification)
respecting = root.get_respecting_entities(ifc_file, verification)

The result is:

tuple[
    list[dict[str, object]],  # one GlobalId-to-value mapping per concept
    dict[str, dict[str, int]],  # GlobalId-to-concept verification matrix
]

Individual structures also expose their own behavior:

concept = next(root.concepts())
parsed_template = concept.template()
entity = ifc_file.by_type(root.entity)[0]

extracted = parsed_template.extract(entity)
valid, report = concept.validate(extracted)

extracted is a list of dictionaries mapping immutable rule objects to IFC values. valid is a boolean and report is a string; validation itself does not print.

Visualization and export

Visualization and spreadsheet generation are deliberately outside this package. Use the returned GlobalIds to select or colour entities in the caller's viewer. For CSV, JSON, dataframe, or spreadsheet output, transform all_data and verification with the corresponding Python library. Keeping those operations at the application boundary means importing this package does not initialize a geometry backend or require a spreadsheet dependency.

Command line

Inspect a document:

python -m ifcopenshell.mvd mvd_examples/wall_extraction.mvdxml

Generate and execute SPARQL against an IFC-OWL Turtle file:

python -m ifcopenshell.mvd model.mvdxml model.ttl

Use python -m ifcopenshell.mvd --help for argument details.