STAC

Documentation for STAC, a Julia client implementation of the SpatioTemporal Asset Catalogs.

STAC catalog

STAC.Catalog — Type

cat = STAC.Catalog(url; limit = 1000)

Open a SpatioTemporal Asset Catalog (STAC) using the provided url. The url should point to a JSON object conforming to the STAC specification. limit indicates default number of items to be return in a single search request.

cat behaves as a julia dictionary with all STAC subcatalogs. cat.items is a dictionary with all STAC items.

using STAC
url = "https://raw.githubusercontent.com/sat-utils/sat-stac/master/test/catalog/catalog.json"
cat = STAC.Catalog(url)
subcat = cat["stac-catalog-eo"]
subcat1 = subcat["landsat-8-l1"]
@show subcat1

item = subcat1.items["LC08_L1TP_152038_20200611_20200611_01_RT"]
@show href(item.assets["B4"])

source

Base.keys — Method

child_ids = keys(cat::Catalog)
subcat = cat[child_id]

Returns all subcatalog identifiers of the STAC catalog cat.

url = "https://raw.githubusercontent.com/sat-utils/sat-stac/master/test/catalog/catalog.json"
cat = STAC.Catalog(url);
keys(cat)

source

Base.getindex — Method

subcat = getindex(cat::Catalog,child_id::AbstractString)
subcat = cat[child_id]

Returns the subcatalogs with the identifier child_id

url = "https://raw.githubusercontent.com/sat-utils/sat-stac/master/test/catalog/catalog.json"
cat = STAC.Catalog(url);
subcat = cat["stac-catalog-eo"]

source

STAC.eachcatalog — Method

cats = eachcatalog(catalog::Catalog)

Returns resursively all subcatalogs in catalog. This can take a long time for deeply nested catalogs.

url = "https://raw.githubusercontent.com/sat-utils/sat-stac/master/test/catalog/catalog.json"

cat = STAC.Catalog(url)
for c in eachcatalog(cat)
    @show id(c)
end

source

STAC.eachitem — Method

cats = eachitem(catalog::Catalog)

Returns resursively all items in catalog. This can take a long time for deeply nested catalogs.

url = "https://raw.githubusercontent.com/sat-utils/sat-stac/master/test/catalog/catalog.json"

cat = STAC.Catalog(url)
for c in eachitem(cat)
    @show id(c)
end

source

STAC.search — Function

search(cat::Catalog, collections, lon_range, lat_range, datetime;
       limit = 100,
       filter = nothing,
       query = nothing,
)

Search items in a STAC.Catalog cat belong to the collections within the longitude range lon_range (start and end longitude), latitude range lat_range, and time range (start and end DateTime).

The optional filter parameter allows to filter the resuts using CQL2 (see example below). STACQL is also supported via the optional query parameter. It is recommended to use CQL2 instead of STACQL. This filter and query are experimental and currently only part of the STAC as a "candiate" or "pilot".

The function search returns an julia Channel with the search results over which one can only iterate once. If the results should be saved use search_results = collect(search(cat,...)).

Example:

using STAC, Dates
collections = ["landsat-8-c2-l2"]
time_range = (DateTime(2018,01,01), DateTime(2018,01,02))
lon_range = (2.51357303225, 6.15665815596)
lat_range = (49.5294835476, 51.4750237087)

catalog = STAC.Catalog("https://planetarycomputer.microsoft.com/api/stac/v1")

search_results = collect(search(catalog, collections, lon_range, lat_range, time_range))

Example with additional CQL2 filter

filter = Dict(
   "op" => "<=",
   "args" => [Dict("property" => "eo:cloud_cover"), 61]
)

search_results = collect(
        search(cat, collections,
               lon_range, lat_range, time_range,
               filter = filter,
))

Currently only POST search requests are supported.

source

STAC.type — Method

data = type(cat::Catalog; default = nothing)

Get the type of a STAC catalog (or default if it is not specified).

source

STAC.stac_version — Method

data = stac_version(cat::Catalog; default = nothing)

Get the stac version of a STAC catalog (or default if it is not specified).

source

STAC.stac_extensions — Method

data = stac_extensions(cat::Catalog; default = nothing)

Get the stac extensions of a STAC catalog (or default if it is not specified).

source

STAC.id — Method

data = id(cat::Catalog; default = nothing)

Get the identifier of a STAC catalog (or default if it is not specified).

source

STAC.title — Method

data = title(cat::Catalog; default = nothing)

Get the title of a STAC catalog (or default if it is not specified).

source

STAC.description — Method

data = description(cat::Catalog; default = nothing)

Get the description of a STAC catalog (or default if it is not specified).

source

STAC.keywords — Method

data = keywords(cat::Catalog; default = nothing)

Get the keywords of a STAC catalog (or default if it is not specified).

source

STAC.license — Method

data = license(cat::Catalog; default = nothing)

Get the license of a STAC catalog (or default if it is not specified).

source

STAC.providers — Method

data = providers(cat::Catalog; default = nothing)

Get the providers of a STAC catalog (or default if it is not specified).

source

STAC.extent — Method

data = extent(cat::Catalog; default = nothing)

Get the extent of a STAC catalog (or default if it is not specified).

source

STAC.summaries — Method

data = summaries(cat::Catalog; default = nothing)

Get the summaries of a STAC catalog (or default if it is not specified).

source

STAC.doi — Method

data = doi(cat::Catalog; default = nothing)

Get the doi of a STAC catalog (or default if it is not specified).

source

STAC item

STAC.id — Method

 data = id(item)

Get the identifier of STAC item.

source

STAC.bbox — Method

 data = bbox(item)

Get the bounding box of STAC item.

source

STAC.links — Method

 data = links(item)

Get the links of STAC item.

source

STAC.properties — Method

 data = properties(item)

Get the properties of STAC item.

source

Dates.DateTime — Method

dt = DateTime(item)

Get the date time of STAC item as a Dates.DateTime (or nothing if this properties is not specified). Get the start date time if the item has a timespan instead.

source

GeoJSON.geometry — Method

data = geometry(item)

Get the geometry of STAC item as a GeoJSON object

source

STAC asset

STAC.href — Method

 data = href(asset; default = nothing)

Get the URI of a STAC asset (or default if it is not specified).

source

STAC.title — Method

 data = title(asset; default = nothing)

Get the title of a STAC asset (or default if it is not specified).

source

STAC.description — Method

 data = description(asset; default = nothing)

Get the description of a STAC asset (or default if it is not specified).

source

STAC.type — Method

 data = type(asset; default = nothing)

Get the type of a STAC asset (or default if it is not specified).

source

Cache

STAC.set_cache_max_size — Function

STAC.set_cache_max_size(cache_max_size::Integer)

Set the maximum number of URLs saved in cache (permanentaly). The default is 1000.

source

STAC.empty_cache — Method

STAC.empty_cache()

Empty the URL cache.

source

Customize

The color scheme used of the STAC client can be customized by the following functions:

STAC.set_catalog_color — Function

    STAC.set_catalog_color(color::Symbol)

Set the catalog color. The default color is Base.info_color(). The color is saved using Preferences.jl.

source

STAC.set_asset_color — Function

    STAC.set_asset_color(color::Symbol)

Set the asset color. The default color is Base.info_color(). The color is saved using Preferences.jl.

source

STAC.set_item_color — Function

    STAC.set_item_color(color::Symbol)

Set the item color. The default color is Base.info_color(). The color is saved using Preferences.jl.

source

STAC.set_title_color — Function

    STAC.set_title_color(color::Symbol)

Set the title color. The default color is Base.error_color(). The color is saved using Preferences.jl.

source