README.md 5.97 KB
Newer Older
Simon Gascoin's avatar
Simon Gascoin committed
1
# Let-it-snow
2
3
## Synopsis

Simon Gascoin's avatar
Simon Gascoin committed
4
This code is a Python/OTB version of the snow cover extent detection algorithm for Sentinel-2 and Landsat-8 data.
Simon Gascoin's avatar
Simon Gascoin committed
5

Simon Gascoin's avatar
Simon Gascoin committed
6
7
The algorithm documentation with examples is available here:

Simon Gascoin's avatar
Simon Gascoin committed
8
* [Algorithm theoretical basis documentation](http://tully.ups-tlse.fr/grizonnet/let-it-snow/blob/master/doc/tex/ATBD_CES-Neige.pdf)
Simon Gascoin's avatar
Simon Gascoin committed
9

Simon Gascoin's avatar
Simon Gascoin committed
10
To read more about the "Centre d'Expertise Scientifique surface enneigée" (in French):
Manuel Grizonnet's avatar
Manuel Grizonnet committed
11

Simon Gascoin's avatar
Simon Gascoin committed
12
* [Bulletin THEIA](https://www.theia-land.fr/sites/default/files/imce/BulletinTHEIA3.pdf#page=10)
Manuel Grizonnet's avatar
Manuel Grizonnet committed
13

14
The input files are Sentinel-2 or Landsat-8 level-2A products from the [Theai Land Data Centre](https://theia.cnes.fr/) or [SPOT-4/5 Take 5 level-2A products](https://spot-take5.org) and the SRTM digital elevation model reprojected at the same resolution as the input image.
15

16
##Usage
17

18
Run the python script run_snow_detector.py with a json configuration file as unique argument:
19

Simon Gascoin's avatar
Simon Gascoin committed
20
```bash
21
python run_snow_detector.py param.json
22
```
23
The snow detection is performed in the Python script [run_snow_detector.py](app/run_snow_detector.py).
Simon Gascoin's avatar
Simon Gascoin committed
24

25
26
27
28
29
All the parameters of the algorithm, paths to input and output data are stored in the json file. See the provided example [param_test_s2_template.json](tes/param_test_s2_template.json) file for an example.

Moreover The JSON schema is available in the [Algorithm theoritical basis documentation](doc/tex/ATBD_CES-Neige.tex) and gives more information about the roles of these parameters.

NB: To build DEM data download the SRTM files corresponding to the study area and build the .vrt using gdalbuildvrt. Edit config.json file to activate preprocessing : Set "preprocessing" to true and set the vrt path. 
30

31

Tristan Klempka's avatar
Tristan Klempka committed
32
33
## Products format

Simon Gascoin's avatar
Simon Gascoin committed
34
* COMPO: Raster image showing the outlines of the cloud (including cloud shadow) and snow masks drawn on the RGB composition of the L2A image (bands SWIR/Red/Green).
Tristan Klempka's avatar
Tristan Klempka committed
35
* SNOW_ALL: Binary mask of snow and clouds.
Tristan Klempka's avatar
Tristan Klempka committed
36
37
38
39
  * 1st bit: Snow mask after pass1
  * 2nd bit: Snow mask after pass2
  * 3rd bit: Clouds detected at pass0 
  * 4th bit: Clouds refined  at pass0
Tristan Klempka's avatar
Tristan Klempka committed
40
41

For example if you want to get the snow from pass1 and clouds detected from pass1 you need to do: 
Simon Gascoin's avatar
Simon Gascoin committed
42
```python
Tristan Klempka's avatar
Tristan Klempka committed
43
pixel_value & 00000101  
Simon Gascoin's avatar
Simon Gascoin committed
44
```
Tristan Klempka's avatar
Tristan Klempka committed
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
* SEB: Raster image of the snow mask and cloud mask. 
  * 0: No-snow
  * 100: Snow
  * 205: Cloud including cloud shadow
  * 254: No data
* SEB_VEC: Vector image of the snow mask and cloud mask. Two fields of information are embbeded in this product. DN (for Data Neige) and type.
  * DN field :
     * 0: No-snow
     * 100: Snow
     * 205: Cloud including cloud shadow
     * 254: No data
  * Type field:
     * no-snow
     * snow
     * cloud
     * no-data
61

62
63
64
65
## Data set example

Sequence of snow maps produced from Sentinel-2 type of observations (SPOT-5 Take 5) over the Deux Alpes and Alpe d'Huez ski resorts are available on [Zenodo](http://doi.org/10.5281/zenodo.159563).

66
67
## Motivation

Simon Gascoin's avatar
Simon Gascoin committed
68
Code to generate the snow cover extent product on Theia platform.
69
70
71

## Installation

Manuel Grizonnet's avatar
Manuel Grizonnet committed
72
73
74
75
### Dependencies

lis dependencies: 

76
GDAL >=2.0
Manuel Grizonnet's avatar
Manuel Grizonnet committed
77
78
79
80
OTB >= 5.0 
Boost-Python
Python interpreter >= 2.7
Python libs >= 2.7
Tristan Klempka's avatar
Tristan Klempka committed
81
82
83
84
Python packages:
numpy
lxml
matplotlib
Manuel Grizonnet's avatar
Manuel Grizonnet committed
85
86
87

GDAL itself depends on a number of other libraries provided by most major operating systems and also depends on the non standard GEOS and PROJ4 libraries. GDAl- Python bindings are also required

Simon Gascoin's avatar
Simon Gascoin committed
88
Python package dependencies: sys, subprocess, glob, os, json, gdal
Manuel Grizonnet's avatar
Manuel Grizonnet committed
89

90
### Installing from the source distribution
Manuel Grizonnet's avatar
Manuel Grizonnet committed
91

92
#### General
93

94
In your build directory, use cmake to configure your build.
Simon Gascoin's avatar
Simon Gascoin committed
95
```bash
96
cmake -C config.cmake source/lis/
Simon Gascoin's avatar
Simon Gascoin committed
97
```
98
In your config.cmake you need to set :
Simon Gascoin's avatar
Simon Gascoin committed
99
```bash
100
LIS_DATA_ROOT
Simon Gascoin's avatar
Simon Gascoin committed
101
```
102
For OTB superbuild users these cmake variables need to be set:
Simon Gascoin's avatar
Simon Gascoin committed
103
```bash
104
105
106
107
OTB_DIR
ITK_DIR
GDAL_INCLUDE_DIR
GDAL_LIBRARY
Simon Gascoin's avatar
Simon Gascoin committed
108
```
Tristan Klempka's avatar
Tristan Klempka committed
109
Run make in your build folder.
Simon Gascoin's avatar
Simon Gascoin committed
110
```bash
Tristan Klempka's avatar
Tristan Klempka committed
111
make
Simon Gascoin's avatar
Simon Gascoin committed
112
```
113
114
To install s2snow python module. 
In your build folder:
Simon Gascoin's avatar
Simon Gascoin committed
115
```bash
116
117
cd python
python setup.py install
Simon Gascoin's avatar
Simon Gascoin committed
118
```
119
or
Simon Gascoin's avatar
Simon Gascoin committed
120
```bash
121
python setup.py install --user
Simon Gascoin's avatar
Simon Gascoin committed
122
```
Tristan Klempka's avatar
Tristan Klempka committed
123
Update environment variables for LIS. Make sure that OTB and other dependencies directories are set in your environment variables:
Simon Gascoin's avatar
Simon Gascoin committed
124
```bash
Tristan Klempka's avatar
Tristan Klempka committed
125
126
export PYTHONPATH=/your/build/directory/bin/:$PYTHONPATH
export PATH=/your/build/directory/bin:$PATH
Simon Gascoin's avatar
Simon Gascoin committed
127
```
128
let-it-snow is now installed.
Manuel Grizonnet's avatar
Manuel Grizonnet committed
129

130
#### On venuscalc
131

Simon Gascoin's avatar
Simon Gascoin committed
132
To configure OTB 5.2.1:
133
134

Create a bash file which contains:
Simon Gascoin's avatar
Simon Gascoin committed
135
```bash
136
source /mnt/data/home/grizonnetm/config_otb_5.6.sh
Simon Gascoin's avatar
Simon Gascoin committed
137
```
138

139
Then build the lis project using cmake
Simon Gascoin's avatar
Simon Gascoin committed
140
```bash
141
cd $build_dir
142
cmake -DCMAKE_CXX_FLAGS:STRING=-std=c++11 -DCMAKE_CXX_COMPILER:FILEPATH=/usr/bin/g++-4.8 -DCMAKE_C_COMPILER:FILEPATH=/usr/bin/gcc-4.8 -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON -DGDAL_INCLUDE_DIR=/mnt/data/home/grizonnetm/build/OTB-install/include -DGDAL_LIBRARY=/mnt/data/home/grizonnetm/build/OTB-install/lib/libgdal.so $source_dir
143
make
Simon Gascoin's avatar
Simon Gascoin committed
144
```
145
146
To install s2snow python module. 
In your build folder:
Simon Gascoin's avatar
Simon Gascoin committed
147
```bash
148
149
cd python
python setup.py install
Simon Gascoin's avatar
Simon Gascoin committed
150
```
151
or
Simon Gascoin's avatar
Simon Gascoin committed
152
```bash
153
python setup.py install --user
Simon Gascoin's avatar
Simon Gascoin committed
154
```
Tristan Klempka's avatar
Tristan Klempka committed
155
Update environment variables for LIS. Make sure that OTB and other dependencies directories are set in your environment variables:
Simon Gascoin's avatar
Simon Gascoin committed
156
```bash
Tristan Klempka's avatar
Tristan Klempka committed
157
158
export PYTHONPATH=/your/build/directory/bin/:$PYTHONPATH
export PATH=/your/build/directory/bin:$PATH
Simon Gascoin's avatar
Simon Gascoin committed
159
```
160
161
let-it-snow is now installed.

162
163
## Tests

Tristan Klempka's avatar
Tristan Klempka committed
164
Enable tests with BUILD_TESTING cmake option. Use ctest to run tests. Do not forget to clean your output test directory when you run a new set of tests.
165

166
167
168
Data (input and baseline) to run validation tests are available on [Zenodo](http://doi.org/10.5281/zenodo.166511).

Download LIS-Data and extract the folder. It contains all the data needed to run tests. Set Data-LIS path var in cmake configuration files. 
Tristan Klempka's avatar
Tristan Klempka committed
169
170
171
172
Baseline : Baseline data folder. It contains output files of S2Snow that have been reviewed and validated. 
Data-Test : Test data folder needed to run tests. It contains Landsat, Take5 and SRTM data.
Output-Test : Temporary output tests folder.
Do not modify these folders.
Manuel Grizonnet's avatar
Manuel Grizonnet committed
173

174
175
## Contributors

Simon Gascoin's avatar
Simon Gascoin committed
176
Manuel Grizonnet (CNES), Simon Gascoin (CNRS/CESBIO), Tristan Klempka (CNES)
Manuel Grizonnet's avatar
Manuel Grizonnet committed
177

178
179
## License

180
181
This is free software under the GNU Affero General Public License v3.0. See
http://www.gnu.org/licenses/agpl.html for details.