bdc_catalog.models

SQLAlchemy model classes for BDC-Catalog.

class bdc_catalog.models.Band(**kwargs)

Model for spectral bands and derived indices (table bdc.band).

A band consists in description of the matrix band values and data storage.

add_eo_meta(resolution_x: float, resolution_y: float, center_wavelength: float | None = None, full_width_half_max: float | None = None, **kwargs)

Set the EO properties to the band definition.

New in version 1.0.0.

This method follows the STAC EO Extension for Bands.

Parameters:

resolution_x – The sensor resolution in X.
resolution_y – The sensor resolution in Y.
center_wavelength – The center wavelength of the band, in micrometers (μm). The center wavelength is calculated from: center_wavelength = (min_wavelength + max_wavelength) / 2.
full_width_half_max – Full width at half maximum (FWHM). The width of the band, as measured at half the maximum transmission, in micrometers (μm).

Keyword Arguments:

solar_illumination (float) – The solar illumination of the band, as measured at half the maximum transmission, in W/m2/micrometers.

created: Define a special declarative member to record the creation of a table row.

property eo_resolutions: Tuple[float, float] | None: Retrieve the EO Band resolution X, Y.

property properties: Retrieve the metadata related STAC Properties for a band.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.BandSRC(**kwargs)

Model for band provenance/lineage.

created: Define a special declarative member to record the creation of a table row.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.Collection(**kwargs)

Model for the main table of image collections and data cubes.

created: Define a special declarative member to record the creation of a table row.

classmethod get_by_id(collection_id: str | int) → Collection

Retrieve a collection using the identifier or Collection Versioning.

New in version 1.0.0.

Parameters:: collection_id – The collection id (int) or the identifier (composed by Name-Version).
Raises:: werkzeug.exceptions.NotFound – When collection not found.

classmethod get_collection_sources(collection: Collection | str | int) → List[Collection]

Trace data cube collection origin.

It traces all the collection origin from the given collection using bdc_catalog.models.CollectionSRC

Raises:: ValueError – When collection is related itself (cyclic relationship).

identifier

Identifier for Name-Version used in SQLAlchemy queries.

New in version 1.0.0.

Example

>>> collection = Collection.query().filter(Collection.identifier == 'S2_L2A-1').first() 
>>> collection.identifier  
S2_L2A-1

property providers: List[CollectionsProviders]: The list of providers relationship of Collection.

New in version 1.0.0.

property sources: List[Collection]: Retrieve the list of referred collections marked as origin.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.CollectionSRC(**kwargs)

Model for collection provenance/lineage.

created: Define a special declarative member to record the creation of a table row.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.CollectionsProviders(**kwargs)

Track the available data providers for an image collection.

This model integrates with STAC Providers spec.

created: Define a special declarative member to record the creation of a table row.

classmethod get_providers(collection_id: int | str) → List[CollectionsProviders]: Retrieve the Providers related to the given collection.

New in version 1.0.0.

Note

You may use both Collection.id or CollectionName-Version as identifier.

to_dict() → dict: Retrieve the relationship as Python Dictionary.

Note

The properties follows the STAC specification in Provider Object.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.CompositeFunction(**kwargs)

Model for table bdc.composite_functions.

A composition function consists in a function that chooses a pixel value, according to a heuristic, from a set of pixels contained within a time interval.

The functions Stack, Median and Identity are offered by default in Brazil Data Cube.

created: Define a special declarative member to record the creation of a table row.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.GridRefSys(**kwargs)

Model for table bdc.grid_ref_sys.

A GridRefSys (GRS - Grid Reference System) ia a geographic reference system that divides the space into regions (TILE) and uses a code system, specified by a set of numbers, letters, or symbols, to identify an unique region, as defined in BDC-Concepts.

classmethod create_geometry_table(table_name: str, features: Iterable[Dict[str, str]], srid=None, **kwargs) → GridRefSys

Create an table to store the features and retrieve a respective Grid instance.

Parameters:

name (table_name - Grid) –
mapped. (features - Iterable with tile and geom) –
db.metadata. (schema - Table schema. Default is value associated in) –
SRID. (srid - SRID for grid. Default is Brazil Data Cube) –

created: Define a special declarative member to record the creation of a table row.

property crs: str | None: Retrieve the Coordinate Reference System (CRS) from the GRID.

property geom_table: Table | None: Retrieve instance GRID geometry table.

classmethod get_geom_table(grs_name: str) → Table | None

Retrieve the GRID geometry table based in the given grs.

Notes

It does not raise error when GRID name does not exist.

Parameters:: grs_name – The GRID name
Returns:: A SQLAlchemy table reference to GRID geometry table.
Return type:: Table

classmethod get_table_id(grs_name: str, schema=None) → str

Retrieve a Table OID from a Grid name.

Raises:: Exception when there is no table geometry for grid name. –

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.Item(**kwargs)

Model for the image item of a collection.

An item is usually defined in Brazil Data Cube concept as a data product scene.

The assets property follows the JSONSchema spec defined in bdc_catalog.jsonschemas.item.assets.json, which uses the function bdc_catalog.utils.multihash_checksum_sha256() to generate the file checksum.

The following example describes an published item of a Sentinel-2 data product scene S2A_MSIL1C_20191018T134211_N0208_R124_T22MFS_20191018T152053:

{
    "id": 423658,
    "name": "S2A_MSIL1C_20191018T134211_N0208_R124_T22MFS_20191018T152053",
    "collection_id": 23, # Collection S2_L1C
    "start_date": "2019-10-18T13:42:11",
    "end_date": "2019-10-18T13:42:11",
    "footprint": POLYGON((-50.094208 -7.23638395134798,-49.099884 -7.23332135700407,-49.09546 -8.22598479222442,-50.09207 -8.22947294680053,-50.094208 -7.23638395134798))",
    "bbox": "POLYGON((-49.09545 -8.225985,-49.099896 -7.233321,-50.094195 -7.236384,-50.092074 -8.229473,-49.09545 -8.225985))",
    "srid": 4326,
    "assets": {
        "thumbnail": {
            "href": "/Repository/Archive/S2_L1C/v001/22/M/FS/2019/S2A_MSIL1C_20191018T134211_N0208_R124_T22MFS_20191018T152053/S2A_MSIL1C_20191018T134211_N0208_R124_T22MFS_20191018T152053.png",
            "type": "image/png",
            "roles": [
                "thumbnail"
            ],
            "created": "2020-12-16T18:50:05",
            "updated": "2020-12-16T18:50:05",
            "bdc:size": 183439,
            "checksum:multihash": "1220476cf4b62525f99e9891634acdd3c4fbfc151e407e762ee8b32ce7ba72824a41"
        },
        "asset": {
            "href": "/Repository/Archive/S2_L1C/v001/22/M/FS/2019/S2A_MSIL1C_20191018T134211_N0208_R124_T22MFS_20191018T152053/S2A_MSIL1C_20191018T134211_N0208_R124_T22MFS_20191018T152053.zip",
            "type": "application/zip",
            "roles": [
                "data"
            ],
            "created": "2020-12-16T18:50:05",
            "updated": "2020-12-16T18:50:05",
            "bdc:size": 789501813,
            "checksum:multihash": "1220f1cebeff261104a35b7ce68083777cf3449a733acf240120ccf949d5c758e31a"
        }
    }
}

add_asset(name: str, file: str, role: List[str], href: str, **kwargs)

Add a new asset in Item context.

New in version 1.0.0.

Note

If asset name already exists, it overwrites the asset definition.

Raises:: ValueError – When could not determine mimetype relationship.

Examples

This example represent a minimal way to generate Item.assets that follows STAC Item Spec.

>>> item = Item(name='LC8-16D_V1_007011_20200101', collection_id=4)
>>> item.cloud_cover = 30.2
>>> item.start_date = '2020-01-01'
>>> item.end_date = '2020-01-16'
>>> item.add_asset('EVI', '/path/to/EVI.tif', role=['data'],
...                href='/cubes/LC8/007011/2020/01/01/EVI.tif')
>>> item.add_asset('thumbnail', '/path/to/thumbnail.png', role=['thumbnail'],
...                href='/cubes/LC8/007011/2020/01/01/thumbnail.png')
>>> item.save()

Parameters:

name (str) – Asset name
file (str) – Absolute file path
role (List[str]) – [‘data’], [‘thumbnail’]
href (str) – Relative file path for item asset.

Keyword Arguments:

**kwargs – All optional attributes specified in bdc_catalog.models.Item.create_asset_definition().
mime_type (str) – Custom mime type for item asset. When no mime type is set, it tries to find in bdc_catalog.models.Band.mime_type. When there is no band relation and the value is None, it will raise ValueError. Defaults to None.

add_processor(processor: Processor) → ItemsProcessors

Attach a processor into item scope.

Note

May raise error when processor is already attached. Make sure to commit or rollback changes.

Parameters:: processor (Processor) – Instance of Processor

classmethod create_asset_definition(file: str, role: List[str], href: str, mime_type: str, checksum: bool = True, created_at: datetime | str | None = None, fmt: str = '%Y-%m-%dT%H:%M:%S', is_raster: bool = False, **kwargs)

Create Item Asset structure.

New in version 1.0.0.

This method follows the STAC Item Spec.

Note

If the parameter is_raster is set, make sure you have rasterio installed.

Parameters:

file (str) – The absolute file path
role (List[str]) – [‘data’], [‘thumbnail’]
href (str) – Relative file path for item asset.
mime_type (str) – Custom mime type for item asset.
checksum (bool) – The algorithm used is sha256.
created_at (datetime|str) – The value indicating when asset were created. Defaults to None, which means to utc now.
fmt (str) – The datetime format for created and updated fields.
is_raster (bool) – Flag to generate Raster metadata in Asset. Defaults to False.

Keyword Arguments:

**kwargs – Any extra field value for Asset definition. You may use this keyword arg to specify for own spec attribute.

created: Define a special declarative member to record the creation of a table row.

get_processors() → List[Processor]: Retrieve the processors related to Item.

property processors: List[Processor]: The processors used that the item were generated.

save(commit=True): Overwrite the BaseModel.save and update the assets metadata.

Note

This method uses SQLAlchemy flag_modified to detect any change in assets.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.ItemsProcessors(**kwargs)

Represent model to integrate with STAC Extension Processing.

See More in Processing Extension Specification.

created: Define a special declarative member to record the creation of a table row.

classmethod get_processors(item_id: int) → List[Processor]: Retrieve the processors related to Item.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.MimeType(**kwargs)

Model for table bdc.providers.

created: Define a special declarative member to record the creation of a table row.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.Processor(**kwargs)

Represent the STAC extension for Processing: Processor.

See More in Processing Extension Specification.

created: Define a special declarative member to record the creation of a table row.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.Provider(**kwargs)

Model for table bdc.providers.

This model provides information about the provider. A provider is any of the organizations that captures, procecesses or host the content of the collection.

See more in STAC Provider Object

created: Define a special declarative member to record the creation of a table row.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.Quicklook(**kwargs)

Model for collection QuickLook info.

created: Define a special declarative member to record the creation of a table row.

get_bands() → Tuple[Band, Band, Band]: Retrieve the Band object reference for each RGB channel.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.ResolutionUnit(**kwargs)

Model for table bdc.resolution_unit.

created: Define a special declarative member to record the creation of a table row.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.SpatialRefSys(**kwargs)

Auxiliary model for the PostGIS spatial_ref_sys table.

query: t.ClassVar[Query]: A SQLAlchemy query for a model. Equivalent to db.session.query(Model). Can be customized per-model by overriding query_class.

Warning

The query interface is considered legacy in SQLAlchemy. Prefer using session.execute(select()) instead.

class bdc_catalog.models.Tile(**kwargs)

Model for table bdc.tile.

A tile is an element of a GRS, associated with a unique code, that represents a geographic region.

created: Define a special declarative member to record the creation of a table row.

name: The tile name (path row) identifier.

updated: Define a special declarative member to record the update of a table row.

class bdc_catalog.models.Timeline(**kwargs)

Model for timeline.

Track the entire time line for a collection.

Notes

This table is filled with trigger event on Item.

created: Define a special declarative member to record the creation of a table row.

updated: Define a special declarative member to record the update of a table row.