Images Service
The Images service allows uploading and managing of images which can be used throughout the IOIO services as well as external services.
The Images service has the following features:
- Supported image formats are
jpeg,jpg,png,gif,webpandsvg. - Maximum image size 5MB.
- Resizing of images.
- Adding custom metadata to an image.
- AI image metadata Below is a short description of the basic functionality of the Images service.
Uploading of Images:
In order to upload an image to the service, the user must have access to the S3 bucket in which the image sources are stored. Such access can be gained via contacting the dev team. The images can be uploaded via the AWS SDK which allows access to the AWS services or directly to S3 via the AWS Interface (Not Recommended). The supported file formats from the service are: jpeg, jpg, png, gif, webp and svg. With a maximum file size of a single image no more than 5MB.
Listing of images via the API:
The endpoint GET /images returns all of the images which have been uploaded to the Images service. A sample image has the following structure:
{
"guid": "<image_guid>",
"originalFileName": "<file_name>jpg",
"meta": {},
"width": 1440,
"height": 900,
"format": "jpeg",
"srcPath": "<images_destination>/image/<image_guid>/<image_guid>.jpeg",
"cdnPath": "https://<cdn_server>/images/image/<image_guid>.jpeg",
"imageMeta": {
"depth": "uchar",
"size": 134996,
"channels": 3,
"chromaSubsampling": "4:2:0",
"isProgressive": false,
"format": "jpeg",
"width": 1440,
"hasProfile": false,
"space": "srgb",
"hasAlpha": false,
"height": 900
},
"hasAIMeta": true
}
All of the images are returned in an array with each entry is a separate image
Query parameters for the GET /images endpoint are:
w - Desired width of the image in pixels. Example format: 320
h - Desired height of the image in pixels. Example format: 160
d - Desired dimension of the image in pixels. Example format: 320x160
List single image
To list a single image’s metadata use the GET /images/{guid}. The request accepts the following query parameters:
w - Desired width of the image in pixels. Example format: 320
h - Desired height of the image in pixels. Example format: 160
withAIMeta - Return image with its AI meta data.
d - Desired dimension of the image in pixels. Example format: 320x160
guid - Image guid
What this endpoint does is that it returns all fields of the entity image as a json structure, sample response can be observed below:
{
"status": true,
"data": {
"guid": "<image_guid>",
"originalFileName": "motorcycle.jpg",
"meta": {},
"width": 500,
"height": 500,
"format": "jpeg",
"srcPath": "<images_destination>/image/<image_guid>/<image_guid>.jpeg",
"cdnPath": "https://<cdn_server>/images/image/<image_guid>.jpeg",
"imageMeta": {
"depth": "uchar",
"size": 23025,
"channels": 3,
"density": 96,
"chromaSubsampling": "4:2:0",
"isProgressive": false,
"format": "jpeg",
"width": 500,
"hasProfile": false,
"space": "srgb",
"hasAlpha": false,
"height": 500
},
"hasAIMeta": true
}
}
Also the image the image with the metadata can be observed below:
{
"status": true,
"data": {
"guid": "<image_guid>",
"originalFileName": "motorcycle.jpg",
"meta": {},
"width": 500,
"height": 500,
"format": "jpeg",
"srcPath": "<images_destination>/image/<image_guid>/<image_guid>.jpeg",
"cdnPath": "https://<cdn_server>/images/image/<image_guid>.jpeg",
"imageMeta": {
"depth": "uchar",
"size": 23025,
"channels": 3,
"density": 96,
"chromaSubsampling": "4:2:0",
"isProgressive": false,
"format": "jpeg",
"width": 500,
"hasProfile": false,
"space": "srgb",
"hasAlpha": false,
"height": 500
},
"hasAIMeta": true,
"AIMeta": {
"celebrities": {
"OrientationCorrection": "ROTATE_0",
"CelebrityFaces": [],
"UnrecognizedFaces": []
},
"text": [],
"faces": [],
"labels": [
{
"Instances": [],
"Confidence": 99.5828857421875,
"Name": "Transportation",
"Parents": []
},
{
"Instances": [
{
"Confidence": 99.5828857421875,
"BoundingBox": {
"Height": 0.40483787655830383,
"Left": 0.12291433662176132,
"Top": 0.27483850717544556,
"Width": 0.6967653632164001
}
}
],
"Confidence": 99.5828857421875,
"Name": "Motorcycle",
"Parents": [
{
"Name": "Transportation"
},
{
"Name": "Vehicle"
}
]
},
{
"Instances": [],
"Confidence": 99.5828857421875,
"Name": "Vehicle",
"Parents": [
{
"Name": "Transportation"
}
]
},
{
"Instances": [],
"Confidence": 91.15457153320312,
"Name": "Machine",
"Parents": []
},
{
"Instances": [],
"Confidence": 81.03328704833984,
"Name": "Motor",
"Parents": [
{
"Name": "Machine"
}
]
},
{
"Instances": [],
"Confidence": 62.272090911865234,
"Name": "Spoke",
"Parents": [
{
"Name": "Machine"
}
]
},
{
"Instances": [],
"Confidence": 50.16193389892578,
"Name": "Engine",
"Parents": [
{
"Name": "Machine"
},
{
"Name": "Motor"
}
]
}
]
}
}
}
Fetching a single image
To fetch a single image the following endpoint should be used: GET /images/image/{guid}
What this endpoint does is it returns a direct URL to the image, if any parameters have been applied, the image will be returned according to the set parameters.
The parameters are listed below:
w - Desired width of the image in pixels. Example format: 320 (Setting only this parameter the returned image will have the set width, the height will be set automatically in order to keep the original aspect ratio).
h - Desired height of the image in pixels. Example format: 160 (Setting only this parameter will return the image with the set height, the width will be set automatically so that the original aspect ratio is kept.
e - Extract a region of the image format in px (left,top,width,height). Example format: 20,200,10,100; Extraction will be executed before resizing
f - Format of the image. If non specified default image format will be returned. Allowed values: jpeg, jpg, png, tiff, webp.
d - Desired dimension of the image in pixels. Example format: 320x160.
q - Quality of the image (between 1 and 100).
guid - Image guid.
The response from the endpoint will be similar to this one: https://<amazonaws_endpoint>/images/image/<image_guid>
This URL does not require any authentication so it can be accessed freely from anywhere.
Examples:
- If we need a picture that needs to have a fixed width we could only use the
“w”parameter which will resize the image to the desired width and the height will be automatically set to keep the aspect ratio like so:https://<amazonaws_endpoint>/images/image/<image_guid>?w=540This URL has the “w” parameter set, if opened we can see that the returned image does have a fixed width of 540 pixels. - If we require a fixed height then the parameter which we should use is
“h”. So the request URL will behttps://<amazonaws_endpoint>/images/image/<image_guid>?h=400 - If we need to crop or extract a particular region of the image, we need to use the
“e”parameter. The format is as follows (left,top,width,height). A sample request would like this:https://<amazonaws_endpoint>/images/image/<image_guid>?e=200%2C200%2C200%2C200.Note the url encoding of the special symbol which is used. The comma “,” is encoded to%2C - We could also change the image format.
This is achievable using the
“f”parameter Supported formats are: jpeg, jpg, png, tiff and webp. A sample URL looks like this:https://<amazonaws_endpoint>/images/image/<image_guid>?f=jpg - We could also set a specified resolution using the
“d”parameter, the format for it is“WxH”. An example URL looks like this:https://<amazonaws_endpoint>/images/image/<image_guid>?d=420x300 - The quality of the image can be adjusted from 1 to 100. With 1 being the lowest quality and 100 being the highest.
Storing Image meta data
The Images service allows to create new custom metadata and store it.
This is done via the POST /images/meta endpoint.
The format is:
{
"meta": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
Where each additional Prop is a custom field which accepts a string as its value.