# INFORTREAT BIM Toolkit — Complete Workflow Guide

This guide walks you through the entire process of producing an interactive BIM web viewer for a historical fortification treatise, starting from a 3D model in Rhino or any compatible 3D application.

---

## Overview

```
STEP 1: 3D Model
  └─ Create your model in any 3D modeling software (layer names = object names)
  └─ Export as .gltf or .glb

STEP 2: Excel Metadata
  └─ Fill in the Excel sheet with one row per object
  └─ The "Name" column must match the layer/object names exactly

STEP 3: Data Enrichment
  └─ Run the INFORTREAT Enrichment GUI
  └─ Select your .gltf and .xlsx files
  └─ Output: model.ifc, model.xkt, model_metadata.json

STEP 4: Web Publication
  └─ Install the WordPress plugin if you intend to use a dedicated web-viewer on your website (01_web_viewer/)
  └─ Upload model.xkt and model_metadata.json to WordPress Media
  └─ Add the shortcode to your page

STEP 5: (Optional) Share with us on the INFORTREAT platform
  └─ See HOW_TO_PARTICIPATE.md
```

---

## Step 1 — Prepare the 3D Model

### Supported software
- **Rhinoceros 3D** (recommended) — use layers or object names
- **Blender**, **SketchUp**, or any software that can export GLTF

### Export format
Export as **GLTF** (`.gltf` with external buffer, or `.glb` as a single file).

### Layer / Object naming (CRITICAL)
The names of layers or objects in your 3D software **must match exactly** the names in the `Name` column of your Excel sheet.

**Example in Rhino:**
```
Layer "Flank Wall"     → corresponds to "Flank Wall" in Excel
Layer "Curtain Wall"   → corresponds to "Curtain Wall" in Excel
Layer "Bastion Tip"    → corresponds to "Bastion Tip" in Excel
```

> **Tip:** Use English names without special characters. Spaces are fine.

---

## Step 2 — Prepare the Excel Metadata Sheet

Open the sample `Sardi_input.xlsx` in `03_sample_sardi/input/` as a reference.

### Required structure

| Name | Type | General_dimensions | Unit | Treatise | Category | Materials | Construction | Definition | ... |
|------|----|---|---|---|---|---|---|---|---|
| Flank Wall | Wall | W=8; H=40 | Piede geometrico = 0.348 m | Corno Dogale, Pietro Sardi, 1638 | Internal Works | Bricks | Masonry wall | Libro II, Cap. IV, p.57 | ... |

### Rules
- **First column must be `Name`** — it links each row to the 3D object
- One row per object/element
- Any column you add becomes a property in the BIM viewer
- Empty cells are ignored (no error)

---

## Step 3 — Run the Data Enrichment

### Prerequisites
1. **Python 3.9+** installed and accessible in the system PATH
2. **Node.js 16+** installed (for XKT conversion via `xeokit-convert`)
3. Run `setup_env.bat` **once** to install Python dependencies

### Installation (first time only)
```
02_data_enrichment\setup_env.bat
```

Then install `xeokit-convert`:
```
npm install -g @xeokit/xeokit-convert
```

### Running the tool
```
02_data_enrichment\run_enrichment.bat
```

This opens the **INFORTREAT Workflow GUI**:

1. **GLTF Model** — click Browse and select your `.gltf` file
2. **Excel Data** — click Browse and select your `.xlsx` file
3. **Output Folder** — where the files will be saved (default: `output/`)
4. **File Name** — base name for all output files (e.g., `mymodel`)
5. Click **"Convert to IFC"**

After the GUI completes, close it. The `.bat` file will then automatically:
- Convert the `.ifc` to `.xkt` using `xeokit-convert`
- Extract metadata to `mymodel_metadata.json`

### Output files
| File | Purpose |
|------|---------|
| `mymodel.ifc` | Standard BIM file (for Revit, ArchiCAD, etc.) |
| `mymodel.xkt` | Optimized 3D file for the web viewer |
| `mymodel_metadata.json` | Property data for the web viewer |

---

## Step 4 — Publish on WordPress

### Install the plugin
1. In WordPress admin → Plugins → Add New Plugin → Upload Plugin
2. Create a ZIP of the `01_web_viewer/` folder and upload it
3. Activate the plugin

### Upload your model files
1. Go to **Media → Add New**
2. Upload `mymodel.xkt` and `mymodel_metadata.json`
3. Copy the URL of `mymodel.xkt`

> **Important:** Both files must be in the **same folder** on the server.

### Add the viewer to a page
In any WordPress page or post, use the shortcode:
```
[bim_viewer url="https://yoursite.com/wp-content/uploads/2026/01/mymodel.xkt" name="Author, Title, Year"]
```

### Optional parameters
| Parameter | Default | Example |
|-----------|---------|---------|
| `height` | `600px` | `height="800px"` |
| `width` | `100%` | `width="100%"` |
| `name` | from filename | `name="Pietro Sardi, 1638"` |

---

## Step 5 — Test with the Sardi Sample

The `03_sample_sardi/` folder contains a complete processed example:
- `input/sardi_test.gltf` — the 3D model
- `input/Sardi_input.xlsx` — the metadata sheet
- `output/sardi_test.xkt` — ready to upload to WordPress
- `output/sardi_test_metadata.json` — ready to upload to WordPress

Upload the two `output/` files to your WordPress media library and use:
```
[bim_viewer url="https://yoursite.com/wp-content/uploads/.../sardi_test.xkt" name="Corno Dogale, Pietro Sardi, 1638"]
```
If you are using this files in any public context, please credit the INFORTREAT project.
---

## Viewer Tools

The viewer includes:
- **Reset** — return camera to default position
- **Slice H / Slice V** — horizontal or vertical section cut; use ➖ ➕ to move it and Flip to invert
- **Measure** — click two points to measure distances; Clear to remove all measurements
- **Ortho / Persp** — switch between orthographic and perspective camera
- **NavCube** — click faces/edges to snap to orthogonal views

---

## Troubleshooting

| Problem | Solution |
|---------|---------|
| `xeokit-convert not found` | Run `npm install -g @xeokit/xeokit-convert` |
| `python not found` | Install Python 3.9+ and add to PATH |
| XKT loads but no properties | Ensure `_metadata.json` is in the same folder as `.xkt` |
| Model not visible after upload | Enable XKT/BIN MIME types (the plugin does this automatically) |
| `Python venv error` | Delete `02_data_enrichment/venv/` folder and run `setup_env.bat` again |

---

*For more information: [infortreat.unipi.it](https://www.infortreat.unipi.it)*
