API Reference

jaxa.earth.je module

This API package for Python has developed to utillize various Earth observation data held by JAXA. By using this API, you can easily acquire and process data without worrying about the specifications, sensors, resolution, etc. of each satellite data.

je module contains four classes : FeatureCollection, ImageCollectionList, ImageCollection, ImageProcess.

# Usage example

# Import module
from jaxa.earth import je

# Read geojson
geoj_path = "gadm36_JPN_0.geojson"
geoj = je.FeatureCollection().read(geoj_path).select([])

# Get images
data_out = je.ImageCollection("JAXA.EORC_ALOS.PRISM_AW3D30.v3.2_global")\
             .filter_date(["2021-01-01T00:00:00","2022-01-01T00:00:00"])\
             .filter_resolution(20)\
             .filter_bounds(geoj[0])\
             .select("DSM")\
             .get_images()

# Process and show images
img = je.ImageProcess(data_out)\
        .show_images()\
        .calc_spatial_stats()\
        .show_spatial_stats()
class jaxa.earth.je.FeatureCollection

Bases: object

The FeatureCollection class is used to read a feature collection and select features of geojson data from your computer.

Returns:

A FeatureCollection class object which has a properry of feature_collection. the object’s properties are set to None by default.

feature_collection

The property is updated after the method read is executed. The default value is None.

Type:

dict

# Usage example: Aquire feature collection data
geoj_path = "C:\MyData\gadm36_JPN_1.geojson"
geoj = je.FeatureCollection().read(geoj_path).select(["Tokyo"])
read(path: str)

The method read reads the inputed path’s geojson data as feature collection.

Parameters:

path (str) – The absolute path to the user’s geojson location.

Returns:

A FeatureCollection class object that stores updated feature_collection property

# Usage example: Read geojson data as feature collection
data_path = "C:\MyData\MyArea.geojson"
data_fc   = je.FeatureCollection.read(data_path)
select(keywords: list = [])

The method select filter the inputed feature collection’s data in properties by keywords. The default is blank list, so all features of feature collection are selected.

Parameters:

keywords (list) – keywords list of your preferred words.

Returns:

geojson features selected by keywords

# Usage example: Select feature from geojson's feature collection
geojson = data_fc.select(["Japan","Tokyo"])
class jaxa.earth.je.ImageCollection(collection: str = None, stac_cog_url: str = None, ssl_verify: bool = None)

Bases: object

The class, ImageCollection gets selected collection’s catalog json data from JAXA Earth database. When you use the class’s method, you can acquire collection’s raster images depending on query such as date limit, resolution, bounds and band.

Parameters:

  • collection (str) – Name of the selected collection. If not specified, “JAXA.EORC_ALOS.PRISM_AW3D30.v3.2_global” is used.

  • stac_cog_url (str) – Users can set valid stac cog url to stac_cog_url.

  • ssl_verify (bool) –

    Users can set valid ssl certification process to True or False. The default is True.

    Note

    Setting the value to False can be a security risk.

Returns:

An ImageCollection class object which has properties of stac_date, stac_ppu , stac_bounds , stac_band and raster. All properties of the object are set to Noe by default.

stac_date

The default value is None. The updated property is set after the method, filter_date. The updated property has four properties such as query , url , id and json. The object is used as input to the method filter_resolution.

Type:

A Stac class object

stac_ppu

The default value is None. The updated property is set after the method, filter_resolution. The updated property has three properties such as query , url and json. The object is used as input to the method filter_bounds.

Type:

A Stac class object

stac_bounds

The default value is None. The updated property is set after the method, filter_bounds. The updated property has three properties such as query , url and json. The object is used as input to the method select.

Type:

A Stac class object

stac_band

The default value is None. The updated property is set after the method, select. The updated property has two properties such as query and url. The object is used as input to the method get_images.

Type:

A Stac class object

raster

The default value is None. The updated property is set after the method, get_images. The updated Raster class object property has properties of img , latlim and lonlim.

Type:

A Raster class object

# Usage example: Get image
data_out = je.ImageCollection("JAXA.EORC_ALOS.PRISM_AW3D30.v3.2_global")\
             .filter_date(["2021-01-01T00:00:00","2023-01-31T00:00:00"])\
             .filter_resolution(20)\
             .filter_bounds([-180,-90,180,90])\
             .select("DSM")\
             .get_images()
filter_bounds(bbox: list = None, geoj: dict = None)

The method, filter_bounds filters collection’s catalog json by the user query of bounds or geojson. If you input both of bbox and geoj, geoj is used to detect bounding box. If you don’t input neither of them, maximum bounding box is selected. In QGIS environment, appropriate area is selected with no input. The property of stac_bounds is updated after the method.

Parameters:

  • bbox (list) – bounding box input.

  • geoj (dict) – geojson input

Returns:

An ImageCollection class object that stores updated stac_bounds property

Note

Attention! You have to use method filter_resolution before the method.

# Usage example: Filter ImageCollection by bbox of geojson
bbox = [120,20,150,50]
data_ic3 = data_ic2.filter_bounds(bbox)
filter_date(dlim: list = [])

The method, filter_date filters collection’s catalog json by the user query of date limit. If no input is given, default date lim parameter is set as [“2021-01-01T00:00:00”,”2021-12-31T23:59:59”]. The property of stac_date is updated after the method.

Parameters:

date_lim (list) – date limits of minimum date, maximum date.

Returns:

An ImageCollection class object that stores updated stac_date property

Note

If normal products are specified for multiple years, the same products is returned for multiple years .

# Usage example: Filter ImageCollection by date limit
date_lim = ["2021-01-01T00:00:00","2022-01-01T00:00:00"]
data_ic1 = data_ic0.filter_date(date_lim)
filter_resolution(ppu: float = None)

The method, filter_resolution filters collection’s catalog json by the user query of resolution of ppu (Pixels Per Unit). Unit means one degree in epsg 4326, 32786m in epsg 3995. If no input is given, minimum value or appropriate value (in QGIS only) is set. The property of stac_ppu is updated after the method.

Parameters:

ppu (float) – ppu input.

Returns:

An ImageCollection class object that stores updated stac_ppu property

Note

Attention! You have to use method filter_date before the method.

# Usage example: Filter ImageCollection by ppu
ppu = 20
data_ic2 = data_ic1.filter_resolution(ppu)
get_images()

The method, get_images gets collection’s images depending on the user’s queries of date limit, resolution, bounds and band. The property of raster will be updated after the method. In addition to this, region of interest area of raster images will be returned.

Returns:

An ImageCollection class object that stores updated raster property

Note

Attention! You have to use method filter_band before the method.

# Usage example: Get Image depend on user's query.
data_out0 = data_ic4.get_images()
select(band: str = None)

The method, select selects collection’s catalog json by the user query of band. If you don’t input band, the first band is selected. Property of stac_band will be updated after the method.

Parameters:

band (str) – band of asset

Returns:

An ImageCollection class object that stores updated stac_band property

Note

Attention! You have to use method filter_bounds before the method.

# Usage example: Filter ImageCollection by band
band = "DSM"
data_ic4 = data_ic3.filter_band(band)
class jaxa.earth.je.ImageCollectionList(ssl_verify: bool = None)

Bases: object

The class, ImageCollectionList gets and filters collection’s catalog json depending on user input keywords.

Parameters:

ssl_verify (bool) –

Users can set valid ssl certification process to True or False. The default is True.

Note

Setting the value to False can be a security risk.

Returns:

An ImageCollectionList class object which has properties of stac_collections.

# Usage example: Get collection's name and band
keywords = ["LST","_half-month"]
collections,bands = je.ImageCollectionList(ssl_verify=False)\
                      .filter_name(keywords=keywords)
filter_name(keywords: list = [])

The method, filter_name filter collection’s catalog json from collection’s id depending on user input keywords.

Parameters:

keywords (list) – keywords of request.

Returns:

filtered collections and filtered bands

# Usage example: Get collection's name and band
key = ["LST","_half-month"]
collections,bands = je.ImageCollectionList()\
                      .filter_name(keywords=key)
class jaxa.earth.je.ImageProcess(data)

Bases: object

The class, ImageProcess execute various process by using inputed ImageCollecion class objects. When you use ImageProcess class method, you can process and get images such as masking images, differential images and calculated temporal/spatial statistics. In addition to the processing, it’s possible to show images or timeseries graph.

Parameters:

data (object) –

ImageCollection class object which contains updated raster property

Note

Attention! ImageCollection class object must have correct raster property.

Returns:

An ImageProcess class object with updated property

raster

The default value is same as inputed ImageCollection class object’s raster property. The property is updated after executing methods of the ImageProcess class object, such as mask_images , diff_images and calc_temporal_stats.

Type:

A Raster class object

timeseries

The default value is None. The property is updated after executing methods of the ImageProcess class object, such as calc_spatial_stats. The updated property has five keys and values such as “mean”, “std”, “min”, “max” and “median”.

Type:

dict

# Usage example: Process and show images
img = je.ImageProcess(data_out0)\
        .show_images()\
        .calc_spatial_stats()\
        .show_spatial_stats()
calc_spatial_stats()

The method, calc_spatial_stats calculate spatial statistics.

Returns:

An ImageProcess class object that stores updated timeseries property. The updated property has five keys and values such as “mean”, “std”, “min”, “max” and “median”.

# Usage example: Calculate spatial stats of data_ip0
data_s_stats = data_ip0.calc_spatial_stats()
calc_temporal_stats(method_query: str = 'mean')

The method, calc_temporal_stats calculate temporal statistics by user inputed query of method_query.

Parameters:

method_query (dict) – “mean” or “max” or “min” or “std” or “median”. The default is “mean”.

Returns:

An ImageProcess class object that stores the updated raster property

# Usage example: Calculate temporal stats of data_ip0
data_t_stats = data_ip0.calc_temporal_stats("mean")
diff_images(ref)

The method, diff_images take difference by user inputed query of ref.

Parameters:

ref (object) –

ImageCollection class object that has updated raster property which is used as ref data.

Note

Attention! The shape of th ref (including resolution) must be the same as the data.

Returns:

An ImageProcess class object that stores the updated raster property

# Usage example: Differential data(data_out0-data_out1)
data_diff = data_ip0.diff_images(data_out1)
mask_images(mask, method_query: str = 'values_equal', values: float = [0, 1])

The method, mask_images masks by using mask, type_query and values.

Parameters:

  • mask (class) –

    ImageCollection class object that has updated raster property which is used as masking data.

    Note

    Attention! The shape of the mask (including resolution) must be the same as the data.

  • method_query (dict) –

    “range” or “values_equal” or “bits_equal”. The default method is “values_equal”.

    ”range” is used when users would like to extract a specific range of values and mask values outside the range. The data type of float is acceptable as a “range” mask.

    ”values_equal” is used when users would like to extract only certain bit values of pixels and mask other bit values of pixels. The data type of float is acceptable. Typically, land cover products is used as “values_equal” mask.

    ”bits_equal” is used when users would like to extract only certain values of pixels and mask other bit values of pixels. The data type of float is not acceptable as a mask. Typically, quality assurance products is used as a “bits_equal” mask.

  • values (list) – user query of values list. if you set type_query as “range”, please set two values, minimum and maximum. If “values_equal”, you can set multiple values list as you like. If “bits_equal”, you can set bit values 0 or 1 as bit values which begins from zero bit. The default value is [0,1].

Returns:

An ImageProcess class object that stores the updated raster property

# Usage example: Mask data_out0 by data_out1
data_masked = data_ip0.mask_images(data_out1,"range",[0,100])
show_images(cmap: str = None, clim: list = [])

The method, show_images shows images of raster property. If multiple date’s image is set, the method shows all of the images.

Parameters:

  • cmap (str) – query of colormap name. User can choose “ndvi”,”turbo” and “spectral”. The default is “turbo”.

  • clim (list) – query of color range (optional).

Returns:

An ImageProcess class object

# Usage example: Show images of data_ip0
data_ip0.show_images()
show_images_qgis(cmap: str = None, clim: list = [])

The method, show_images_qgis shows images in qgis.

Parameters:

  • cmap (str) – query of colormap name. User can choose “ndvi”,”turbo” and “spectral”. Default is “turbo”.

  • clim (list) – query of color range (optional).

Returns:

An ImageProcess class object

Note

Attention! This method is only valid in QGIS environment.

# Usage example: Show images of data_ip0 in qgis
data_ip0.show_images_qgis()
show_spatial_stats(ylim: list = [])

The method, show_spatial_stats shows graph of calculation result of the method calc_spatial_stats.

Parameters:

ylim (list) – query of color range (optional)

Returns:

An ImageProcess class object

Note

Attention! You should use the method calc_spatial_stats before the method.

# Usage example: Show graph of calclation result of the method calc_spatial_stats
data_s_stats.show_spatial_stats()