Introduction
Karttur’s GeoImagine Framework uses default regions to process spatial data. The standard default region is a country, but can also be several countries in a continent or an entire continent. It can also be smaller regions than a country. The Framework database contains the definition of a hierarchical set of regional categories, but no actual geographical regions smaller than a country are included in the default Framework. The default set of countries, sub-continents and continents are available at the Framework GitHub repo. This manual details how the country data was prepared and how to import the data to the Framework, extract the individual countries, continents etc. Note that if you setup the Framework by restoring the database you anyway need to run the commands in this tutorial to retrieve the default regions as actual vector maps.
Prerequisites
You must have completed the post on setup process.
Systems and regions
In the Framework a system refers to a projection with predefined tiles that can be used for processing spatiotemporal datasets. Even if the processing is using tiles, the regions given by the user are always geographical, like a country or a river basin. In the database, the tiles forming the regions are listed, and the processing takes place using the tiles. Most static datasets are regarded as ancillary datasets and belong to the system ancillary. All default regions, used for defining geographic process regions, instead belong to the core system, called system. But existing data can not be directly imported as system layers and must be imported as ancillary and subsequently defined as default regions, and then also end up as system datasets.
Setup default regions
To start setup of default regions you must have completed the setup of processes, or restored the default database.
In your Python environment (e.g. Eclipse), open the module setup_process_main. To avoid reinstalling the processes every time you run the python script, comment out SetupProcesses (under the __main__ section):
#SetupProcesses(prodDB)
and remove the comment sign (“#”) for SetupDefaultRegions:
# SetupDefaultRegions starts a subroutine with different region processing
SetupDefaultRegions(prodDB)
In the subroutine SetupDefaultRegions there is a list of boolean setup options:
DefaultRegions = False
MODIS = False
...
Change DefaultRegions to True and running the module will look for a file (regions_karttur_setup_YYYYMMDD.txt) linking to definitions of default regions and create a set of both general and special regions.
if DefaultRegions:
projFN = 'regions_karttur_setup_20211108.txt'
SetupProcessesRegions('regiondoc', projFN, prodDB)
The json commands for setup of default schemas and tables are linked via the text file db_karttur_setup_YYYYMMDD.txt. It is under the directory regiondoc in the GeoImagine Framework GitHub repo for setup_processes. The json files are also available as web (html) documents, and linked under button.
You can skip individual json command files by setting a comment sign (‘#’) in front of the link to the json file.
If you want to create your own default regions for longitude-latitude coordinates, use the command file add_arbitrary_default_regions_v090.json as template. If you want to create a default region bounded by a continent or a country, you can instead use add_Africa-Sub_Sahara_default-region_v090.json as a template. Note that however you create a new default region, you have to give the correct default parent region as well as region category defined in the command file add_region_categories_v090.json.
Add region categories
The explained in the post on , the Framework spatial data are organized in projection and tiling systems. In additions there is also a hierarchical spatial system, ranging from the entire globe and down to a quarter or local domain. In addition there are two custom spatial scales that define a project: tract and site. A tract must be defined as being part of, or equal to, an existing default region of one of the default categories. A tract can thus be the entire globe or just a quarter or the even smaller domain. A tract can then be divided into any number of arbitrary sites, or just constitute a single site (that then equals the tract). The project file to the db add_region_categories_v090.json adds the default sptial categories to the Framework database.
Add global default regions
The project file add_arbitrary_default_regions_v090.json adds some arbitrary global default regions that might be useful. if you do not need these, just comment out the call to the project file. You can also use the project file as a template and define your own global, continental or national (etc) default regions.
Global default regions
The Framework comes with a set of global default regions, originally created from a 2014 dataset of global national countries. The dataset is generalised into the following spatial layers:
- countries
- continents
- continent-countries (transcontinental countries divided into continent parts)
- subcontinents
- land (all terrestrial land masses)
The same conglomeration of datasets are also available for countries including maritime regions.
Simplifying vector layers
The original layer of the global terrestrial political boundaries is a very high (~10 m) accuracy vector map. The original country map is large in size, too large to be stored for free with GitHub. The versions included in Karttur’s GitHub repo are thus simplified versions of the original. The terrestrial country maps (countries and continent-countries) are simplified using a tolerance of 100 m. With the continental and subcontinental maps using a tolerance of 1 km. The post Simplify vector lines and polygons explains how the simplification was done, and can be applied for other vector layers using the Framework itself.
As part of the simplification process also the validity of each polygon was tested and rectified if found erroneous. The copies available at Karttur’s GeoImagine Repo github should thus be free or errors. You should be able to import them without checking validity. The parameterisation fo the import process (OrganizeAncillary) is set to use the gdal utility ogr2ogr (set to true) and to include a checkfixvalidity (set to true).
# "process": [
{
"processid": "OrganizeAncillary",
"overwrite": false,
"verbose": 3,
"parameters": {
"importcode": "shp",
"epsg": "4326",
"orgid": "karttur",
"dsname": "globalROI",
"dsversion": "1.0",
"accessdate": "20170320",
"regionid": "globe",
"regioncat": "globe",
"dataurl": "",
"metaurl": "",
"title": "Global default regions",
"label": "Global default regions based on countries and continents",
"tolerance": 0.0086,
"checkfixvalidity": true
},
Add default regions
Once imported as ancillary vector layers, the countries, subcontinents and continents are added as default regions with the process DefaultRegionFromVector. The project file for that is add_default_regions_from-vector_v090.json. For each layer to import you have to state the fiels of the vector layer database that define the default region and its parent region.
Next step
The next step is adding MODIS tile regions and data access.