Image Transformations Added to CLI

the DocumentAlchemy blog

Image Transformations Added to CLI

The DocumentAlchemy API has a fairly sophisticated image transformation endpoint. With this endpoint, you can define a “chain” of transformations—things like resizing, cropping, rotating, blurring, etc.—to apply to a given image.

Support for many of these transformations has been added to the command-line interface.

Below you'll find an overview of each of the added transformations and how to use them.

Installation instructions

As a reminder, to install the DocumentAlchemy CLI you'll first need to install node.js.

With node (and more to the point, npm) available, installing the DocumentAlchemy CLI is as simple as:

npm install document-alchemy-cli -g

See the documentation found in the npm module and GitHub repo for more information.

General syntax

The generic form of the image transformation command in the CLI is this:


where [OPTIONS] are any of the standard DocumentAlchemy CLI options, <IMAGE> is the filename of the image you'd like to transform and <SUBCOMMAND> [SUBCOMMAND-PARAMETERS] is a specific transformation and transformation-specific parameters, as described below.

Resize an image

To resize an image, with the command-line interface, we use one of these three commands:

resize <WIDTH> <HEIGHT>
resize <WIDTH> <HEIGHT> enlarge

In the first case (resize <W> <H>), the specified image will be scaled down until it fits snuggly within the specified rectangle. That is, the image will be scale down (respecting the original aspect ratio) until both the width and height of the image are less than or equal to the specified values.

The second case (resize <W> <H> enlarge), is exactly like the first except that if necessary the image will be scaled up (respecting the aspect ratio) until either the width of the image or the height of the image (or both) matches the width and height specified in the command line parameters.

The third case (resize <W> <H> <G>) is the only one of the resize commands that will generate an image of a different aspect ratio than the original file. This version of resize will first scale the image (respecting aspect ratio) until one (or both) dimensions matches the specified values. This scaled image will then be cropped to the exact height and width that are specified.

The <GRAVITY> parameter controls what part of the sclaed image is retained when cropping. The value c (or center) will center the cropped rectangle on the center of the image. The other values (n(orth), s(outh), e(ast), w(est)) will cause DocumentAlchemy to center the cropped rectangle along the specified edge of the scaled image (top, bottom, right, left, respectivly).


Shrink an image until it fits in a 240 by 120 pixel area:

document-alchemy transform image.png resize 240 120

Shrink or enlarge an image until it is at most 600 pixels wide or 400 pixels tall:

document-alchemy transform image.png resize 600 400 enlarge

Shrink or enlarge an image until it is at least 600 pixels wide and 400 pixels tall, then crop the resized image to exactly 600x400 pixels:

document-alchemy transform image.png resize 600 400 center

Crop an image

In addition to the resize <W> <H> <G> transform, you can also crop an image to an arbitrary rectangle using the crop command:


The crop command will extract the specified rectangle from the original image.


Grab a 200-by-100 pixel area of the original image, taken from the top-left corner:

document-alchemy transform image.png crop 0 0 200 100

Grab a 200-by-100 pixel area of the original image at some offset from the top-left corner:

document-alchemy transform image.png crop 50 70 200 100

Rotate an image

You can rotate an image 90 degrees (or an integer multiple of 90 degrees) using the rotate command:

rotate [<ANGLE>]

where <ANGLE> is one of 90, 180 or 270. The image will be rotated the specified number of degrees in a clockwise direction.

A “special” <ANGLE> of auto will cause DocumentAlchemy to use the images EXIF metadata (if any) to correctly orient the image (usually a photograph), even when taken with a phone that was itself rotated or flipped around.

auto is also the default value, used when no <ANGLE> is specified.


Rotate an image 270 degrees clockwise:

document-alchemy transform image.png rotate 270

Auto-orient an image using EXIF data:

document-alchemy transform photo.jpg rotate

Flip an image

You can flip an image across its horizontal or vertical axis using the flip command:

flip <AXIS>

where <AXIS> is one of h or x (for horizontal) or v or y (for vertical).


Flip an image on the horizontal axis:

document-alchemy transform image.png flip x

Convert an image to grayscale

The grayscale sub-command is simplest of all:



Convert a color image to gray scale:

document-alchemy transform image.png gs

Note that grayscale and greyscale are both accepted as synonyms for gs.

Blur an image

To blur an image, we use the aptly named blur sub-command:

blur [<RADIUS>]

where <RADIUS> specifies the radius (in pixels) of the surrounding pixels that will influence the final color of a given pixel.


To blur an image just a little bit:

document-alchemy transform image.png blur 5

To blur an image a lot:

document-alchemy transform image.png blur 100

Sharpen an image

To sharpen an image, we use the also aptly named sharpen sub-command:

sharpen [<RADIUS>]

where <RADIUS> specifies the radius (in pixels) of the surrounding pixels that will influence the final color of a given pixel.


To sharpen an image using fine-grained areas:

document-alchemy transform image.png sharpen 5

To sharpen an image using coarse-grained areas:

document-alchemy transform image.png sharpen 100


Don't forget, the document-alchemy command-line application is open source software published under the MIT license, so you're both able and welcome to take a look under the hood or even make (or suggest) changes and enhancments to better suit your needs.

The source code is available in the documentalchemy/document-alchemy-cli repository at GitHub.

A “compiled” version of the component is available as an npm module.

About DocumentAlchemy

DocumentAlchemy is a RESTful web service that developers can use to add document generation, conversion and processing features to their app.

Visit our live demonstrations or interactive API reference to explore Document Alchemy's rapidly growing API for working with MS Office documents, PDFs, images, web pages and more.

Copyright © 2018 DocumentAlchemy.