Commit 038ecc08 authored by Breno Rilho Lemos's avatar Breno Rilho Lemos 💬

Update README.md

parent 09763b0c
......@@ -20,28 +20,46 @@ The whole process is a lot more user-friendly than it may seem at first glance;
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.
First, create a directory to keep everything:
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/
```bash
$ mkdir -p ~/alice
```
Enter this directory:
Before starting, you must also clone this repository:
```bash
mkdir -p ~/alice
cd ~/alice
git clone https://git.cta.if.ufrgs.br/ALICE-open-data/alice-blender-animation.git
$ 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
```
The animation making can be summarized in three basic steps:
Make sure the repository is inside the `alice` directory you created.
1) Installing Aliroot;
2) Getting an ESD file;
3) Running script to process ESD data and generate Blender animations using its results.
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.
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.
```bash
$ wget https://download.blender.org/release/Blender2.79/blender-2.79b-linux-glibc219-x86_64.tar.bz2
```
## Step 1 - Installing Aliroot
Extract files from package:
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.
```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:
1) Install aliBuild. Follow instructions on https://alice-doc.github.io/alice-analysis-tutorial/building/custom.html
......@@ -61,49 +79,140 @@ $ aliDoctor AliPhysics
aliBuild build AliPhysics --defaults user -z aliroot5
```
## Step 2 - Getting an ESD file
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.
ESD files regarding the ALICE experiment can be found on http://opendata.cern.ch/search?page=1&size=20&experiment=ALICE. If you have doubts on which file to pick for a test, you can select any file on this list: http://opendata.cern.ch/record/1102.
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:
Here, there are two options from which you can choose:
### 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`.
```bash
$ cd ~/alice/alice-blender-animation
```
### Automatic Download
Have your ESD be downloaded automatically; just copy the URL for the chosen ESD file (the address you would access to download it) so you can paste it on the command line when you run the script that generates the animation, according to the next section.
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:
## Step 3 - Generating animation
```bash
./workflow_sketch.sh --fps 24 -t 8
```
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
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:
```bash
./workflow_sketch.sh --help
```
Standard values to all these parameters are set so the minimum code required is simply
In case you have chosen the automatic ESD download option, run the code as:
```bash
./workflow_sketch.sh
./workflow_sketch.sh --url <URL> --download
```
If you have chosen the automatic ESD download option above, the code becomes
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:
```bash
./workflow_sketch.sh --url <URL> --download
./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
```
where ``<URL>`` is the copied ESD URL.
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!
---------------------------------------------------------------------------------------------------------------------
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!
# Default Animation
For generating a default animation, simply run the script `workflow_sketch.sh` in your terminal as below:
For generating a default animation, simply run the script `workflow_sketch.sh` in your terminal as below, from inside the project's repository directory:
```bash
./workflow_sketch.sh -a
```
After this, a single default animation should be ready. It will be available inside the `blender` 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! You may want to check the table
above for information on the using options.
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