BRIDGE 4D STARTER KIT - BIM Corner / Road to BIM
=================================================
Guide: https://bimcorner.com/4d-from-ifc-bonsai-blender-construction-animation/

WHAT IS IN THIS FOLDER
----------------------
Bridge_START_no_4D.ifc      Bridge BR-01, IFC 4.3 (IFC4X3_ADD2). Geometry only, NO schedule.
                            This is the file you use to follow the guide, step by step.
03_Bridge_BEST_IFC4x3.ifc   The same bridge WITH the finished 4D schedule: 5 stages,
                            17 tasks, dates, dependencies, 51 task-to-element links.
                            Use it to compare your result, or to see the film right away.
Run_4D_animation.bat        Windows: double-click this to build the animation and the MP4
                            from 03_Bridge_BEST_IFC4x3.ifc. No typing needed.
bonsai_4d.py                The script the .bat runs. Not a double-click program (see below).
README.txt                  This file.


BEFORE YOU START (one time, about 10 minutes)
---------------------------------------------
1. Unzip the whole folder first (right-click the ZIP > Extract All).
   Nothing works from inside the ZIP.
2. Install Blender 4.2 or newer: https://www.blender.org/download/
   The kit was tested with Blender 5.1.
3. Install Bonsai inside Blender:
   Blender > Edit > Preferences > Get Extensions > search "Bonsai" > Install.
   (If Blender asks to allow online access, allow it.) Close Blender afterwards.
   The kit was tested with Bonsai 0.8.5.


OPTION A - FOLLOW THE GUIDE BY HAND (recommended, this is how you learn it)
--------------------------------------------------------------------------
1. Start Blender. File > Open IFC Project > Bridge_START_no_4D.ifc > Load Project.
2. Follow the 13 steps in the guide (link at the top).
3. When you are done, compare with 03_Bridge_BEST_IFC4x3.ifc.


OPTION B - SEE THE FINISHED FILM IN ONE CLICK (Windows)
-------------------------------------------------------
1. Double-click Run_4D_animation.bat.
   If Windows shows "Windows protected your PC": click "More info" > "Run anyway".
   The .bat is plain text, you can open it in Notepad and read every line first.
2. It finds Blender by itself. If it cannot, it asks you to drag blender.exe into
   the window (usually C:\Program Files\Blender Foundation\Blender 5.1\blender.exe).
3. Type 1 (full run, film) or 2 (quick run, preview images only) and press Enter.
4. Wait. Lines starting with [4D] show progress. The full run takes 1-10 minutes
   depending on your computer.
5. When it says DONE, the film opens. Everything is saved in the new 4D_output folder:
     Bridge_4D.mp4    the construction film (1920x1080, about 12 seconds)
     Bridge_4D.blend  the animated scene: open it in Blender and press Space to play,
                      or drag the timeline to any date
     stills\          6 preview images


OPTION C - COMMAND LINE (Windows, macOS, Linux)
-----------------------------------------------
Open a terminal in this folder and run (adjust the path to Blender):

  Windows:
    "C:\Program Files\Blender Foundation\Blender 5.1\blender.exe" --background --factory-startup --python bonsai_4d.py

  macOS:
    /Applications/Blender.app/Contents/MacOS/Blender --background --factory-startup --python bonsai_4d.py

  Linux:
    blender --background --factory-startup --python bonsai_4d.py

Without extra options it animates 03_Bridge_BEST_IFC4x3.ifc into the 4D_output folder.
Your own file or other settings go after a double dash:

    ... --python bonsai_4d.py -- --ifc my_bridge.ifc --out my_output --fpw 6

  --ifc FILE     IFC file WITH a work schedule (default: 03_Bridge_BEST_IFC4x3.ifc)
  --out FOLDER   where the results go (default: 4D_output)
  --fpw N        animation frames per week of construction (default 12; 6 = faster film)
  --res WxH      video size (default 1920x1080)
  --no-render    build the scene and preview images only, no MP4
  --stills N     number of preview images (default 6, 0 = none)
  --hold S       seconds to hold the finished bridge at the end (default 2)


WHY DOES DOUBLE-CLICKING bonsai_4d.py NOT WORK?
-----------------------------------------------
The script needs Blender's own built-in Python (it starts with "import bpy").
Double-clicking a .py file uses a normal Python installation, if you have one:
a black window flashes and closes with "No module named 'bpy'". Or Windows asks
which program to open it with. Always run it through Blender (options B or C).


IF SOMETHING GOES WRONG
-----------------------
"Bonsai is not installed"    Do step 3 of BEFORE YOU START, then try again.
"Blender was not found"      Install Blender, or drag blender.exe into the window.
"no IfcWorkSchedule"         You ran it on Bridge_START_no_4D.ifc. That file has no
                             schedule yet, which is the point of the exercise. Use
                             03_Bridge_BEST_IFC4x3.ifc, or your own file after
                             finishing the guide.
"... is missing"             You started it from inside the ZIP. Extract All first.
Window closes immediately    You double-clicked bonsai_4d.py. Use Run_4D_animation.bat.
Film is empty / all grey     Open Bridge_4D.blend and check that tasks have dates
                             and that elements are assigned to tasks (guide steps 6-7).


WHAT IS DELIBERATELY NOT IN THESE FILES
---------------------------------------
Only what the 4D exercise needs is inside: the spatial tree
(Project > Site > Bridge > Bridge parts), 151 physical elements with their IFC class,
name, geometry and colour, and the railing posts under the railings.

Properties, quantities, classifications, materials, alignment and stationing,
georeferencing, cost data, the analysis model and document links are removed.
The full-information version of the same bridge is shown in the free webinar
"IFC 2x3 vs IFC 4.3": https://roadtobim.com/webinar/
