Commit 97a255af authored by Breno Rilho Lemos's avatar Breno Rilho Lemos 💬

Update README instructions

parent 3efa74b5
...@@ -2,11 +2,23 @@ ...@@ -2,11 +2,23 @@
## Project Description ## Project Description
This project has the purpose of generating 3D animations of ALICE particle collision events, inside the LHC, using data obtained from CERN's Open Data Portal, which makes ESDs - Event Summary Data files, that contain information about such events - open and available for analysis. 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éairewhich*, 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.
## 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.
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.
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.
The text files containing all the physics data are then read by the Python scripts responsible for generating the animation, completing the procedure.
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.
ESD files regarding the ALICE experiment can be found on http://opendata.cern.ch/search?page=1&size=20&experiment=ALICE, and they should be somehow referenced along the process, as explained further. ESD files regarding the ALICE experiment can be found on http://opendata.cern.ch/search?page=1&size=20&experiment=ALICE, and they should be somehow referenced along the process, as explained further.
The software that makes the animation is Blender, which is free and open source. Blender's 2.79b version should be downloaded for this project, and can be found on https://www.blender.org/download/releases/2-79/ The software used for animating events is Blender, which is free and open source. Blender's 2.79b version should be downloaded for this project, and can be found on https://www.blender.org/download/releases/2-79/
Before starting, you must also clone this repository: Before starting, you must also clone this repository:
```bash ```bash
...@@ -19,13 +31,13 @@ The animation making can be summarized in three basic steps: ...@@ -19,13 +31,13 @@ The animation making can be summarized in three basic steps:
1) Installing aliRoot; 1) Installing aliRoot;
2) Getting an ESD file; 2) Getting an ESD file;
3) Run script to process ESD data and generate Blender animations using its results. 3) Running script to process ESD data and generate Blender animations using its results.
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. For detailed steps on how to make the animation from ESDs, as described above, read the following sections. 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. For detailed steps on how to make the animation from ESDs, as described above, read the following sections.
## Step 1 - Installing aliRoot ## Step 1 - Installing aliRoot
Here is the sequence of steps for installing aliRoot, so you are able to process the relevant information for the project. Here is the sequence of steps for installing Aliroot, CERN's official software for ALICE physics analysis, so you are able to process the relevant information for the project.
1) Install aliBuild. Follow instructions on https://alice-doc.github.io/alice-analysis-tutorial/building/custom.html 1) Install aliBuild. Follow instructions on https://alice-doc.github.io/alice-analysis-tutorial/building/custom.html
...@@ -51,47 +63,35 @@ ESD files regarding the ALICE experiment can be found on http://opendata.cern.ch ...@@ -51,47 +63,35 @@ ESD files regarding the ALICE experiment can be found on http://opendata.cern.ch
Here, there are two options from which you can choose: Here, there are two options from which you can choose:
- the first one is to download your ESD file and save it in the `alice-blender-animation` directory, which was cloned from the git repository. Make sure you save it on the same path as this `README.md` file and the `workflow_sketch.sh` script, not inside the "aliRoot" or "animate" directories. Also make sure the file is named `AliESDs.root`. # Manual Download
Manually download your ESD file and save it in the `alice-blender-animation` directory, which was cloned from the git repository. Make sure you save it on the same path as this `README.md` file and the `workflow_sketch.sh` script, not inside the "aliRoot" or "animate" directories. Also make sure the file is named `AliESDs.root`.
- the second one is to copy the URL for the ESD file (the address you would access to download it) and paste it on the command line when you run the script that generates the animation, according to the next section. # Automatic Download
Copy the URL for the chosen ESD file (the address you would access to download it) and paste it on the command line when you run the script that generates the animation, according to the next section, so it automatically downloads it for you.
## Step 3 - Generating animation ## Step 3 - Generating animation
Once you are all set, all there is left to do is run the `workflow_sketch.sh` script through your terminal. Once you are all set, all there is left to do is run the `workflow_sketch.sh` script through your terminal. This script offers several options regarding parameters such as animation time duration and resolution. For more information, run it as
If you have already downloaded the ESD file, run it as follows:
```bash ```bash
./workflow_sketch.sh --maxparticles <MAXPARTICLES> --duration <DURATION> --resolution <RESOLUTION> ./workflow_sketch.sh --help
``` ```
where `<MAXPARTICLES>` is the highest number of particles that you wish the events about to be animated have. It means events with more particles than that will not be animated. Keep in mind that it takes extra amount of time to generate animations with too many particles, say, 5000 or more. Standard values to all these parameters are set so the minimum code required is simply
`<DURATION>` is the time duration, in seconds, each animation will last.
Finally, `<RESOLUTION>` is the animation resolution percentage, ranging from 0 (you don't want it to be 0) to 100.
Here is a running example:
```bash ```bash
./workflow_sketch.sh --maxparticles 2000 --duration 15 --resolution 100 ./workflow_sketch.sh
``` ```
If you have copied the ESD's URL in the previous section and wish to download it automatically, run the script as: If you have chosen the automatic ESD download option above, the code becomes
```bash ```bash
./workflow_sketch.sh --url <URL> --download --maxparticles <MAXPARTICLES> --duration <DURATION> --resolution <RESOLUTION> ./workflow_sketch.sh --url <URL> --download
``` ```
where `<URL>` is the ESD's URL you have at hand, and all the other arguments are the same as above. where <URL> is the copied ESD URL.
Here is a running example:
```bash
./workflow_sketch.sh --url http://opendata.cern.ch/record/1103/files/assets/alice/2010/LHC10h/000139173/ESD/0004/AliESDs.root --download --maxparticles 2000 --duration 15 --resolution 100
```
After running the script, your Blender animations should be ready! Have in mind that it may take a long time to generate all the animations. For each event inside the ESD file - with fewer particles than you have specified -, there will be three animations saved in .mp4 format, each one corresponding to a different view of the event. They will be available inside the `output` directory. Enjoy! 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!
# Default Animation # Default Animation
...@@ -102,4 +102,4 @@ For generating a default animation, simply run the script `workflow_sketch.sh` i ...@@ -102,4 +102,4 @@ For generating a default animation, simply run the script `workflow_sketch.sh` i
./workflow_sketch.sh -a ./workflow_sketch.sh -a
``` ```
After this, a single default animation should be ready. It will be available inside the `output` directory, in mp4 format. Enjoy! After this, a single default animation should be ready. It will be available inside the `blender` directory, in *.mp4* format. Enjoy!
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment