The latest Fast Track version of Nuxeo, Nuxeo Platform 7.1, was released a few days ago. It contains some amazing new features and enhancements (see the Release Notes for a quick overview). Among these new features, there is one that allows easy conversion and manipulation of pictures using a RunConverter operation. This new way to convert and transform pictures to any size, color, or format is easy and awesome! For any Digital Asset Management solution, this feature will go a long way in organizing and searching image files, converting them to meet your needs, and re-purposing them efficiently. Let’s talk about this RunConverter operation, since it’s incredibly useful(1)!

The goal of this operation is to let you convert or transform pictures without having to write a dedicated Java plug-in for it. All you have to do is simply declare the conversion in XML, which can be done in Nuxeo Studio in seconds(2).


Conversion to gray and max 600 pixels width/400 pixels height

Easy Picture Conversion and Manipulation

Converting or transforming images in Nuxeo has never been easier. Whether you want to convert any image to png, watermark a picture, resize it, or make it B&W - it’s all possible. In Nuxeo Studio, you just have to add some lines of XML and the Automation Chain that uses the Blob.RunConverter operation. Yes, it’s that simple! Following are the steps::

  • Contribute (via XML) a _CommandLine _with its unique name
  • Contribute (also via XML) a Converter with a unique name which uses this command line
  • You can now use the Blob.RunConverter operation, which expects the name of the converter and optional parameters

Let’s take an example where you want to convert a picture to Gray color, with a maximum size of 600 pixels (width) and 400 pixels (height), using ImageMagick. A good trick before testing a conversions in Nuxeo is to run it at the command line level. So to achieve what we want in this example, we have to:

convert the-image.jpg -resize 600x400 -colorspace Gray the-image-gray.jpg

First, create a new XML Extension (Project > Advanced Settings > XML Extensions) in Nuxeo Studio and give it a name, (in our example it is “max600x400Gray”). In this XML, copy and paste the following declaration:

  <command name="max600x400Gray" enabled="true">
    <parameterString>#{sourceFilePath} -resize 600x400 -colorspace Gray  #{targetFilePath}</parameterString>
    <installationDirective>You need to install ImageMagick.</installationDirective>

<extension target="org.nuxeo.ecm.core.convert.service.ConversionServiceImpl"
  <converter name="max600x400Gray"
      <parameter name="CommandLineName">max600x400Gray</parameter>
  • We first declare the CommandLine which ultimately performs the conversion. We are using only two dynamic parameters here, and these parameters belong to the operation itself: sourceFilePath and targetFilePath. sourceFilePath will be replaced by the full path of the picture and tagetFilePath by the path of the resulting file after conversion (used by the operation to build the resulting blob).
  • Then we declare the Converter that will be used by the operation. This declaration is quite basic where we just reference our CommandLine contribution.

Notice that they both have the same name, “max600x400Gray”. It’s not a requirement to give the same name, but I find it convenient.

We can now create an Automation Chain using our converter. Let’s call it “DownloadAsGrayPNG”. We end it with “PNG” because we want to convert the picture to PNG in this example. The chain will use the picture embedded in the current document, convert it to gray-PNG-max-600x400 and let the user download it. Here it is:


targetFileName is a special parameter belonging to the operation It lets you to give an explicit name to the result file.

This is exactly what we want to do here, because that’s how ImageMagick converts one format to another - by just looking at the file extension of the destination file. So, when the operation is called its input is the blob of the document (after the call to Files > Get Document File). We can use the This object to get the current file name of the picture (for example “Island.jpg”). We just have to add the suffix (“-gray”) and the extension we need (“.png”).

For testing this, we can create a new User Action, bind it to our “DownloadAsGrayPNG” Automation Chain, save, deploy on the test server, and voilà (cf. the first screen shot of this blog).

With Dynamic Parameters

In previous example, we hard-coded the maximal width and height of the resulting picture. Now we will see how to make these parameters dynamic. Here are the steps:

  • Add two variables to the CommandLine declaration. maxWidth and maxHeight For example:

      <parameterString>#{sourceFilePath} -resize #{maxWidth}x#{maxHeight} -colorspace Gray #{targetFilePath}
  • Now, fill these parameters while calling the operation:

      targetFileName[email protected]{This.filename}-gray.png
  • Of course, you can use a dynamic MVEL expression:

      targetFileName[email protected]{This.filename}-gray.png
      maxWidth[email protected]{an expression for the width}
      maxHeight[email protected]{an expression for the height}
  • (Also, you can rename the converter if you want)

No Limits to the Power

The main principle here is to avoid writing a Java plug-in and to do everything in XML and Automation. Thanks to Nuxeo Platform 7.1, you can now very easily use the full power of ImageMagick. For example:

  • Generic converter using ImageMagick:

    • The command line would be just #{sourceFilePath} #{targetFilePath}:

        <command name="convertToAny" enabled="true">
        <parameterString>#{sourceFilePath} #{targetFilePath}</parameterString>
    • The parameters of the operation just add the correct extension:

        targetFileName[email protected]{This.filename}.png


        targetFileName[email protected]{This.filename}.jpg

      You can even convert your pictures to pdf:

        targetFileName[email protected]{This.filename}.pdf
  • Convert a PDF to a picture

    • Here, there is a trick! You must tell ImageMagick which page must be converted by adding [page-number] to the sourceFilePath parameter:

        <command name="convertPDFToImage" enabled="true">
        <parameterString>#{sourceFilePath}[0] #{targetFilePath}</parameterString>
    • The parameter of the operation could be the destination format:

        targetFileName[email protected]{This.filename}.png


        targetFileName[email protected]{This.filename}.jpg
  • Add a Watermark:

    • You will find in our documentation an example of Watermarking. The command line is quite long in this case:

        #{sourceFilePath}  -gravity #{gravity} -fill #{textColor} -stroke #{strokeColor} -strokewidth #{strokeWidth} -pointsize #{textSize} -annotate #{textRotation}x#{textRotation}+#{xOffset}+#{yOffset} #{textValue} #{targetFilePath}

There is something awesomely cool about this operation - since it wraps a CommandLine, you are not limited to ImageMagick. For example, you can use GraphicsMagick instead if you wish (for better performance) or ffmpeg to cut a video by raw copy:

  • The command line:

      <command name="ffmpegCutByCopy" enabled="true">
      <parameterString>-i #{sourceFilePath} -ss #{start} -t #{duration} -c copy #{targetFilePath}</parameterString>
  • In this case, the parameters of the operation could be (cutting at one minute for 10 seconds):

      targetFileName=From-0100-for-10[email protected]{This.filename}

A quick notice on the availability: This operation is available in the FastTrack release only. If you need it with your Long Time Support version (Nuxeo Platform 6.0), you can instead use nuxeo-labs.

(1) Don’t get me wrong: All the new features are incredibly useful (2) Isn’t life so cool?