====== GIDB API ======

===== General information =====


General image database (GIDB) support WEB API, which is available only through  [[https://cmv.cowi.com/Cowi.GIDB.EWebAPI/API/|HTTPS end-point]]. In GIDB terms "image" is aggregation
 of metadata + raster. The images are grouped by projects. All requests must contain your login and password which are sent as HTTP Basic authentication header:

C#:

<code csharp>
string authInfo = username + ":" + password;
authInfo = Convert.ToBase64String(Encoding.Default.GetBytes(authInfo));
WebRequest request = System.Net.WebRequest.Create(apiURL);
request.Headers["Authorization"] = "Basic " + authInfo;
WebResponse response = request.GetResponse();
</code>

JavaScript:

<code javascript>
$.ajax({
	url: apiURL,
	dataType: "json",
	beforeSend: function (xhr) {
		xhr.setRequestHeader ("Authorization", "Basic " + btoa(username + ":" + password));
	},
	success: function (data, textStatus, jqXHR) {},
	error: function (jqXHR, textStatus, errorThrown) {}
});
</code>
===== Metadata of GIDB's images  =====

The metadata of GIDB's images represents as:

  * **Required attributes** for all images: Id, AcquisitionTime, AltitudeWGS84, BitsPerChannel, Channels, ImageHeight, ImageWidth, LatitudeWGS84, LongitudeWGS84, Metadata, ScaleOptions, SharedMetadataId, StorageFormat, TileSize, ULStorageFormat, UniqueName
  * **Customizable attributes**: X, Y, Z, Yaw, Pitch, Roll, Omega, Phi, Kappa, etc. These attributes are available via property Metadata in response.
  * **Shared attributes**: set of attributes is the same for more than one image (generally shared attributes is xml file – can be stored more than key/value pairs). The attributes uses for optimization the storage from server side and requests/traffic from client side.

Graphically it can be represented as follows:

{{ :api:gidb-metadata.jpg?800 |}}

===== API =====

^ Function       ^ Verb     ^ Description       ^        
| API/GetAllProjects    | GET | Retrieves metadata for all projects, filtered by the access rights of the current user |
| API/FindImages/{projectId}/{minLongitude}/ {minLatitude}/{maxLongitude}/{maxLatitude}/ {maxresults} | POST | PPerforms a spatial query for images using a bounding box. The returned set of images is a random sample if more images than 'maxresults' are found. The message body can optionally specify a metadata search condition* |
| API/FindNearestImages/{projectId}/{longitude}/ {latitude}/{maxdistance}/{maxresults}| POST | Searches for a set of images nearest to the specified position. Only images within the specified maximum distance are considered. The message body can optionally specify a metadata search condition* |
| API/GetImage/{projectId}/{imageId} | GET | Returns the attributes for an image specified by id |
| API/GetImageSharedMetadata/{projectId}/{imageId} | GET | Returns shared metadata for an image |
| API/GetTile/{projectId}/{imageId}/{quadKey?} | GET | Returns the raw tile data for an image straight from backend storage, regardless the storage format of the tile. This will include tile data in a format that a web client possibly cant handle|

//* - to return a set of images with the metadata Yaw property in the range 180 to 270 specify the condition as: MetadataXML.value('(/Metadata/Yaw)[1]','float') > 180 and MetadataXML.value('(/Metadata/Yaw)[1]','float'). Do not forget add header "Content-Type: text/plain; charset=utf-8"//

The minimal image data contains information about the image and tile sizes. To calculate the number of levels and number of tiles at lowest level, the following equations can be used:

C#

<code csharp>
int size = Math.Max(ImageWidth,ImageHeight);
int TileSize = = Math.Max(TileSizeX,TileSizeY);
int levels = (int) Math.Ceiling(Math.Log(size / TileSize) / Math.Log(2));
int LowestLevelColumns = ImageWidth/TileSize;
int LowestLevelRows = ImageHeight/TileSize
</code>

JavaScript#

<code javascript>
var size = Math.max(ImageWidth, ImageHeight);
var levels = Math.ceil(Math.log(size / TileSize) / Math.log(2));
var lowestLevelColumns = ImageWidth/TileSize;
var lowestLevelRows = ImageHeight/TileSize
</code>


Top level (level 0) quad key is the empty string. Other quadkeys can be calculated from:

C#

<code csharp>
public static string TileXYToQuadKey(int tileX, int tileY, int level)
{
	StringBuilder quadKey = new StringBuilder();
	for (int i = level; i > 0; i--)
	{
		char digit = '0';
		int mask = 1 << (i - 1);
		if ((tileX & mask) != 0)
		{
			digit++;
		}
		if ((tileY & mask) != 0)
		{
			digit++;
			digit++;
		}
		quadKey.Append(digit);
	}
	return quadKey.ToString();
}
</code>

JavaScript

<code javascript>
function TileXYToQuadKey(tileX, tileY, level) {
	quadKey = "";
	for (var lev = level; lev > 0; lev--) {
		digit = '0';
		mask = 1 << (lev - 1);
		if ((tileX & mask) != 0) {
			digit++;
		}
		if ((tileY & mask) != 0) {
			digit++;
			digit++;
		}
		quadKey += digit;
	}
	return quadKey;
}
</code>

===== WMS representation of the images positions =====

GIDB supports WMS representation of the image positions, which is available only through  [[https://https://cmv.cowi.com/Cowi.GIDB.EWebAPI/wms.ashx|HTTPS end-point]]:

{{ :api:wms-representation.png?800 |}}