Moya has support for reading, processing, and writing images. The could be anything from icons, photographs, profile pictures, etc. Image tags may be used for offline processing, via commands, or in the context of a request (to handle image uploads).


Moya Image tags use the namespace "".

Reading Images

You can read images with <read> which reads an image file (such as a .jpg or.png), and creates an image object.

<image:read fs="media" filename="photos/profile.jpg" dst="photo" />

This reads a file called photos/profile.jpg in the media filesystem, and creates an image object called photo. Image objects are used in tags that process the image, and may later be written to a filesystem. Image objects contain the following properties:

The original filename of the image (not including the path).
The mode of the image, which specifies the color depth. Typical values are 1, L, RGB, or CMYK. See here for more information on modes.
The size of the image as a list of [WIDTH, HEIGHT]

Writing Images

You can use the <write> to to write an image to a filesystem. Here's an example:

<image:write dirpath="profiles/${}/" filename="profile.jpg" fs="media" />

If you are saving the images as a jpeg, you can set the quality wit the LET extension as follows:

<image:write dirpath="profiles/${}/" filename="profile.jpg" fs="media" let:quality="85"/>

The value, quality, should be an integer between 0 and 100, where 100 is the maximum quality.

Creating Blank Images

You can create a new blank image, initialized to a given color, with the <new> tag. Here's an example:

<image:new size="[64,64]" color="#00FF00" dst="green_square" />

This create a blank 64x64 image set to 100% green.


You can copy an image with <copy>, which takes the image to be copied as image and the destination for the new image as dst. Here's an example:

<image:copy image="profile_photo" dst="profile_photo_copy"/>

Image Operations

Moya supports a number of image operations which you can use to process your images.


The <resize> tag resized the image to fit in to new dimensions. This can result in stretching of the image, if you want to ensure that the image doesn't stretch, see Resize To Fit.

The resample attribute defines how Moya should scale the image, and should be one of the following values:

The quickest scaling method, but lowest quality.
Uses bilinear filtering to scale the image. Offers reasonable quality and speed.
Uses bicubic filtering to scale the image. Offers better quality than bilinear, at comparable speeds.
The highest quality filtering, but the slowest of the options.

The default is to use the antialias because it is usually worth sacrificing speed for quality.

Resize To Fit

The <resize-to-fit> tag resizes an image so that it will fit within the given dimensions. while maintaining the aspect ratio (the image won't be stretched). This may result in the image having a lower width or height that requested.

Resize Canvas

The <resize-canvas> changes the size of the image without scaling. If you make the image smaller, it will be cropped. If you make the image larger, it will have a border. You may set the color of the border with the color attribute.


The <square> tag makes the dimensions of the image equal (i.e. a square). This will crop part of the image, if the image was not already a square.


The <crop> tag crops to a part of the image. The area to crop is specified in the box attribute, which should be a list. If the list is two items long, the image is cropped to [WIDTH, HEIGHT]. If the list is four items long, the image is cropped to [X, Y, WIDTH, HEIGHT] where X and Y are the coordinates of the point to start cropping from.

When the image is cropped, the new dimensions will be the width and height specified in box.

Debugging Images

When debugging, you can use the <show> tag which will pop up a window containing the image. You will need ImageMagick installed for this to work.

This tag only works in debug, as you wouldn't want or need to show an image in a window on a headless server. If you forget to remove the <show> in production, Moya will write a warning to the logs.