Protocol Documentation

Table of Contents

Top

pb/geocube.proto

Geocube

API Documentation may be detailed in Request/Response sections.

Method Name Request Type Response Type Description
CreateRecords CreateRecordsRequest CreateRecordsResponse Create one or a list of records
GetRecords GetRecordsRequest GetRecordsResponseItem stream Get records from their ID
ListRecords ListRecordsRequest ListRecordsResponseItem stream List records given criterias
AddRecordsTags AddRecordsTagsRequest AddRecordsTagsResponse Update records, adding or updating tags
RemoveRecordsTags RemoveRecordsTagsRequest RemoveRecordsTagsResponse Update records, removing tags
DeleteRecords DeleteRecordsRequest DeleteRecordsResponse Delete records
CreateAOI CreateAOIRequest CreateAOIResponse Create an AOI if not exists or returns the aoi id of the aoi.
GetAOI GetAOIRequest GetAOIResponse Get an AOI from its ID
CreateVariable CreateVariableRequest CreateVariableResponse Create a variable
GetVariable GetVariableRequest GetVariableResponse Get a variable given its id, name or one of its instance id
UpdateVariable UpdateVariableRequest UpdateVariableResponse Update some fields of a variable
DeleteVariable DeleteVariableRequest DeleteVariableResponse Delete a variable iif no dataset has a reference on
ListVariables ListVariablesRequest ListVariablesResponseItem stream List variables given a name pattern
InstantiateVariable InstantiateVariableRequest InstantiateVariableResponse Instantiate a variable
UpdateInstance UpdateInstanceRequest UpdateInstanceResponse Update metadata of an instance
DeleteInstance DeleteInstanceRequest DeleteInstanceResponse Delete an instance iif no dataset has a reference on
CreatePalette CreatePaletteRequest CreatePaletteResponse Create or update a palette that can be used to create a display of a dataset
GetContainers GetContainersRequest GetContainersResponse GetInfo on containers
IndexDatasets IndexDatasetsRequest IndexDatasetsResponse Index new datasets in the Geocube
ListDatasets ListDatasetsRequest ListDatasetsResponse List datasets from the Geocube
DeleteDatasets DeleteDatasetsRequest DeleteDatasetsResponse Delete datasets using records, instances and/or filepath
ConfigConsolidation ConfigConsolidationRequest ConfigConsolidationResponse Configurate a consolidation process
GetConsolidationParams GetConsolidationParamsRequest GetConsolidationParamsResponse Get the configuration of a consolidation
Consolidate ConsolidateRequest ConsolidateResponse Start a consolidation job
ListJobs ListJobsRequest ListJobsResponse List the jobs given a name pattern
GetJob GetJobRequest GetJobResponse Get a job given its name
CleanJobs CleanJobsRequest CleanJobsResponse Delete jobs given their status
RetryJob RetryJobRequest RetryJobResponse Retry a job
CancelJob CancelJobRequest CancelJobResponse Cancel a job
ContinueJob ContinueJobRequest ContinueJobResponse Continue a job that is in waiting state
GetCube GetCubeRequest GetCubeResponse stream Get a cube of data given a CubeParams
GetXYZTile GetTileRequest GetTileResponse Get a XYZTile (can be used with a TileServer, provided a GRPCGateway is up)
CreateLayout CreateLayoutRequest CreateLayoutResponse Create a layout to be used for tiling or consolidation
DeleteLayout DeleteLayoutRequest DeleteLayoutResponse Delete a layout given its name
ListLayouts ListLayoutsRequest ListLayoutsResponse List layouts given a name pattern
FindContainerLayouts FindContainerLayoutsRequest FindContainerLayoutsResponse stream Find all the layouts known for a set of containers
TileAOI TileAOIRequest TileAOIResponse stream Tile an AOI given a layout
CreateGrid CreateGridRequest stream CreateGridResponse Create a grid that can be used to tile an AOI
DeleteGrid DeleteGridRequest DeleteGridResponse Delete a grid
ListGrids ListGridsRequest ListGridsResponse List grids given a name pattern
Version GetVersionRequest GetVersionResponse Version of the GeocubeServer

Top

pb/geocubeDownloader.proto

GeocubeDownloader

API GeocubeDownloader to download a cube from metadata

Method Name Request Type Response Type Description
DownloadCube GetCubeMetadataRequest GetCubeMetadataResponse stream Request cube using metadatas returned by a call to Geocube.GetCube()
Version GetVersionRequest GetVersionResponse Version of the GeocubeDownloader

Top

pb/admin.proto

TidyDBRequest

Request to remove from the database all the pending entities (entities that are not linked to any dataset)

Field Type Label Description
Simulate bool If true, a simulation is done, nothing is actually deleted
PendingAOIs bool Remove AOIs that are not linked to any Records
PendingRecords bool Remove Records that do not reference any Datasets
PendingVariables bool Remove Variables that have not any instances
PendingInstances bool Remove Instances that do not reference any Datasets
PendingContainers bool Remove Containers that do not contain any Datasets
PendingParams bool Remove ConsolidationParams that are not linked to any Variable or Job

TidyDBResponse

Return the number of entities that were deleted (or should have been deleted if Simulate=True)

Field Type Label Description
NbAOIs int64
NbRecords int64
NbVariables int64
NbInstances int64
NbContainers int64
NbParams int64

UpdateDatasetsRequest

Update fields of datasets that can be tricky

Field Type Label Description
simulate bool If true, a simulation is done, nothing is actually updated
instance_id string Instance id that references the datasets to be updated
record_ids string repeated Record ids that reference the datasets to be updated
dformat DataFormat Internal data format (DType can be Undefined)
real_min_value double Real min value (dformat.min_value maps to real_min_value)
real_max_value double Real max value (dformat.max_value maps to real_max_value)
exponent double 1: linear scaling (RealMax - RealMin) * pow( (Value - Min) / (Max - Min), Exponent) + RealMin

UpdateDatasetsResponse

Return the number of modifications per kind of modification

Field Type Label Description
results UpdateDatasetsResponse.ResultsEntry repeated

UpdateDatasetsResponse.ResultsEntry

Field Type Label Description
key string
value int64

Admin

Service providing some functions to update or clean the database Must be used cautiously because there is no control neither possible rollback

Method Name Request Type Response Type Description
TidyDB TidyDBRequest TidyDBResponse
UpdateDatasets UpdateDatasetsRequest UpdateDatasetsResponse
DeleteDatasets DeleteDatasetsRequest DeleteDatasetsResponse

Top

pb/records.proto

AOI

Geographic AOI

Field Type Label Description
polygons Polygon repeated

AddRecordsTagsRequest

Add the given tags to a set of records

Field Type Label Description
ids string repeated
tags AddRecordsTagsRequest.TagsEntry repeated

AddRecordsTagsRequest.TagsEntry

Field Type Label Description
key string
value string

AddRecordsTagsResponse

Returns the number of records impacted by the addition

Field Type Label Description
nb int64

Coord

Geographic coordinates (4326)

Field Type Label Description
lon float
lat float

CreateAOIRequest

Create a new AOI

Field Type Label Description
aoi AOI

CreateAOIResponse

Returns the ID of the AOI

Field Type Label Description
id string

CreateRecordsRequest

Create new records

Field Type Label Description
records NewRecord repeated

CreateRecordsResponse

Returns the ID of the created records

Field Type Label Description
ids string repeated

DeleteRecordsRequest

Delete records by ID

Field Type Label Description
ids string repeated
no_fail bool If true, do not fail if some records still have datasets that refer to them and delete the others.

DeleteRecordsResponse

Return the number of deleted records

Field Type Label Description
nb int64

GetAOIRequest

Request the AOI given its ID

Field Type Label Description
id string

GetAOIResponse

Returns a geometric AOI

Field Type Label Description
aoi AOI

GetRecordsRequest

Get record from its id

Field Type Label Description
ids string repeated

GetRecordsResponseItem

Return a record

Field Type Label Description
record Record

GroupedRecordIds

Record ids that are considered as a unique, merged record (e.g. all records of a given date, whatever the time of the day)

Field Type Label Description
ids string repeated

GroupedRecordIdsList

List of groupedRecordIds

Field Type Label Description
records GroupedRecordIds repeated

GroupedRecords

Records that are considered as a unique, merged record (e.g. all records of a given date, whatever the time of the day)

Field Type Label Description
records Record repeated

LinearRing

Geographic linear ring

Field Type Label Description
points Coord repeated

ListRecordsRequest

Request to find the list of records corresponding to multiple filters (inclusive)

Field Type Label Description
name string Name pattern (support * and ? for all or any characters and trailing (?i) for case-insensitiveness)
tags ListRecordsRequest.TagsEntry repeated cf RecordFilters
from_time google.protobuf.Timestamp cf RecordFilters
to_time google.protobuf.Timestamp cf RecordFilters
aoi AOI cf RecordFiltersWithAOI
limit int32
page int32
with_aoi bool Also returns the AOI (may be big)

ListRecordsRequest.TagsEntry

Field Type Label Description
key string
value string

ListRecordsResponseItem

Field Type Label Description
record Record

NewRecord

Structure to create a new record

Field Type Label Description
name string
time google.protobuf.Timestamp
tags NewRecord.TagsEntry repeated
aoi_id string

NewRecord.TagsEntry

Field Type Label Description
key string
value string

Polygon

Geographic polygon

Field Type Label Description
linearrings LinearRing repeated

Record

Record

Field Type Label Description
id string
name string
time google.protobuf.Timestamp
tags Record.TagsEntry repeated
aoi_id string
aoi AOI optional

Record.TagsEntry

Field Type Label Description
key string
value string

RecordFilters

RecordFilters defines some filters to identify records

Field Type Label Description
tags RecordFilters.TagsEntry repeated Tags of the records
from_time google.protobuf.Timestamp Minimum date of the records
to_time google.protobuf.Timestamp Maximum date of the records

RecordFilters.TagsEntry

Field Type Label Description
key string
value string

RecordFiltersWithAOI

RecordFiltersWithAOI defines some filters to identify records, including an AOI in geometric coordinates

Field Type Label Description
filters RecordFilters
aoi AOI Geometric coordinates of an AOI that intersects the AOI of the records

RecordIdList

List of record ids that are considered separately

Field Type Label Description
ids string repeated

RemoveRecordsTagsRequest

Remove the given tags for a set of records

Field Type Label Description
ids string repeated
tagsKey string repeated

RemoveRecordsTagsResponse

Returns the number of records impacted by the removal

Field Type Label Description
nb int64

Top

pb/variables.proto

CreatePaletteRequest

Create a new palette or update it if already exists (provided replace=True)

Field Type Label Description
palette Palette Palette to be created
replace bool Replace the current existing palette if exists

CreatePaletteResponse

Return nothing.

CreateVariableRequest

Define a new variable. Return an error if the name already exists.

Field Type Label Description
variable Variable

CreateVariableResponse

Return the id of the new variable.

Field Type Label Description
id string

DeleteInstanceRequest

Delete an instance Return an error if the instance is linked to datasets.

Field Type Label Description
id string UUID-4 of the instance to delete

DeleteInstanceResponse

Return nothing

DeleteVariableRequest

Delete a variable Return an error if the variable has still instances

Field Type Label Description
id string UUID-4 of the variable to delete

DeleteVariableResponse

Return nothing

GetVariableRequest

Read a variable given either its id, its name or the id of one of its instance

Field Type Label Description
id string UUID-4 of the variable
name string Name of the variable
instance_id string UUID-4 of an instance

GetVariableResponse

Return the variable and its instances

Field Type Label Description
variable Variable

Instance

Field Type Label Description
id string Null at creation
name string
metadata Instance.MetadataEntry repeated

Instance.MetadataEntry

Field Type Label Description
key string
value string

InstantiateVariableRequest

Instantiate a variable. Return an error if the instance_name already exists for this variable.

Field Type Label Description
variable_id string
instance_name string
instance_metadata InstantiateVariableRequest.InstanceMetadataEntry repeated

InstantiateVariableRequest.InstanceMetadataEntry

Field Type Label Description
key string
value string

InstantiateVariableResponse

Return the new instance (its id, name and metadata)

Field Type Label Description
instance Instance

ListVariablesRequest

List variables given a name pattern

Field Type Label Description
name string Pattern of the name of the variable (support * and ? for all or any characters, (?i) suffix for case-insensitiveness)
limit int32 Limit the number of variables returned
page int32 Navigate through results (start at 0)

ListVariablesResponseItem

Return a stream of variables

Field Type Label Description
variable Variable

Palette

Define a palette with a name and a set of colorPoint. Maps all values in [0,1] to an RGBA value, using piecewise curve defined by colorPoints. All intermediate values are linearly interpolated.

Field Type Label Description
name string Name of the palette (Alpha-numerics characters, dots, dashes and underscores are supported)
colors colorPoint repeated Set of colorPoints. At least two points must be defined, corresponding to value=0 and value=1.

UpdateInstanceRequest

Update an instance Return an error if the name is to be updated but the new name already exists.

Field Type Label Description
id string UUID-4 of the instance to update
name google.protobuf.StringValue [Optional] New name of the variable. Empty to ignore
add_metadata UpdateInstanceRequest.AddMetadataEntry repeated Pairs of metadata (key, values) to be inserted or updated
del_metadata_keys string repeated Metadata keys to be deleted

UpdateInstanceRequest.AddMetadataEntry

Field Type Label Description
key string
value string

UpdateInstanceResponse

Return nothing

UpdateVariableRequest

Update the non-critical fields of a variable Return an error if the name is to be updated but the new name already exists.

Field Type Label Description
id string UUID-4 of the variable to update
name google.protobuf.StringValue [Optional] New name of the variable. Empty to ignore
unit google.protobuf.StringValue [Optional] New unit of the variable. Empty to ignore
description google.protobuf.StringValue [Optional] New description of the variable. Empty to ignore
palette google.protobuf.StringValue [Optional] New default palette of the variable. Empty to ignore
resampling_alg Resampling [Optional] New default resampling algorithm of the variable. UNDEFINED to ignore

UpdateVariableResponse

Return nothing

Variable

Variable

Field Type Label Description
id string Internal UUID-4 of the variable (ignored at creation)
name string Name of the variable (Alpha-numerics characters, dashs, dots and underscores)
unit string Unit of the variable (for user information only)
description string Description of the variable (for user information only)
dformat DataFormat Format of the data. Range.Min and Range.Max are used for data mapping from internal data format of a dataset (See IndexDatasets for more details), DType and NoData are used for the outputs of GetCube.
bands string repeated Name of each band. Can be empty when the variable refers to only one band, must be unique otherwise.
palette string Name of the default palette for color rendering.
resampling_alg Resampling Default resampling algorithm in case of reprojection.
instances Instance repeated List of instances of the variable (ignored at creation)

colorPoint

Define a color mapping from a value [0-1] to a RGBA value.

Field Type Label Description
value float
r uint32
g uint32
b uint32
a uint32

Resampling

Resampling algorithms (supported by GDAL)

Name Number Description
UNDEFINED 0
NEAR 1
BILINEAR 2
CUBIC 3
CUBICSPLINE 4
LANCZOS 5
AVERAGE 6
MODE 7
MAX 8
MIN 9
MED 10
Q1 11
Q3 12

Top

pb/dataformat.proto

DataFormat

Format of the data of a dataset. Format is defined by the type of the data, its no-data value and the range of values (its interpretation depends on the use)

Field Type Label Description
dtype DataFormat.Dtype Type of the data
no_data double No-data value (supports any float values, including NaN)
min_value double Min value (usually used to map from one min value to another)
max_value double Max value (usually used to map from one min value to another)

DataFormat.Dtype

Type of data supported by the Geocube & GDAL

Name Number Description
UNDEFINED 0
UInt8 1
UInt16 2
UInt32 3
Int8 4
Int16 5
Int32 6
Float32 7
Float64 8
Complex64 9 Pair of float32

Top

pb/catalog.proto

GetCubeMetadataRequest

Request a cube from metadatas (provided by Geocube.GetCube())

Field Type Label Description
datasets_meta DatasetMeta repeated List of Metadatas needed to download and generate the slices of the cube
grouped_records GroupedRecords repeated List of GroupedRecords describing the slices of the cube
ref_dformat DataFormat Output dataformat
resampling_alg Resampling Resampling algorithm to use for reprojection
pix_to_crs GeoTransform
crs string
size Size
format FileFormat Format of the output data
predownload bool Predownload the datasets before merging them. When the dataset is remote and all the dataset is required, it is more efficient to predownload it.
protocol_v11x bool For compatibility with older clients. Clients with version above 1.1.0 must set this field to true.

GetCubeMetadataResponse

Return either information on the cube, information on an image or a chunk of an image

Field Type Label Description
global_header GetCubeResponseHeader
header ImageHeader
chunk ImageChunk

GetCubeRequest

Request a cube of data

Field Type Label Description
records RecordIdList List of record ids requested. At least one. One image will be returned by record (if not empty)
filters RecordFilters Filters to list the records that will be used to create the cube
grouped_records GroupedRecordIdsList List of groups of record ids requested. At least one. One image will be returned by group of records (if not empty). All the datasets of a group of records will be merged together using the latest first.
instances_id string repeated Instances of a variable defining the kind of images requested. At least one, and all must be instance of the same variable. Only one is actually supported
crs string Coordinates Reference System of the output images (images will be reprojected on the fly if necessary)
pix_to_crs GeoTransform GeoTransform of the requested cube (images will be rescaled on the fly if necessary)
size Size Shape of the output images
compression_level int32 Define a level of compression to speed up the transfer, values: -3 to 9 (-2: Huffman only, -1:default, 0->9: level of compression from the fastest to the best compression, -3: disable the compression). The data is compressed by the server and decompressed by the Client. Use -3 or -2 if the bandwidth is not limited. 0 is level 0 of DEFLATE (thus, it must be decompressed by DEFLATE even though the data is not compressed). If the client can support -3, 0 is useless.
headers_only bool Only returns headers (including all metadatas on datasets)
format FileFormat Format of the output images
resampling_alg Resampling Resampling algorithm used for reprojecion. If undefined, the default resampling algorithm associated to the variable is used.
protocol_v11x bool For compatibility with older clients. Clients with version above 1.1.0 must set this field to true.

GetCubeResponse

Return either information on the cube, information on an image or a chunk of an image

Field Type Label Description
global_header GetCubeResponseHeader
header ImageHeader
chunk ImageChunk

GetCubeResponseHeader

Return global information on the requested cube

Field Type Label Description
count int64
nb_datasets int64
ref_dformat DataFormat Output dataformat
resampling_alg Resampling Resampling algorithm to use for reprojection
geotransform GeoTransform Geotransform used for mapping
crs string

GetTileRequest

Request a web-mercator tile, given a variable and a group of records

Field Type Label Description
instance_id string
x int32
y int32
z int32
min float
max float
records GroupedRecordIds Group of record ids. At least one. All the datasets of the group of records will be merged together using the latest first.
filters RecordFilters All the datasets whose records have RecordTags and time between from_time and to_time

GetTileResponse

Return a 256x256 png image

Field Type Label Description
image ImageFile

ImageChunk

Chunk of the full image, to handle the GRPC limit of 4Mbytes/message

Field Type Label Description
part int32 Index of the chunk (from 1 to ImageHeader.nb_parts-1). The first part (=0) is ImageHeader.data
data bytes Chunk of the full array of bytes

ImageFile

ByteArray of a PNG image 256x256pixels

Field Type Label Description
data bytes

ImageHeader

Header of an image (slice of the cube) It describes the image, the underlying datasets and the way to recreate it from the array of byte : 1. Append ImageHeader.data and ImageChunk.data from part=0 to part=nb_parts-1 2. If compression=True, decompress the array of bytes using deflate 3. Cast the result to the dtype using byteOrder 4. Reshape the result

Field Type Label Description
shape Shape Shape of the image (widthxheight)
dtype DataFormat.Dtype Type of the data (to interprete "ImageHeader.data + ImageChunk.data")
nb_parts int32 Number of parts the image is splitted into
data bytes First part of the image as an array of bytes
size int64 Size of the full array of bytes
order ByteOrder ByteOrder of the datatype
compression bool Deflate compressed data format, described in RFC 1951
grouped_records GroupedRecords Group of records used to generate this image
dataset_meta DatasetMeta All information on the underlying datasets that composed the image
error string If not empty, an error occured and the image was not retrieved.

ListDatasetsRequest

List Datasets

Field Type Label Description
instance_id string Instance of a variable defining the kind of datasets requested.
records RecordIdList List of record ids requested.
filters RecordFilters Filters to list the records that will be used to create the cube

ListDatasetsResponse

Returns metadata on datasets that match records x instance

Field Type Label Description
records Record repeated List of records
dataset_metas DatasetMeta repeated For each record, list of the datasets

Shape

Shape of an image width x height x channels

Field Type Label Description
dim1 int32
dim2 int32
dim3 int32

ByteOrder

ByteOrder for the conversion between data type and byte.

Name Number Description
LittleEndian 0
BigEndian 1

FileFormat

Available file formats

Name Number Description
Raw 0 raw bitmap
GTiff 1

Top

pb/layouts.proto

Cell

Define a cell of a grid

Field Type Label Description
id string Cell identifier
crs string Coordinate reference system used in the cell
coordinates LinearRing Geographic coordinates

CreateGridRequest

Create a new grid.

Field Type Label Description
grid Grid

CreateGridResponse

CreateLayoutRequest

Create a new layout Return an error if the name already exists

Field Type Label Description
layout Layout

CreateLayoutResponse

DeleteGridRequest

Delete a grid

Field Type Label Description
name string

DeleteGridResponse

DeleteLayoutRequest

Delete a layout by name

Field Type Label Description
name string

DeleteLayoutResponse

FindContainerLayoutsRequest

Find all the layouts used by the datasets on an AOI or a set of records It can be used to tile the AOI with an optimal layout.

Field Type Label Description
instance_id string
records RecordIdList List of record ids
filters RecordFiltersWithAOI Filters to select records

FindContainerLayoutsResponse

Stream the name of the layout and the associated containers

Field Type Label Description
layout_name string Name of the layout
container_uris string repeated List of containers having the layout

GeoTransform

GDAL GeoTransform

Field Type Label Description
a double x offset
b double x resolution
c double
d double y offset
e double
f double y resolution

Grid

Define a grid

Field Type Label Description
name string Unique name of the grid
description string Description of the grid
cells Cell repeated Cells of the grid

Layout

Define a layout for consolidation. A layout is composed of an external and an internal layout. External layout is a grid that is used to cover any area with tiles. TODO Internal layout defines the internal structure of a dataset

Interlacing_pattern defines how to interlace the [R]ecords, the [B]ands, the [Z]ooms level/overview and the [T]iles (geotiff blocks). The four levels of interlacing must be prioritized in the following way L1>L2>L3>L4 where each L is in [R, B, Z, T]. This order should be understood as: for each L1: for each L2: for each L3: for each L4: addBlock(L1, L2, L3, L4) In other words, all L4 for a given (L1, L2, L3) will be contiguous in memory. For example: - To optimize the access to geographical information of all the bands (such as in COG) : R>Z>T>B => For a given record, zoom level and block, all the bands will be contiguous. - To optimize the access to geographical information of one band at a time : B>R>Z>T => For a given band, record and zoom, all the blocks will be contiguous. - To optimize the access to timeseries of all the bands (such as in MUCOG): Z>T>R>B => For a given zoom level and block, all the records will be contiguous.

Interlacing pattern can be specialized to only select a list or a range for each level (except Tile level). - By values: L=0,2,3 will only select the value 0, 2 and 3 of the level L. For example B=0,2,3 to select the corresponding band level. - By range: L=0:3 will only select the values from 0 to 3 (not included) of the level L. For example B=0:3 to select the three firsts bands. First and last values of the range can be omitted to define 0 or last element of the level. e.g B=2: means all the bands from the second. Z=0 is the full resolution, Z=1 is the overview with zoom factor 2, Z=2 is the zoom factor 4, and so on.

To chain interlacing patterns, use ";" separator.

For example: - MUCOG optimizes access to timeseries for full resolution (Z=0), but geographic for overviews (Z=1:). Z=0>T>R>B;Z=1:>R>T>B - Same example, but the bands are separated: B>Z=0>T>R;B>Z=1:>R>T - To optimize access to geographic information of the three first bands together, but timeseries of the others: Z>T>R>B=0:3;B=3:>Z>R>T

Field Type Label Description
name string
grid_flags string repeated External layout: Grid:Cell (CRS)
grid_parameters Layout.GridParametersEntry repeated
block_x_size int64 Internal layout: Cell, Tile
block_y_size int64
max_records int64
overviews_min_size int64 Maximum width or height of the smallest overview level. 0: No overview, -1: default=256.
interlacing_pattern string Define how to interlace the [R]ecords, the [B]ands, the [Z]ooms level/overview and the [T]iles (geotiff blocks).

Layout.GridParametersEntry

Field Type Label Description
key string
value string

ListGridsRequest

List all the grids given a name pattern (does not retrieve the cells)

Field Type Label Description
name_like string Name pattern (support * and ? for all or any characters and trailing (?i) for case-insensitiveness)

ListGridsResponse

Return a list of grids

Field Type Label Description
grids Grid repeated

ListLayoutsRequest

List all the layouts given a name pattern

Field Type Label Description
name_like string Name pattern (support * and ? for all or any characters and trailing (?i) for case-insensitiveness)

ListLayoutsResponse

Return a list of layouts

Field Type Label Description
layouts Layout repeated

Size

Define a size

Field Type Label Description
width int32
height int32

Tile

Define a rectangular tile in a given coordinate system (CRS).

Field Type Label Description
transform GeoTransform Transform to map from pixel coordinates to CRS
size_px Size Size of the tile in pixel
crs string Coordinate reference system

TileAOIRequest

Tile an AOI, covering it with cells defined by a grid. In the future, it will be able to find the best tiling given the internal layout of datasets.

Field Type Label Description
aoi AOI
layout_name string Name of an existing layout
layout Layout User-defined layout

TileAOIResponse

Return tiles, thousand by thousand.

Field Type Label Description
tiles Tile repeated

Top

pb/operations.proto

CancelJobRequest

Cancel a job (e.g. during consolidation)

Field Type Label Description
id string
force_any_state bool Force cancel even when the job is not in a failed state or consolidation step (could corrupt the data)

CancelJobResponse

CleanJobsRequest

Clean terminated jobs

Field Type Label Description
name_like string Filter by name (support *, ? and (?i)-suffix for case-insensitivity)
state string Filter by terminated state (DONE, FAILED)

CleanJobsResponse

Return the number of jobs that have been deleted

Field Type Label Description
count int32

ConfigConsolidationRequest

Configure the parameters of the consolidation attached to the variable

Field Type Label Description
variable_id string
consolidation_params ConsolidationParams

ConfigConsolidationResponse

ConsolidateRequest

Create and start a consolidation job given a list of records and an instance_id to be consolidated on a layout Optionnaly, the job can be done step by step, pausing and waiting for user action, with three levels: - 1: after each critical steps - 2: after each major steps - 3: after all steps

Field Type Label Description
job_name string
instance_id string
layout_name string
execution_level ExecutionLevel Execution level of a job. A consolidation job cannot be executed synchronously
collapse_on_record_id string [Optional] Collapse all records on this record (in this case only, original datasets are kept, data is duplicated)
records RecordIdList At least one
filters RecordFilters

ConsolidateResponse

Return the id of the job created

Field Type Label Description
job_id string

ConsolidationParams

Parameters of consolidation that are linked to a variable, to define: - how to resample the data during consolidation - how to store the data: - Compression - CreationParams (supported: see GDAL drivers: PHOTOMETRIC, COMPRESS, PREDICTOR, ZLEVEL, ZSTDLEVEL, MAX_Z_ERROR, JPEGTABLESMODE and with _OVERVIEW suffix if exists)

Field Type Label Description
dformat DataFormat dataformat of the data. See exponent for the mapping formula.
exponent double 1: linear scaling (RealMax - RealMin) * pow( (Value - Min) / (Max - Min), Exponent) + RealMin
create_overviews bool Deprecated. Use Layout.overviews_min_size instead
resampling_alg Resampling Define how to resample the data during the consolidation (if a reprojection is needed or if the overviews are created)
compression ConsolidationParams.Compression Define how the data is compressed at block level
creation_params ConsolidationParams.CreationParamsEntry repeated map of params:value to configure the creation of the file. See Compression to list the supported params
bands_interleave bool Deprecated. If the variable is multibands, define whether the bands are interleaved. Use Layout.interlacing_pattern instead
storage_class StorageClass Define the storage class of the created file (support only GCS)

ConsolidationParams.CreationParamsEntry

Field Type Label Description
key string
value string

Container

Define a container of datasets. Usually a container is a file containing one dataset. But after a consolidation or if the container has several bands, it can contain several datasets.

Field Type Label Description
uri string URI of the file
managed bool True if the Geocube is responsible for the lifecycle of this file
datasets Dataset repeated List of datasets of the container

ContinueJobRequest

Proceed the next step of a step-by-step job

Field Type Label Description
id string

ContinueJobResponse

Dataset

Define a dataset. A dataset is the metadata to retrieve an image from a file. It is defined by a record and the instance of a variable.

A dataset defines: - Which band(s) are indexed (usually all the bands, but it can be a subset) - How to map the value of its pixels to the dataformat of the variable. In more details: . the dataformat of the dataset (dformat.[no_data, min, max]) that describes the pixel of the image . the mapping from each pixel to the data format of the variable (variable.dformat). This mapping is defined as [MinOut, MaxOut, Exponent].

Field Type Label Description
record_id string
instance_id string
container_subdir string
bands int64 repeated
dformat DataFormat Internal data format (DType can be Undefined)
real_min_value double Real min value (dformat.min_value maps to real_min_value)
real_max_value double Real max value (dformat.max_value maps to real_max_value)
exponent double 1: linear scaling (RealMax - RealMin) * pow( (Value - Min) / (Max - Min), Exponent) + RealMin

DeleteDatasetsRequest

Remove the datasets referenced by instances and records without any control The containers (if empty) are not deleted

Field Type Label Description
record_ids string repeated Instance id that references the datasets to be deleted
instance_ids string repeated Record ids that reference the datasets to be deleted
dataset_patterns string repeated Dataset file patterns (support * and ? for all or any characters and trailing (?i) for case-insensitiveness) (or empty to ignore)
execution_level ExecutionLevel Execution level (see enum)
job_name string Name of the job (if empty, a name will be generated)

DeleteDatasetsResponse

Return the number of deleted datasets

Field Type Label Description
job Job

GetConsolidationParamsRequest

Retrieve the consolidation parameters attached to the given variable

Field Type Label Description
variable_id string

GetConsolidationParamsResponse

Return consolidation parameters

Field Type Label Description
consolidation_params ConsolidationParams

GetContainersRequest

Request info on containers

Field Type Label Description
uris string repeated List of container uris

GetContainersResponse

Field Type Label Description
containers Container repeated

GetJobRequest

Retrieve a job given its id

Field Type Label Description
id string
log_page int32
log_limit int32

GetJobResponse

Return a job with the requested id

Field Type Label Description
job Job

IndexDatasetsRequest

Request to index all the datasets of a container

Field Type Label Description
container Container TODO Index several containers: repeated ?

IndexDatasetsResponse

Job

Job to modify datasets (consolidation, deletion, ingestion...) Some lifecycle operations are required to be done cautiously, in order to garantee the integrity of the database. Such operations are defined by a job and are done asynchronously. A job is a state-machine that can be rollbacked anytime during the operation until it ends.

Field Type Label Description
id string Id of the job
name string Name of the job (must be unique)
type string Type of the job (consolidation, deletion...)
state string Current state of the state machine
creation_time google.protobuf.Timestamp Time of creation of the job
last_update_time google.protobuf.Timestamp Time of the last update
logs string repeated Job logs: if logs are too big to fit in a grpc response, logs will only be a subset (by default, the latest)
active_tasks int32 If the job is divided into sub tasks, number of pending tasks
failed_tasks int32 If the job is divided into sub tasks, number of failed tasks
execution_level ExecutionLevel Execution level of a job (see ExecutionLevel)
waiting bool If true, the job is waiting for user to continue

ListJobsRequest

List jobs given a name pattern

Field Type Label Description
name_like string
page int32
limit int32

ListJobsResponse

Return a list of the job whose name matchs the pattern

Field Type Label Description
jobs Job repeated

RetryJobRequest

Retry a job that failed or is stuck (e.g. during consolidation)

Field Type Label Description
id string
force_any_state bool Force retry even when the job is not in a failed state (could corrupt the data)

RetryJobResponse

ConsolidationParams.Compression

Name Number Description
NO 0
LOSSLESS 1
LOSSY 2
CUSTOM 3 configured by creation_params

ExecutionLevel

Execution level of a job

Name Number Description
ExecutionSynchronous 0 Job is done synchronously
ExecutionAsynchronous 1 Job is done asynchronously, but without any pause
StepByStepCritical 2 Job is done asynchronously, step-by-step, pausing at every critical steps
StepByStepMajor 3 Job is done asynchronously, step-by-step, pausing at every major steps
StepByStepAll 4 Job is done asynchronously, step-by-step, pausing at every steps

StorageClass

Storage class of a container. Depends on the storage

Name Number Description
STANDARD 0
INFREQUENT 1
ARCHIVE 2
DEEPARCHIVE 3

Top

pb/datasetMeta.proto

DatasetMeta

DatasetMeta contains all the metadata on files and fileformats to download and generate a slice of a cube

Field Type Label Description
internalsMeta InternalMeta repeated Information on the images composing the slice

InternalMeta

InternalMeta contains all the metadata on a file to download it and to map its internal values to the external range.

Field Type Label Description
container_uri string URI of the file storing the data
container_subdir string Subdir of the file storing the data
bands int64 repeated Subbands of the file requested
dformat DataFormat Internal dataformat of the data
range_min double dformat.RangeMin will be mapped to this value
range_max double dformat.RangeMax will be mapped to this value
exponent double Exponent used to map the value from dformat to [RangeMin, RangeMax]

Top

pb/version.proto

GetVersionRequest

Request the version of the Geocube

GetVersionResponse

Return the version of the Geocube

Field Type Label Description
Version string

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)