Manual (REST) call
Overview
Behind the scenes the AME APEX plug-in and PL/SQL API is creating a JSON file that will be sent to the AME server. Below you find more details about the JSON structure that is used. By understanding this JSON structure you can manually interact with the AME server in case you wanted to code in PL/SQL or other languages.
JSON File
The JSON file is a file that follows the standard JSON structure (http://json.org/).
This JSON file contains an JSON object meaning it starts with { and ends with }. This JSON object contains four compulsory JSON attributes/objects namely "media_files", "output", "api_key" and a few optional object "version", "request_origin" or "apex_version". The purpose of each object will now be explained.
## "apex_version" attribute or "request_origin" attribute\
One of the two must be present. The apex_version will contain the version of oracle APEX where the call is happening from.
The request_origin attribute will give info about the callee.
"api_key" attribute
The API key that should be used for processing the request.
"manipulator" attribute
This is an optional attribute that will specify which image/video manipulator to use. Available manipulators: "sharp" or "jimp". (default "sharp");
"media_files" array
This array will contain the media files that need to be processed or analyzed. Each object inside this array will have the following structure:
{
//Mandatory
"file":"",//The content of the media file.
//This can be a URL (ftp or http), base64 encoded media file or a relative location from the server inside ame_resources folder.
//Optional
"manipulator" : "sharp" //the image manipulator to use for the image.
// Available options:
// 'jimp'
// 'sharp'
"return_output": true, //whether the output should be returned, if false, only the metadata will be returned back in base64.
"output_mime_type":"", // the mime type of the output wished, default: mime type of the input file
"greyscale": false, //whether the image should be greyscaled
"quality": 80, // quality of the output (JPEG quality): number between 0-100.
"rotate": 45, // the amount to rotate the image. (rotates counterclock wise).
"flip": {
"horizontal": true, //whether the image should be flipped horizontally
"vertical": false, //whether the image should be flipped vertically
},
"overlay":[{ //array containing the overlays
//Overlay is either text or image.
//For text
"text": "Watermark", // The overlay text
"font_size": "", //font size in pixels
"font_color":"", //currently either white or black
//for image
"image": "", //URL or base64 or location/ similar to file.
//For both text and image.
"x": 25, //x position where the overlay should be placed
"y": 40, //y position where the overlay should be placed.
"rotation": 0, // whether the overlay should be rotated.
}],
"crop":{ //If the image should be cropped.
"x":0, //The x position where the cropping should start
"y":0, // The y position where the cropping should start
"width":200, // The width of the crop
"height":200 // The height of the crop
},
//resizing
"width": 200, //output image width, absolute
"height": 200, //ouptut image height, absolute
"max_width": 300, // maximum output width allowed for the output image, will be rescaled if the width of the input image is greater. Will keep aspect ratio.
"max_height": 300, // maximum output width allowed for the output image, will be rescaled if the width of the input image is greater. Will keep aspect ratio.
"resize_method": "nearest_neighbour", //the method to use for resizing, optional
//Available resize methods for Sharp:
// nearest_neighbour
// bicubic
// mitchell
// lanczos2
// lanczos3
//Available resize methods for Jimp:
// nearest_neighbour
// bilinear
// bicubic
// hermite
// bezier
"manipulation_order":"resize:greyscale:quality:rotate:flip:overlay:crop" //The order on which the manipulations should be performed.
//Default: resize:greyscale:quality:rotate:flip:overlay:crop
//If this is present, only the manipulations present will be performed.
}
"output" object
This object should contain what the output encoding should be, together with whether or not the output image should be stitched:
"output": {
"output_encoding":"raw" //can be either raw or base64.
"output_stitch": { //Optional
"orientation":"vertical"
}
}
Output Encoding
When the ouput_encoding is raw, the processed binary file will be returned back. When the output_encoding is base64 a JSON array wll be sent back with the following structure:
[
{
"initialHeight": 1079, //will contain the inital height of the image.
"initialWidth": 1224, // the initial width of the image.
"height": 1079, // the height of the output image (might be changed if resizing happens)
"width": 1224, // the widht of the output image.
"input_mime_type": "image/jpeg", //input mime type
"input_extension": "jpg", //input extension
"output_mime_type": "image/jpeg", // mime type of the output file
"output_filename": "dog.jpeg", // the output file name provided
"output_extension": "jpg", // extension of the output
"output": "", //Will contain the base64 encoded output image
"meta_data": { //This object will contain the meta data thats found in the input image and the attributes will vary depending on the input provided.
"bits_per_sample": "8",
"image_height": "1079px",
"image_width": "1224px",
"color_components": "3",
"subsampling": "YCbCr4:2:0 (2 2)",
"documentid": "xmp.did:e855160a-a4da-8647-adbe-228545e4e525",
"instanceid": "xmp.iid:e855160a-a4da-8647-adbe-228545e4e525",
"originaldocumentid": "adobe:docid:photoshop:ad6929cc-b8b5-11d9-a342-ccefd3333069",
"history": "action: saved; instanceID: xmp.iid:13769CA4BBB6E3119318908B2E34C886; when: 2014-03-28T14:04:20-07:00; softwareAgent: Adobe Photoshop CS6 (Windows); changed: /, action: converted; parameters: from image/jpeg to application/vnd.adobe.photoshop, action: derived; parameters: converted from image/jpeg to application/vnd.adobe.photoshop, action: saved; instanceID: xmp.iid:14769CA4BBB6E3119318908B2E34C886; when: 2014-03-28T14:04:20-07:00; softwareAgent: Adobe Photoshop CS6 (Windows); changed: /, action: saved; instanceID: xmp.iid:e855160a-a4da-8647-adbe-228545e4e525; when: 2014-04-16T16:59:57-07:00; softwareAgent: Adobe Illustrator CC (Windows); changed: /",
"derivedfrom": "instanceID: xmp.iid:610c07d7-91e0-5c4e-a82e-011f8599aecd; documentID: xmp.did:610c07d7-91e0-5c4e-a82e-011f8599aecd; originalDocumentID: adobe:docid:photoshop:ad6929cc-b8b5-11d9-a342-ccefd3333069; renditionClass: proof:pdf",
"renditionclass": "proof:pdf",
"legacyiptcdigest": "00000000000000000000000000000001",
"colormode": "1",
"creatortool": "Adobe Illustrator CC (Windows)",
"modifydate": "2014-04-17T00:00:05Z",
"createdate": "2014-04-16T16:59:57-07:00",
"metadatadate": "2014-04-16T16:59:57-07:00",
"thumbnails": "",
"format": "image/jpeg",
"marked": "False",
"imagewidth": "1500",
"imagelength": "1239",
"bitspersample": "8, 8, 8, 8",
"photometricinterpretation": "1",
"orientation": "Horizontal (normal)",
"samplesperpixel": "4",
"xresolution": "1500000/10000",
"yresolution": "1500000/10000",
"resolutionunit": "2",
"exifversion": "0221",
"colorspace": "65535",
"pixelxdimension": "1500",
"pixelydimension": "1239"
}
}
]
Stitching Images
The output object also contains the output_stitch object if the stitching of the multiple images need to be done. The structure of output_stitch is given as :
"output": {
"output_stitch":{
"orientation": "vertical", //the orientation on how the images should be stitched, can be horizontal or vertical.
//Available orientation
// vertical
// horizontal
"alignment": "center", //defines how an image should be stitched, when the width or height of the to stitched image is smaller than the output image,
//Available alignment
// top/left
// bottom/right
// center
// if alignment is not passed then center alignment is set as default.
"background_color": "grey", //background color of the image used in background
// any color such as black, grey, red, green etc can be given as input.
// Black color is set as default color when no input color is given.
"mime_type": "image\/jpeg", //type or format of the output image
"filename": "stitched.jpeg", //output file name of the stitched image
"manipulator": "sharp" //manipulator that is used for the stitching process
//Available options for the manipulator:
// sharp
// jimp
}
}
"version" attribute
This attribute will contain the version of AME JSON structure. This will be used for backwards compatibility by the AME server.
Routes Path
AME allows you to query some information about the environment using different routes. You can check the version of application and supported input & output types by the different manipulator.
/version
This will return the current version of AME.
/marco
This will always return "polo" string back. Useful for checking if the server is running.
/get_supported_input_type
This returns the supported input types of the image manipulators in JSON format.
/get_supported_output_type
This returns the supported output types of the image manipulators in JSON format.