bimdelta-core 0.4.0__tar.gz

bimdelta_core-0.4.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.local
+.env.production
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test / coverage
+.pytest_cache/
+htmlcov/
+.coverage
+
+# Node
+node_modules/
+
+# IFC temp files
+*.ifc.tmp
+
+# Docker
+docker-compose.override.yml
+
+# Claude
+.claude/
+
+# Revit project and family files, including backups (*.0001.rvt)
+*.rvt
+*.rfa
+
+# Local session file
+\!sessionid.txt

bimdelta_core-0.4.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.5
+Name: bimdelta-core
+Version: 0.4.0
+Summary: Element-level diff engine for IFC building models
+Project-URL: Repository, https://github.com/kaan36875/BIMDelta
+License-Expression: MIT
+Keywords: bim,diff,ifc,ifcopenshell,openbim
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: ifcopenshell>=0.8.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bimdelta-core
+
+Element-level diff engine for IFC building models, built on [IfcOpenShell](https://ifcopenshell.org).
+
+```python
+from bimdelta_core import load_settings, run_diff
+
+result = run_diff("rev-a.ifc", "rev-a.ifc", "rev-b.ifc", "rev-b.ifc", load_settings())
+print(result.summary.added, result.summary.removed, result.summary.modified)
+print(result.model_dump_json(indent=2))
+```
+
+Elements are matched by `GlobalId`, then by the authoring tool's element id in `IfcElement.Tag`,
+then by class, name, storey and placement. Matched pairs are compared on properties and
+quantities, placement, type, storey and a geometry signature (bounding box and volume).
+
+A noise filter keeps export artefacts out of the result; see
+[docs/noise-filter.md](https://github.com/kaan36875/BIMDelta/blob/main/docs/noise-filter.md).
+
+Part of [BIMDelta](https://github.com/kaan36875/BIMDelta). MIT licensed.

bimdelta_core-0.4.0/README.md

@@ -0,0 +1,20 @@
+# bimdelta-core
+
+Element-level diff engine for IFC building models, built on [IfcOpenShell](https://ifcopenshell.org).
+
+```python
+from bimdelta_core import load_settings, run_diff
+
+result = run_diff("rev-a.ifc", "rev-a.ifc", "rev-b.ifc", "rev-b.ifc", load_settings())
+print(result.summary.added, result.summary.removed, result.summary.modified)
+print(result.model_dump_json(indent=2))
+```
+
+Elements are matched by `GlobalId`, then by the authoring tool's element id in `IfcElement.Tag`,
+then by class, name, storey and placement. Matched pairs are compared on properties and
+quantities, placement, type, storey and a geometry signature (bounding box and volume).
+
+A noise filter keeps export artefacts out of the result; see
+[docs/noise-filter.md](https://github.com/kaan36875/BIMDelta/blob/main/docs/noise-filter.md).
+
+Part of [BIMDelta](https://github.com/kaan36875/BIMDelta). MIT licensed.

bimdelta_core-0.4.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bimdelta-core"
+version = "0.4.0"
+description = "Element-level diff engine for IFC building models"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["ifc", "bim", "diff", "openbim", "ifcopenshell"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "ifcopenshell>=0.8.0",
+    "numpy>=1.26.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.6.0",
+]
+
+[project.urls]
+Repository = "https://github.com/kaan36875/BIMDelta"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bimdelta_core"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

bimdelta_core-0.4.0/src/bimdelta_core/__init__.py

@@ -0,0 +1,44 @@
+"""Element-level diff engine for IFC building models."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .config import CONFIG_FILENAME, Settings, load_settings
+from .engine import filter_result, run_diff
+from .quantities import quantity_delta
+from .schemas import (
+    SCHEMA_VERSION,
+    ChangeType,
+    DiffResult,
+    DiffSummary,
+    ElementDiff,
+    MatchMethod,
+    PropertyChange,
+    QuantityDelta,
+    QuantityDeltaRow,
+    QuantityTotals,
+)
+
+try:
+    __version__ = version("bimdelta-core")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "CONFIG_FILENAME",
+    "SCHEMA_VERSION",
+    "ChangeType",
+    "DiffResult",
+    "DiffSummary",
+    "ElementDiff",
+    "MatchMethod",
+    "PropertyChange",
+    "QuantityDelta",
+    "QuantityDeltaRow",
+    "QuantityTotals",
+    "Settings",
+    "__version__",
+    "filter_result",
+    "load_settings",
+    "quantity_delta",
+    "run_diff",
+]

bimdelta_core-0.4.0/src/bimdelta_core/comparator.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from .config import Settings
+from .geometry import compute_geometry_signature, representation_fingerprint, signatures_equal
+from .noise import NO_FILTER, PropertyFilter
+from .parser import ParsedElement, ParsedModel, PropertyValue
+from .schemas import (
+    ChangeType,
+    ElementDiff,
+    MatchMethod,
+    PropertyChange,
+    PropertySource,
+)
+
+
+def compare_matched(
+    v1_el: ParsedElement,
+    v2_el: ParsedElement,
+    method: str,
+    cfg: Settings,
+    v1_model: ParsedModel | None = None,
+    v2_model: ParsedModel | None = None,
+    prop_filter: PropertyFilter = NO_FILTER,
+) -> ElementDiff:
+    prop_changes, ignored = _compare_properties(
+        v1_el.properties, v2_el.properties, cfg.float_tolerance, prop_filter
+    )
+
+    placement_changed = _placement_changed(v1_el, v2_el, cfg)
+    type_changed = v1_el.type_name != v2_el.type_name
+    name_changed = v1_el.name != v2_el.name
+    storey_changed = v1_el.storey != v2_el.storey
+
+    already_modified = (
+        bool(prop_changes) or placement_changed or type_changed or name_changed or storey_changed
+    )
+
+    geom_changed = False
+    geom_unknown = False
+    if not already_modified:
+        geom_changed, geom_unknown = pair_geometry_state(v1_el, v2_el, v1_model, v2_model, cfg)
+
+    is_modified = already_modified or geom_changed
+
+    return ElementDiff(
+        global_id=v2_el.global_id,
+        ifc_class=v2_el.ifc_class,
+        name=v2_el.name,
+        storey=v2_el.storey,
+        change_type=ChangeType.MODIFIED if is_modified else ChangeType.UNCHANGED,
+        match_method=MatchMethod(method),
+        matched_global_id=v1_el.global_id if v1_el.global_id != v2_el.global_id else None,
+        property_changes=prop_changes,
+        geometry_changed=geom_changed,
+        geometry_unknown=geom_unknown,
+        placement_changed=placement_changed,
+        type_changed=type_changed,
+        name_changed=name_changed,
+        storey_changed=storey_changed,
+        ignored_property_changes=ignored,
+        old_name=v1_el.name if name_changed else None,
+        old_storey=v1_el.storey if storey_changed else None,
+        old_type_name=v1_el.type_name if type_changed else None,
+        new_type_name=v2_el.type_name if type_changed else None,
+    )
+
+
+def build_added(el: ParsedElement) -> ElementDiff:
+    return ElementDiff(
+        global_id=el.global_id,
+        ifc_class=el.ifc_class,
+        name=el.name,
+        storey=el.storey,
+        change_type=ChangeType.ADDED,
+    )
+
+
+def build_removed(el: ParsedElement) -> ElementDiff:
+    return ElementDiff(
+        global_id=el.global_id,
+        ifc_class=el.ifc_class,
+        name=el.name,
+        storey=el.storey,
+        change_type=ChangeType.REMOVED,
+    )
+
+
+def pair_geometry_state(
+    v1_el: ParsedElement,
+    v2_el: ParsedElement,
+    v1_model: ParsedModel | None,
+    v2_model: ParsedModel | None,
+    cfg: Settings,
+) -> tuple[bool, bool]:
+    if v1_model is not None and v2_model is not None:
+        if same_geometry_source(v1_el, v2_el, v1_model, v2_model):
+            return False, False
+    ensure_pair_geometry(v1_el, v2_el, v1_model, v2_model)
+    return geometry_state(v1_el, v2_el, cfg)
+
+
+def same_geometry_source(
+    v1_el: ParsedElement, v2_el: ParsedElement, v1_model: ParsedModel, v2_model: ParsedModel
+) -> bool:
+    """True if both elements are defined by identical IFC geometry, without tessellating."""
+    if not math.isclose(v1_model.unit_scale, v2_model.unit_scale):
+        return False
+    return _fingerprint(v1_el, v1_model) == _fingerprint(v2_el, v2_model)
+
+
+def _fingerprint(el: ParsedElement, model: ParsedModel) -> str | None:
+    if el.geometry_fingerprint is None and model._ifc_file is not None:
+        if el._ifc_entity_id is not None:
+            entity = model._ifc_file.by_id(el._ifc_entity_id)
+            el.geometry_fingerprint = representation_fingerprint(entity, model._fingerprint_memo)
+    return el.geometry_fingerprint
+
+
+def geometry_state(v1_el: ParsedElement, v2_el: ParsedElement, cfg: Settings) -> tuple[bool, bool]:
+    """Return (changed, unknown). A missing signature without a failure means no representation."""
+    if v1_el.geometry_failed or v2_el.geometry_failed:
+        return False, True
+    changed = not signatures_equal(
+        v1_el.geometry_signature,
+        v2_el.geometry_signature,
+        cfg.geometry_bbox_tolerance,
+        cfg.geometry_volume_tolerance,
+    )
+    return changed, False
+
+
+def _compare_properties(
+    v1_props: list[PropertyValue],
+    v2_props: list[PropertyValue],
+    float_tol: float,
+    prop_filter: PropertyFilter,
+) -> tuple[list[PropertyChange], int]:
+    v1_map = {(p.pset_name, p.property_name, p.source): p.value for p in v1_props}
+    v2_map = {(p.pset_name, p.property_name, p.source): p.value for p in v2_props}
+
+    changes: list[PropertyChange] = []
+    ignored = 0
+
+    for key in sorted(set(v1_map) | set(v2_map)):
+        pset, prop, source = key
+        old = v1_map.get(key)
+        new = v2_map.get(key)
+
+        if _values_equal(old, new, float_tol):
+            continue
+        if prop_filter.is_ignored(pset, prop):
+            ignored += 1
+            continue
+
+        changes.append(
+            PropertyChange(
+                pset_name=pset,
+                property_name=prop,
+                source=PropertySource(source),
+                old_value=old,
+                new_value=new,
+            )
+        )
+
+    return changes, ignored
+
+
+def _values_equal(
+    a: str | float | int | bool | None,
+    b: str | float | int | bool | None,
+    float_tol: float,
+) -> bool:
+    if a is None and b is None:
+        return True
+    if a is None or b is None:
+        return False
+    if type(a) is bool or type(b) is bool:
+        return a == b
+    if isinstance(a, (int, float)) and isinstance(b, (int, float)):
+        return math.isclose(float(a), float(b), abs_tol=float_tol)
+    return a == b
+
+
+def _placement_changed(v1_el: ParsedElement, v2_el: ParsedElement, cfg: Settings) -> bool:
+    m1 = v1_el.storey_relative_placement
+    m2 = v2_el.storey_relative_placement
+
+    # Fall back to world placement if no storey context
+    if m1 is None or m2 is None:
+        m1 = v1_el.world_placement
+        m2 = v2_el.world_placement
+
+    return not _matrices_close(
+        m1, m2, cfg.placement_translation_tolerance, cfg.placement_rotation_tolerance_deg
+    )
+
+
+def _matrices_close(
+    m1: np.ndarray,
+    m2: np.ndarray,
+    trans_tol: float,
+    rot_tol_deg: float,
+) -> bool:
+    t1 = m1[:3, 3]
+    t2 = m2[:3, 3]
+    if float(np.linalg.norm(t1 - t2)) > trans_tol:
+        return False
+
+    r1 = m1[:3, :3]
+    r2 = m2[:3, :3]
+    r_diff = r1.T @ r2
+    trace = float(np.trace(r_diff))
+    trace_clamped = max(-1.0, min(3.0, trace))
+    angle_rad = math.acos(max(-1.0, min(1.0, (trace_clamped - 1.0) / 2.0)))
+    angle_deg = math.degrees(angle_rad)
+    return angle_deg <= rot_tol_deg
+
+
+def ensure_pair_geometry(
+    v1_el: ParsedElement,
+    v2_el: ParsedElement,
+    v1_model: ParsedModel | None,
+    v2_model: ParsedModel | None,
+) -> None:
+    v1_qto, v2_qto = pair_qto_volumes(v1_el, v2_el)
+    ensure_geometry(v1_el, v1_model, v1_qto)
+    ensure_geometry(v2_el, v2_model, v2_qto)
+
+
+def ensure_geometry(
+    el: ParsedElement, model: ParsedModel | None, qto_volume: float | None = None
+) -> None:
+    """Lazily compute the geometry signature; record a failure instead of hiding it."""
+    if el.geometry_signature is not None or el.geometry_failed or not el.has_representation:
+        return
+    if model is None or model._ifc_file is None or el._ifc_entity_id is None:
+        return
+    ifc_entity = model._ifc_file.by_id(el._ifc_entity_id)
+    signature = compute_geometry_signature(ifc_entity, model.unit_scale, qto_volume)
+    if signature is None:
+        el.geometry_failed = True
+    else:
+        el.geometry_signature = signature
+
+
+_VOLUME_QUANTITIES = ("NetVolume", "GrossVolume")
+
+
+def pair_qto_volumes(
+    v1_el: ParsedElement, v2_el: ParsedElement
+) -> tuple[float | None, float | None]:
+    """Exported volume quantities, used only when both sides carry the same one.
+
+    Mixing an exported quantity on one side with a mesh-derived volume on the other would
+    report a geometry change whenever "export base quantities" differs between exports.
+    """
+    v1_vols = _volume_quantities(v1_el.properties)
+    v2_vols = _volume_quantities(v2_el.properties)
+    for name in _VOLUME_QUANTITIES:
+        if name in v1_vols and name in v2_vols:
+            return v1_vols[name], v2_vols[name]
+    return None, None
+
+
+def _volume_quantities(props: list[PropertyValue]) -> dict[str, float]:
+    return {
+        p.property_name: p.value
+        for p in props
+        if p.property_name in _VOLUME_QUANTITIES and isinstance(p.value, float)
+    }

bimdelta_core-0.4.0/src/bimdelta_core/config.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+CONFIG_FILENAME = ".bimdelta.yml"
+
+# Matched against "<property set>.<property>" with fnmatch-style wildcards.
+DEFAULT_IGNORE_PROPERTIES: tuple[str, ...] = (
+    # Revit worksharing: the user currently holding the element, not a model property.
+    "*.Edited by",
+)
+
+
+class Settings(BaseSettings):
+    # All lengths in metres
+    float_tolerance: float = 1e-5
+    placement_translation_tolerance: float = 0.001
+    placement_rotation_tolerance_deg: float = 0.01
+    fallback_placement_tolerance: float = 0.050
+    geometry_bbox_tolerance: float = 0.001
+    geometry_volume_tolerance: float = 1e-6  # m³
+
+    include_openings: bool = False
+
+    # Disables every noise rule: ignore patterns and one-sided property set handling.
+    strict: bool = False
+    ignore_properties: list[str] = Field(default_factory=lambda: list(DEFAULT_IGNORE_PROPERTIES))
+
+    model_config = SettingsConfigDict(env_prefix="BIMDELTA_", env_file=".env", extra="ignore")
+
+
+def load_settings(config_path: str | Path | None = None, **overrides: Any) -> Settings:
+    """Build settings from defaults, BIMDELTA_* env vars, an optional YAML file and overrides.
+
+    Precedence (highest first): overrides, YAML file, environment, defaults.
+    """
+    data: dict[str, Any] = {}
+    if config_path is not None:
+        data.update(_read_config_file(Path(config_path)))
+    data.update(overrides)
+    return Settings(**data)
+
+
+def _read_config_file(path: Path) -> dict[str, Any]:
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict):
+        raise ValueError(f"{path}: expected a mapping at the top level")
+
+    known = set(Settings.model_fields)
+    unknown = sorted(set(raw) - known)
+    if unknown:
+        raise ValueError(
+            f"{path}: unknown setting(s) {', '.join(unknown)}. "
+            f"Valid settings: {', '.join(sorted(known))}"
+        )
+    return raw

bimdelta_core-0.4.0/src/bimdelta_core/engine.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import threading
+from collections import Counter, defaultdict
+from collections.abc import Callable
+from datetime import datetime, timezone
+
+from .comparator import build_added, build_removed, compare_matched
+from .config import Settings
+from .matcher import match_elements
+from .noise import build_property_filter, find_one_sided_psets
+from .parser import ParsedModel, parse_ifc
+from .schemas import (
+    DiffResult,
+    DiffSummary,
+    ElementDiff,
+    NoiseReport,
+    OneSidedPset,
+    PropertyChangeCount,
+    StoreyElevationChange,
+)
+
+TOP_CHANGED_PROPERTIES = 20
+
+
+# IfcOpenShell is not safe to use from several threads at once: parallel ifcopenshell.open()
+# calls intermittently fail to parse the header or crash the process. Diffs run one at a time.
+IFC_LOCK = threading.Lock()
+
+
+def run_diff(
+    v1_path: str,
+    v1_filename: str,
+    v2_path: str,
+    v2_filename: str,
+    cfg: Settings | None = None,
+) -> DiffResult:
+    cfg = cfg if cfg is not None else Settings()
+
+    with IFC_LOCK:
+        v1 = parse_ifc(v1_path, v1_filename, cfg.include_openings)
+        v2 = parse_ifc(v2_path, v2_filename, cfg.include_openings)
+
+        one_sided = [] if cfg.strict else find_one_sided_psets(v1, v2)
+        prop_filter = build_property_filter(cfg, one_sided)
+
+        match_result = match_elements(v1, v2, cfg.fallback_placement_tolerance)
+
+        elements: list[ElementDiff] = [
+            compare_matched(v1_el, v2_el, method, cfg, v1, v2, prop_filter=prop_filter)
+            for v1_el, v2_el, method in match_result.matched
+        ]
+
+    for el in match_result.added:
+        elements.append(build_added(el))
+
+    for el in match_result.removed:
+        elements.append(build_removed(el))
+
+    storey_changes = _compute_storey_elevation_changes(v1, v2)
+    summary = _build_summary(v1, v2, elements, storey_changes, cfg, one_sided)
+
+    return DiffResult(
+        v1_filename=v1_filename,
+        v2_filename=v2_filename,
+        v1_ifc_schema=v1.ifc_schema,
+        v2_ifc_schema=v2.ifc_schema,
+        timestamp=datetime.now(timezone.utc),
+        summary=summary,
+        elements=elements,
+    )
+
+
+def _build_summary(
+    v1: ParsedModel,
+    v2: ParsedModel,
+    elements: list[ElementDiff],
+    storey_changes: list[StoreyElevationChange],
+    cfg: Settings,
+    one_sided: list[OneSidedPset],
+) -> DiffSummary:
+    noise = NoiseReport(
+        strict=cfg.strict,
+        ignore_properties=[] if cfg.strict else list(cfg.ignore_properties),
+        ignored_property_changes=0,
+        one_sided_psets=one_sided,
+    )
+    summary = DiffSummary(
+        total_v1=len(v1.elements),
+        total_v2=len(v2.elements),
+        added=0,
+        removed=0,
+        modified=0,
+        unchanged=0,
+        by_class={},
+        by_storey={},
+        storey_elevation_changes=storey_changes,
+        noise=noise,
+    )
+    return _tally(summary, elements)
+
+
+def filter_result(result: DiffResult, keep: Callable[[ElementDiff], bool]) -> DiffResult:
+    """A copy of ``result`` with only the elements ``keep`` accepts, and the summary counts
+    recomputed for them. Model totals, storey elevation changes and the noise settings are
+    properties of the two models and stay as they are."""
+    elements = [el for el in result.elements if keep(el)]
+    summary = _tally(result.summary.model_copy(deep=True), elements)
+    return result.model_copy(update={"summary": summary, "elements": elements})
+
+
+def _tally(summary: DiffSummary, elements: list[ElementDiff]) -> DiffSummary:
+    """Fill the per-element counts of ``summary`` from ``elements``."""
+    counts: Counter[str] = Counter()
+    by_class: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
+    by_storey: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
+    changed_props: Counter[tuple[str, str]] = Counter()
+
+    for el in elements:
+        ct = el.change_type.value
+        counts[ct] += 1
+        by_class[el.ifc_class][ct] += 1
+        by_storey[el.storey or "(no storey)"][ct] += 1
+        changed_props.update({(p.pset_name, p.property_name) for p in el.property_changes})
+
+    summary.added = counts["added"]
+    summary.removed = counts["removed"]
+    summary.modified = counts["modified"]
+    summary.unchanged = counts["unchanged"]
+    summary.by_class = {k: dict(v) for k, v in by_class.items()}
+    summary.by_storey = {k: dict(v) for k, v in by_storey.items()}
+    summary.geometry_unknown = sum(1 for el in elements if el.geometry_unknown)
+    summary.top_changed_properties = [
+        PropertyChangeCount(pset_name=pset, property_name=prop, element_count=n)
+        for (pset, prop), n in sorted(changed_props.items(), key=lambda kv: (-kv[1], kv[0]))[
+            :TOP_CHANGED_PROPERTIES
+        ]
+    ]
+    if summary.noise is not None:
+        summary.noise.ignored_property_changes = sum(el.ignored_property_changes for el in elements)
+    return summary
+
+
+def _compute_storey_elevation_changes(
+    v1: ParsedModel, v2: ParsedModel
+) -> list[StoreyElevationChange]:
+    changes: list[StoreyElevationChange] = []
+    common_storeys = set(v1.storeys.keys()) & set(v2.storeys.keys())
+    for name in sorted(common_storeys):
+        old_elev = v1.storeys[name]
+        new_elev = v2.storeys[name]
+        if abs(old_elev - new_elev) > 1e-6:
+            changes.append(
+                StoreyElevationChange(
+                    storey_name=name,
+                    old_elevation=old_elev,
+                    new_elevation=new_elev,
+                )
+            )
+    return changes