Skip to content

API Documentation

Jump to bottom Edit New page
snapwiredev edited this page May 14, 2018 · 33 revisions

General operation

Input

{
  "input_url": <input file>,
  ...
  "operations": [
    {
      "type": <operation1 type>,
      "params": { ... }
    },
    {
      "type": <operation2 type>,
      "params": { ... }
    }
  ]
}

Response

{
  "result" : <result>,
  ...
  "info": [
    {
      "result": true/false,
      "type": <operation1 type>,
      ...
    },
    {
      "result": true/false,
      "type": <operation2 type>,
      ...
    }
  ]
}

Example command

This example generates a single thumbnail with a 230px width. Output sharpening is applied with a radius of 0.5 and a strength of 80%. The final image is saved as a jpeg with 85% quality without any original metadata.

NOTE: In this example the height parameter is provided as the absolute maximum height (e.g. if the thumbnail height more than 2000px the thumbnail width is proportionally scaled to a 2000px height).

Input

{
  "input_url": "file://input.jpg",
  "correct_rotation":true,
  "operations": [
    {
      "type": "resize",
      "params": {
        "type": "width",
        "width": 230,
        "height": 2000,
        "preserve_meta": false,
        "sharpen_amount": 80,
        "sharpen_radius": 0.5,
        "quality": 85,
        "watermark":false,
        "output_url": "file://output.jpg"
      }
    }
  ]
}

Response

{
  "result" : true,
  "time" : 0.18,
  "height" : 864,
  "width" : 1296,
  "info" : [
    {
      "type" : "resize",
      "result" : true,
      "output_url" : "file://output.jpg",
      "output_height" : 153,
      "output_width" : 230,
      "time" : 0.02
    }
  ]
}

Input parameters

The input_url is a required field and there needs to be at least one operation specified. All other fields are optional.

Type Name Description
string input_url The location of the input file (currently only supports local files). As of v0.2.0 the file:// prefix is entirely optional (when no prefix is provided the file is assumed to be local)
boolean correct_rotation Reads jpeg EXIF meta data to determine the proper orientation for the image. If true image rotation is corrected before producing thumbnail(s). Otherwise no rotation is performed. It is recommended to set this to true
boolean allow_skip_decode_image If true then arion will try to avoid decode image (less execution time). This useful when writing/reading IPTC info without resizing image. Please note that if operation is required to have image (like resize) then this param will be ignored. Limitations - if this param activated then arion not able to produce image width and height. Default value is false. From v0.5.2
object write_meta An object of fields to write into image metadata
list operations A list of operations to be performed on the image

Write_meta object

Type Name Description
string object_name Document Title
string urgency Specifies the editorial urgency of content and not necessarily the envelope handling priority. The "1" is most urgent
list subject This field can specify and categorize the content of a photograph by one or more subjects listed in the IPTC “Subject NewsCode” taxonomy available from http://www.newscodes.org/. Each subject term is represented as an eight-digit numerical string in an unordered list. Only subjects from a controlled vocabulary should populate this field; enter free-choice text in the Keyword field.
string category Identifies the subject of the object data in the opinion of the provider. A list of categories will be maintained by a regional registry
list supplemental_category Supplemental categories further refine the subject of an object data. A supplemental category may include any of the recognised categories as used in tag . Otherwise
string caption Store caption information
list keywords Store list of keywords
list location_name Provides a full, publishable name of a country/geographical location referenced by the content of the object, according to guidelines of the provider
string special_instructions Store special instructions about the image (IPTC-specific, more details [here](http://www.photometadata.org/meta-resources-field-guide-to-metadata#Special Instructions))
date date_created Represented in the form CCYYMMDD to designate the date the intellectual content of the object data was created rather than the date of the creation of the physical representation. Follows ISO 8601 standard.
string program Identifies the type of program used to originate the object data.
string program_version Used to identify the version of the program mentioned in tag .
list byline Contains name of the creator of the object data
list byline_title A by-line title is the title of the creator or creators of an object data. Where used
string city Store city to save
string province_state Store province/state to save
string country_code Indicates the code of the country/primary location where the intellectual property of the object data was created
string country_name Store country name
string transmission_reference A code representing the location of original transmission according to practices of the provider.
string headline A publishable entry providing a synopsis of the contents of the object data.
string credit Identifies the provider of the object data
string source Identifies the original owner of the intellectual content of the object data. This could be an agency
string copyright Store copyright information
list contact Identifies the person or organisation which can provide further background information on the object data.
list writer Identification of the name of the person involved in the writing

Operations list

Type Name Description
string type

The operation to perform

resize create one or more resized images from the source (i.e. thumbnails)
read_meta read header metadata
copy efficiently copy the image without any pixel manipulation
and write metadata provided by write_meta parameter (if any)
fingerprint get a unique identifier of pixel data (fingerprint)
object params Operation parameters

Operation parameters

resize operation

Type Name Description
string type

The type of resize to perform

width Thumbnail will be constrained by the width parameter
height Thumbnail will be constrained by the height parameter
square Thumbnail will be a square crop from the center of the image
fill Thumbnail will fill into the specified dimensions
integer width When type is width or square this will be the target width. When type is height this will determine the maximum width of the image
integer height When type is height this will be the target height. When type is width this will determine the maximum height of the image. When type is square this parameter is ignored
string gravity When the type is fill this will determine what region of the image will be cropped (see possible values below)
integer quality The output JPEG quality of the image
string interpolation

Interpolation method of resize

nearest nearest neighbor interpolation
linear bilinear interpolation
cubic bicubic interpolation
area (default) resampling using pixel area relation. It may be a preferred method for image decimation, as it gives moire-free results. But when the image is zoomed, it is similar to the nearest method.
lanczon4 Lanczos interpolation over 8x8 neighborhood
linear_exact Bit exact bilinear interpolation
string output_url The location to write the resize image (currently only supports local files). As of v0.2.0 the file:// prefix is entirely optional (when no prefix is provided the file is assumed to be local)
boolean preserve_meta When set to true all metadata (EXIF/IPTC/XMP) of the original image is saved and when false (default value) no EXIF data is saved. Arion also have a white list of data to save that not depends on that option. For 0.3.0 white list contains Exif.Image.Orientation and Exif.Image.InterColorProfile option
string watermark_url The location of the watermark file (currently only supports local files). The file must be a png with an alpha layer. As of v0.2.0 the file:// prefix is entirely optional (when no prefix is provided the file is assumed to be local)
string watermark_type

Watermark type (standard by default)

standard Apply an opacity based watermark
adaptive Apply an adaptive watermark that compensates for source image pixel brightness
float watermark_amount The amount to blend the watermark (0.0 - 1.0)

Only used when watermark_type is standard
float watermark_min The minimum amount to blend the watermark (0.0 - 1.0)

Only used when watermark_type is adaptive
float watermark_max The maximum amount to blend the watermark (0.0 - 1.0).

Only used when watermark_type is adaptive
integer sharpen_amount The amount of sharpening to apply to the thumbnail (must also include radius parameter)
float sharpen_radius The radius of the gaussian filter used to unsharpen the image. If excluded or set to 0.0 no sharpening is applied (must also include the amount parameter)
boolean pre_filter When set to true gaussian blurring is applied on the input image to help reduce aliasing during the resize operation. This is slow, but produces good results on images with high-frequency data. Disabled by default.

Gravity Parameter

Value Alt. Description
center c Focus on the center of the image
north n Focus on the top most region, horizontally centered
south s Focus on the bottom most region, horizontally centered
west w Focus on the left most region, vertically centered
east e Focus on the right most region, vertically centered
northwest nw Focus on the top left region
northeast ne Focus on the top right region
southwest sw Focus on the bottom left region
southeast se Focus on the bottom right region

See example usage.

read_meta operation

The read_meta operation reads EXIF/IPTC/XMP headers and returns key fields.

Type Name Description
boolean info

If set to true read the following from metadata

caption keywords
copyright city
province/state country name
country code instructions
See example usage.

copy operation

The copy operation simply copies an image byte for byte and then applies any meta data overrides provided in the write_meta parameter.

Type Name Description
string output_url The location to write the image copy (currently only supports local files). As of v0.2.0 the file:// prefix is entirely optional (when no prefix is provided the file is assumed to be local)
See example usage.

fingerprint operation

The fingerprint returns a unique image identifier based on the source image pixel data. This is useful for image duplicate detection or identification.

Type Name Description
string type

Fingerprint type

md5 Computes an md5 hash of the image pixel data
See example usage.

Output parameters

Type Name Description
boolean result Operation result. true if all operations were successful, false otherwise
float time Total execution time in seconds
integer height The height of the input image
integer width The width of the input image
list info The return information for each operation. The order corresponds to the order each input operation was provided.
Add a custom footer
Add a custom sidebar
Clone this wiki locally