Commit 74e323ed authored by Cresson Remi's avatar Cresson Remi
Browse files

DOC: update doc

parent 67b54060
Pipeline #36199 passed with stages
in 5 minutes and 30 seconds
......@@ -2,7 +2,7 @@
theme:
name: "material"
icon:
repo: material/github
repo: fontawesome/brands/gitlab
features:
- content.code.annotate
- navigation.tabs
......@@ -30,7 +30,7 @@ extra:
feature:
tabs: true
social:
- icon: material/gitlab
- icon: fontawesome/brands/gitlab
link: https://gitlab.irstea.fr/umr-tetis/scenes
markdown_extensions:
......@@ -50,5 +50,6 @@ markdown_extensions:
# rest of the navigation..
site_name: Scenes
repo_url: https://gitlab.irstea.fr/umr-tetis/scenes
repo_name: umr-tetis/scenes
docs_dir: doc/
......@@ -5,12 +5,11 @@ This module aims to deal with dates.
---
The `datetime.datetime` class is used as internal date type.
```
#!python
``` py
dt = datetime.datetime(year=2020, month=12, day=2)
```
Is equivalent to:
```
``` py
dt = str2datetime("02-12-2020")
dt = str2datetime("2020-12-02")
dt = str2datetime("02/12/2020")
......@@ -18,7 +17,7 @@ dt = str2datetime("02/12/2020")
The `any2datetime` method returns a `datetime.datetime` instance, whatever the input is (`str` or
`datetime.datetime`).
```
``` py
dt1 = datetime.datetime(year=2020, month=12, day=2)
dt2 = str2datetime("02-12-2020")
dt1_2 = any2datetime(dt1) # same
......@@ -26,7 +25,7 @@ dt2_2 = any2datetime("02-12-2020") # same
```
The `get_timestamp` method converts a `datetime.datetime` instance into a number of seconds (int).
```
``` py
ts = get_timestamp(dt) # 1606780800.0
```
"""
......
"""
This module provides tools to easily interact with deep learning models.
OTBTF is needed to use this module.
---
# Super-resolution
## Super-resolution
The SR4RS model can be applied over any `scenes.core.Source` instance.
We recall that this model is intended to be used over Sentinel-2 optical images.
For example, here is how we perform the super-resolution of a Theia S2 product.
```
#!python
``` py
import scenes
archive = "SENTINEL2B_..._T31TEJ_D_V1-8.zip"
s2_scene = scenes.sentinel.Sentinel22AScene(archive)
......
......@@ -14,45 +14,44 @@ password_theia = thisisnotmyrealpassword
```
To instantiate the `scenes.download.TheiaDownloader`:
```
#!python
``` py
import scenes
cfg_file = "config.txt" # Theia config file
theia = scenes.download.TheiaDownloader(cfg_file)
```
# Bounding box + temporal range
## Bounding box + temporal range
The following example shows how to use the `scenes.download.TheiaDownloader` to search
or download all Sentinel-2 images in a bounding box within a temporal range.
## Search
### Search
When the `download_dir` is not set, the download is not performed, and only the search results
are returned from the function.
```
``` py
bbox = scenes.spatial.BoundingBox(43.706, 43.708, 4.317, 4.420)
trange = ("01/01/2020", "O1/O1/2022")
results = theia.download_in_range(bbox, trange, level="LEVEL2A")
print(results)
```
## Download
### Download
To download the files, the `download_dir` must be specified:
```
``` py
theia.download_in_range(bbox, trange, "/tmp/download/", "LEVEL2A")
```
When files already exist, the md5sum is computed and compared with the one in the catalog,
in order to determine if it has to be downloaded again. If the file is already downloaded and
is complete according to the md5sum, its download is skipped.
# Bounding box + single date
## Bounding box + single date
In the same manner, the downloader can search or download the closest images from a specific date.
The returned dict from the function is updated with a "delta" key storing the value of the number of
days from the specific date.
```
``` py
# For searching only
results = theia.download_in_range(bbox, trange, "LEVEL2A")
......
......@@ -7,37 +7,36 @@ The `scenes.indexation.Index` uses an R-Tree to perform the indexation of object
Example: spatio-temporal indexation of multiple `scenes.core.Scene` instances.
# Build a spatio temporal index
## Build a spatio temporal index
```
#!python
``` py
import scenes
scenes_list = [...] # a list of various `scenes.core.Scene` instances.
index = scenes.indexation.Index(scenes_list) # build the index
```
# Search from a `BoundingBox`
## Search from a `BoundingBox`
The `find_indices()` method returns the indices of the indexed `scenes.core.Scene` instances matching
the query.
The `find()` method returns the indexed `scenes.core.Scene` instances matching the query.
```
``` py
bbox = BoundingBox(43.706, 43.708, 4.317, 4.420)
indices_results = index.find_indices(bbox) # spatial query returning scenes indices
scenes_results = index.find(bbox) # spatial query returning scenes instances
```
# Spatio-temporal search
## Spatio-temporal search
A date min and/or a date max can be added in the query.
```
``` py
scenes_results = index.find(bbox, "01/01/2020" "01/01/2022")
```
# Search from a vector data file
## Search from a vector data file
The search can also be performed with a vector data file.
```
``` py
vec = "/path/to/vector.gpkg"
scenes_results = index.find(vec, "01/01/2020" "01/01/2022")
```
......
......@@ -3,34 +3,115 @@ This module contains Sentinel-2 classes (sources and scenes).
Right now everything is ready to use THEIA L2A and L3A products.
# Scene
## `Scene` based classes
The `Sentinel22AScene` and `Sentinel23AScene` classes carry metadata and sources
respectively for Sentinel-2 Level 2A and Level 3A products. They both inherit from
the generic abstract `Sentinel2SceneBase` class.
the generic abstract `Sentinel2SceneBase` class, which itself inherits from `Scene`.
``` mermaid
classDiagram
Scene <|-- Sentinel2SceneBase
Sentinel2SceneBase <|-- Sentinel22AScene
Sentinel2SceneBase <|-- Sentinel23AScene
class Scene{
+datetime acquisition_date
+int epsg
+bbox_wgs84
+get_metadata()
+__repr__()
}
class Sentinel2SceneBase{
+__init__(archive, tag)
+get_file()
+get_band()
+get_metadata()
+Sentinel2Source get_10m_bands()
+Sentinel2Source get_20m_bands()
}
class Sentinel22AScene{
+__init__(archive)
+str clm_r1_msk_file
+str clm_r2_msk_file
+str edg_r1_msk_file
+str edg_r2_msk_file
+get_metadata()
}
class Sentinel23AScene{
+__init__(archive)
+str flg_r1_msk_file
+str flg_r2_msk_file
+get_metadata()
}
```
## Instantiation
### Instantiation
`Sentinel22AScene` and `Sentinel23AScene` are instantiated from the archive (.zip file)
or the product folder.
```
#!python
``` py
import scenes
sc_2a = scenes.sentinel.Sentinel22AScene("SENTINEL2B_..._T31TEJ_D_V1-8.zip")
sc_3a = scenes.sentinel.Sentinel23AScene("SENTINEL2X_...L3A_T31TEJ_D_V1-0.zip")
```
## Metadata
### Metadata
The scene metadata can be accessed with the `get_metadata()` method, like any
`scenes.core.Scene` instance.
```
``` py
md_dict = sc_2a.get_metadata()
for key, value in md_dict.items():
print(f"{key}: {value}")
```
## Sources
## `Source` based classes
The `Sentinel22ASource` and `Sentinel23ASource` classes carry imagery sources
respectively for Sentinel-2 Level 2A and Level 3A products. They both inherit from
the generic `Sentinel2Source` class, which itself inherits from `Source`.
``` mermaid
classDiagram
Source <|-- Sentinel2Source
Sentinel2Source <|-- Sentinel22ASource
Sentinel2Source <|-- Sentinel23ASource
class Source{
+__init__(root_scene, out, parent=None)
+Scene root_scene
+Source parent
+Source drilled(msk_vec_file, nodata=0)
+Source cld_msk_drilled(nodata=0)
+Source resample_over(ref_img, interpolator="nn", nodata=0)
+Source clip_over_img(ref_img)
+Source clip_over_vec(ref_vec)
+Source new_source(*args)
}
class Sentinel2Source{
+R1_SIZE
+R2_SIZE
+Sentinel2Source msk_drilled(msk_dict, exp, nodata=0)
}
class Sentinel22ASource{
+Sentinel22ASource cld_msk_drilled(nodata=0)
}
class Sentinel23ASource{
+Sentinel23ASource flg_msk_drilled(keep_flags_values=(3, 4), nodata=0)
}
```
The sources carry the following images for Level 2 and Level 3 products:
- The 10m spacing channels, in the following order: 4, 3, 2, 8
- The 20m spacing channels, in the following order: 5, 6, 7, 8a, 11, 12
......@@ -48,14 +129,14 @@ no-data value (default is 0).
The following example show how to derive a child source replacing the
pixels that are in the clouds with pixels at -10000 (which is the no-data
value in Theia products):
```
``` py
drilled = bands_10m_2a.cld_msk_drilled()
```
The `Sentinel23ASource` implements the `Sentinel23ASource.flg_msk_drilled` method, that
enable to mask the pixels on a selection of labels of the quality mask.
The following example shows how to mask pixels of anything other that land with -10000:
```
``` py
drilled = bands_10m_3a.flg_msk_drilled(keep_flags_values=(4,))
```
......@@ -63,7 +144,7 @@ drilled = bands_10m_3a.flg_msk_drilled(keep_flags_values=(4,))
hence implemented sources transformations (e.g. `scenes.core.Source.masked`,
`scenes.core.Source.clip_over_img`, `scenes.core.Source.resample_over`,
`scenes.core.Source.reproject`, etc.
```
``` py
clipped = drilled.clip_over_img(roi)
reprojected = clipped.reproject(epsg=4328)
```
......@@ -71,11 +152,11 @@ Note that the resulting transformed `Sentinel22ASource` and `Sentinel23ASource`
instances of `Sentinel22ASource` and `Sentinel23ASource` even after generic operations
implemented in `scenes.core.Source`.
# Usage with pyotb
## Usage with pyotb
As `scenes.core.Source`, it also can be used like any `pyotb.core.otbObject`.
The following example show how to use an OTB application with a source at input.
```
``` py
rgb_nice = pyotb.DynamicConvert(reprojected)
rgb_nice.write("image.tif", pixel_type="uint8")
```
......
......@@ -5,15 +5,41 @@ for Spot 6/7 products.
---
# Scene
# `Scene` based class
The `Spot67Scene` class carries metadata and image sources for Spot-6/7 sensors.
``` mermaid
classDiagram
Scene <|-- Spot67Scene
class Scene{
+datetime acquisition_date
+int epsg
+bbox_wgs84
+get_metadata()
+__repr__()
}
class Spot67Scene{
+float azimuth_angle
+float azimuth_angle_across
+float azimuth_angle_along
+float incidence_angle
+float sun_azimuth_angle
+float sun_elev_angle
+get_metadata()
+Spot67Source get_xs()
+Spot67Source get_pan()
+Spot67Source get_pxs()
}
```
## Instantiation
A `Spot67Scene` is instantiated from the .XML DIMAP files of PAN and XS:
```
#!python
``` py
import scenes
sc = scenes.spot.Spot67Scene(dimap_file_xs="DIM_SPOT6_MS..._1.XML",
dimap_file_pan="DIM_SPOT6_P..._1.XML")
......@@ -23,7 +49,7 @@ sc = scenes.spot.Spot67Scene(dimap_file_xs="DIM_SPOT6_MS..._1.XML",
The scene metadata can be accessed with the `get_metadata()` method, like any
`scenes.core.Scene` instance.
```
``` py
md_dict = sc.get_metadata()
for key, value in md_dict.items():
print(f"{key}: {value}")
......@@ -31,14 +57,39 @@ for key, value in md_dict.items():
## Sources
The `Spot67Source` is the class for the different Spot-6/7 sources.
``` mermaid
classDiagram
Source <|-- Spot67Source
class Source{
+__init__(root_scene, out, parent=None)
+Scene root_scene
+Source parent
+Source drilled(msk_vec_file, nodata=0)
+Source cld_msk_drilled(nodata=0)
+Source resample_over(ref_img, interpolator="nn", nodata=0)
+Source clip_over_img(ref_img)
+Source clip_over_vec(ref_vec)
+Source new_source(*args)
}
class Spot67Source{
+Spot67Source cld_msk_drilled(nodata=0)
}
```
### Different sources
The `Spot67Scene` delivers three kind of `Spot67Source` instances:
The `Spot67Scene` delivers three `Spot67Source` instances:
- The multispectral image (xs)
- The Panchromatic image (pan)
- The pansharpenend image (pxs)
```
``` py
xs = sc.get_xs()
pan = sc.get_pan()
pxs = sc.get_pxs(method="bayes")
......@@ -53,7 +104,7 @@ Three level of radiometry are available for Spot-6/7 images:
- TOA (Top Of Atmosphere)
- TOC (Top Of Canopy)
```
``` py
p_dn = sc.get_pan()
xs_toa = sc.get_xs(reflectance="toa")
pxs_toc = sc.get_pxs(reflectance="toc")
......@@ -64,14 +115,14 @@ enable to mask the cloud masks over the root source, with the specified
no-data value (default is 0).
The following example show how to derive a child source replacing the
pixels that are in the clouds with zero-valued pixels:
```
``` py
pxs_drilled = pxs.cld_msk_drilled()
```
The `Spot67Source` inherits from `scenes.core.Source`, hence implemented
sources transformations (e.g. `scenes.core.Source.masked()`, `scenes.core.Source.clip_over_img()`,
`scenes.core.Source.resample_over()`, `scenes.core.Source.reproject()`, etc.
```
``` py
clipped = pxs_drilled.clip_over_img(roi)
reprojected = clipped.reproject(epsg=4328)
```
......@@ -82,7 +133,7 @@ Note that the resulting transformed `Spot67Source` is still an instance of
As `scenes.core.Source`, it also can be used like any `pyotb.core.otbObject`.
The following example show how to use an OTB application with a source at input.
```
``` py
rgb_nice = pyotb.DynamicConvert(reprojected)
rgb_nice.write("image.tif", pixel_type="uint8")
```
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment