ImageProcessor for Apps

[Mario]

In order to implement some features for the upcoming IMatch Anywhere 2018™ I had to add image processing features in IMWS. These will also be accessible for apps running in IMatch.

TL;DR;

IMWS will gain a powerful feature for processing images in future versions.


For IMatch WebViewer and other projects accessing IMWS I needed something that allowed me to perform several tasks:

+ Create a resized version of an image managed in IMatch, in JPEG, PNG, GIF and TIFF format.
+ Use either the original image, the original with favor of the embedded preview, the IMatch cache image (if running in IMatch) or one of the cache images managed by IMWS as the source.
+ Place the image on a canvas (with fill color or even image fill)
+ Add text overlays (for image captions, watermarks, copyright notices)
+ Add image overlays (for watermarks, signs, logos)
+ Add selectable metadata

Probably you've guessed it already, it's basically the IMatch Batch Processor feature set, but accessible in IMWS.
So I separated the batch process engine, stripped what was not needed and implemented a new endpoint named /imageprocessor for IMWS. Still, it was a bit of work, especially processing and handling the over 50  possible parameters. No worries, many have defaults so you can get this working with very little code.

There is also a mode where you create a 'blank' image from scratch, without using an original. This is a great way to do QR codes or just produce an image by combining multiple other images via overlays.

It's quite clever and supports both GET and POST requests!

Using it with a GET request allows you to generate images on-the-fly for <img> tags, or even for download links ("Download this image").

The POST request allows you to create derivative images on the server (the machine running IMWS/IMatch), which makes this a powerful tool for implementing things like image galleries, file uploaders and similar. For this kind of app you probably only need the "give me a 600 pixel version of this file" functionality.

In the IMatch WebViewer context I can now add features to allow download of "versions" of an image at defined sizes, with added text, logo or watermarks for protection. Or allow users to download a version of an image with a size perfect for inclusion in a blog post, a publication etc. This was an often requested functionality for IMatch WebViewer.

Over the next weeks I will test this further, document everything and then include it in IMatch 2018 and IMatch Anywhere 2018. I may also create a few apps which utility this to do "stuff" 

Examples:

Download a version of the file with id 123, size 300 x 300 pixel (maintain aspect ratio) in JPEG format. Use the original image (no cache) as the source:

    let params = {
        id : 123,
        imagesize: 'original',
        sizetype: 'wh',
        width: 300,
        height: 300,
        format: 'jpeg',
        quality: 80
    }

    let url = `${IMWS.config.imwsUrl}/v1/imageprocessor?auth_token=${IMWS.config.auth_token}&params=${encodeURIComponent(JSON.stringify(params))}`;
    $('#img-container').append(`<img src="${url}">`);

These statements setup the params object which describes the image processor what to do.
It then creates an IMWS URL for the /imageprocessor endpoint with the current auth_token. The JavaScript parameter object is converted to a string and supplied as a parameter.

This may look strange but actually produces a normal URL which you can use as the src= attribute in an image tag (like above) or maybe in an <a> tag to allow a download of the file. You supply the URL, and the browser automatically calls IMWS when needed (e.g. when the image needs to be shown). IMWS produces the requested image on-the-fly and returns it. Neat.

Text overlays are provided as an array (any number of overlays possible). In the simplest form, without bells and whistles like margins, padding or background, this looks like:

            params.textoverlays = [
                {
                    align: 'canvas',
                    alignment : {
                        horz: 'center',
                        vert: 'middle'
                    },
                    opacity: 1.0,
                    textalignment: {
                        horz: 'center',
                        vert: 'middle'
                    },
                    font: {
                        family: 'Tahoma',
                        size: 32,
                        color: 'ffffff'
                    },
                    text: 'IMatch is Powerful.'
                }

This renders the text "IMatch is Powerful." centered on top of the image, in white and a 32pt Tahoma font. Great for watermarks.
Of course variables are supported for text overlays.

Image overlays are created in similar ways. There are even QR codes.

To add a custom XMP title and a rating of 4 to the output file, all that is needed is

params.metadata = {
  custom: [
        '-xmp:title=This is my title',
        '-xmp:rating=4',
  ]
}

Easy! You have control over the metadata contained in the downloaded file. From no metadata at all to XMP, IPTC, EXIF or even a mix + custom tags (like in the Batch Processor).

This should cover the majority of use cases.
For all else. you can use this to download an image and store it in a HTML canvas. Then you have all the features provided by canvas and GPU-powered imaging functionality available in HTML 5 at your disposal. Which is a lot.

[lbo]

[...] I had to add image processing features in IMWS. These will also be accessible for apps running in IMatch.

[...] it's basically the IMatch Batch Processor feature set, but accessible in IMWS.

So I separated the batch process engine, stripped what was not needed and implemented a new endpoint named /imageprocessor for IMWS.

please excuse my lazyness, this time I didn't read all the docs because it seems to be a huge effort to answer just a simple question, and I didn't even find the /imageprocessor docs:

Does this allow to write new image files (resized, with overlays etc.) from within an IMatch script, just as in the batch processor but under control of an IMatch JavaScript based app?

[Mario]

This endpoint may become part of IMatch 2020. I have not yet decided.