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

{
  "objectname": "name of the object",
  "description": "description of action",
  "prop": "name of property",
  "preset": "name of preset"
  "command": { definition of command set }
}

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

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

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

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

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

• 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"} } ] }

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:

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

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

GET http://host:port/app/api/json/imaging/{actionName}/{id}{/transform}

GET http://host:port/app/api/json/imaging

Legacy endpoint:

http://host:port/app/_plugins/WXM_RESTAPI/page/imaging.jspz

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.

• 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

GET http://host:port/app/api/json/catalog/imaging

Legacy endpoint:

http//host:port/app/_plugins/WXM_RESTAPI/page/catalog/imaging.jspz

Supported methods: GET, HEAD

Parameters

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

Response format

{
  "catalog": "list of image processing actions",
  "response": {
    "data": [ {
      "name": "name of the action",
      "description": "description of the action",
      "preset": "name of preset"
      "command": { description of command }
      }
    }
    ]
  },
  "links": {
    "href": "http://host:port/app/_plugins/WXM_RESTAPI/page/catalog/imaging.jspz"
  },
  "status": 200,
  "time": 29
}

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:

{
  "resize": [100,-1],
  "format": "png"
}

Example of array command set:

[
  {
   "command":"crop",
   "width":100
  },
  ["preset","identifierOfPreset"],
  {
    "resize": {"width":"50%","height":"50%"}
  }
]

commenting commands

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

{
  "resize": [100,-1],
  "$format_cpl20180812": "jpg",
  "format": "png"
}

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:

"resize": [100,-1],

Example of full syntax command:

"resize": {
   "width":100,
   "height":"proportional"
}

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:

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

w_100,h_100,c_resize

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

tx_hello

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

tx_"hello you!"

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

tx_"say ""hello""!"

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.

tx_"First line\nSecond line: \\n"

(the text will be:

first line
second line: \n

)

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

tx_"\u00a9xxx"

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

t_10%,+fixed,c_crop

"crop": ["fixed","10%"]

"crop": {
         "fixed":true,
         "top":"10%"
        }

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

  "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)

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.

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

factor value

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"

angle value

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"

boolean value

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

"fixed": true,
"centered": "false"

color value

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"

  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

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

  "font": "Arial"

  "font": "Arial|16pt"

  "font": "Candice|20%|bold"

  "font": "Candice|bold|italic"

• an array

  "font": ["Arial","16pt"]

  "font": ["Candice","20%","bold"]

  "font": ["Candice","bold","italic"]

• an object

  "font": { "name":"Candice", "size":"10%", "style":["bold","italic"] }

  "font": { "name":"Candice", "size":"10%", "style":"bold" }

• a number, that specifies the size in point

  "font": 24

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

  "gravity": "north"

• northeast means at the top right

  "gravity": "northeast"

• east means at the center right

  "gravity": "east"

• southeast means at the bottom right

  "gravity": "southeast"

• south means at the center bottom

  "gravity": "south"

• southwest means at the bottom left

  "gravity": "southwest"

• west means at the center left

  "gravity": "west"

• northwest means at the top left

  "gravity": "northwest"

• center means at the center

  "gravity": "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.

"shade": "45x90"

string value

A simple text or word

"text": "hello!"

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:

  "color": "red"

• object, specifying what properties to set:

  { "foreground":"red", "background":"black", "outline":"blue", "stroke":"5px", "shade":"45x90" }

  or
  

  { "color":"red", "background":"black", "outline":"blue", "stroke":"5px", "shade":"45x90" }

• 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

  "fixed":["50%","50%"]

  "fixed":[100]

  "fixed":true

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

Value	Description	Notes
BRICKS	brick pattern, 16×16
CHECKERBOARD	checkerboard, 30×30
CIRCLES	circles pattern, 16×16
CROSSHATCH	crosshatch pattern, 8×4
CROSSHATCH30	crosshatch pattern with lines at 30 degrees, 8×4
CROSSHATCH45	crosshatch pattern with lines at 45 degrees, 8×4
FISHSCALES	fish scales pattern, 16×8
GRAY0	0% intensity gray, 32×32
GRAY5	5% intensity gray, 32×32
GRAY10	10% intensity gray, 32×32
GRAY15	15% intensity gray, 32×32
GRAY20	20% intensity gray, 32×32
GRAY25	25% intensity gray, 32×32
GRAY30	30% intensity gray, 32×32
GRAY35	35% intensity gray, 32×32
GRAY40	40% intensity gray, 32×32
GRAY45	45% intensity gray, 32×32
GRAY50	50% intensity gray, 32×32
GRAY55	55% intensity gray, 32×32
GRAY60	60% intensity gray, 32×32
GRAY65	65% intensity gray, 32×32
GRAY70	70% intensity gray, 32×32
GRAY75	75% intensity gray, 32×32
GRAY80	80% intensity gray, 32×32
GRAY85	85% intensity gray, 32×32
GRAY90	90% intensity gray, 32×32
GRAY95	95% intensity gray, 32×32
GRAY100	100% intensity gray, 32×32
HEXAGONS	hexagon pattern, 30×18
HORIZONTAL	horizontal line pattern, 8×4
HORIZONTAL2	horizontal line pattern, 8×8
HORIZONTAL3	horizontal line pattern, 9×9
HORIZONTALSAW	horizontal saw-tooth pattern, 16×8
HS_BDIAGONAL	backward diagonal line pattern (45 degrees slope), 8×8
HS_CROSS	cross line pattern, 8×8
HS_DIAGCROSS	diagonal line cross pattern (45 degrees slope), 8×8
HS_FDIAGONAL	forward diagonal line pattern (45 degrees slope), 8×8
HS_HORIZONTAL	horizontal line pattern, 8×8
HS_VERTICAL	vertical line pattern, 8×8
LEFT30	forward diagonal pattern (30 degrees slope), 8×4
LEFT45	forward diagonal pattern (45 degrees slope), 8×8
LEFTSHINGLE	left shingle pattern, 24×24
OCTAGONS	octagons pattern, 16×16
RIGHT30	backward diagonal line pattern (30 degrees), 8×4
RIGHT45	backward diagonal line pattern (30 degrees), 8×8
RIGHTSHINGLE	right shingle pattern, 24×24
SMALLFISHSCALES	small fish scales pattern, 8×8
VERTICAL	vertical line pattern, 8×8
VERTICAL2	vertical line pattern, 8×8
VERTICAL3	vertical line pattern, 9×9
VERTICALBRICKS	vertical brick pattern, 16×16
VERTICALLEFTSHINGLE	vertical left shingle pattern, 24×24
VERTICALRIGHTSHINGLE	vertical right shingle pattern, 24×24
VERTICALSAW	vertical saw-tooth pattern, 8×16