Custom functions

Cloudinary supports injecting a custom function into the image transformation pipeline. You can either use a remote function/lambda as your source, run a WebAssembly function from a compiled wasm file uploaded to your product environment, or use a jq filter to select an asset to deliver.

To specify a custom function to call, use the custom_function parameter (fn in URLs). The parameter accepts an object detailing the function to inject as follows:

WebAssembly functions

Compiled wasm files may be uploaded as raw and authenticated resources to your Cloudinary product environment and then referenced in a custom function. Use the custom_function parameter with the function_type set to "wasm" (fn_wasm in URLs), and the source parameter set to the public_id of your compiled wasm file. If the public ID includes slashes, replace the slashes with colons (e.g., custom/example.wasm becomes custom:example.wasm).

For example, to deliver an image after running the WebAssembly functions located in a compiled wasm file:

1. Upload your compiled wasm file to your product environment as an authenticated raw file:

2. Deliver the oldman_village_st image after running the WebAssembly functions located in your now uploaded quantize.wasm file:

WebAssembly contract

Your wasm file should be compiled for a server environment (not JavaScript), and the WebAssembly functions in your compiled wasm file need to comply with a specific interface - you must provide the following 3 public functions:

1. alloc

Your alloc method needs to allocate memory according to the size given and then return a pointer to the allocated memory.

2. dealloc

Your dealloc method should deallocate memory at the given pointer, according to the size given.

3. transform

Your transform method should include the code you want to perform the actual transformation of the image. The method receives the image width, image height, a pointer to the pixel buffer (of size = width x height x 4) where the pixel scheme is guaranteed to be RGBA interleaved, a pointer to the metadata, and the metadata size.

Metadata is given as a JSON structure which contains:

• current_page - The current page in a multi-paged asset.
• variables - Any user-defined variables specified as part of the transformation.

You can pass files to WebAssembly functions as base64 encoded strings using file reference variables, as shown in this example.

The transform function must return a pointer to the output buffer that contains the following information: width as a 32 bit BigEndian, followed by the height as a 32 bit BigEndian, followed by the image pixel buffer (RGBA scheme again).

WebAssembly example

The following example applies a blur effect to an image:

Remote functions

You can call a remote function/lambda as part of the transformation chain. The remote function receives an input image file (PNG) along with metadata, and must return an image file (optionally along with metadata also). Use the custom_function parameter with the function_type set to "remote" (fn_remote in URLs), and the source parameter set to the URL of the custom function. The delivery URL also needs to be signed, which means also adding the sign_url parameter set to "true" to the SDK method.

For example, to deliver the 'sample' image after running the remote function located at 'https://my.example.custom/function':

The code generates a URL similar to:

Request structure

The URL of your remote function receives the following information in the HTTP POST request from Cloudinary:

Request headers:

• X-Cld-Timestamp - an integer value representing the time the request was sent in Unix time.
  
• X-Cld-Signature - a signature string for verification: the string is an SHA512 Hex-Digest of the timestamp + your API secret.

Request body:

• file - the (binary) image file.
  

• metadata - a JSON structure that includes the current_page, tags, coordinates (each key represents a coordinate source) and variables (key-value pairs representing variable names and values). For example:

Response structure

Your response should include the image Content-Type in the header and the image data in the body. For example, if using API Gateway to host your remote function then the response would be similar to:

The body of your response can contain just the image data or you can include new metadata as follows:

1. Start the response body with the string 'CLDB'.
2. Add 4 bytes (BigEndian) describing the byte length of the result image buffer.
3. Add the image buffer.
4. Add 4 bytes (BigEndian) describing the byte length of the result metadata JSON buffer.
5. Add the metadata buffer.

Sample remote function

The following code is an example of a remote function that is hosted on AWS lambda behind an API gateway and is written in JavaScript. The function resizes an image to a width of 314px and adds a text overlay of the current date (subsequent requests will retrieve this image from the CDN cache and the date will not change). It also returns new metadata:

Preprocessing custom functions (for remote functions)

You can insert your custom function earlier in the transformation chain, before Cloudinary does any processing whatsoever on the image. Whereas the remote function option described above is sent an image in PNG format, a preprocessing remote function is sent the original image file, as uploaded to Cloudinary. For example, you can upload images in a format Cloudinary does not support for transformations and use a custom function to return an image format that Cloudinary does support.

Only Remote Functions are supported for preprocessing as described above, except for the following differences:

1. Use the custom_pre_function parameter (fn_pre in URLs) to call the custom function to preprocess. The parameter accepts the same type of object as the custom_function parameter, detailing the function_type ('remote') and source.
2. The preprocessing function is sent the original unaltered image, plus any defined variables, and must return an image in a format that Cloudinary supports for transformations.
3. Any other Cloudinary transformations given are applied to the result of the preprocessing function: the custom_pre_function parameter is applied first, no matter its location in the transformation chain.

For example, to deliver the 'sample' image after preprocessing the remote function located at 'https://my.preprocess.custom/function':

The code generates a URL similar to:

Select custom functions

The select custom function (fn_select in URLs) can be used to deliver assets based on filters using tags and structured metadata. This feature can be used for eCommerce use cases such as:

• Assigning tags to all assets required for a 'product ID' and delivering the main image or video (aka the Hero Image) on Product listing pages (PLPs).
• Displaying images based on expected position in a product gallery on Product Detail Pages (PDPs). Here, the expected position can be assigned using SMD.
• Displaying alternate images (or videos) on PLPs when the user hovers on a product tile.
• Delivering assets using complex logic based on the existence of Structured Metadata.
  

The general URL syntax takes the form:

Where:

• cloud - your Cloudinary product environment's cloud name.
• resource_type - the type of resource to deliver, image or video.
• jq_filter - the jq filter to use for selecting the asset.
• transformations - (optional) any transformations to apply to the selected asset.
• tag - the tag for generating the list of assets.

Under the hood, the jq filter is applied to the JSON response from a client-side call to generate a list of all assets with the same tag. The jq filter would most commonly select a single public_id based on the values of structured metadata saved with the assets, but the filter can select based on any of the resource properties returned in the response.

An example of a JSON response snippet, listing assets with the same tag ('samples'):

jq filters

You select the asset by using a jq filter to return a single public ID which will then be delivered to the browser, along with any necessary transformations. jq is a popular command line parser for JSON, and you can create complex filters to fit your needs.

An example jq filter to select an asset where the value of its 'product-hero-image' metadata field is 'yes':

The filter must also be URL safe, so we need to convert it using a 3rd party library or tools such as URL Encode and Decode - Online to get:

Putting all the above in a single URL:

Note that running the jq filter above on the example response, returns the asset with a public_id of cld-sample.

Select base64 alternative

Instead of specifying the jq filter as a URL safe string, the select custom function also supports specifying the filter in base64 (url-safe variant), that not only makes the filter URL safe, but also pretty since there won't be any special characters. The syntax is similar to the above, except for using the parameter as fn_select:jqb64 to indicate that it's a base64 encoded filter.

For example:

JavaScript filters

You can use a JavaScript filter to select the asset to deliver, along with any necessary transformations. The filter is applied to the JSON response from a client-side call to generate a list of all assets with the same tag. The filter would most commonly select a single asset based on the values of structured metadata saved with the assets, but the filter can select based on any of the resource properties returned in the response.

The JavaScript filter should return details of the asset to deliver as an object, for example:

JavaScript files may be uploaded as raw authenticated assets to your Cloudinary product environment and then referenced in a custom function. Use the custom_function parameter with the function_type set to select:js (fn_select:js in URLs), and the source parameter set to the public ID of your JavaScript file. If the public ID includes slashes, replace the slashes with colons (e.g., custom/example.js becomes custom:example.js).

For example, to deliver an image based on the result of a filter located in a JavaScript file that runs on the JSON response from a list of assets with the 'samples' tag:

1. Upload your JavaScript file to your product environment as an authenticated raw file:

2. Deliver the image after running the select filter located in your now uploaded my_example.js file on the JSON response from a list of assets with the 'samples' tag:

   

JavaScript file contents

The JavaScript file must contain a single main function that then returns the asset to be delivered. Additionally, the following calls can be made within your code to access relevant data:

• getDocument() - returns the response of a call to list all assets with the same tag, or the contents of a custom data file (see below).
• getContext() - returns an object listing all the transformation parameters used in the dynamic URL as well as the public ID. For example, for the URL, https://res.cloudinary.com/demo/image/list/fn_select:js:match-resource.js/c_scale,w_150/samples.json:
  • getContext()["transformation"] returns "fn_select:js:match-resource.js/c_scale,w_150/json".
  • getContext()["resource"] returns "samples".

For example, to select the asset where the value of its "product-hero-image" metadata field is "yes":

You can also add a transformation into the code, for example to scale the image to 150 pixels in width (this is the JavaScript in my_example.js from above):

Alternatively, you can add a transformation into the URL itself:

If you want to set a transformation in the JavaScript in addition to in the URL, you can use the getContext() function to get the URL transformation, extract the transformation after the fn_select component, and combine them:

For the following example, getContext()["transformation"] (from the code above) returns fn_select:js:combine-tx.js/e_grayscale/a_30/f_png/json, so extractTransformation is used to return only e_grayscale/a_30/f_png. This is then added to the c_scale,w_150 transformation.

Custom data file

The JavaScript filter can be applied to a custom data file instead of applying the filter to the JSON response listing all assets with the same tag.

You first upload the custom data file as a raw asset to your Cloudinary product environment and then the JavaScript filter is applied in the delivery URL for that raw custom file.

The general URL syntax for applying a JavaScript filter to a raw custom file takes the form:

Where:

• cloud - your Cloudinary product environment's cloud name.
• type - the type of the uploaded raw file, either upload, authenticated or private.
• js_file - the public_id of the JavaScript filter uploaded as a separate raw file.
• transformations - (optional) any transformations to apply to the selected asset.
• data_file - the public_id of the raw custom data file.

The JavaScript filter still needs to return the asset to deliver, but the filter can now be applied to any information you supply in the custom data file.

For example, to apply the JavaScript filter uploaded as a raw file called "my_example.js" to the source data file uploaded as "sample-db.txt":

Refine custom functions

You can use the refine custom function (fn_refine in URLs) to filter the list of assets returned when using the list delivery type (see Client-side asset lists for syntax details).

You can use this, for example, to hide confidential metadata that you don't want to be made publicly available on the client side.

Specify the filter as JavaScript code, uploaded to your product environment as an authenticated raw file.

1. Create your JavaScript file. In this example, the JavaScript code filters the response from the list call to return details of assets that are of format jpg and smaller than 500 pixels in height, excluding the metadata field from each asset's response:

   format-height-no-metadata.js
   Notes

   1. The code must contain a main() function.
   2. getDocument() is a function built into Cloudinary, which returns the response of the list API call.

2. Upload your JavaScript file to your product environment as an authenticated raw file (here, we're also setting the public ID to docs/format-height-no-metadata):

3. Deliver a JSON file containing the refined list response for assets tagged amazing, based on the code in the JavaScript file (note that any slashes (/) in the public ID are replace with colons (:)):

   This is the returned JSON:

   Tip

   Compare this with the unrefined list response.