README.md 7.35 KB
Newer Older
Peter Kettig's avatar
Peter Kettig committed
1
2
# WASP - Weighted Average Synthesis Processor

Olivier Hagolle's avatar
Olivier Hagolle committed
3
Image processing chain based on OTB to create monthly syntheses of cloud-free reflectances for Sentinel-2 or Venus Level-2A products distributed by the [Theia Land data centre](https://theia.cnes.fr/atdistrib/rocket/#/home).
Peter Kettig's avatar
Peter Kettig committed
4

5
<a href="Package/wasp.jpg"><img  title="Monthly synthesis over France" src="Package/wasp.jpg" alt="" width="500" height="400" align="middle"  /></a>
Peter Kettig's avatar
Peter Kettig committed
6
7

## Inputs, algorithm and outputs
8
The processing chain creates a synthesis image from multiple Level-2A tiles produced with [MAJA](https://labo.obs-mip.fr/multitemp/maccs-how-it-works/). MAJA Level 2A products can be obtained:
Peter Kettig's avatar
Peter Kettig committed
9

10
11
* [From Theia, the French Land data centre, for several countries or regions](https://theia.cnes.fr/atdistrib/rocket/#/search?page=1&collection=SENTINEL2&processingLevel=LEVEL2A)
* [From PEPS, as an on-demand processing, anywhere on the world](https://github.com/olivierhagolle/maja_peps)
12
* [Using MAJA on user side](https://gitlab.orfeo-toolbox.org/maja/maja/)
Peter Kettig's avatar
Peter Kettig committed
13

14
The weigted average synthesis method to combine the inputs into one single synthesis is described [here](https://labo.obs-mip.fr/multitemp/theias-sentinel-2-l3a-monthly-cloud-free-syntheses/).
Peter KETTIG's avatar
Peter KETTIG committed
15
Once synthesized, a Level-3 product is generated further described in the [format description](https://labo.obs-mip.fr/multitemp/theias-l3a-product-format/). Analysis-Ready Level-3 products can be obtained from the following locations:
16

Peter KETTIG's avatar
Peter KETTIG committed
17
18
* Theia produces [Level 3A products with WASP over France, Italy, Spain and other selected regions](https://theia.cnes.fr/atdistrib/rocket/#/search?page=1&collection=SENTINEL2&processingLevel=LEVEL3A)
* DLR runs WASP over Germany and adjacent S2 tiles, you can access it [here](https://code-de.org/en/portfolio/?id=19)
19

Peter KETTIG's avatar
Peter KETTIG committed
20
Should you want to produce your own Level-3 products, follow the instructions on how to install WASP below.
Peter Kettig's avatar
Peter Kettig committed
21
22
23

## Getting Started

Olivier Hagolle's avatar
Olivier Hagolle committed
24
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. MAJA is available as pre-compiled binary, or as a source code that you will have to compile.
Peter Kettig's avatar
Peter Kettig committed
25
26
27
28


### Pre-compiled binaries

29
WASP binaries are available for Linux distributions [**under the following link**](https://logiciels.cnes.fr/en/node/128?type=tel). Develop versions are accessible [here](https://gitlab.orfeo-toolbox.org/remote_modules/wasp/-/jobs).
Peter Kettig's avatar
Peter Kettig committed
30

31
32
33
34
35
36
37
38
39
40
41
42
43
44
To install it, first make sure you have GLU installed:

__For CentOS__

```
yum install mesa-libGLU-devel
```

__For Ubuntu__
```
apt-get install libglu1-mesa-dev
```

Then extract and execute the downloaded executable:
Peter Kettig's avatar
Peter Kettig committed
45
46

```
47
./WASP-x.x.run --target /path/to/install
Peter Kettig's avatar
Peter Kettig committed
48
49
50
51
```

### Compiling from source

Olivier Hagolle's avatar
Olivier Hagolle committed
52
53
54
#### Prerequisites

The program has the following dependencies:
55
56
* OTB 7.4 (https://orfeo-toolbox.org)
* Python >3.6 (https://www.python.org/downloads/)
Julie Brossard's avatar
Julie Brossard committed
57
* CMake >3.10.2 (https://cmake.org)
Olivier Hagolle's avatar
Olivier Hagolle committed
58
59
* GCC >6.3.0 (https://gcc.gnu.org) or any other C/C++ compiler for your system

Peter Kettig's avatar
Peter Kettig committed
60
61
62
63
In order to install the software, first install CMake, the c/c++ compiler and the python interpreter (optional). Then follow the tutorial on how to install OTB via the Superbuild to the desired location:

*https://www.orfeo-toolbox.org/SoftwareGuide/SoftwareGuidech2.html#x16-220002.1.2*

64
Note: You do not need to activate/deactivate any modules. The default configuration works out of the box.
Olivier Hagolle's avatar
Olivier Hagolle committed
65
66

#### compile and install WASP:
Peter Kettig's avatar
Peter Kettig committed
67
68
69
70
71
72
73
```
cd $WASP_DIR
mkdir build && install
cd build
cmake .. -DCMAKE_PREFIX_PATH=/path/to/OTB
```

74
Eventually you have to specify the location to your compiler by setting ```CMAKE_C_COMPILER``` and ```CMAKE_CXX_COMPILER```. `-DCMAKE_INSTALL_PREFIX=/path/to/your/binaries` might also help.
Peter Kettig's avatar
Peter Kettig committed
75
76
77
78
79
80
81
82
83
84
85
86
87
88
Then, run
```
make && make install
```

## Run the software

In order to run the processing chain, the script WASP located in the bin/ folder after installation has to be called.
For an explanation on which inputs the program takes, simply execute

```
./bin/WASP --help
```

89
90
91
92
93
94
You will need the python interpreter within the same directory. Should it be located elsewhere, but still within your `PATH`, then run:

```
python ./bin/WASP.py --help
```

Peter Kettig's avatar
Peter Kettig committed
95
96
### Example

Olivier Hagolle's avatar
Olivier Hagolle committed
97
First, you need to download and unzip the Level-2 products of your choice. Have a look at the [theia_download tool](https://github.com/olivierhagolle/theia_download) if you don't know how to do this.
Peter Kettig's avatar
Peter Kettig committed
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
The following command line creates a composite centered around the 2018/05/02 out of 9 Level-2A products from a 46-day period:

```
./bin/WASP \
--input ./SENTINEL2A_20180525-103024-462_L2A_T32ULV_D_V1-
7/SENTINEL2A_20180525-103024-462_L2A_T32ULV_D_V1-7_MTD_ALL.xml \
./SENTINEL2A_20180518-104024-461_L2A_T32ULV_D_V1-7/SENTINEL2A_20180518-104024-
461_L2A_T32ULV_D_V1-7_MTD_ALL.xml \
./SENTINEL2A_20180508-104025-460_L2A_T32ULV_D_V1-7/SENTINEL2A_20180508-104025-
460_L2A_T32ULV_D_V1-7_MTD_ALL.xml \
./SENTINEL2A_20180515-103024-459_L2A_T32ULV_D_V1-7/SENTINEL2A_20180515-103024-
459_L2A_T32ULV_D_V1-7_MTD_ALL.xml \
./SENTINEL2A_20180505-103125-791_L2A_T32ULV_D_V1-7/SENTINEL2A_20180505-103125-
791_L2A_T32ULV_D_V1-7_MTD_ALL.xml \
./SENTINEL2A_20180415-103544-548_L2A_T32ULV_D_V1-7/SENTINEL2A_20180415-103544-
548_L2A_T32ULV_D_V1-7_MTD_ALL.xml \
./SENTINEL2B_20180420-103302-810_L2A_T32ULV_D_V1-7/SENTINEL2B_20180420-103302-
810_L2A_T32ULV_D_V1-7_MTD_ALL.xml \
./SENTINEL2A_20180418-104512-083_L2A_T32ULV_D_V1-7/SENTINEL2A_20180418-104512-
083_L2A_T32ULV_D_V1-7_MTD_ALL.xml \
./SENTINEL2A_20180412-105510-678_L2A_T32ULV_D_V1-7/SENTINEL2A_20180412-105510-
678_L2A_T32ULV_D_V1-7_MTD_ALL.xml \
--out . \
--date 20180502 \
--synthalf 23 \
```

Once the processing finishes, the following line should be displayed:
```
================= WASP synthesis of 9 inputs finished in xxxx.xx s =================
```

The resulting product can be then found under
```
./SENTINEL2X-20180502-000000-000_L3A_T32ULV_C_V1-1
```

135
Click [here](https://labo.obs-mip.fr/multitemp/theias-l3a-product-format/) for the format description.
Peter Kettig's avatar
Peter Kettig committed
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
## Light mode

The light mode is available ony for Sentinel 2 products, it allow to obtain R3 products with a resolution of 60m. Additional parameters are
created specifically for this mode: lightmode, bands and writedts.

- lightmode : activate the lightmode
- bands : list of bands to keep in numerical order (B4 and B8 mandatory for NDVI computation)
- writedts : write DTS mask in the output product

### Example with light mode

```
./bin/WASP \
--input ./SENTINEL2A_20180525-103024-462_L2A_T32ULV_D_V1-
7/SENTINEL2A_20180525-103024-462_L2A_T32ULV_D_V1-7_MTD_ALL.xml \
./SENTINEL2A_20180518-104024-461_L2A_T32ULV_D_V1-7/SENTINEL2A_20180518-104024-
461_L2A_T32ULV_D_V1-7_MTD_ALL.xml
--out . \
--lightmode True
--bands B4,B8,B11,B12
--writedts True

```

Peter Kettig's avatar
Peter Kettig committed
161
162
163
164
## Built With

* [OTB](https://orfeo-toolbox.org) - The Orfeo toolbox

Olivier Hagolle's avatar
Olivier Hagolle committed
165
## History/Copyright
Peter Kettig's avatar
Peter Kettig committed
166

Olivier Hagolle's avatar
Olivier Hagolle committed
167
168
169
170
WASP method was initially developped at CESBIO by O.Hagolle for the VENµS satellite.
WASP processor comes from the initial work performed within the [Sen2Agri](http://www.esa-sen2agri.org/) project, by the following consortium :

* **Université Catholique de Louvain (UCL)**
Peter Kettig's avatar
Peter Kettig committed
171
* **CS Romania**
Olivier Hagolle's avatar
Olivier Hagolle committed
172
173
* **CS France**
* **Centre d'Etudes Spatiales de la Biosphère (CESBIO)**
Peter Kettig's avatar
Peter Kettig committed
174

Olivier Hagolle's avatar
Olivier Hagolle committed
175
176
Within Sen2Agri, WASP processor was mainly developped at CS-Romania by :
Cosmin Udroiu, Alex Grosu, Laurentiu Nicola, Lucian Barbulescu and Anca Trasca
Peter Kettig's avatar
Peter Kettig committed
177

Olivier Hagolle's avatar
Olivier Hagolle committed
178
WASP was then adapted to CNES context by Peter Kettig from
Peter Kettig's avatar
Peter Kettig committed
179
180
181
182
* **Centre National d'Etudes Spatiales (CNES)** 

## License

Olivier Hagolle's avatar
Olivier Hagolle committed
183
This project is licensed under the GPLv3+ License - see the [LICENSE.md](LICENSE.md) file for details
184