Home
Welcome to the Process_SMOS_L1C wiki!
Process_SMOS_L1C is a mex function to process L1C binary data files from the Soil Moisture Ocean Salinity (SMOS) mission from the European Space Agency (ESA). SMOS L1C binary data files contain mainly the brightness temperature in full polarization emitted by Earth surface and ocean as sensed by the radiometric instrumentation at the satellite orbit altitude and satellite antenna reference frame.
The L1C data needs to be processed in order to obtain brightness temperatures with polarization at surface reference frame (horizontal and vertical polarization), and need to be filtered from radio frequency interference that might jeopardize the accuracy of the measurements.
Compilation tested for the versions:
- as a MATLAB function via MEX compiler, revision: 1.1.6.3 or higher,
- as a GNU/Octave mex function via MKOCTFILE compiler version 3.6.2 or higher.
The mex function source code is suitable to be compiled either for Matlab or Octave, accordingly the following instructions:
For compilation the GNU Scientific Library is needed. In case of Octave the MATIO library is additionally needed.
>[MATLAB_BIN_PATH]/mex CFLAGS='$CFLAGS -std=gnu++11' Process_SMOSxL1C.cpp -lgsl -lgslcblas
creates the mex function Process_SMOSxL1C.mexa64
> mex Process_SMOSxL1C.cpp -lgsl -lgslcblas
creates the mex function Process_SMOSxL1C.mexa64
> mkfileobj --mex Process_SMOSxL1C.cpp -lgsl -lgslcblas -lmatio
this creates the octave mex function Process_SMOSxL1c.mex
Use the provided Makefile adapting the enviroment variable MATLABROOT or OCTAVEROOT with the path for matlab version installed in your system, e.g. MATLABROOT = /usr/local/matlab7.8/, then in linux console run:
> make
to create the matlab mex function Process_SMOSxL1C.mexa64 or
> make octave
to create the Octave mex function Process_SMOSxL1C.mex
The program requires:
- The GNU Scientific Library (GSL) version 2.2.1 for C and C++ language,
- the GNU C GSL Basic Linear Algebra Subprograms (GSLCBLAS) version 3.6.0.,
- MATIO library version 1.5.9 is required for Octave to support MAT-file archiving.
Under Ubuntu 16.04 LTS, it has been reported that a symbolic link from /usr/lib/x86_64-linux-gnu/libgsl.so to /usr/lib/libgsl.so.0 was needed before the .mexa64 file would work.
If Matlab doen't run >> [TSF, SSI] = Process_SMOSxL1C; and shows the following error:
Invalid MEX-file
'/home/user/Process_SMOS_L1C/Process_SMOSxL1C.mexa64':
libgsl.so.0: cannot open shared object file: No such file or directory.
then follow these instruction to fix libgsl.so.0 dependency:
-
From linux command line install GSL library with the command:
sudo apt-get install libgsl-dev
-
From linux command line, create symbolic link with the command:
sudo ln -s /usr/lib/x86_64-linux-gnu/libgsl.so /usr/lib/libgsl.so.0
-
From Matlab run again the Processor as:
[TSF, SSI] = Process_SMOSxL1C;
then the file selector will pop-up to let you chose a SMOS DBL file.
The Process_SMOSxL1C.cpp code has been successfully compiled with GNU C++ version 4.7, 4.7.1, 4.8.5 in a Linux 64bit system. The compiled mex-function has been tested in three different Matlab versions: v7.8.0.347 (R2009a), v7.11.0 (R2010b), R2015b, and v9.1.0.441655 (R2016b). Similarly the code has been compiled and tested for Octave version 3.6.2. and 4.0.3.
> [TSF, SSI] = Process_SMOSxL1C;
then, a file browser will pop-up to select a SMOS L1C DBL file to open,
once the DBL file is selected a dialog box will pop-up to introduce the latitude and longitude limits for a geographical region of interest:
For the Octave version < 4, the last step is done only by the command line in the Octave workspace (dialog-box not supported).
> [TSF, SSI] = Process_SMOSxL1C('fname.DBL',GEO_LIMS,outdir);
WHERE:
'fname.DBL': full path string of DBL file to work with,
GEOLIMS: a 4 element vector as [LAT1, LON1, LAT2, LON2],
with elements indicating the latitude and longitude of bottom-left of box and latitude and longitude of upper-right of a box representing the geographical region of interest (default is [-90 -180 90 180]).
outdir: (optional) string with directory where the output variables will be saved as MAT-file. The file name of the MAT-file is the same as the DBL input file with the extension switched from .DBL to .mat
> [TSF, SSI] = Process_SMOSxL1C('fname.DBL',GEO_LIMS);
same as usage #2, but an output MAT-file will not be generated.
The MEX-function requires at least one output variable.
TSF: Structure with all variables for [Temp_Swath_Full] dataset.
SSI: Structure with all variables for [Snapshot_Information] dataset (this output variable is optional).
- The TSF structure includes all variables corresponding for the L1C dataset but extracted for the geographic region of interest selected GEOLIMS = [LAT1, LON1, LAT2, LON2]. Additionally TSF includes the Brightness Temperature in HV-polarization reference frame after performing the Geometric and Faraday rotation from the Antenna XY-polarization reference plane.
- The TSF member variables TB_Fixed_IncAngle and Fixed_IncAngle, are representing the Brightness Temperatures at averaged over fixed incident angles classes (normally from 0 to 60 deg classified in bins of 1 deg step).
For the following examples, a SMOS science land full-polarization data file is used. The archive can be found at the ESA SMOS Dissimination website (you might needed to log-in first) or via FTP:
[Sample data file: SM_OPER_MIR_SCLF1C_20150702T042618_20150702T051937_620_001_1.zip]
or for testing purposes I keep a copy of the same file in my DropBox site.
> TSF=Process_SMOSxL1C('/mission/smos/SM_OPER_MIR_SCLF1C_20150702T042618_20150702T051937_620_001_1.DBL',[47.5 7.5 50 10],'/data/output/');
The example above process the DataBlock file SM_OPER_MIR_SCLF1C_20150702T042618_20150702T051937_620_001_1.DBL located at /mission/smos/ directory, extracting data from a geographically limited box with 47.5° latitude and 7.5° longitude left-bottom boundary and 50° latitude and 10° longitude right-upper boundary. Then the processed data is archived at the /data/ouput directory as a MAT-file. The delivered variable is the TSF structure with fields given as follow:
TSF =
File_Name: 'SM_OPER_MIR_SCLF1C_20150702T042618_20150702T051937_620_001_1.DBL'
GEOBoxLimits: [2x2 double]
Start_End_Time: [2x17 char]
GridPoint_ID: [1041x1 double]
GridPoint_Latitude: [1041x1 double]
GridPoint_Longitude: [1041x1 double]
GridPoint_Altitude: [1041x1 double]
GridPoint_Mask: [1041x1 double]
BT_Data_Counter: [1041x1 double]
flags: {1041x1 cell}
BTvalue_re: {1041x1 cell}
BTvalue_im: {1041x1 cell}
PixelRadiometry_acc: {1041x1 cell}
Incidence_angle: {1041x1 cell}
Azimuth_angle: {1041x1 cell}
FaradayRotation_angle: {1041x1 cell}
GeometricRotation_angle: {1041x1 cell}
Snapshot_ID_Pixels: {1041x1 cell}
Footprint_Axis1: {1041x1 cell}
Footprint_Axis2: {1041x1 cell}
TBxy: {1041x1 cell}
TBhv: {1041x1 cell}
RA: {1041x1 cell}
idx_SnapshotID: {1041x1 cell}
TB_Fixed_IncAngle: [1041x61x4 double]
Fixed_IncAngle: [61x1 double]
An output MAT-file will be created with the TSF and SSI structures, located at the directory '/data/output/' and with a file name as `SM_OPER_MIR_SCLF1C_20150702T042618_20150702T051937_620_001_1.mat'
Example MAT-file output in DropBox: SM_OPER_MIR_SCLF1C_20150702T042618_20150702T051937_620_001_1.mat
A simple plotting of brightness temperatures from the field TSF.TB_Fixed_IncAngle within a region for a specific incidence angle can be done by:
>> scatter(TSF.GridPoint_Longitude,TSF.GridPoint_Latitude,250,TSF.TB_Fixed_IncAngle(:,41,1),'o','filled');
this single line will show TBs at 40° (2nd dim = 41) and H-pol (3rd dim = 1) as seen at the following figure:
The Matlab script example_3IncAngles.m is an example to reproduce the Figure 2 in the JORS paper (figure above), which is currently under revision, i.e. brightness temperatures for three different incidence angles: 35, 40 and 45° taken from the field TSF.Fixed_IncAngle([36,41,46]).
TSF : stands for Temperature Snapshot Full polarized. The TSF structure comprises of 26 elements, 2 are character type, 9 are matrices, and 15 are cell types.
TSF.File_Name : contains the source L1C DBL file.
TSF.GEOBoxLimits: is a 2x2 matrix with containing [LAT1 LON1; LAT2 LON2] of the left-bottom and right-upper limits of the extracted geographic region.
TSF.Start_End_Time: composed by 2 character strings with the initial and final time for the snapshots contained within [LAT1 LON1; LAT2 LON2] geographic box.
TSF.TB_Fixed_IncAngle: 3-D matrix with the number of snapshots within the selected geographic region, number of incidence angles, and 4 (2) elements for polarization 4 vector Stokes (dual-pol).
TSF.Fixed_IncAngle: is a vector with the incidence angle classes where the brightness temperature has been rearranged. By default it ranges from 0° to 60° with 1° bin.
The TSF members which are cell variables represent the raw data loaded from the L1C data-block (DBL) file and the meaning of their content is described at the "SMOS DPGS Level 1 and Auxiliary Data Products Specification", section 4.2.5.1 and 4.2.5.2. The TSF structure members host the data described in fields 36 to 46, while the SSI structure members are the data described in fields 1 to 35 of the Data-block description in the before mentioned document. The SSI structure contains, however, all the information for the Half-orbit DBL data file, on the other hand the TSF structure only contains data extracted for the geographic region of interest.
Every cell class is composed by the number of snapshots found within [LAT1 LON1; LAT2 LON2] geographic box, and every class member as TSF.BT_Data_Counter elements which are different for every snapshot. For instance, TSF.TBxy{1000} is the brightness temperature at antenna polarization frame at the incidence angle given by TSF.Incidence_angle{1000} and with number of elements given in TSF.BT_Data_Counter(1000).