Welcome to OBIA4RTM’s documentation!¶
Created on Sat Jul 13 09:44:14 2019
This module is part of OBIA4RTM.
Copyright (c) 2019 Lukas Graf
@author: Lukas Graf, graflukas@web.de
- OBIA4RTM.configurations.connect_db.close_db_connection(con, cursor)[source]¶
closes an opened database connection
- Parameters
- conpsycopg2 Database Connection
connection to be closed
- cursorpsycopg2 Database Cursor
cursor to be closed
- OBIA4RTM.configurations.connect_db.connect_db()[source]¶
connect to PostgreSQL database by using the specifications in ‘postgres.ini’ File in the root of the OBIA4RTM home directory stored in the user-profile
- Returns
- connpsycopg2 Database connection
connection object to PostgreSQL database
- cursor psycopg2 Database cursor
cursor for querying and inserting data from and to PostgreSQL DB
- OBIA4RTM.configurations.connect_db.get_db_connection_details()[source]¶
reads and returns the postgres.ini connection details
Returns:¶
- parserConfigParser Object
parsed database configurations from postgres.ini file
Created on Tue Jul 30 15:38:37 2019
This module is part of OBIA4RTM.
Copyright (c) 2019 Lukas Graf
@author: Lukas Graf, graflukas@web.de
- OBIA4RTM.configurations.db_management.update_luc_table(landcover_table, landcover_cfg=None)[source]¶
updates the land-cover/ land use table in OBIA4RTM that is required for performing land-cover class specific vegetation parameter retrieval Make sure that the classes in the config file match the land cover classes provided for the image objects and used for generating the lookup-table. Otherwise bad things might happen.
NOTE: in case land cover classes that are about to be inserted are already stored in the table, they will be overwritten!
- Parameters
- landcover_tableString
name of the table with the land cover information (<schema.table>)
- landcover_cfgString
file-path to land cover configurations file
- Returns
- None
Created on Fri Jul 5 14:11:59 2019
This module is part of OBIA4RTM.
Copyright (c) 2019 Lukas Graf
@author: Lukas Graf, graflukas@web.de
- OBIA4RTM.configurations.logger.close_logger(logger)[source]¶
close a logger after program shut-down and releases the handlers
- Parameters
- loggerlogging Object
logger of OBIA4RTM ‘OBIA4RTM_logger’
- OBIA4RTM.configurations.logger.determine_logdir()[source]¶
searches the logging directory used for OBIA4RTM
- Returns
- log_dirString
Path of logging directory
- OBIA4RTM.configurations.logger.get_logger(logname=None)[source]¶
setups up a new logging object using Rotating File Handlers
- Parameters
- OBIA4RTM_log_dirString
directory, the log-file should be written to
- lognameString
name of the logger (opt.); per default OBIA4RTM_Logger will be used
- Returns
- ——
- loggerlogging Logger
Logger with stream handler for tracing OBIA4RTM’s activities and errors
Created on Sat Mar 9 09:03:14 2019
This module is part of OBIA4RTM.
@author: Lukas Graf, graflukas@web.de
- OBIA4RTM.inversion.distributions.gaussian(minimum, maximum, num, mean, std)[source]¶
draws a truncated gaussian distribution between min and max
- Parameters
- minimumfloat
lower bound of the truncated Gaussian distribution
- maximumfloat
upper bound of the truncated Gaussian distribution
- numInteger
number of samples to be drawn
- meanfloat
centre of the truncated Gaussian distribution
- stdflaot
standard deviation, controlls the width of the distribution betweem min and max
- Returns
- truncatednp.array
Array with values drawn from the truncated Gaussian distribution
- OBIA4RTM.inversion.distributions.uniform(minimum, maximum, num)[source]¶
draws a uniform distribution between min and max
- Parameters
- minimumfloat
lower bound of the uniform distribution
- maximumfloat
upper bound of the uniform distribution
- numInteger
number of samples to be drawn
- Returns
- uninp.array
Array with values drawn from the uniform distribution
Created on Sat Mar 9 10:58:16 2019
This module is part of OBIA4RTM.
Copyright (c) 2019 Lukas Graf
- OBIA4RTM.inversion.handle_metadata.get_bands(conn, cursor, sensor, logger)[source]¶
reads in sensor band centers and FWHM stored in database
- Parameters
- connpsycopg2 Database connection
connection to OBIA4RTM PostgreSQL database
- cursorpsycopg2 Database cursor
cursor for DB inserts and queries
- sensorString
name of the sensor; currently either ‘S2A’ or ‘S2B’
- loggerlogging Logger
for recording errors to the log file
- Returns
- centersList
list of central wavelengths of the spectral bands of the sensor (nm)
- fwhmList
list of the full width half maximum of the spectral bands (nm)
- OBIA4RTM.inversion.handle_metadata.get_resampler(conn, cursor, sensor, logger)[source]¶
get the spectral properties of a sensor and generate a resampler object. Currently, Sentinel-2A and Sentinel-2B are supported
- Parameters
- connpsycopg2 Database connection
connection to OBIA4RTM PostgreSQL database
- cursorpsycopg2 Database cursor
cursor for DB inserts and queries
- sensorString
name of the sensor; currently either ‘S2A’ or ‘S2B’
- loggerlogging Logger
for recording errors to the log file
- Returns
- resamplerspectral BandResampler
Resampler Object for resampling the ProSAIL output to the spectral resolution of Sentinel-2
Created on Sat Jul 13 11:14:32 2019
This module is part of OBIA4RTM.
Copyright (c) 2019 Lukas Graf
@author: Lukas Graf, graflukas@web.de
- OBIA4RTM.inversion.handle_prosail_cfg.get_landcover_classes(landcover_cfg)[source]¶
get the number and names of the land cover classes stored in the ProSAIL.cfg file
- Parameters
- cfg_fileString
path to the land cover configuration file
- Returns
- luc_classesList
list of landcover classes (code + semantics)
- OBIA4RTM.inversion.handle_prosail_cfg.read_params_per_class(prosail_cfg, landcover_cfg, logger)[source]¶
reads in the vegetation parameters for the ProSAIL model for each land cover class
- Parameters
- cfg_fileString
path to the ProSAIL configurations file
- landcover_cfgString
path to the landcover configuration file
- loggerlogging.Logger
for recording errors
- Returns
- containerDictionary
dict with the ProSAIL parameters per land cover class
Created on Sat Mar 9 10:34:57 2019
This module is part of OBIA4RTM.
Copyright (c) 2019 Lukas Graf
@author: Lukas Graf, graflukas@web.de
- class OBIA4RTM.inversion.inversion.inversion(scene_id)[source]¶
super-class for the object-based inversion of satellite scenes
Methods
do_inversion
(land_use, num_solutions, ...[, ...])performs inversion on all objects for a given date.
do_obj_inversion
(object_id, acqui_date, ...)performs inversion per single object using mean of xx best solutions (RMSE criterion) and stores result results table params to be inverted/ returned should be passed as list of strings e.g: inv_params = ["LAI", "CAB"] also inverted spectra can be returned: therefore just append the band numbers to the list of strings of parameters: e.g.
gen_lut
(inv_mapping_table, inv_table[, ...])Generates the lookup table and stores it in the DB must be run seperately from the inversion part
queries the relevant scene metadata from the database
set_ProSAIL_config
([path_to_config])read in the config file holding the vegetation parameters for setting up the lookup table using the ProSAIL radiative transfer model
set_landcover_config
([path_to_lc_config])read in the land cover config file holding the land cover classes for setting up the lookup table using the ProSAIL radiative transfer model
set_soilrefl
([path_to_soilrefl_file])set up the file-path to the txt file containing the soil-reflectance required for ProSAIL to account for the soil background and read in the values
- do_inversion(land_use, num_solutions, res_table, object_table, inv_mapping_table, lut_table, return_specs=True)[source]¶
performs inversion on all objects for a given date. NOTE: the object reflectance values must be already available in the data base. Run gen_lut therefore before! Works as a wrapper around the do_object_inversion method
- Parameters
- lande_useInteger
land cover code for the specific object and date
- num_solutionsInteger
how many solutions should be used for generating the inversion result
- res_tableString
tablename where to store the results of the inversion (<schema.table>)
- object_tableString
tablename of table containing the object spectra (<schema.table>)
- inv_mapping_tableString
tablename of the table containing the parameters to be inverted per acqusition date (scene) and land use/ cover class
- lut_tableString
table containing the ProSAIL lut on a per scene and landuse / cover class base
- return_specsBoolean
determines whether inverted spectra should be returned (True; default)
- Returns
- None
- do_obj_inversion(object_id, acqui_date, land_use, num_solutions, inv_params, res_table, object_table, lut_table)[source]¶
performs inversion per single object using mean of xx best solutions (RMSE criterion) and stores result results table params to be inverted/ returned should be passed as list of strings e.g: inv_params = [“LAI”, “CAB”] also inverted spectra can be returned: therefore just append the band numbers to the list of strings of parameters: e.g. inv_params = [“LAI”, “CAB”, “B2”, “B3”, etc.]
- Parameters
- object_idInteger
ID of the current object (derived from OBIA4RTM database)
- acqui_dateDate (YYYY-MM-DD)
acquisition date of the image used for the inversion
- lande_useInteger
land cover code for the specific object and date
- num_solutionsInteger
how many solutions should be used for generating the inversion result
- inv_paramsList
list of the parameters (must be named) to be inverted
- res_tableString
tablename where to store the results of the inversion (<schema.table>)
- object_tableString
tablename of the table containing the object spectra (<schema.table>)
- lut_tableString
tablename of the lookup-table (<schema.table>)
- Returns
- statusInteger
zero if everything is OK
- gen_lut(inv_mapping_table, inv_table, landcover_config_path=None, prosail_config_path=None, soil_path=None)[source]¶
Generates the lookup table and stores it in the DB must be run seperately from the inversion part
- Parameters
- inv_mapping_tableString
name of the table storing the inversion mapping required for performing the inversion
- inv_tableString
Name of the table the lookup-table should be written to (<schema.table>)
- landcover_config_pathString
file-path to landcover config file (opt.; per default the OBIA4RTM delivered file will be used)
- prosail_config_pathString
file-path to landcover config file (opt.; per default the OBIA4RTM delivered file will be used)
- soil_pathString
file-path to file with soil reflectance values (opt.; per default the OBIA4RTM delivered file will be used)
- set_ProSAIL_config(path_to_config=None)[source]¶
read in the config file holding the vegetation parameters for setting up the lookup table using the ProSAIL radiative transfer model
- Parameters
- path_to_configString
optinal, path and filename of config-file for ProSAIL
- Returns
- path_to_configString
definite location of the config file or error if file not found
- set_landcover_config(path_to_lc_config=None)[source]¶
read in the land cover config file holding the land cover classes for setting up the lookup table using the ProSAIL radiative transfer model
- Parameters
- path_to_lc_configString
optinal, path and filename of config-file for land cover classes
- Returns
- path_to_configString
definite location of the config file or error if file not found
- set_soilrefl(path_to_soilrefl_file=None)[source]¶
set up the file-path to the txt file containing the soil-reflectance required for ProSAIL to account for the soil background and read in the values
- Parameters
- path_to_soilrefl_fileString
optional, file to the txt file with soil reflectance values
- Returns
- soilsNumpy Array
array of soil reflectance values (1 nm steps)
Created on Sat Mar 9 06:52:00 2019
This module is part of OBIA4RTM.
Copyright (c) 2019 Lukas Graf
@author: Lukas Graf, graflukas@web.de
- class OBIA4RTM.inversion.lookup_table.lookup_table[source]¶
class for creating and storing biophysical parameters in a lookup table (LUT) like structure
Methods
generate_param_lut
(params)get the minima, maxima, number and distribution type of parameters to be inverted and prepares them for storing in a LUT accordingly
Created on Fri Jul 26 15:42:10 2019
This module is part of OBIA4RTM.
Copyright (c) 2019 Lukas Graf
@author: Lukas Graf, graflukas@web.de
- OBIA4RTM.S2_PreProcessor.install_6S.install_6S(link=None)[source]¶
installs the 6S algorithm required for atmospheric correction from the Fortran source code using gfortran. The sources will be installed to the OBIA4RTM install dir (somewhere in the user profile) where also the config files are stored.
Currently, only Linux/ Unix systems are supported for this operation.
In case you expire any problems automatically downloading and building 6S, please also consult: https://py6s.readthedocs.io/en/latest/installation.html
Windows-Users please note that the installation might not be that smoothly as on Posix, as you will have to install a bunch of additional functionalities
Created on Wed Jul 31 12:32:24 2019
This module is part of OBIA4RTM. It is part of the (optional) Sen2Core preprocessing wrapper addon that takes care about image preprocessing (i.e atmospheric correction) using Sen2Core software (see: http://step.esa.int/main/third-party-plugins-2/sen2cor/)
NOTE: Sen2Core must be installed on your computer!
NOTE: Windows users might have to add the GDAL binaries (they come with OSGEO) to their PATH variable
Copyright (c) 2019 Lukas Graf
@author: Lukas Graf, graflukas@web.de
- OBIA4RTM.S2_PreProcessor.s2_sen2core_attcor.call_gdal_merge(sentinel_data_dir_l2, resolution, storage_dir=None)[source]¶
calls the gdal_merge.py script to make an image layer stack and prepare the imagery for usage in OBIA4RTM. Outputs a GeoTiff with the nine Sentinel-2 bands used in OBIA4RTM and the SCL band that contains the preclassification information.
You can use this function also if you L2 data
- Parameters
- sentinel_data_dir_l2String
path of the directory containing the output of sen2core in L2 level
- resolutionInteger
spatial resolution of the atmospherically corrected imagery possible value: 10, 20, 60 meters
- storage_dirString
path to the directory the layer stack should be moved to. If None, the layer stack will remain the sentinel_data_dir_l2 in the img folder
- Returns
- fname_stackString
file-path to the stacked imagery
- metadata_xmlString
file-path to the metadata xml file
- OBIA4RTM.S2_PreProcessor.s2_sen2core_attcor.call_sen2core(sentinel_data_dir, zipped, resolution, path_sen2core)[source]¶
calls Sen2Core and runs it on a downloaded Sentinel 1C dataset to convert it to Level 2A. The output spatial resolution must be provided (10, 20 or 60 meters)
NOTE: If you have already L2 imagery then only run the gdal_merge wrapper and to not use this function
- Parameters
- sentinel_data_dirString
path to the directory that contains the Level-1C data. In case the data is zipped (default when downloaded from Copernicus) specify the file-path of the zip
- zippedBoolean
specifies if the directory with the Sat data is zipped
- resolutionInteger
spatial resolution of the atmospherically corrected imagery possible value: 10, 20, 60 meters
- path_sen2coreString
directory containing Sen2Core software (top-most level; e.g. /home/user/Sen2Core/). Must be the same directory as specified during the Sen2Core installation process using the –target option
- Returns
- sentinel_data_dir_l2
- OBIA4RTM.S2_PreProcessor.s2_sen2core_attcor.check_sen2core_installation(path)[source]¶
check if Sen2Core is installed and can be used
- Parameters
- pathString
user-provided path to Sen2Core installation directory
- Returns
- ——-
- existsBoolean
True, if directory exists and False if tests fail
- cmdString
command for testing if Sen2Core is working
- OBIA4RTM.S2_PreProcessor.s2_sen2core_attcor.do_sen2core_preprocessing(sentinel_data_dir, zipped, resolution, path_sen2core, storage_dir=None)[source]¶
calls the sen2core wrapper and the gdal_merge wrapper to carry out the atmospheric correction and preclassification on Sentinel-1 imagery (L1C level) required for OBIA4RTM.
NOTE: If you have already L2 imagery then only run the gdal_merge wrapper and to not use this function Make also sure that gdal_merge can be executed from the command line.
NOTE: Windows users might have add the gdal binaries to their PATH!!
- Parameters
- sentinel_data_dirString
path to the directory that contains the Level-1C data. In case the data is zipped (default when downloaded from Copernicus) specify the file-path of the zip
- zippedBoolean
specifies if the directory with the Sat data is zipped
- resolutionInteger
spatial resolution of the atmospherically corrected imagery possible value: 10, 20, 60 meters
- path_sen2coreString
directory containing Sen2Core software (top-most level; e.g. /home/user/Sen2Core/). Must be the same directory as specified during the Sen2Core installation process using the –target option
- storage_dirString
path to the directory the final layer stack should be moved to. If None, the layer stack will remain the sentinel_data_dir_l2 in the img folder
- Returns
- fname_stackString
file-path to the stacked imagery (required in OBIA4RTM)
- metadata_xmlString
file-path to the metadata xml file (required in OBIA4RTM)
Created on Thu Jul 25 10:15:38 2019
This module is part of OBIA4RTM.
Copyright (c) 2019 Lukas Graf
@author: Lukas Graf, graflukas@web.de
- OBIA4RTM.setup_db.create_schema.check_if_exists(schema, table_name, cursor)[source]¶
auxiiliary function to check whether a given table exists in a given schema
- Parameters
- schemaString
name of the schema the table should be created in
- table_nameString
name of the table to be created
- cursorpsycopg2 Database Cursor
for querying the database
- Returns
- existsBoolean
True, if table already exists, False else
- OBIA4RTM.setup_db.create_schema.create_function_statement(sql_function, logger)[source]¶
create a SQL statement for creating/ replacing a SQL function
- Parameters
- sql_functionString
file-path to the sql-function
- loggerlogging.Logger
for logging errors
- Returns
- sql_statementString
processed and ready-to-execute sql statement
- OBIA4RTM.setup_db.create_schema.create_schema()[source]¶
this function is used to generate a new schema in the OBIA4RTM database. In case the schema already exists, nothing will happen. The schema to be created is taken from the obia4rtm_backend.cfg file
- Parameters
- None
- Returns
- statusinteger
zero if everything was OK
- OBIA4RTM.setup_db.create_schema.create_sql_statement(sql_file, schema, table_name, logger)[source]¶
auxiiliary function to create the sql_statement required to create the specific tables in the DB schema
- Parameters
- sql_fileString
file-path to the sql-template containing the sql-statement for creating the table
- schemaString
name of the schema the table should be created in
- table_nameString
name of the table to be created
- loggerlogging.Logger
for logging errors
- Returns
- sql_statementString
processed and ready-to-execute sql statement
Created on Thu Jul 18 15:08:29 2019
This module is part of OBIA4RTM.
Copyright (c) 2019 Lukas Graf
@author: Lukas Graf, graflukas@web.de
- class OBIA4RTM.setup_db.setup_postgres.setupDataBase[source]¶
class for setting up a PostgresSQL database as backend for OBIA4RTM
Methods
connects to default Postgres database running on specified host in postgres.ini file to create the OBIA4RTM Postgres database
create the OBIA4RTM database using the specification of the postgres.uni file
enables PostGIS and HSTORE extension required for OBIA4RTM
runs the whole setup-procedure for creating the OBIA4RTM backend
setups the RMSE function used in OBIA4RTM for doing the inversion
setups all those tables, that are required in the public schema of the OBIa4RTM backend database
- connect_to_postgres()[source]¶
connects to default Postgres database running on specified host in postgres.ini file to create the OBIA4RTM Postgres database
- Returns
- conpsycopg2 Database Connection
Connection to DEFAULT Postges database (not OBIA4RTM database)
- cursorpsycopg2 Database Cursor
Cursor for this default database
Created on Fri Jul 19 10:43:55 2019
This module is part of OBIA4RTM.
Copyright (c) 2019 Lukas Graf
@author: Lukas Graf, graflukas@web.de
- OBIA4RTM.install.install(install_addons=False)[source]¶
does a full-installation of OBIA4RTM backend facilities including the PostgreSQL database setup and copying of configuration files to a user- accessible directory NOTE: PostgreSQL must be almost installed as well as PostGIS
- Parameters
- install_addonsBoolean
Def: False; if True 6S for atmospheric correction together with GEE will be installed -> please read the requirements before!