Bonsai Impl Qto

Bonsai QTO (Quantity Takeoff): Implementation Skill

Bonsai v0.8.x | Module: bonsai.bim.module.qto | NEVER use blenderbim.bim.module.qto

1. Quick Reference

Critical Warnings

• ALWAYS verify objects have mesh geometry before running QTO calculators. Empties, curves, and lights cause failures.
• ALWAYS ensure objects have an IFC class assigned via Bonsai before running QTO. Calculator functions query IFC properties.
• ALWAYS assign Pset_MaterialCommon.MassDensity BEFORE running weight calculations (get_net_weight, get_gross_weight).
• ALWAYS re-run QTO calculations after modifying geometry. Quantities are NOT live-linked to geometry.
• NEVER assume get_gross_volume() accounts for openings. Gross = original geometry WITHOUT openings. Net = WITH openings subtracted.
• NEVER use the legacy blenderbim module path. ALWAYS use bonsai.bim.module.qto.

Decision Tree: Which QTO Approach?

Need quantities for IFC elements?
├── Single element, single quantity?
│   └── Use bim.calculate_single_quantity operator
│       Parameters: calculator, qto_name, prop_name, calculator_function
│
├── Single element, all base quantities?
│   └── Use bim.perform_quantity_take_off with element selected
│       Select object → Set qto_rule → Execute operator
│
├── Multiple elements, standard base quantities?
│   └── Use bim.perform_quantity_take_off in batch mode
│       Select all target objects → Set qto_rule → Execute operator
│
├── All elements of a class?
│   └── Use bim.perform_quantity_take_off with no selection
│       Operator processes all IfcElement instances matching the rule
│
├── Custom quantity (edge lengths, face areas)?
│   └── Use mesh-level operators in Edit Mode:
│       - bim.calculate_edge_lengths (selected edges)
│       - bim.calculate_face_areas (selected faces)
│       - bim.calculate_circle_radius (selected vertices)
│
└── Need gross vs net distinction?
    ├── With openings (doors/windows in walls) → Use net variants
    │   get_net_volume(), get_net_surface_area(), get_net_footprint_area()
    └── Without openings (original geometry) → Use gross variants
        get_gross_volume(), get_gross_surface_area(), get_gross_footprint_area()

2. Module Architecture

File Structure

Two-Layer System

1. Calculator functions (calculator.py) — Extract numeric values from Blender geometry (bpy.types.Object)
2. QTO rules (JSON configuration) — Map IFC classes to standard quantity sets and calculator functions

Core/Tool/Operator Pattern

bonsai.core.qto        → Pure logic functions (accept tool interfaces)
bonsai.tool.Qto        → Blender-specific implementations
bonsai.bim.module.qto  → Operators that wire core to tool

3. Calculator Functions by Category

Linear Quantities

Area Quantities

Volume Quantities

Weight Quantities

Specialized Quantities

4. QTO Rules (JSON Configuration)

Rules map IFC classes to standard quantity sets and calculator functions. Stored as JSON in ifc5d.qto.rules.

Rule Structure

{
    "Name": "Qto_WallBaseQuantities",
    "Description": "Standard wall base quantities per IFC4",
    "Calculator": "Blender",
    "Mappings": {
        "IfcWall": {
            "Qto_WallBaseQuantities": {
                "Length": "get_length",
                "Width": "get_width",
                "Height": "get_height",
                "GrossFootprintArea": "get_gross_footprint_area",
                "NetFootprintArea": "get_net_footprint_area",
                "GrossSideArea": "get_gross_surface_area",
                "NetSideArea": "get_net_surface_area",
                "GrossVolume": "get_gross_volume",
                "NetVolume": "get_net_volume"
            }
        }
    }
}

Rule Selection

• BIMQtoProperties.qto_rule — Enum populated from tool.Qto.get_qto_rules()
• Rules are filtered by IFC schema version (IFC4 vs IFC4X3)
• BIMQtoProperties.fallback=True — Tries alternative calculators if primary lacks support

5. Standard Quantity Sets

6. Operators Reference

PerformQuantityTakeOff: Primary Batch Operator

# Bonsai v0.8.x: Batch quantity takeoff
import bpy

bpy.ops.bim.perform_quantity_take_off(
    qto_rule="Qto_WallBaseQuantities"  # Rule name from JSON config
)

Behavior: Processes selected objects. If no objects selected, processes ALL IfcElement instances matching the rule's IFC class filter.

CalculateSingleQuantity: Targeted Calculation

# Bonsai v0.8.x: Single quantity calculation
bpy.ops.bim.calculate_single_quantity(
    calculator="Blender",
    qto_name="Qto_WallBaseQuantities",
    prop_name="GrossVolume",
    calculator_function="get_gross_volume"
)

7. Cost Integration

QTO integrates with Bonsai cost management:

# Bonsai v0.8.x: QTO-Cost linkage
# tool.Qto.get_related_cost_item_quantities(product) returns:
# [{"cost_item": <IfcCostItem>, "quantities": [<matched quantity properties>]}]

Unit conversion: tool.Qto.convert_to_project_units() handles measurement system conversion using IFC schema unit definitions.

8. External Dependencies

9. Gross vs. Net: Critical Distinction

Gross quantities:
  - Original element geometry WITHOUT openings
  - Wall with door opening → gross volume = solid wall volume
  - Use when: material ordering, structural analysis

Net quantities:
  - Element geometry WITH openings subtracted
  - Wall with door opening → net volume = wall volume minus door void
  - Use when: actual material in place, cost calculation

ALWAYS choose the correct variant. Using gross when net is required (or vice versa) produces incorrect quantity takeoffs.

10. Reference Files

• references/methods.md — Complete API signatures for all calculator functions and operators
• references/examples.md — Working QTO workflow examples
• references/anti-patterns.md — Common QTO mistakes and correct approaches