README.md 12.6 KB
Newer Older
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
1
2
3
4
# ALICE Open Data Blender animation

## Project Description

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
5
This project has the purpose of generating 3D animations of ALICE particle collision events using data obtained from CERN's Open Data Portal. ALICE stands for "A Large Ion Collider Experiment" and it is a particle detector inside the LHC - Large Hadron Collider -, the world's largest and highest-energy particle collider, located beneath the France–Switzerland border. CERN stands for *Organisation européenne pour la recherche nucléaire*, which is French for European Organization for Nuclear Research, and it is the home of LHC. CERN's Open Data Portal is an open online platform that contains data files from particle physics; those include the ESDs - Event Summary Data files -, which hold information about ALICE events and are of great help making the animations look like real representations of such events.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
6
7
8
9

## How it all works

Before diving into how to run this project, it is important to develop some intuition on how the pieces all fit together to make the whole thing work out just right.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
10

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
11
The animation of a particle collision event is generated through 3D modeling software, which sets the position of all the particles at any given time - until the animation is over - with the help of their respective mass, charge and initial linear momentum values, plus the value of the magnetic field and the collision vertex, a spot from which we consider all the particles originate.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
12

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
13
All this information must be obtained from somewhere - that somewhere is the above-mentioned ESD files, which contain data about several events each. The ESDs come in a *.root* extension and may only be interpreted by ROOT, CERN's official software for particle physics analysis. This is done through C++ code, which is written in order to specifically refer to the ESD desired data, in accordance with the available libraries, and run by ROOT to export this data to textual format. That is why the download of Aliroot, ROOT's version for ALICE events analysis, is required.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
14

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
15
The text files containing all the physics data are then read by the Python scripts responsible for generating the animation, completing the procedure.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
16

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
17
18
19
20
21
The whole process is a lot more user-friendly than it may seem at first glance; except for installing a couple of programs - ROOT and Blender -, the only thing left for the user to do is run a line of code from the terminal, which executes a script that automatizes everything from running ROOT to rendering and saving every animation *.mp4* file. The final result is a directory inside of which is a series of animation clips, each one corresponding to a different event in the chosen ESD file.

## Laying the groundwork

This project was developed in Ubuntu 18.04 version of Linux, therefore this is the recommended OS for running it.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
22

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
23
First, create a directory to keep everything:
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
24

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
25
26
27
28
29
```bash
$ mkdir -p ~/alice
```

Enter this directory:
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
30
31

```bash
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
32
33
34
35
36
37
38
$ cd ~/alice
```

If you haven't yet, clone the project's repository:

```bash
$ git clone https://git.cta.if.ufrgs.br/ALICE-open-data/alice-blender-animation.git
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
39
40
```

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
41
Make sure the repository is inside the `alice` directory you created.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
42

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
43
44
It is then time to download Blender, a free and open source software that is used for animating events. Stick to version 2.79b, or there is no 
guarantee the code will work.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
45

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
46
47
48
```bash
$ wget https://download.blender.org/release/Blender2.79/blender-2.79b-linux-glibc219-x86_64.tar.bz2
```
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
49

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
50
Extract files from package:
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
51

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
52
53
54
55
56
57
58
59
60
61
62
```bash
$ tar -jxvf blender-2.79b-linux-glibc219-x86_64.tar.bz2
```

The next step is to install Aliroot, which is CERN's official software for ALICE physics analysis, so you are able to process the relevant information 
for the events.

In case you are not conCERNed about the data being used for the animation and only wish to generate a standard one, skip to the 
Default Animation section below.

Here is the sequence of steps for installing Aliroot:
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

1) Install aliBuild. Follow instructions on https://alice-doc.github.io/alice-analysis-tutorial/building/custom.html

2) Initialize AliPhysics

```bash
cd ~/alice
aliBuild init AliPhysics@master
```
3) Verify dependencies (Optional)

```bash
$ aliDoctor AliPhysics
```
4) Build AliPhysics with aliroot5 (this may take a long time)
```bash
aliBuild build AliPhysics --defaults user -z aliroot5
```

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
82
83
84
85
After that, you are ready to pick an ESD file at CERN's Open Data Portal. ESD files regarding the ALICE experiment can be found on 
http://opendata.cern.ch/search?page=1&size=20&experiment=ALICE. You can either manually download your ESD file and save it in the 
project's repository directory (in the same path as this `README.md` file), under the name `AliESDs.root`, or have your ESD be downloaded automatically, as explained
further.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
86

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
87
88
Once you're all set, all there is left to do is run the `workflow_sketch.sh` script through your terminal. Don't forget to access the project's repository 
directory first:
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
89

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
90
91
92
```bash
$ cd ~/alice/alice-blender-animation
```
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
93

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
94
95
The script offers several options in order to personalize the output. For example, in order to set the number of frames per second (fps) to 24 and the video 
time duration to 8 seconds, one should run the command like this:
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
96

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
97
98
99
```bash
./workflow_sketch.sh --fps 24 -t 8
```
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
100

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
101
102
103
As you can see, options are either preceded by double dashes (as in `--fps 24`) or by a single dash (as in `-t 8`). The option's value should follow 
the option's name, also separated by a space. Some options, such as the `--download` option, don't expect arguments. When any available option is not called, it runs 
the code with its standard value. See below for a detailed list of all the available options, which can also be checked out by entering:
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
104
105

```bash
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
106
./workflow_sketch.sh --help
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
107
108
```

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
109
In case you have chosen the automatic ESD download option, run the code as:
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
110

111
```bash
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
112
./workflow_sketch.sh --url <URL> --download
113
114
```

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
115
116
where ``<URL>`` is the URL address for the chosen ESD file. Of course, you can add other options as well, if you wish. Here's another working example, including 
the download option:
117
118

```bash
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
119
./workflow_sketch.sh --url http://opendata.cern.ch/record/1103/files/assets/alice/2010/LHC10h/000139173/ESD/0004/AliESDs.root --download -t 4 --cameras Overview,Forward
120
121
```

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
   ---------------------------------------------------------------------------------------------------------------------
     Option             Entry                     Action                                                 Standard Value
   ------------------- ------------------------- ------------------------------------------------------ ----------------
     -h or --help       none                      Shows a list with all possible using options.                 -
     
     -d or
     --download         none                      Informs to download the ESD file, rather than trying          -
                                                  to find one locally 
                                               
     -u or --url        ESD file URL              Informs ESD file URL, in case download option is              -
                                                  called
                                               
     -m ou              Positive integer          Sets the maximum number of particles allowed in the         1000
     --maxparticles                               events to be animated.
     
     --minparticles     Positive integer          Sets the minimum number of particles allowed in the           0
                                                  events to be animated. 
                                               
     -n or              Non-negative integer      Sets number of events to be animated inside chosen           10
     --numberofevents                             ESD file
     
     --minavgpz         Positive number           Gets only events for which the absolute value of              0
                                                  average momentum in the z direction is greater than
                                                  or equal to the specified value, in GeV/c. Useful
                                                  for animating events with 'boosts' of particles to
                                                  the same side.
                                                  
     --minavgpt         Positive number           Get only events for which the average transversal             0
                                                  momentum is greater than or equal to the specified
                                                  value, in GeV/c. Useful for animating events with
                                                  'boosts' of particles on the xy plane. 
     -t or
     --duration         Positive integer          Sets animation duration, in seconds                          10 
     
     -r ou --radius     Positive number           Scales the particle's radius to the informed value            1 
     
     --resolution       Whole number from         Sets animation resolution percentage.                       100 
                        1 to 100
                        
     --fps              Positive integer          Sets animation number of frames per second                   24 
     
     --transparency     Positive number           Sets detector transparency, where zero is full                1
                                                  transparency and 1 is standard transparency  
                                                  
     -c ou --cameras    Comma-separated list      Sets cameras to animate events with                       Overview
                        (with no spaces) of
                        cameras. Options:
                        Barrel, Forward,
                        Overview, Side,
                        Moving1, Moving2,
                        Moving3, Moving4    
                        
     --mosaic           none                      Makes animations in four different cameras (Barrel,           -
                                                  Forward, Overview and Moving1) and combines them
                                                  into a single 2x2 clip containing all four
                                                  perspectives.  
                                                  
     --picpct           Whole number from         Informs percentage of animation to take HD picture,          80
                        1 to 100                  saved along with the clip.
                             
     --bgshade          Number from 0 to 1        Set background shade of black to VALUE, where 0 is            0
                                                  totally black and 1 is totally white.
                                                  
     -a ou --sample     none                      Creates a sample Blender animation of Event 2 from            -
                                                  URL http://opendata.cern.ch/record/1102/files/asset
                                                  s/alice/2010/LHC10h/000139038/ESD/0001/AliESDs.root   
                                                  
     --its              none                      Removes ITS detector from animation                           - 
     
     --detailedtpc      none                      Includes a more detailed version of the TPC                   -
                                                  geometry, made by researcher Stefan Rossegger
                                                  (stefan.rossegger@gmail.com)  
                                                  
     --tpc              none                      Removes TPC detector from animation                           - 
      
     --trd              none                      Removes TRD detector from animation                           -
     
     --emcal            none                      Removes EMCal detector from animation                         - 
     
     --blendersave      none                      Saves Blender file along with animation clip                  - 
   -----------------------------------------------------------------------


After running the script, it may take a long time to generate all the animations, but as soon as it is done, they will be available inside a new directory uniquely 
identified according to the chosen ESD file. Each clip is also identified by event number. Enjoy!
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
207
208
209
210


# Default Animation

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
211
For generating a default animation, simply run the script `workflow_sketch.sh` in your terminal as below, from inside the project's repository directory:
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
212
213

```bash
214
./workflow_sketch.sh -a
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
215
```
216

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
217
218
After this, a single default animation should be ready. It will be available inside the `blender` directory, in *.mp4* format. Enjoy! You may want to check the table 
above for information on the using options.