# INFORTREAT Web BIM - WordPress Plugin

A WordPress plugin for embedding interactive 3D BIM models of Early Modern fortifications using xeokit-sdk. This viewer enables scholars, heritage professionals, and students to explore theoretical models from historical treatises on military architecture.

![INFORTREAT Logo](INFOTREAT_Logotipo_03.png)

## About INFORTREAT

**INFORTREAT** (Reconstructing the Early Modern bastioned front. INformation models for the fruition of constructive knowledge in FORtified architecture TREATises, 16th-18th Century) is a research project aimed at creating a new integrated analysis tool for the interpretation, restoration and maintenance of Early Modern fortified heritage.

The project produces Heritage-Building Information Models (H-BIM) of bastioned fortifications, making historical construction knowledge accessible through 3D representations and interactive web-based viewers.

### Project Website
Visit [infortreat.unipi.it](https://www.infortreat.unipi.it) for more information about the research project.

---

## Features

- **Interactive 3D Viewer**: Explore BIM models directly in your WordPress pages
- **Property Inspection**: Click on elements to view detailed metadata (materials, dimensions, construction techniques)
- **External Metadata Support**: Load property sets from external JSON files
- **Multi-Treatise Support**: Display models from different historical treatises on separate pages
- **Customizable Styling**: Easy CSS customization with predefined color variables
- **Responsive Design**: Works on desktop and mobile devices
- **Mouse Wheel Control**: Scroll to zoom when hovering over the model (no page scroll interference)

---

## Installation

### Prerequisites
- WordPress 5.0 or higher
### Basic Shortcode

```wordpress
[bim_viewer url="https://yoursite.com/wp-content/uploads/2025/01/model.xkt" name="Pietro Sardi, 1639"]
```

### Shortcode Parameters

| Parameter | Required | Description | Default |
|-----------|----------|-------------|---------|
| `url` | Yes | URL to the .xkt or .bin model file | - |
| `name` | No | Display name of the treatise/model | Extracted from filename |
| `height` | No | Viewer height | `600px` |
| `width` | No | Viewer width | `100%` |

### Example with All Parameters

```wordpress
[bim_viewer 
    url="https://yoursite.com/wp-content/uploads/2025/01/sardi.xkt" 
    name="Corno Dogale dell'Architettura Militare, Pietro Sardi, 1638"
    height="800px"
    width="100%"]
```

---

## File Structure

```
infortreat-web-bim/
├── infortreat-web-bim.php    # Main plugin file
├── viewer.js                  # Viewer initialization and interaction logic
├── viewer.css                 # Styling (customizable)
├── README.md                  # This file
├── LICENSE                    # AGPLv3 license
├── CUSTOMIZATION.md           # Guide for customizing colors and styles
└── QUICKSTART.md              # Quick installation guide
```

---

## Model Preparation

This plugin requires models in **XKT format** with optional external **JSON metadata**. Here's how to prepare your files:

### 1. Converting IFC to XKT

**XKT** is xeokit's optimized 3D format. Convert your IFC files using [xeokit-convert](https://github.com/xeokit/xeokit-convert):

```bash
# Install xeokit-convert
npm install -g @xeokit/xeokit-convert

# Convert IFC to XKT
xeokit-convert -s model.ifc -o model.xkt
```

**Important:** The XKT file contains the 3D geometry but **not all IFC metadata** by default.

**Reference:** [xeokit-convert documentation](https://github.com/xeokit/xeokit-convert)

### 2. Extracting Metadata from IFC

To display property sets in the viewer, create a JSON metadata file using **IfcOpenShell**:

```python
import ifcopenshell
import json

ifc_file = ifcopenshell.open("model.ifc")
meta_objects = []

# Extract properties for each element
for element in ifc_file.by_type("IfcBuildingElementProxy"):
    psets = []
    for rel in element.IsDefinedBy:
        if rel.is_a("IfcRelDefinesByProperties"):
            pset_data = rel.RelatingPropertyDefinition
            if pset_data.is_a("IfcPropertySet"):
                props = []
                for prop in pset_data.HasProperties:
                    props.append({
                        "name": prop.Name,
                        "value": str(prop.NominalValue.wrappedValue) if prop.NominalValue else "N/A"
                    })
                psets.append({"name": pset_data.Name, "properties": props})
    
    meta_objects.append({
        "id": element.GlobalId,
        "name": element.Name,
        "type": element.is_a(),
        "propertySets": psets
    })

# Save as JSON
with open("model_metadata.json", "w") as f:
    json.dump({"metaObjects": meta_objects}, f, indent=2)
```

**Naming Convention:** If your model is `model.xkt`, name the metadata `model_metadata.json`.

### 3. Upload to WordPress

1. Upload both `model.xkt` and `model_metadata.json` to the **same WordPress media folder**
2. The plugin automatically looks for `modelname_metadata.json` alongside the XKT file

**Reference:** [xeokit-sdk MetaModel docs](https://github.com/xeokit/xeokit-sdk/wiki/Models#metadata)

---

## Customization

See [CUSTOMIZATION.md](CUSTOMIZATION.md) for detailed instructions on customizing colors, fonts, and layout.

### Quick Color Change

Edit `viewer.css` and modify the CSS variables in `:root`:

```css
:root {
    --sbv-primary-color: #55452A;  /* Main color */
    --sbv-bg-light: #CFC5B4;       /* Light background */
    --sbv-bg-white: #99A170;       /* Panel background */
}
```

---

## Metadata Format

The plugin supports external metadata files in JSON format. Place a `modelname_metadata.json` file alongside your `.xkt` file.

Example: If your model is `sardi.xkt`, create `sardi_metadata.json`:

```json
{
  "metaObjects": [
    {
      "id": "unique-guid",
      "name": "Bastion Terre-plein",
      "type": "IfcBuildingElementProxy",
      "propertySets": [
        {
          "name": "Pset_HistoricalTreatise",
          "properties": [
            { "name": "Treatise", "value": "Corno Dogale, Pietro Sardi, 1638" },
            { "name": "Type", "value": "Terre-plein" },
            { "name": "Materials", "value": "Earth" }
          ]
        }
      ]
    }
  ]
}
```

---

## Technical Details

### Dependencies
- **[xeokit-sdk](https://github.com/xeokit/xeokit-sdk)** (loaded via CDN): 3D BIM viewer engine - AGPLv3 licensed
- **[xeokit-convert](https://github.com/xeokit/xeokit-convert)**: CLI tool for IFC → XKT conversion (required for model preparation)
- **[IfcOpenShell](https://ifcopenshell.org/)**: Python library for IFC metadata extraction (optional, for metadata files)
- WordPress 5.0+
- ES6 Module support in browser

### Browser Compatibility
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

### Model Format
- **Input:** IFC files (Industry Foundation Classes)
- **Viewer:** XKT files (xeokit optimized format)
- **Metadata:** JSON files following xeokit's `metaObjects` structure

**External Documentation:**
- [xeokit-sdk GitHub](https://github.com/xeokit/xeokit-sdk)
- [xeokit-convert GitHub](https://github.com/xeokit/xeokit-convert)
- [IFC format specification](https://technical.buildingsmart.org/standards/ifc/)

---

## License

This plugin is licensed under the **GNU Affero General Public License v3.0 (AGPLv3)**.

This is required because it uses [xeokit-sdk](https://github.com/xeokit/xeokit-sdk), which is also AGPLv3 licensed.

### What This Means
- You can use, modify, and distribute this plugin
- You must keep the same AGPLv3 license
- You must provide source code to users (network use clause applies)
- Modifications must be shared back to the community

See [LICENSE](LICENSE) for full terms.

---

## Contributing

Contributions are welcome! This is an open-source research project.

### How to Contribute
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

---

## Funding Acknowledgment

Research Project financed by the **European Union – Next-GenerationEU** – **National Recovery and Resilience Plan (NRRP)** – **MISSION 4 COMPONENT 2, INVESTMENT N. 1.1, CALL PRIN 2022 D.D. 104 02-02-2022**.

**Project:** INFORTREAT - Reconstructing the Early Modern bastioned front. INformation models for the fruition of constructive knowledge in FORtified architecture TREATises (16th-18th Century): a new integrated analysis tool for the interpretation, restoration and maintenance of Early Modern fortified heritage.

**CUP:** I53D23005420006

![PNRR NextGenerationEU](HEADER_Tavola-disegno-1-2-scaled.jpg)

---

## Contact

**Dipartimento di Ingegneria dell'Energia, dei Sistemi, del Territorio e delle Costruzioni**  
Università di Pisa  
Largo Lucio Lazzarino 1  
56122 Pisa, Italy

Email: [infortreat@ing.unipi.it](mailto:infortreat@ing.unipi.it)  
Website: [infortreat.unipi.it](https://www.infortreat.unipi.it)  
Publications: [Publications Page](https://www.infortreat.unipi.it/publications/)

**For technical issues with this plugin:**
-  Contact us at [infortreat@ing.unipi.it](mailto:infortreat@ing.unipi.it)
-  Check the [CUSTOMIZATION.md](CUSTOMIZATION.md) guide

---

## Research Team & Partners

**Principal Institution:** University of Pisa (Italy)

For the full list of research units and partner institutions, visit the [INFORTREAT Partners page](https://www.infortreat.unipi.it/partners/).

---

##  Citation

If you use this plugin in your research, please cite:

```
INFORTREAT Web BIM - WordPress Plugin (2025). 
Developed as part of the INFORTREAT research project.
```

---
