Introduction
The Landsat series of polar orbiting and sun-synchronous satellites have captured multi-spectral images of the Earth going back to 1972. Each acquired scene is approximately 180 x 180 km and positioned in a defined scene or tiling system, the Worldwide Reference System (WRS). To retrieve and organise Landsat data in Karttur’s GeoImagine Framework you need to setup Landsat WRS as a scene positioning system. This post explains how to do that.
Prerequisites
You must have installed Karttur’s GeoImagine Framework.
Systems and regions
In the Framework a system refers to a projection with predefined tiles (or scenes) that can be used for processing spatiotemporal datasets. As a legacy the original Landsat WRS (both version 1 for MultiSpectral Scanner [MSS] and version 2 for all later sensors) systems are included in the Framework. The Landsat system of the framework can only be used for processing Landsat images. To combine the Landsat data with other data you need to first translate the Landsat data to the more generic systems (e.g. MGRS, EASE2 grids or MODIS SIN-grid).
Import Landsat WRS
The Landsat series of satellites orbit the Earth at an angle of approximately 9 degrees compared to the longitudes and each scene is thus tilted compared to a north-south axis. The combined WRS systems, including both the [D]escending (daytime) and [A]scending (nighttime) paths of the satellites, contain approximately 120,000 scene positions. Importing the scene position layers and retrieving the corners of each scene position in longitude-latitude (WGS84) is fast and should just take a few minutes at the most. The vector polygons of the WRS scene positions that come with the Framework GitHub repo were prepared by using the Framework itself, and a specially written simplification algorithm as explained in the post Simplify vector lines and polygons.
Linking the individual scene positions to different default regions is a very time consuming process. Especially for large, global regions where the process includes testing every Landsat scene position against a very large (global) multipolygon vector. The rest of this post is thus divided into two parts; a first part that describes how to import a prepared version the complete Landsat dataset on WRS scene corners and links to default regions. This is done by simply importing the prepared database dumps that come with the Framework GitHub repo. The second part explains how the scene positions are linked from scratch using ordinary Framework processing.
Import Landsat database
The Framework GitHub repo comes with prepared text (.csv) and postgres (.sql) files where all the links between Landsat WRS and the Framework default regions are defined. You can thus simply run the Framework process CopyTableCsv or RestoreTableSQL to add the records defining all the links between Landsat WRS and the default regions. The commands for this are included in landsat_karttur_setup_YYYYMMDD.txt.
To run the database restoration from the package setup_processes just change variable Landsat to True under the defined functions SetupDefaultRegions
def SetupDefaultRegions(prodDB):
...
DefaultRegions = False
MODIS = False
EASE2 = False
Landsat = True
...
When you run the module, the Landsat linked scripts (defined in landsat_karttur_setup_YYYYMMDD.txt) will be executed.
if Landsat:
'''Link to project file that imports the Landsat WRS system'''
projFN = 'landsat_karttur_setup_20211108.txt'
SetupProcessesRegions('landsatdoc',projFN, prodDB)
The file landsat_karttur_setup_YYYYMMDD.txt links to a set of json command files that restores the Landsat database tables for scenecoords and regions. Inspect the processes by toggling the button and click on the linked json file names.
Link Landsat scenes to default regions
The prepared database dumps, used above to restore the Framework database, were originally created using the Framework process LinkDefaultRegionScenes. As noted above, the process takes a long time when a large number of scene positions (polygons) need to be tested for overlap vis-a-vis a large multipolygon (i.e. the landmass of the world). However, for smaller (default) regions LinkDefaultRegionScenes first extracts only the tiles falling inside the region boundary, and then the search for overlap is quicker. In addition, by setting the parameter defregmask (default region mask) to a parent (or grand-parent etc) region of the actual region(s) to link to scene positions, the overlap test is restricted even further. This is how the overlap between all default regions and the Landsat WRS positions is accomplished in the Framework.
LinkDefaultRegionScenes
The Framework process LinkDefaultRegionScenes has 15 parameters [default setting]:
- defregmask [“land”], default region for restricting scenes
- srcepsgL [4326], Csv list of source epsg to use for Linking
- regioncat, region category to link
- regionid, [“*”], specific region to link, (or "*" for all regions)
- checkfixvalidity [false], whether or not to control region vector validity
- ogr2ogr [false], wheter or not to use the gdal utility ogr2ogr or python scripting for reprojections
- cmdpath [None], operating system path to gdal executable, if required
- clipsrc [””], empty (default) or csv for source minx, miny, maxx, maxy
- clipdst [false], whether or not to clip scene search to default region extent
- wrapdateline [true], only applicable when projecting to Geographic coordinates
- onlyregionsfullywithinsystem [true], only link scenes to default regions fully within system boundaries
- onlytiling [false], do not reproject region, only find the overlapping scenes
- wrs [2], the wrs system to analyse (1 or 2)
- dir [‘D’], the path direction to analyse ([D]escending or [A]scending)
- minarea [0], minimum overlap area of region and scene for linking
The naming of the output layers from the processes are defaulted, and you do not need to explicitly give any “dstcomp” (destination compositions) when running LinkDefaultRegionScenes. However, as each default region (e.g. africa) is associated with four (4) different Landsat WRS scene systems:
- WRS 1 ascending
- WRS 1 descending
- WRS 2 ascending
- WRS 2 descending
you should explicitly state the output layers for the tiles (but keep the region the same). For processes that require more than a single source (src) or destination (dst) layer, you have to give the correct id for each layer in the json commands. LinkDefaultRegionScenes then generates two output layers for each input:
- region (the reprojected default region)
- tiles (the tiles or scenes covering the region in the system projection)
Thus the command to link Landsat WRS 2 Descending (daytime) scenes to all continental regions becomes:
{
"userproject": {
"userid": "karttur",
"projectid": "karttur",
"tractid": "karttur",
"siteid": "*",
"plotid": "*",
"system": "landsat"
},
"period": {
"startyear": 2014,
"endyear": 2014,
"timestep": "singleyear"
},
"process": [
{
"processid": "LinkDefaultRegionScenes",
"overwrite": false,
"version": "0.9",
"verbose": 2,
"parameters": {
"defregmask": "land",
"regioncat": "continent",
"dir": "D",
"wrs": 2,
"ogr2ogr": true,
"cmdpath": "/usr/local/bin",
"clipsrc": "-180,0,180,90",
"onlytiling": false,
"minarea": 0
},
"srcpath": {
"volume": "GeoImg2021",
"hdr": "shp",
"dat": "shp"
},
"dstpath": {
"volume": "GeoImg2021",
"hdr": "shp",
"dat": "shp"
},
"srccomp": [
{
"regions": {
"source": "karttur",
"product": "karttur",
"content": "roi",
"layerid": "defreg",
"prefix": "defreg",
"suffix": "tol@1km"
}
}
],
"dstcomp": [
{
"region": {
"source": "karttur",
"product": "karttur",
"content": "roi",
"layerid": "defreg",
"prefix": "defreg",
"suffix": "tol@1km"
},
"tiles": {
"source": "karttur",
"product": "karttur",
"content": "roi",
"layerid": "tiles",
"prefix": "tiles-wrs2-D",
"suffix": "0"
}
}
]
}
]
}
Note that the parameter defregmask is set to land. For this to work you must start the processing chain by actually linking the global landmass to the approximately 30000 Landsat scenes defined in WRS 2 descending (daytime). This is thus the first process in the chain outlined in the next section. Note also how the file name prefix of the tiles destination composition (dstcomp) is set ot tiles-wrs2-D, while the layerid is just tiles. You can check the settings for producing all the other WRS tiles under the next section or in te GitHub repo.
Process chain
The process chain for setting up the Landsat WRS scene positions and linking them to the default regions are in the file landsat_karttur_setup-from-scratch_20211108.txt. Inspect the processes by toggling the button and click on the linked json file names.
If you want to run the above commands you have to replace the default linked file (landsat_karttur_setup_YYYYMMDD.txt) and replace it with landsat_karttur_setup-from-scratch_YYYYMMDD.txt, in the python script.
if Landsat:
'''Link to project file that imports the Landsat WRS system'''
projFN = 'landsat_karttur_setup-from-scratch_20211108.txt'
SetupProcessesRegions('landsatdoc',projFN, prodDB)