diff --git a/src/bonsai/docs/users/images/uninstall.png b/src/bonsai/docs/users/images/uninstall.png new file mode 100644 index 0000000000..0131459a27 Binary files /dev/null and b/src/bonsai/docs/users/images/uninstall.png differ diff --git a/src/bonsai/docs/users/images/update.png b/src/bonsai/docs/users/images/update.png new file mode 100644 index 0000000000..15db3e8449 Binary files /dev/null and b/src/bonsai/docs/users/images/update.png differ diff --git a/src/bonsai/docs/users/quickstart/images/install-blenderbim-2.png b/src/bonsai/docs/users/quickstart/images/install-blenderbim-2.png index ab81f74adf..fdd17caedf 100644 Binary files a/src/bonsai/docs/users/quickstart/images/install-blenderbim-2.png and b/src/bonsai/docs/users/quickstart/images/install-blenderbim-2.png differ diff --git a/src/bonsai/docs/users/quickstart/images/install-blenderbim-3.png b/src/bonsai/docs/users/quickstart/images/install-blenderbim-3.png index 7af37299d9..0d04bc0456 100644 Binary files a/src/bonsai/docs/users/quickstart/images/install-blenderbim-3.png and b/src/bonsai/docs/users/quickstart/images/install-blenderbim-3.png differ diff --git a/src/bonsai/docs/users/quickstart/images/install-blenderbim-4.png b/src/bonsai/docs/users/quickstart/images/install-blenderbim-4.png index 553eb91982..8a22736026 100644 Binary files a/src/bonsai/docs/users/quickstart/images/install-blenderbim-4.png and b/src/bonsai/docs/users/quickstart/images/install-blenderbim-4.png differ diff --git a/src/bonsai/docs/users/quickstart/images/install-blenderbim-5.png b/src/bonsai/docs/users/quickstart/images/install-blenderbim-5.png new file mode 100644 index 0000000000..989e31e7b1 Binary files /dev/null and b/src/bonsai/docs/users/quickstart/images/install-blenderbim-5.png differ diff --git a/src/bonsai/docs/users/quickstart/installation.rst b/src/bonsai/docs/users/quickstart/installation.rst index e0b31458e1..30c3fa8a06 100644 --- a/src/bonsai/docs/users/quickstart/installation.rst +++ b/src/bonsai/docs/users/quickstart/installation.rst @@ -1,11 +1,6 @@ Installation ============ -.. raw:: html - - - - 1. **Download and install Blender** Blender is a free and open-source program for 3D authoring. It works on @@ -20,121 +15,28 @@ Installation No administrator rights on Windows? Choose the "Portable .zip" option when downloading from the Blender website. -2. **Download the BlenderBIM Add-on** - - The BlenderBIM Add-on extends Blender with OpenBIM related capabilities. - -.. container:: blockbutton - - `Download Bonsai `__ - -3. **Install the BlenderBIM Add-on** - - Open up Blender, and click on ``Edit > Preferences``. +2. Open up Blender, and click on ``Edit > Preferences``. .. image:: images/install-blenderbim-1.png - Select the **Add-ons** tab, and press **Install...** on the top right. Navigate - to the .zip you downloaded in Step 2, and press **Install Add-on**. +3. Select the **Get Extensions** tab, and press **Allow Online Access**. .. image:: images/install-blenderbim-2.png - .. warning:: - - You do not need to unzip the add-on file. You should install it as a zipped file. - - You should now see **System: BlenderBIM** available in your add-ons list. Enable the add-on by pressing the checkbox. +4. Search for **Bonsai** in the top left search bar, then press the **Install** button. .. image:: images/install-blenderbim-3.png -All done! Your interface will now look similar to below. If you check the ``File`` menu you should also see an option to ``Open IFC Project``. +5. You should now see **Bonsai** available in your add-ons list. You're done! -.. image:: images/install-blenderbim-4.png + .. image:: images/install-blenderbim-4.png + +Your interface will now look similar to below. If you check the ``File`` menu you should also see an option to ``Open IFC Project``. + +.. image:: images/install-blenderbim-5.png You can enable add-ons permanently by using ``Save User Settings`` from the Addons menu. .. seealso:: If you are a poweruser, you may be interested in the **Unstable installation** to help with testing. :doc:`Read more ` - -.. _where is the add-on installed: - -Updating --------- - -First follow the `Uninstalling`_ section below, then install the latest version. - -Uninstalling ------------- - -Navigate to ``Edit > Preferences > Add-ons``. Due to a limitation in Blender, -you have to **first disable the BlenderBIM Add-on in your Blender preferences** -by pressing the checkbox next to the add-on, then **restart Blender**. It is -critical to follow this sequence of disabling first, and then restarting. - -After restarting, you can uninstall the BlenderBIM Add-on by pressing the -``Remove`` button in the Blender preferences window. - -Alternatively, you may uninstall manually by deleting the ``blenderbim`` -directory in :ref:`your Blender add-ons directory`. - -.. warning:: - - It is important to follow the sequence of disabling, restarting, then removing. - If you do not restart Blender, the add-on will fail to remove correctly, and you - will need to uninstall manually. - -Where is the add-on installed? ------------------------------- - -Upon installation, the BlenderBIM Add-on is stored in Blender configuration -folder. However, the location of your Blender configuration folder depends on -how you have installed Blender. - -If you downloaded Blender as a ``.zip`` file without running an installer, the -BlenderBIM Add-on will be installed in the following directory, where ``X.XX`` -is the Blender version: - -:: - - /path/to/blender/X.XX/ - -Otherwise, if you installed Blender using an installation package, the Blender -configuration folder depends on which operating system you use. - -On Linux, if you are installing the add-on as a user: - -:: - - ~/.config/blender/X.XX/ - -On Linux, if you are deploying the add-on system-wide (this may also depend on -your Linux distribution): - -:: - - /usr/share/blender/X.XX/ - -On Mac, if you are installing the add-on as a user: - -:: - - /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/ - -On Mac, if you are deploying the add-on system-wide: - -:: - - /Library/Application Support/Blender/X.XX/ - -On Windows: - -:: - - C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\ - -Inside the Blender configuration folder, the BlenderBIM Add-on is stored in two -different locations. The extension itself is stored in -``extensions/blender_org/blenderbim`` whereas the Python packages are installed -into ``extensions/.local/lib/pythonX.XX/site-packages/``. diff --git a/src/bonsai/docs/users/troubleshooting.rst b/src/bonsai/docs/users/troubleshooting.rst index 3727cdfa17..f8f0aa9290 100644 --- a/src/bonsai/docs/users/troubleshooting.rst +++ b/src/bonsai/docs/users/troubleshooting.rst @@ -1,9 +1,9 @@ Troubleshooting =============== -The BlenderBIM Add-on is alpha software. There are many bugs! When something -goes wrong, you may see some computer code flash up on your screen. You may -also see an error message: +Bonsai is alpha software. There are many bugs! When something goes wrong, you +may see some computer code flash up on your screen. You may also see an error +message: .. image:: images/error-message.png @@ -25,12 +25,26 @@ or other powerusers. `Chat live with a developer `_ +Updating +-------- + +We always recommend to use the latest version. + +Open up Blender, click on ``Edit > Preferences``, and select the **Get +Extensions** tab. If an update is available, you will see a button next to the +**Bonsai** add-on. + +Updates are typically available every 2 months. If you need something more +frequent, check out :ref:`devs/installation:unstable installation` which is +updated every day. + +.. image:: images/update.png + Installation issues ------------------- -If you are unable to install the BlenderBIM Add-on, make sure you are using -**Blender 4.2** installed from https://blender.org/ and have -:ref:`updated to the latest version `. +If you are unable to install Bonsai, make sure you are using **Blender 4.2** +installed from https://blender.org/. Other common solutions are listed below. If none of these fix the problem, you can `report a bug `_ or @@ -39,12 +53,12 @@ can `report a bug `_ or 1. **Some other error prevents me from installing or doing basic functions with the add-on. Is it specific to my environment?** - Try installing and using the BlenderBIM Add-on on a "clean environment". A - clean environment is a fresh Blender installation with no other add-ons - enabled with factory settings. + Try installing and using Bonsai on a "clean environment". A clean + environment is a fresh Blender installation with no other add-ons enabled + with factory settings. To quickly test in a clean environment, first :ref:`find your Blender - configuration folder`. Rename the folder from ``X.XX`` to something else like ``X.XX_backup``, then restart Blender and try follow the :doc:`installation instructions` again. @@ -69,9 +83,9 @@ can `report a bug `_ or Saving and loading blend files ------------------------------ -The BlenderBIM Add-on transform Blender into a native IFC authoring platform. -This means that you can open and save IFC files directly without using -Blender's ``.blend`` format. +Bonsai transforms Blender into a native IFC authoring platform. This means +that you can open and save IFC files directly without using Blender's +``.blend`` format. All data about your model is saved in your IFC. No data is stored in the ``.blend`` format. This means that if you save or open a ``.blend`` file, you @@ -84,3 +98,72 @@ editing something that doesn't actually exist in your IFC model. This will create unpredictable, and sometimes unrecoverable errors. To avoid this issue, only open and save IFCs. + +Where is the add-on installed? +------------------------------ + +Upon installation, Bonsai is stored in Blender configuration folder. However, +the location of your Blender configuration folder depends on how you have +installed Blender. + +If you downloaded Blender as a ``.zip`` file without running an installer, +Bonsai will be installed in the following directory, where ``X.XX`` is the +Blender version: + +:: + + /path/to/blender/X.XX/ + +Otherwise, if you installed Blender using an installation package, the Blender +configuration folder depends on which operating system you use. + +On Linux, if you are installing the add-on as a user: + +:: + + ~/.config/blender/X.XX/ + +On Linux, if you are deploying the add-on system-wide (this may also depend on +your Linux distribution): + +:: + + /usr/share/blender/X.XX/ + +On Mac, if you are installing the add-on as a user: + +:: + + /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/ + +On Mac, if you are deploying the add-on system-wide: + +:: + + /Library/Application Support/Blender/X.XX/ + +On Windows: + +:: + + C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\ + +Inside the Blender configuration folder, Bonsai is stored in two different +locations. The extension itself is stored in +``extensions/blender_org/bonsai`` whereas the Python packages are installed +into ``extensions/.local/lib/pythonX.XX/site-packages/``. + +Uninstalling +------------ + +Open up Blender, click on ``Edit > Preferences``, and select the **Get +Extensions** tab. In the dropdown menu to the right of the **Bonsai** add-on, +click on **Uninstall**. + +.. image:: images/uninstall.png + +Alternatively, you may start from a fresh setup by renaming or deleting the +Blender version folder, found in the add-on path. In the screenshot above, this +is ``/home/dion/.config/blender/4.2``. + +