Assorted fixes

Merge pull request #8 from kenohori/cgal

merge

…eets

This commit adds a complete Bill of Quantities (BOQ) export system for the
federation module with three critical fixes:

## Critical Fixes Applied

### Fix IfcOpenShell#1: Correct Quantity Calculation (Strategy A)
- **Problem**: BOQ was summing ALL quantity types together (Length + Area + Volume)
  resulting in nonsensical mixed units and costs in billions
- **Solution**: Use PRIMARY quantity only per element type:
  - IfcWall → GrossSideArea (M2) only, not mixed with NetVolume
  - IfcBeam → Length (M) only, not mixed with Volume
  - IfcDoor → Count (EA)
- **Result**: Realistic costs instead of billions

### Fix IfcOpenShell#2: Friendly IFC Element Descriptions
- **Problem**: BOQ showed technical names like "IfcWall" instead of readable text
- **Solution**: Created ifc_labels table in database with 28 friendly names
- **Examples**:
  - IfcWall → "Blockwork Wall (150mm)"
  - IfcBeam → "Structural Steel I-Beam"
  - IfcDuct → "Galvanized Steel Ductwork"

### Fix IfcOpenShell#3: Reference Sheets with Excel Cell Formulas
- **Problem**: Users couldn't see or edit unit costs
- **Solution**: Added 3 reference sheets with editable rates:
  - 📋 Material Rates (25+ materials)
  - 👷 Labor Rates (8 trades)
  - 🚜 Equipment Rates (7+ equipment types)
- **Benefit**: Change rate in ONE place → all BOQ sheets recalculate automatically

## New Files Added

1. **comprehensive_boq_export_fixed.py** (658 lines)
   - Fixed BOQ exporter with Strategy A quantity logic
   - Dual-schema support (aggregated + enhanced databases)
   - Creates 13-sheet Excel: Cover + Dashboard + 3 Reference + 8 BOQ sheets
   - Executive Dashboard with Pie & Bar charts

2. **create_ifc_labels_table.py** (280 lines)
   - Creates ifc_labels table with 28 IFC class descriptions
   - Maps primary quantity type per element (Length, Area, Count, etc.)
   - Usage: python3 create_ifc_labels_table.py <database_path>

3. **BOQ_System_User_Guide_For_Accountants.md** (1040 lines)
   - Complete user guide for accountants & quantity surveyors
   - Appendix A: Cost calculation reference tables (390 lines)
   - Shows where to edit rates, regional adjustments, inflation factors

## Features

- ✅ Primary quantity logic prevents mixed unit aggregation
- ✅ IFC labels integration with graceful fallback
- ✅ Excel cell formulas link BOQ to reference sheets
- ✅ Executive Dashboard with charts (Pie + Bar)
- ✅ Malaysian construction standards (CIDB N3C, BCISM 2024)
- ✅ Dual database schema support (auto-detection)
- ✅ 8 disciplines: ACMV, ARC, CW, ELEC, FP, LPG, SP, STR

## Technical Details

- Database tables: elements_meta, element_properties, simple_qto, ifc_labels
- Query optimization for both aggregated and enhanced schemas
- openpyxl charts: PieChart, BarChart with DataBar formatting
- Cost sources: CIDB N3C 2024-Q4, BCISM Cost Book, MBAM-CIDB Survey 2024

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

…mation

Provides ready-to-use scripts for professional construction showcases
with sectional reveals and automated camera flythroughs.

## New Example Scripts

**Location:** `src/bonsai/docs/federation/examples/`

### 1. sectional_reveal_mep.py (11KB)
- Hides building envelope (ARC + STR) at specified frames
- Reveals hidden MEP systems (ACMV, ELEC, FP) dramatically
- 4 presets: single reveal, three-stage, long section, MEP-only
- Configurable timing and disciplines

### 2. automated_mep_showcase.py (17KB)
- ✅ Automated camera flythrough (orbits around/inside building)
- ✅ Sectional reveal (hides envelope during MEP phase)
- ✅ Auto-switches to camera view (no numpad 0 needed!)
- ✅ Perfectly timed to construction schedule
- Auto-calculated camera path based on building bounds
- Smooth Bezier interpolation for cinematic movement
- Three-phase sequence: Approach → Interior orbit → Exit

### 3. automated_mep_showcase_fast.py (8KB)
- Same as IfcOpenShell#2 but with real-time progress output
- Shows progress every 1000 objects (for 49k elements)
- Displays estimated time remaining
- Use when original script seems slow

## Features

**Automated Camera Path:**
```
Frame 3800:      Camera approaches from outside
Frame 4000:      💥 Envelope HIDES + Camera ENTERS
Frame 4000-4200: Camera orbits INSIDE (shows MEP systems)
Frame 4200:      Envelope RETURNS + Camera EXITS
Frame 4300:      Overview shot
```

**Multiple Presets:**
- Early MEP reveal (frame 2000 - foundation phase)
- Midpoint reveal (frame 4000 - MEP rough-in) [DEFAULT]
- Late reveal (frame 6000 - ceiling MEP)
- Extended showcase (500 frames for presentations)

**Hands-Free Operation:**
1. Run script → 2-5 minutes processing
2. Auto-switches to camera view
3. Press SPACEBAR → Watch cinematic showcase!

## Workflow: Multiple Versions

Users can create specialized versions for different audiences:
- Basic (architects): No scripts, basic construction
- MEP Reveal (coordinators): Sectional cut only
- Full Showcase (clients): Automated camera + reveal
- Custom (managers): Different timing/phases

Each version ~840MB, kept separately.

## Documentation Updates

**4D_Scheduling_Animation_Guide.md:**
- New section: "Example Scripts: Automated MEP Showcase"
- Complete usage instructions for all 3 scripts
- Timeline sequences and preset descriptions
- Camera tips and customization guide
- Workflow for creating multiple versions
- Updated "Future Enhancements" (camera automation ✅ done)
- Updated "Related Documentation" with script links

## Benefits vs Manual Workflow

**Traditional (manual):**
- Manually create keyframes for sectional cuts (hours)
- Manually animate camera path (hours)
- Risk of jerky camera movement
- Tedious trial-and-error for timing

**With these scripts (automated):**
- Run script, press SPACEBAR (2-5 min setup)
- Professional cinematic camera paths
- Perfect timing with construction schedule
- Reusable for different projects

## Validation

**Tested on Terminal 1 project:**
- 49,059 elements
- Processing time: 2-3 minutes
- Camera path: 9 keyframes (smooth Bezier)
- Building bounds: Auto-detected (121.5, -21.7, -0.8), radius 51.6m
- Result: Professional MEP showcase ready for clients

**No numpad needed:**
- Auto-switches to camera view after setup
- Accessibility improvement for laptops
- One less thing for users to remember

## Use Cases

1. **Client presentations** - Impress stakeholders with flythrough
2. **MEP coordination** - Show hidden systems to subcontractors
3. **Design reviews** - Reveal envelope conflicts visually
4. **Marketing** - Create promotional videos from 4D model
5. **Training** - Demonstrate construction sequence

## Technical Highlights

**Auto-calculated camera positioning:**
- Analyzes building bounding box
- Calculates orbit radius (70% of building width)
- Positions camera at mid-height for best view
- Points camera at building center (always in frame)

**Smooth interpolation:**
- Bezier curves for all keyframes
- Auto handles for natural camera movement
- No jerky motion or sudden stops

**Discipline filtering:**
- Configurable which disciplines to hide
- Default: ARC + STR (envelope)
- Can extend to CW, FP for deeper reveals

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>