Chapter 2 Batch Processes
2.1 Batch Functions
Select multiple images in the Finder and use the functions under the Batch menu to apply transformations to all of the selected images. The individual processes will be added to the Queue and complete in the background.
I am writing an R package to do much of this on your own computer, which can often be faster than the webmorph server.
Replace text, add a prefix or suffix, or add an index to selected images.
Align delineated images on two points. This rotates and resizes images so that the specified points are all in the same place (usually the pupils).
The default values for the alignment come from Preferences, but you can change them.
If the alignment makes an image smaller than the image size, the background will be the specified colour.
Crop an image by specifying the number of pixels to add or remove from each side.
You can select the background colour for added pixels from the average of a patch of the image whose coordinates you specify (defaulting to the top left 10 pixel square).
Masking allows you to use the delineation lines to mask off areas of an image. There are several masks built into WebMorph that work with the FRL-Face template, but you can define your own.
You can combine masks. The interface will let you visualise what each mask is. Reversing a mask puts the colour inside the mask instead of outside (although the masking interface still shows an external mask, sorry). If you set the mask to transparent, the masked images will be PNGs with transparency.
The blur function doesn’t work as well as PsychMorph’s and you usually can’t tell the difference with images that are large.
You can create a custom mask by unselecting all of the built-in masks and directly typing the points to use in the text box that appears. For example, with the custom 10-point template “outline”, you can mask the face with this:
0,1,2,3,4,5,6,7,8,9,0. Notice how the first point is also appended to the end. If you don’t do this, masks will have a jagged corner.
You can build a mask by clicking on the delineation points you want to add in the Template interface. Load an image with the correct template and choose Custom Mask Builder from the Template menu. Click on points to add them to the text box. Separate points with commas, lines with semicolons, and mask areas with colons.
You can’t get out of the Custom Mask Builder interface. Until I fix it, just reload the page to get out.
For example, this will create one mask that masks the pupils, as the points 2-9 delineate the left pupil and points 10-17 delineate the right pupil. Reverse the mask to replace the pupils with the mask colour.
2,3,4,5,6,7,8,9,2 : 10,17,16,15,14,13,12,11,10
Batch mirror mirror-reverses the images and their templates. Templates need to have their symmetry points defined in order to do this. Most of the built-in templates in WebMorph have this, but you will need to do this yourself for any custom templates.
For example, in the FRL-Face template, point 0 is the left pupil and point 1 is the right pupil, so in the mirror-reversed version, the x-coordinates are all flipped and the identities of matching points are swapped so that the pupil point on the left side of the image is 0 in both original and mirror-reversed versions. This is the first step to creating a symmetric face.
Resize images by percent or pixel. If you only enter one of width or height, the other dimension is scaled to the same aspect ratio as the original image. You will see a table of the original and new dimensions to check before you click Resize.
Set the number of degrees to rotate (e.g. 90 degrees rotates the images one-quarter of a turn clockwise).
If your rotated image is squint, you need to set a background colour to fill in the triangles in the edges. If you choose “Select color from patch,” each image’s background will be taken from the average of the specified pixels.
Some vision research uses scrambled images as controls. They will have the same distribution of colour as the unscrambled image, but scrambling introduces horizontal and vertical structure that isn’t present in the original image, so we recommend to place grid lines on both the original and scrambled images.
Scramble an image by choosing the grid size and offset, then select/unselect the squares to scramble by clicking or dragging on the image.
If your selected squares are symmetric, you can choose a symmetric scramble, where the squares on the left side are scrambled, and the squares on the right side are in a mirrored pattern. This looks pretty creepy, but maintains the bilateral symmetry of the original image in the scrambled version. Each face in a set is scrambled
The symmetric image scrambling methods were first published in Conway et al. (2008), so please do cite that paper if you use this method.
You can scramble only inside a masked area, although this is experimental and sometimes is glitchy. Set the grid size fairly small and turn off grid lines to create a pixelated look.
You can symmetrise an image in shape, color, or both. Just like batch mirroring, templates need to have their symmetry points defined in order to do this. Most of the built-in templates in WebMorph have this, but you will need to do this yourself for any custom templates.
2.2 Batch Files
WebMorph has three types of batch files that let you process many images programmatically.
2.2.1 Batch Average
Put the name of each average on the first row and the images in the average in the rows below. Put each average in a new column.
In the example below, the first average is made from two images (m_multi and f_multi) and will be saved in a folder called avg_test as androgynous.jpg. The second example will be made from 4 images, 3 of which are the same (so will be 1/4 f_multi and 3/4 m_multi).
2.2.2 Batch Transform
2.2.3 Batch Edit
The batch edit function lets you align, resize, rotate, crop, mask, symmetrise, and/or mirror images in any order. Every row must have a valid
image name of an image that exists in your project, and a valid
outname that can’t overwrite an existing image.
- image: The path to the image file: e.g.,
pt1, pt2, x1, y1, x2, y2, width, height, [color]e.g.,
top, right, bottom, left, [color]e.g.,
(mask names or custom mask), blur, [color]e.g.,
trueor leave blank
- order: defaults to
- outname: The path to save the result to: e.g.,
/male/edited/avg.jpgThe file needs all 10 columns with their headers, but I’ll show each batch function below with only the relevant columns.
Align using your default alignment (
DEFAULT), the default FRL-face alignment (
FRL), or the specified alignment in the order
point 1, point 2, x1, y1, x2, y2, width, height.
Resize images with a single percentage, or width and height as pixels or percentages. To omit width or height, use
Rotate images with the degrees to rotate. If you need to set a non-default background color, add this after the rotation value in the format
rgb(r, g, b).
Crop images by setting the top, right, bottom and left pixels. Set a non-default background color in the format
rgb(r, g, b).
Put the mask names inside parentheses (comma-delimited), then the blur level (0-10), and an optional background color in the format
rgb(r, g, b).
color, separated by a comma.
FALSE, or leave blank.
You can apply several edits to a single image in one step.
2.3 Other Functions
2.3.1 Calculate FacialMetrics
Use the x and y coordinates of templates to calculate facial metrics.
There are two built-in metrics:
FWH: face width-to height ratio, face height is the distance between the upper lip and the highest point of the eyelids, face width is the maximum distance between the left and right facial boundary (i.e., bizygomatic width) (following Lefevre et al. 2013)
Eye-spacing: the distance between the centres of the pupils (this isn’t very useful, but mainly there to remind you of the equation for the distance between two points)
sqrt(pow(x-x, 2) + pow(y-y,2))
Click calculate after choosing a metric to add its calculation to a table for downloading.
You can also write your own equations. refer to points by their number, e.g.,
y. You can find the point numbers by hovering over them in the Delineate window.
Allowed functions in equations are:
rad2deg. Units are in pixels. The origin (0,0) is in the upper left corner.
Max and min values of template points can be useful for knowing how much you can crop a set of images without going into the templates. Here are the relevant points for the FRL-Face template.
- Top: y of the highest halo point,
- Bottom: minimum y of the adams apple points,
- Left: x of left halo point outside the ear,
- Right: x of right halo point outside the ear,
If you’re using the Hand template, you can calculate 2D4D (the ratio of the second to fourth digit) with the following equation:
sqrt(pow(x-x, 2) + pow(y-y,2)) / sqrt(pow(x-x, 2) + pow(y-y,2))
For anything more complicated, it’s probably better to download all the x and y coordinates and process them yourself. There is a button for getting all the coordinates from a set of templates into one spreadsheet.
2.3.2 Lab* Pixels
Create CSV files with CIELAB color values for each pixel. Check ‘ignore mask’ to omit pixel values that are the same as the top left pixel color. A CSV file will be created for each image with columns x, y, L , a, and b, with the x and y-coordinates of each pixel and their L*, a* and b* colour values.
2.3.3 Image Grid
Make a 2-dimensional grid of images.
2.3.4 Multiple Continua
Create multiple morphing continua.
2.3.5 Moving Gif
Select a set of images, such as a multiple continuum, choose Moving Gif from the Batch menu, and create an animated image.