Imaging : downloading and applying image transformations

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

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

• 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:

      { "presetSuffix": "eval:org.apache.commons.io.FilenameUtils.getExtension(fileinfos.getName())=='mp4'?'jpg':'png'" }

    • The body of a slightly more complex function

      Example:

      { "presetSuffix": "eval:var extension=org.apache.commons.io.FilenameUtils.getExtension(fileinfos.getName());switch(extension){case'jpg':case'png':return extension;default:return'jpg';}" }

    • 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:

      { "fileFilter": "png" }

    • 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:

        { "fileFilter": "eval:org.apache.commons.io.FilenameUtils.getExtension(fileinfos.getName())=='jpg'" }

      • The body of a slightly more complex function

        Example:

        { "fileFilter": "eval:var extension=org.apache.commons.io.FilenameUtils.getExtension(fileinfos.getName());switch(extension){case'jpg':case'png':return true;default:return false;}" }

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

    Example:

    { "fileFilter": ["png","jpg"] }

  • 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:

        { "fileFilter": { "extension":"jpg" } }

      • 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:

        { "fileFilter": { "extension":["jpg","png"] } }

        Example 2:
        
        

        { "filter": { "mimetype":["application/pdf",{"startswith":"image/"}] } }

    • Property as logical operator.

      • or The value must be an array of conditions.

        Example:

        { "fileFilter": { "or": [ {"path": {"ct":"/asset/"}}, {"path": {"ct":"/legacy/"}} ] ] } }

      • and The value must be an array of conditions.

        Example:

        { "fileFilter": { "and": [ {"extension":"jpg"}, {"length":{"<":"2MiB"}} ] ] } }

      • not The value must be an object

        Example:

        { "fileFilter": { "not": { "extension": ["zip","mp4"] ] } } }

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

    Example:

    { "fileFilter": [ { "extension":"jpg" }, { "extension":"png", "length":{"<":"2MiB"} } ] }

There are two endpoints available:

• To download a file

• To get a list of available actions

• No parameter endpoints: 11.12

  GET http://host:port/app/media/{actionName}/{id}{/transform}
  GET http://host:port/app/rest/media/{actionName}/{id}{/transform}

11.14

11.12

Legacy endpoint:

Supported methods: GET, HEAD

• 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

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>.

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

11.12

Legacy endpoint:

Supported methods: GET, HEAD

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

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

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:

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.

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.

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:

  +fixed

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.

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:

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

  "width": "100", "height": 100

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

  "width": "100px", "height": "100 px"

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

  "width": "2f", "height": "0.5f"

  means doubled width and halved height.

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

  "width": "200%", "height": "50p"

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

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.

  "width": "50mm"

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

  "width": "50'"

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

  "width": "72pt"

Defines a factor.

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

  "width": "2", "height": 0.5

  means doubled width and halved height.

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

  "width": "2f", "height": "0.5×"

  means doubled width and halved height.

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

  "width": "200%", "height": "50p"

Defines an angle value, in degrees by default.

• a number means a value in degrees

  "rotate": -45

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

  "rotate": "45°"
  "rotate": "60deg"
  "rotate": "-120 deg"

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

  "rotate": "3.14rad"

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

  "rotate": "1.5pi"

  means ³⁄₂ × π

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

  "rotate": "2>"
  "rotate": "right"

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

  "rotate": "left"
  "rotate": "2left"

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

Defines a color, with

• html color name

  "color": "red"

• gray level

  "color": "gray50"

• hexadecimal RGB code

  "color": "#FF0000"

• word none, for transparent color

  "color": "none"

• 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

  "color": [255,0,0]
  "color": [255,0,0,"50%"]
  "color": [255,0,0,0.5]

• 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

    "color": "$dom"

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

  "color": "$gradient:red-blue"

  You can specify an extent with a dimension value:

  "color": "$gradient:red-blue-50%"

  No color value means none:

  "color": "$gradient:red"

  is equivalent to

  "color": "$gradient:red-none"

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

  "color": "$pattern:checkerboard"

  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.

    "color": "$blur:25x25"

  • $blur is equivalent to $blur:3x3

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

  "font": "Arial"
  "font": "Arial|16pt"
  "font": "Candice|20%|bold"