Imaging : downloading and applying image transformations

Introduction

The endpoint of this service allows to download images with some transformations.

Configuration

Each action is associated to an identifier and a JSON configuration.

JSON example

Properties and sections

• objectname: String - Name of the object (type)

• description: String - Short description of action

• prop: String - Name of property that contains the file or image

• preset: String, optional - Name of the preset

• commands: JSON object (or array), optional - A command set (a list of transformation commands). If this property is set, preset property is ignored.

• strip: Boolean, default to true. If set, the metadata are removed from the file.

• rscname: JSON, optional - The description of name for attachment (see "Download image or file" for details).

• 11.19 exposeAsPreset: Boolean, default to false. If set, a preset is automatically created using the transform of this action. This feature does’nt work with dynamic (with parameters) transform. The object type, object property and attachment name are not relevant for preset.

• 11.19 presetSuffix: String - Suffix of preset if exposed. This could be:

  • a simple extension

    Example:

    { "presetSuffix": "png" }

  • the keyword $original to specify the suffix is the original file extension

    Example:

    { "presetSuffix": "$original" }

  • an evaluable expression, starting with eval:. The language is JavaScript. Choose a simple and quick expression to execute. The image file is represented by the variable fileinfos. The type of the evaluated value must be String. The value could be:

    • a simple expression statement. In this case the return could be omitted.

      Example:

    • The body of a slightly more complex function

      Example:

    • if the property is not set, we try to evaluate the extension according to the commands if possible. If the extension is undetermined, a default extension will be selected by the preset process.

• 11.19 presetName: String - Name of preset. If not set, the name of prefix is the concatenation of preset default prefix (see configuration of plug-in) and action name, normalized to preset name.

• 11.19 presetDescription: String - Description for preset. If not set, the action description will be used.

• 11.20 fileFilter: Different types of data - filter for preset. This filter determines if the preset can be built for the presented file.

  • String. An extension or an evaluable JavaScript expression.

    • An extension. The preset is built if the extension of the input file is equal to this one.

      Example:

    • An evaluable JavaScript expression, if string starts with eval:. The language is JavaScript. Choose a simple and quick expression to execute. The image file is represented by the variable fileinfos. The type of the evaluated value must be boolean. The value could be:

      • a simple expression statement. In this case the return could be omitted.

        Example:

      • The body of a slightly more complex function

        Example:

  • a String array, as a list of file extensions for which the preset can be built.

    Example:

  • a JSon Object, as an conditional expression (and combination of all properties)

    • Property as variable

      • extension: extension of file

      • mimetype: mimetype of file

      • name:name of file

      • basename:name of file (without extension)

      • path: relative to san path of the file

      • length: length of file (bytes)

      • lastmodified: last modified timestamp (unix epoch time)

        Value is the test to be performed, as

      • a simple value. To check if the variable is equal to the value

        Example:

      • an object, and combination of all properties, where name is an operator and value, the value to be used with the operator, or an array of values (combined with an or)

        • eq or =: testing for equality

        • ne or !=: testing for difference

        • gt or >: testing for greater than

        • gte or >=: testing for greater than or equals

        • lt or <: testing for lower than

        • lte or ⇐: testing for lower than or equals

        • sw or startswith: testing for lower than

        • ew or endswith: testing for lower than or equals

        • e or empty: testing for is empty

        • ct or contains: testing for contains

        • mt or matches: testing for regular expression (java)

      • an array. or combination of all items

        Example 1:

        Example 2:
        
        

    • Property as logical operator.

      • or The value must be an array of conditions.

        Example:

      • and The value must be an array of conditions.

        Example:

      • not The value must be an object

        Example:

  • an array, as a combination table of the above types

    Example:

EndPoints

There are two endpoints available:

• To download a file

• To get a list of available actions

EndPoint: Transform and download an image

• No parameter endpoints: 11.12

11.14

11.12

Legacy endpoint:

Supported methods: GET, HEAD

Parameters

• actionName: String - Action identifier

• id (or form_id): Object identifier (mandatory)

• commands: String, or JSON, optional - A preset or a command set, to replace the default configured one. If the parameter contains a simple String, it is considered as a preset name, and if it contains JSON, it is considered as command set.

• transform: String, optional - A command set using simplified syntax.

• 11.13 attachment: boolean, optional (default is true): specify if the Content-Disposition header is set (with filename) or not

Response format

The transformed image is returned in the body, as attachment. The response contains the following specific header:

• Content-ID: the ID of the content. The form of the content ID is <the name of the view>.

Security

The imageprocessing action of the RESTAPI domain allows the management of endpoint call authorisation. Its unique parameter is actionName, the action identifier.

Error codes

EndPoint: available action list

11.12

Legacy endpoint:

Supported methods: GET, HEAD

Parameters

• actionName: Character string, an optional Regular Expression type filter (by default, all accessible actions are displayed)

Response format

Security

The catalog action of RESTAPI domain allows the management of the endpoint call authorisation. Its unique parameter is endPoint, with a imageprocessing value.

Error codes

Command set

Introduction

A command set is a list of commands that will be executed one after the other on the image. There are three different forms of syntaxes:

• simplified: this syntax could be used within the transform parameter. The syntax is very simplified but not all options are available

• short syntax: this syntax use arrays to shorten commands and the parameters aren’t explicitely named. This syntax is less flexible than the full syntax

• full syntax: this syntax use object to configure each command and all options are available with it.

A command set can be configured as an object, where each property is a command name. As the JSON syntax doesn’t allows to have several properties with the same name, you can use an array of objects (JSON object with command property, JSON array with command name as first item, or object with a single property) .

Example of object command set:

Example of array command set:

commenting commands

A command can be temporarily disabled by commenting its name: just prefix the name with the dollar character ($).

To comment a command in simplified syntax, take care to put the $ at the beginning of the name of command, not before the prefix, like this by example: w_100,h_100,c_resize,e_png,c_$format. The command and all its parameters are skipped in that case.

short syntax versus full syntax

Example of shorten syntax (array) command:

Example of full syntax command:

The array syntax is shorter, but you’ll have to care of the order of parameters, and sometimes some ambiguities will force you to use the full syntax. Note that full syntax allows some default values for missing parameters that cannot be handled in short syntax.

the simplified syntax

This syntax does not use JSON syntax. The command set is defined by a comma separated list of parameters:

• a prefix (one or two letters) followed by an underscore then by a value. The prefix defines the type of value:

  • c for a command name

  • w for width

  • h for height

  • etc

• a name without underscore possibly prefixed by a + or a -
  by example:

This kind of parameters are boolean switches. By default, the value is true. The prefix - set it to false and the prefix + explicitly set it to true.

Each command is preceded by its parameters.

Example:

Simple text (without spaces or special characters) can be specify also:

To specify text with spaces, or other special characters, embrace it between double-quotes:

You can put double-quotes within text by duplicate them:

Use antislash \ to escape special characters, like \n for carriage return. Use two of them to get an antislash: \\n means exactly \n, not carriage return.

(the text will be:

)

You can use \u followed by unicode codepoint (four hexadecimal digits mandatory) to specify special characters:

(the text will be: ©xxx)

Spaces are not allowed in shorten syntax, except within texts.

values

Except for switches, the values for the parameters are the same for all syntaxes. For switches, in full syntax, use the values true or false, and in short syntax, only the name of the switch.

By example, these three syntaxes mean the same:

dimension value

Defines a dimension (x, y, width, height, top, right, bottom or left) in pixels. It could be absolute or relative to the size of the image.

• a positive number means an absolute size in pixels

• a positive number followed by px means an absolute size in pixels

• a positive number followed by f (or ×) means a factor

  means doubled width and halved height.

• a number followed by % (or p) means a percentage

• the word proportional could be used as value in some commands (you can use also the number -1)

size value

Defines a dimension in different units. The same values as used for dimension value could be used, and the followed additional syntaxes:

• a number followed by mm means a size in millimeters.

• a number followed by a quote means a size in inches.

• a number followed by pt means a size in points.

factor value

Defines a factor.

• a positive number means a factor: the final size will be the original size multiplied by the factor

  means doubled width and halved height.

• a number followed by f (or ×) means a factor

  means doubled width and halved height.

• a number followed by % (or p) means a percentage

angle value

Defines an angle value, in degrees by default.

• a number means a value in degrees

• a number followed by ° or deg means an angle in degrees:

• a number followed by rad means an angle in radians:

• a number followed by pi, (or % or π) means pi multiplied by the value:

  means ³⁄₂ × π

• an integer followed by >, (or "right") means a clockwise 90 degrees rotation (number 1 may be omitted):

• an integer followed by <, (or "left") means a counterclockwise 90 degrees rotation (number 1 may be omitted):

boolean value

Defines a boolean. Value can be true or false (JSON boolean or string).

color value

Defines a color, with

• html color name

• gray level

• hexadecimal RGB code

• word none, for transparent color

• an array of RGB (three components for red, green and blue, between 0 and 255 included) or RGBA (four components adding alpha component to RGB components, between 0.0 and 1.0 included or "0" and "100%") components

• a string starting with $dom to specify the dominant color of the image. It can be followed with the index of the dominant color.

  • $dom means the first dominant color

  • $dom2 means the second dominant color

  • $dom2-1 means the second dominant color, skipping the first one

• a string starting with $gradient:, followed with the starting and the ending colors, separated by a dash, to specified a vertical gradient.

  You can specify an extent with a dimension value:

  No color value means none:

  is equivalent to

• a string starting with $pattern:, followed with the name of a pattern, to specified a pattern.

  2021.6 The name of the pattern could be followed by a scaling factor, separated with an asterisk. Example : $pattern:checkerboard*5 (multiply size by 5).
  See list of Available fill patterns below.

• the string $blur, or a string starting with $blur: followed with blur parameters, to specify a blur of the background image.

  • blur parameters: It’s two positive integers separated with an x. The first is radius and the second sigma.

  • $blur is equivalent to $blur:3x3

font description

Defines a font, with a font name (a string), a font size (cf "size value"), font styles (bold, italic…​).

• a string, with component separated with a pipe

• an array

• an object

• a number, that specifies the size in point

Font styles are a combination of different parameters:

• style

  • Italic

  • Oblique

• weight

  • Thin

  • ExtraLight

  • Light

  • Medium

  • DemiBold

  • Bold

  • ExtraBold

  • Heavy

• stretch

  • Condensed

  • Expanded

  • ExtraCondensed

  • ExtraExpanded

  • SemiCondensed

  • SemiExpanded

  • UltraCondensed

  • UltraExpanded

When the font size is relative (to the height of image, in percent, or fraction), the pointsize is computed taking into account a default standard resolution of 96 DPI. It’s possible to be take into account the resolution of the image (yDPI) with the parameter (or switch) tiad.

text decoration parameter

Specifies a text decoration, one of these values:

• None

• Underline

• LineThrough

• Overline

gravity value

Specifies a location in the image, like in this grid:

• north means at the center top

• northeast means at the top right

• east means at the center right

• southeast means at the bottom right

• south means at the center bottom

• southwest means at the bottom left

• west means at the center left

• northwest means at the top left

• center means at the center

Gravity often can be mixed with a location by coordinates (x and y):

• if both coordinates are provided, gravity value is ignored

• if only one of the two is provided, gravity is used to locate on other axis

preset value

Designates a preset name (cf presets documentation)

shade parameters

It’s two positive integers (angles in degrees) separated with an x. The first is direction and the second elevation, of a light source.

string value

A simple text or word

text color parameters:

It consists of several parameters to colorize a text:

• foreground: a color value, white by default. The color of characters

• background: a color value, none by default. The color of background

• outline: a color value, white by default. The color of the text outline (borders)

• strokewidth: a dimension value, 1 by default. The thickness of the outline

• shade: shade parameters, ignored by default. The shade effect

The text color parameters can be configured as

• single string value: it is considered as foreground:

• object, specifying what properties to set:

  or
  
  

• an array
  
  

  • [foreground]

  • [foreground,shade]

  • [outline,strokewidth]

  • [outline,strokewidth,shade]

  • [foreground,background]

  • [foreground,background,shade]

  • [foreground,outline,strokewidth]

  • [foreground,outline,strokewidth,shade]

  • [foreground,background,outline]

  • [foreground,background,outline,strokewidth]

  • [foreground,background,outline,shade]

  • [foreground,background,outline,strokewidth,shade]

fixed size parameter

A boolean or a couple of dimension values. Values can be:

• true: fixed size activated with default size

• false: fixed size deactivated

• one dimension value: fixed size activated with width and height equal to this value

• an array of two dimension values: fixed size activated with width and height respectively equal to the first and second values from the array

overlay parameter

Used to configure an overlay for watermarking

colorization

A color blending factor (in percent from 1 to 100), or an array of three factors, one for each color channel (red, green and blue), or a string that contains the triplet like 50,25,70 or 50|25|70.

commands

simplified command shortcuts

Some commands have shortcuts in simplified syntax. The command name is useless in a shortcut, but it is not possible to chain several commands.

crop

• Provide x, y, width and height parameters to crop to a boundary box.

  Example: x_10,y_10,w_100,h_100

• Provide top, right, bottom and left to crop on insets.

  Example: t_10,r_10,b_10,l_10

• Provide border to crop on insets.

  Example: bd_10

format

• Provide extension to format

  Example: e_png

• Provide preset to apply preset

  Example: n_circle_png

rescale

• Provide factor to rescale

  Example: f_2f

resize

• Provide width and height to resize

  Example: w_100,h_100

• Provide width or height to resize

  Examples: w_100 or h_100

rotate

• Provide angle to rotate

  Example: a_45

watermark

• Provide text, font, background and foreground to draw centered text on image

  Example: f_Candice|24|bold,tx_"\u00a9Wedia",bg_black,fg_#00A5C8

• Provide font, text and foreground to draw centered text on image

  Example: f_Candice|24|bold,tx_"\u00a9Wedia",fg_#00A5C8

• Provide font, text and background to draw white centered text width background on image

  Example: f_Candice|24|bold,tx_"\u00a9Wedia",bg_black

• Provide font and text to draw white centered text on image

  Example: f_Candice|24|bold,tx_"\u00a9Wedia"

Available fill patterns