README.md 6.19 KB
Newer Older
strakpe's avatar
update  
strakpe committed
1
# BHeappe
Milan Jaros's avatar
Milan Jaros committed
2

strakpe's avatar
strakpe committed
3
#### BLENDER ADD-ON TO EXTEND ITS CAPABILITIES IN TERMS OF RENDERING ON AN HPC CLUSTER
strakpe's avatar
strakpe committed
4

strakpe's avatar
strakpe committed
5
We provide a Python add-on for Blender software that can re-formulate typical task of a user scene rendering to a specific HPC computational job.
strakpe's avatar
update  
strakpe committed
6
It uses [HEAppE](http://heappe.eu/) middleware as a middle layer to communicate with a cluster. In this way, support for rendering on an HPC cluster is provided.
strakpe's avatar
strakpe committed
7
This add-on has been developed at [IT4Innovations National Supercomputing Center](https://www.it4i.cz/).
strakpe's avatar
strakpe committed
8

strakpe's avatar
strakpe committed
9 10 11
---
# Content
---
strakpe's avatar
strakpe committed
12

strakpe's avatar
strakpe committed
13
1. [Installation & Authentication](https://code.it4i.cz/raas/bheappe#installation-authentication)
strakpe's avatar
strakpe committed
14
2. [Compatibility](https://code.it4i.cz/raas/bheappe#compatibility)
strakpe's avatar
strakpe committed
15 16
3. [Add-on functionality](https://code.it4i.cz/raas/bheappe#add-on-functionality)
4. [License](https://code.it4i.cz/raas/bheappe#license)
strakpe's avatar
strakpe committed
17 18
5. [Acknowledgement](https://code.it4i.cz/raas/bheappe#acknowledgement)

strakpe's avatar
strakpe committed
19

strakpe's avatar
strakpe committed
20
---
strakpe's avatar
strakpe committed
21
# Installation & Authentication
strakpe's avatar
strakpe committed
22 23
---

strakpe's avatar
strakpe committed
24
For add-on installation you first need to have 2.80 or higher version of Blender.
strakpe's avatar
strakpe committed
25
Blender is a free and open-source software which can be downloaded at [https://www.blender.org](https://www.blender.org).
strakpe's avatar
strakpe committed
26 27

Blender uses Python API to provide users with scripting support and to allow creation of user defined add-ons.
strakpe's avatar
update  
strakpe committed
28
We use this API to provide add-on's functionality. We also use several Python modules that are necessary. Those are installed using Python Wheels system. The installation is done automatically with the add-on setup.
strakpe's avatar
update  
strakpe committed
29

strakpe's avatar
update  
strakpe committed
30
The add-on needs SSH support to be installed in the operating system. This is done depending on the OS as:
strakpe's avatar
update  
strakpe committed
31

strakpe's avatar
update  
strakpe committed
32
- Ubuntu
strakpe's avatar
update  
strakpe committed
33
```console
strakpe's avatar
update  
strakpe committed
34 35
$ sudo apt install openssh-server openssh-client
```
strakpe's avatar
update  
strakpe committed
36
- MacOS
strakpe's avatar
update  
strakpe committed
37
    - It is installed by default.
strakpe's avatar
update  
strakpe committed
38
- Windows 10
strakpe's avatar
update  
strakpe committed
39
    - To install OpenSSH, go to  *Settings* then go to *Apps*→*Apps and Features*→*Manage Optional Features*.
strakpe's avatar
update  
strakpe committed
40 41 42
    - Scan the opened list to see if OpenSSH client is already installed. If not, then at the top of the page select *Add a feature*, then:
        - To install the OpenSSH client, locate *OpenSSH Client*, click *Install*.
        - To install the OpenSSH server, locate *OpenSSH Server*, click *Install*.
strakpe's avatar
update  
strakpe committed
43

strakpe's avatar
update  
strakpe committed
44
To setup the add-on in Blender, first download *bheappe* folder from this repository and save it as a .zip file. Use this link to [download](https://code.it4i.cz/raas/bheappe/-/archive/master/bheappe-master.zip?path=bheappe) it.
strakpe's avatar
update  
strakpe committed
45 46

Then open Blender and go to *Edit/Preferences*.
strakpe's avatar
strakpe committed
47
Click on *Add-ons* tab, see below, and from there click the *Install* button.
strakpe's avatar
strakpe committed
48
It will open the file browser.
strakpe's avatar
update  
strakpe committed
49
Locate the downloaded *zip* file and click *Install Add-on* button.
strakpe's avatar
strakpe committed
50
Search for *bheappe* within the list of add-ons and check the tick mark at the add-on name.
strakpe's avatar
strakpe committed
51

strakpe's avatar
strakpe committed
52 53
![](img/install_addon.png) 

strakpe's avatar
strakpe committed
54 55
To be able to provide rendering on a supercomputer it is necessary to have a valid access.
This can be obtain within our service called Rendering-as-a-Service (RaaS).
strakpe's avatar
update  
strakpe committed
56
For information about the service contact either <petr.strakos@vsb.cz> or <milan.jaros@vsb.cz>.
strakpe's avatar
strakpe committed
57 58
Requests will be solved individually.

strakpe's avatar
strakpe committed
59
With granted access you will be given specific username and password.
strakpe's avatar
strakpe committed
60
Provided information has to be used and validated at the authentication part of the add-on in Blender preferences, see below.
strakpe's avatar
strakpe committed
61
After successful authentication save the preferences at lower left corner of the *Preferences* window before you close it. 
strakpe's avatar
strakpe committed
62

strakpe's avatar
strakpe committed
63 64
![](img/addon_authorization.png)

strakpe's avatar
strakpe committed
65

strakpe's avatar
strakpe committed
66 67 68
---
# Compatibility
---
strakpe's avatar
strakpe committed
69

strakpe's avatar
strakpe committed
70
Add-on is compatible with Blender version 2.80 and higher. Older versions of Blender software are not supported.
strakpe's avatar
update  
strakpe committed
71
Add-on has been tested on Windows and MacOS platform.
strakpe's avatar
strakpe committed
72

strakpe's avatar
strakpe committed
73

strakpe's avatar
strakpe committed
74 75 76
---
# Add-on functionality
---
strakpe's avatar
strakpe committed
77

strakpe's avatar
update  
strakpe committed
78
BHeappe add-on is added to the ***Render properties*** menu of Blender.
strakpe's avatar
strakpe committed
79 80
Add-on supports *Cycles* rendering only.
Thus it is available only in case *Cycles* is selected as *Render Engine*, see figure below.
strakpe's avatar
strakpe committed
81 82 83

![](img/render_menu.png)

strakpe's avatar
update  
strakpe committed
84
***BHeappe*** menu is divided in ***Status*** menu and two other menus called ***New Job*** and ***Jobs***.
strakpe's avatar
strakpe committed
85 86 87 88
See figure below. 

***Status*** menu provides user with information about progress of ongoing action, e.g. sending query for job update etc.

strakpe's avatar
update  
strakpe committed
89
***New Job*** menu lets user define details about a rendering job that will be submitted.
strakpe's avatar
update  
strakpe committed
90
You can set project name, use your email to be notified when job is done (only in case you have been assigned computational resources and this email address was used), select type of the computing queue and choose whether only one image or sequence of images (animation) will be rendered.
strakpe's avatar
strakpe committed
91 92 93

![](img/bheappe_menu.png) 

strakpe's avatar
update  
strakpe committed
94
Within the *Queue* selection, *CyclesPhi CPU/CyclesPhi MIC* choices are available.
strakpe's avatar
update  
strakpe committed
95
These queues allow user to perform multi node rendering on CPUs or MIC accelerators, respectively.  
strakpe's avatar
strakpe committed
96 97 98

Beside the mentioned options, there are the following settings to be specified by the user before the job can be submitted for computation:

strakpe's avatar
update  
strakpe committed
99
- *Nodes/MICs* - number of allocated computational nodes/MICs accelerators for the job.
strakpe's avatar
strakpe committed
100 101 102
- *Walltime* - maximal processing time allocated for specific part of the whole rendering task such as *Preprocessing*, *Rendering*, *Postprocessing*.
- *Current Frame* or *Frame Start/End/Step* - depending whether one image or animation is being selected, user can choose a frame number or consecutive set of frames.

strakpe's avatar
update  
strakpe committed
103 104
Additional setting regarding the rendered image/images such as resolution, aspect ratio, etc. can be set in standard way from ***Output properties*** menu of Blender. Setting of a number of samples per pixel during rendering can be done as common from ***Output properties*** menu of Blender. 

strakpe's avatar
update  
strakpe committed
105
After setting important values, rendering job is sent to the cluster by ***Submit Job*** button.  
strakpe's avatar
strakpe committed
106

strakpe's avatar
update  
strakpe committed
107
***Jobs*** menu provides user with the overview about the submitted jobs. Actual states of the jobs can be checked.
strakpe's avatar
strakpe committed
108

strakpe's avatar
update  
strakpe committed
109
If some particular job from the list in the ***Jobs*** menu is selected and in FINISHED state, user can download the results to his/her local folder and browse them by opening a file explorer via button. 
strakpe's avatar
strakpe committed
110

strakpe's avatar
update  
strakpe committed
111

strakpe's avatar
strakpe committed
112 113 114
---
# License
---
strakpe's avatar
strakpe committed
115

strakpe's avatar
strakpe committed
116
This software is licensed under the terms of the [GNU General Public License](https://code.it4i.cz/raas/bheappe/blob/master/LICENSE).
strakpe's avatar
strakpe committed
117

strakpe's avatar
strakpe committed
118

strakpe's avatar
strakpe committed
119 120 121
---
# Acknowledgement
---
strakpe's avatar
strakpe committed
122

strakpe's avatar
update  
strakpe committed
123
This work was supported by The Ministry of Education, Youth and Sports from the Large Infrastructures for Research, Experimental Development, and Innovations project “e-INFRA CZ – LM2018140”.
strakpe's avatar
strakpe committed
124