If you have ever come across the documentation for the /upload/handle and /image/resize Robots, you may have seen the output_meta parameter. You may then also have wondered what exactly it does. After all, unlike with most other parameters, its use might not be immediately clear from the name alone :)

So, why not take a moment to explain how this parameter works, and why it was created!

The output_meta parameter

The idea behind the output_meta parameter is to give our customers the ability to collect certain metadata about their files. Sounds nice to have on all the time, right? Well, it is also a lot more taxing on CPU power to calculate. So, in order to keep those Assemblies running fast all the time, we made a parameter for the collection of some metadata and kept it disabled by default.

You can define the output_meta parameter on our Robots' Steps in order to choose whether you want extra metadata per encoding result. While this gives our users the luxury of fine control and granularity, it also led to a problem: how do you enable it for uploaded files? We have supported file uploads since 2008, but they have always been a bit of an odd duck, because uploads used to be the only files that weren't the result of our Robots.

So, after the introduction of fine-grained control through the output_meta parameter, the next logical step was to encapsulate upload handling in a Robot of its own and launch the /upload/handle Robot alongside the new parameter. Now there are no more exceptions, and behavior can be modified at every Step for every file.

A drawing of the /output/meta Robot, with it using a magnifying glass to get metadata from the image it's holding.

How does it work?

The output_meta parameter accepts an object. For now, however, we only have the boolean property has_transparency available. If this property is set to true, it analyzes the image and tells you if it has transparent parts. Since calculating has_transparency can take a long time for certain files, we have it excluded from the result set by default. After all, we don't want to have our customers paying a premium in execution time if they don't even care about this property in the first place.

If you do want to know whether, for instance, your uploaded files have transparent areas, you can set "output_meta": { "has_transparency": true } on the /upload/handle Robot, after which you'll find meta.has_transparency set on the resulting files.

Let's take a look at how to build an Assembly that uses this parameter. Feel free to follow along!

Creating the Assembly

In this section, we will be creating two separate Assembly Instructions, which will show us how the parameter is used in both the /upload/handle Robot and the /image/resize Robot.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle",
      "output_meta": {
        "has_transparency": true
      }
    }
  }
}

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "resized": {
      "use": [":original"],
      "robot": "/image/resize",
      "result": true,
      "background": "white",
      "flatten": false,
      "height": 500,
      "imagemagick_stack": "v2.0.3",
      "resize_strategy": "pad",
      "rotation": 0,
      "strip": true,
      "trim_whitespace": true,
      "width": 250,
      "output_meta": {
        "has_transparency": true
      }
    }
  }
}

Here, we have two different sets of Assembly Instructions. One using only the /upload/handle Robot and the other using the /image/resize Robot.

Notice that in the Assembly Instructions that feature the /image/resize Robot, the output_meta property does not appear in the :original step, but in the resized step. This is because in these Assembly Instructions, we are testing for transparency when the file is being resized and not when it is uploaded.

The results

After running any of the above Assembly Instruction sets, we can see from the JSON result for the /upload/handle Robot that the meta property of the uploads key has a field called has_transparency, which is set to true. This property only returns true if the image has transparent parts.

Likewise, for the JSON result returned for the /image/resize Robot, the meta property of the resized key under the results section has a field called has_transparency, which is set to true.

As you can see, the output_meta parameter can be quite handy! We're also considering to let you opt out of other existing meta keys in order to speed up Assemblies. For instance, we're currently calculating MD5 hashes for all files by default, even though many use cases may not need that. So, as soon as we have more properties that can be specified with this parameter, we'll be sure to let you know! 💖