Skip to content
Geo Engine Docs

datasets

Module for working with datasets and source definitions

UnixTimeStampType Objects

Section titled “UnixTimeStampType Objects”
class UnixTimeStampType(Enum)

A unix time stamp type

OgrSourceTimeFormat Objects

Section titled “OgrSourceTimeFormat Objects”
class OgrSourceTimeFormat()

Base class for OGR time formats

UnixTimeStampOgrSourceTimeFormat Objects

Section titled “UnixTimeStampOgrSourceTimeFormat Objects”
@dataclass
class UnixTimeStampOgrSourceTimeFormat(OgrSourceTimeFormat)

An OGR time format specified in seconds (UNIX time)

AutoOgrSourceTimeFormat Objects

Section titled “AutoOgrSourceTimeFormat Objects”
@dataclass
class AutoOgrSourceTimeFormat(OgrSourceTimeFormat)

An auto detection OGR time format

CustomOgrSourceTimeFormat Objects

Section titled “CustomOgrSourceTimeFormat Objects”
@dataclass
class CustomOgrSourceTimeFormat(OgrSourceTimeFormat)

A custom OGR time format

OgrSourceDuration Objects

Section titled “OgrSourceDuration Objects”
class OgrSourceDuration()

Base class for the duration part of a OGR time format

value

Section titled “value”
@classmethod
def value(
    cls,
    value: int,
    granularity: TimeStepGranularity = TimeStepGranularity.SECONDS
) -> ValueOgrSourceDurationSpec

Returns the value of the duration

ValueOgrSourceDurationSpec Objects

Section titled “ValueOgrSourceDurationSpec Objects”
class ValueOgrSourceDurationSpec(OgrSourceDuration)

A fixed value for a source duration

ZeroOgrSourceDurationSpec Objects

Section titled “ZeroOgrSourceDurationSpec Objects”
class ZeroOgrSourceDurationSpec(OgrSourceDuration)

An instant, i.e. no duration

InfiniteOgrSourceDurationSpec Objects

Section titled “InfiniteOgrSourceDurationSpec Objects”
class InfiniteOgrSourceDurationSpec(OgrSourceDuration)

An open-ended time duration

OgrSourceDatasetTimeType Objects

Section titled “OgrSourceDatasetTimeType Objects”
class OgrSourceDatasetTimeType()

A time type specification for OGR dataset definitions

start

Section titled “start”
@classmethod
def start(cls, start_field: str, start_format: OgrSourceTimeFormat,
          duration: OgrSourceDuration) -> StartOgrSourceDatasetTimeType

Specify a start column and a fixed duration

start_end

Section titled “start_end”
@classmethod
def start_end(
        cls, start_field: str, start_format: OgrSourceTimeFormat,
        end_field: str,
        end_format: OgrSourceTimeFormat) -> StartEndOgrSourceDatasetTimeType

The dataset contains start and end column

start_duration

Section titled “start_duration”
@classmethod
def start_duration(
        cls, start_field: str, start_format: OgrSourceTimeFormat,
        duration_field: str) -> StartDurationOgrSourceDatasetTimeType

The dataset contains start and a duration column

NoneOgrSourceDatasetTimeType Objects

Section titled “NoneOgrSourceDatasetTimeType Objects”
@dataclass
class NoneOgrSourceDatasetTimeType(OgrSourceDatasetTimeType)

Specify no time information

StartOgrSourceDatasetTimeType Objects

Section titled “StartOgrSourceDatasetTimeType Objects”
@dataclass
class StartOgrSourceDatasetTimeType(OgrSourceDatasetTimeType)

Specify a start column and a fixed duration

StartEndOgrSourceDatasetTimeType Objects

Section titled “StartEndOgrSourceDatasetTimeType Objects”
@dataclass
class StartEndOgrSourceDatasetTimeType(OgrSourceDatasetTimeType)

The dataset contains start and end column

StartDurationOgrSourceDatasetTimeType Objects

Section titled “StartDurationOgrSourceDatasetTimeType Objects”
@dataclass
class StartDurationOgrSourceDatasetTimeType(OgrSourceDatasetTimeType)

The dataset contains start and a duration column

OgrOnError Objects

Section titled “OgrOnError Objects”
class OgrOnError(Enum)

How to handle errors when loading an OGR dataset

AddDatasetProperties Objects

Section titled “AddDatasetProperties Objects”
class AddDatasetProperties()

The properties for adding a dataset

symbology

Section titled “symbology”

TODO: add vector symbology if needed

__init__

Section titled “__init__”
def __init__(display_name: str,
             description: str,
             source_operator: Literal["GdalSource", "OgrSource",
                                      "MultiBandGdalSource"] = "GdalSource",
             symbology: RasterSymbology | None = None,
             provenance: list[Provenance] | None = None,
             name: str | None = None)

Creates a new AddDatasetProperties object

to_api_dict

Section titled “to_api_dict”
def to_api_dict() -> geoengine_api_client.AddDataset

Converts the properties to a dictionary

VolumeId Objects

Section titled “VolumeId Objects”
class VolumeId()

A wrapper for an volume id

__eq__

Section titled “__eq__”
def __eq__(other) -> bool

Checks if two volume ids are equal

pandas_dtype_to_column_type

Section titled “pandas_dtype_to_column_type”
def pandas_dtype_to_column_type(dtype: np.dtype) -> FeatureDataType

Convert a pandas dtype to a column type

upload_dataframe

Section titled “upload_dataframe”
def upload_dataframe(df: gpd.GeoDataFrame,
                     display_name: str = "Upload from Python",
                     name: str | None = None,
                     time: OgrSourceDatasetTimeType | None = None,
                     on_error: OgrOnError = OgrOnError.ABORT,
                     timeout: int = 3600) -> DatasetName

Uploads a given dataframe to Geo Engine.

Parameters

Section titled “Parameters”

df The dataframe to upload. display_name The display name of the dataset. Defaults to "Upload from Python". name The name the dataset should have. If not given, a random name (UUID) will be generated. time A time configuration for the dataset. Defaults to OgrSourceDatasetTimeType.none(). on_error The error handling strategy. Defaults to OgrOnError.ABORT. timeout The upload timeout in seconds. Defaults to 3600.

Returns

Section titled “Returns”

DatasetName The name of the uploaded dataset

Raises

Section titled “Raises”

GeoEngineException If the dataset could not be uploaded or the name is already taken.

StoredDataset Objects

Section titled “StoredDataset Objects”
class StoredDataset(NamedTuple)

The result of a store dataset request is a combination of upload_id and dataset_name

from_response

Section titled “from_response”
@classmethod
def from_response(cls, response: api.StoredDataset) -> StoredDataset

Parse a http response to an StoredDataset

Volume Objects

Section titled “Volume Objects”
@dataclass
class Volume()

A volume

from_response

Section titled “from_response”
@classmethod
def from_response(cls, response: geoengine_api_client.Volume) -> Volume

Parse a http response to an Volume

volumes

Section titled “volumes”
def volumes(timeout: int = 60) -> list[Volume]

Returns a list of all volumes

volume_by_name

Section titled “volume_by_name”
def volume_by_name(volume_name: str, timeout: int = 60) -> Volume | None

Returns a volume with the specified name or None if none exists

add_dataset

Section titled “add_dataset”
def add_dataset(data_store: Volume | UploadId | Literal["external"],
                properties: AddDatasetProperties,
                meta_data: geoengine_api_client.MetaDataDefinition,
                timeout: int = 60) -> DatasetName

Adds a dataset to the Geo Engine

GdalMultiBandMetaData Objects

Section titled “GdalMultiBandMetaData Objects”
class GdalMultiBandMetaData()

The metadata (result descriptor) of a MultiBandGdalSource dataset

__init__

Section titled “__init__”
def __init__(bands: list[RasterBandDescriptor],
             data_type: RasterDataType,
             spatial_reference: str,
             grid_or_geo_transform: SpatialGridDescriptor | GeoTransform,
             time: TimeDescriptor | None = None,
             cache_ttl: int | None = None) -> None

Create a GdalMultiBandMetaData object.

When time is not given, a regular time dimension with an epoch origin and a step of one day is used. When spatial_grid is not given, a placeholder source grid is used; the Geo Engine derives the final grid when tiles are added to the dataset. The placeholder grid uses the given geo_transform (or a 1 by 1 unit grid), as the tile files' geo transforms must be compatible with the dataset grid's geo transform. cache_ttl sets the dataset-level cache lifetime in seconds. None uses the server default and 0 disables caching.

to_api_dict

Section titled “to_api_dict”
def to_api_dict() -> geoengine_api_client.MetaDataDefinition

Converts the metadata to a MetaDataDefinition for the API

MultiBandGdalFileSpec Objects

Section titled “MultiBandGdalFileSpec Objects”
@dataclass
class MultiBandGdalFileSpec()

A single file that is added as a tile to a MultiBandGdalSource dataset

to_api_dict

Section titled “to_api_dict”
def to_api_dict() -> geoengine_api_client.AddDatasetTile

Converts the file spec to an AddDatasetTile for the API

add_dataset_tiles

Section titled “add_dataset_tiles”
def add_dataset_tiles(dataset: DatasetName | str,
                      tiles: list[MultiBandGdalFileSpec],
                      timeout: int = 60) -> None

Add files (tiles) to an existing MultiBandGdalSource dataset

add_multiband_gdal_source

Section titled “add_multiband_gdal_source”
def add_multiband_gdal_source(name: str,
                              bands: list[RasterBandDescriptor],
                              data_type: RasterDataType,
                              spatial_reference: str,
                              files: list[MultiBandGdalFileSpec],
                              data_store: Volume | str = "external",
                              spatial_grid: SpatialGridDescriptor
                              | None = None,
                              time: TimeDescriptor | None = None,
                              display_name: str | None = None,
                              description: str = "",
                              share_with: list[RoleId] | None = None,
                              permission: Permission = Permission.READ,
                              timeout: int = 60,
                              cache_ttl: int | None = None) -> DatasetName

Create a MultiBandGdalSource dataset, grant optional permissions and add the given files as tiles.

By default the dataset is created as external data, so GDAL resolves the files (e.g. https or s3 links) when they are queried. A volume name or a Volume can be given to store the files in a Geo Engine volume. No permissions are granted unless share_with is given. cache_ttl sets the dataset-level cache lifetime in seconds as a fallback for tiles without their own TTL. None uses the server default and 0 disables caching.

add_or_replace_dataset_with_permissions

Section titled “add_or_replace_dataset_with_permissions”
def add_or_replace_dataset_with_permissions(
        data_store: Volume | UploadId | Literal["external"],
        properties: AddDatasetProperties,
        meta_data: geoengine_api_client.MetaDataDefinition,
        permission_tuples: list[tuple[RoleId, Permission]] | None = None,
        replace_existing=False,
        timeout: int = 60) -> DatasetName

Add a dataset to the Geo Engine and set permissions. Replaces existing datasets if forced!

delete_dataset

Section titled “delete_dataset”
def delete_dataset(dataset_name: DatasetName, timeout: int = 60) -> None

Delete a dataset. The dataset must be owned by the caller.

list_datasets_page

Section titled “list_datasets_page”
def list_datasets_page(
        offset: int = 0,
        limit: int = 20,
        order: DatasetListOrder = DatasetListOrder.NAME_ASC,
        name_filter: str | None = None,
        timeout: int = 60) -> list[geoengine_api_client.DatasetListing]

List datasets

list_datasets

Section titled “list_datasets”
def list_datasets(
        offset: int = 0,
        limit: int = 200,
        order: DatasetListOrder = DatasetListOrder.NAME_ASC,
        name_filter: str | None = None,
        timeout: int = 60) -> Iterator[geoengine_api_client.DatasetListing]

List datasets

dataset_info_by_name

Section titled “dataset_info_by_name”
def dataset_info_by_name(
        dataset_name: DatasetName | str,
        timeout: int = 60) -> geoengine_api_client.models.Dataset | None

Get dataset information.

dataset_metadata_by_name

Section titled “dataset_metadata_by_name”
def dataset_metadata_by_name(
    dataset_name: DatasetName | str,
    timeout: int = 60
) -> geoengine_api_client.models.MetaDataDefinition | None

Get dataset information.