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.

2.1.1 Rename

Replace text, add a prefix or suffix, or add an index to selected images.

Batch Rename.

Figure 2.1: Batch Rename.

2.1.2 Align

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.

Batch Align.

Figure 2.2: Batch Align.

2.1.3 Crop

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).

Batch Crop.

Figure 2.3: Batch Crop.

2.1.4 Mask

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.

Batch Mask.

Figure 2.4: Batch Mask.

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.

Custom Masks.  The image on the left didn't include the starting point at the end.

Figure 2.5: Custom Masks. The image on the left didn’t include the starting point at the end.

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

2.1.5 Mirror

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.

2.1.6 Resize

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.

Batch Resize

Figure 2.6: Batch Resize

2.1.7 Rotate

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.

Batch Rotate 45 degrees with Select color from patch

Figure 2.7: Batch Rotate 45 degrees with Select color from patch

2.1.8 Scramble

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

Batch Scramble

Figure 2.8: Batch Scramble

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.

Batch Scramble inside a mask.

Figure 2.9: Batch Scramble inside a mask.

2.1.9 Symmetrise

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.

Batch Symmetrise. Original image, symmetric shape, symmetric colour, and both.

Figure 2.10: Batch Symmetrise. Original image, symmetric shape, symmetric colour, and both.

2.2 Batch Files

WebMorph has three types of batch files that let you process many images programmatically.

2.2.1 Batch Average

Batch Average Template

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).

/avg_test/androgynous.jpg /avg_test/3male1female.jpg
/composites/m_multi.jpg /composites/f_multi.jpg
/composites/f_multi.jpg /composites/m_multi.jpg

2.2.2 Batch Transform

Batch Transform Template

trans-img from-img to-img shape color texture outname
/composites/f_multi.jpg /composites/m_multi.jpg /composites/f_multi.jpg 50 0 0 /trans_test/female_fem50.jpg
/composites/f_multi.jpg /composites/m_multi.jpg /composites/f_multi.jpg -50 0 0 /trans_test/female_masc50.jpg
/composites/m_multi.jpg /composites/m_multi.jpg /composites/f_multi.jpg 50 0 0 /trans_test/male_fem50.jpg
/composites/m_multi.jpg /composites/m_multi.jpg /composites/f_multi.jpg -50 0 0 /trans_test/male_masc50.jpg
/composites/f_white.jpg /composites/f_multi.jpg /composites/f_white.jpg 25% 25% 25% /trans_test/f_wh_caric.jpg

2.2.3 Batch Edit

Batch Edit Template

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., /male/avg.jpg
  • align: pt1, pt2, x1, y1, x2, y2, width, height, [color] e.g., 0,1,497,825,853,825,1350,1800,rgb(0,0,0) or DEFAULT
  • resize: width, height e.g., 50%,50% or 300px,400px or null,400px
  • rotate: degrees, [color] e.g., 90,rgb(255,255,255)
  • crop: top, right, bottom, left, [color] e.g., -100,100,-100,100,rgb(0,0,0)
  • mask: (mask names or custom mask), blur, [color] e.g., (face,neck,ears),0,rgb(255,255,255) or (face),10,transparent
  • sym: shape and/or color
  • mirror: true or leave blank
  • order: defaults to align,resize,rotate,crop,mask,sym,mirror
  • outname: The path to save the result to: e.g., /male/edited/avg.jpg The file needs all 10 columns with their headers, but I’ll show each batch function below with only the relevant columns. Align

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.

image align outname
/composites/f_multi.jpg DEFAULT /edit_test/align_default.jpg
/composites/f_easian.jpg FRL /edit_test/align_frl.jpg
/composites/f_african.jpg 0,1,200,300,400,300,600,600 /edit_test/align_square.jpg Resize

Resize images with a single percentage, or width and height as pixels or percentages. To omit width or height, use null.

image resize outname
/composites/f_white.jpg 50% /edit_test/resize_50_percent.jpg
/composites/f_wasian.jpg null,400px /edit_test/resize_400px_tall.jpg
/composites/m_multi.jpg 200px,200px /edit_test/resize_200x200px.jpg
/composites/m_easian.jpg 300px,null /edit_test/resize_300px_wide.jpg
/composites/m_african.jpg 50%,25% /edit_test/resize_50x25_percent.jpg Rotate

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).

image rotate outname
/composites/m_white.jpg 90 /edit_test/rotate_90.jpg
/composites/m_wasian.jpg 45,rgb(255,0,0) /edit_test/rotate_45red.jpg
/composites/f_multi.jpg -90 /edit_test/rotate_neg90.jpg Crop

Crop images by setting the top, right, bottom and left pixels. Set a non-default background color in the format rgb(r, g, b).

image crop outname
/composites/f_multi.jpg -300,0,-300,0 /edit_test/crop_short.jpg
/composites/f_multi.jpg 100,100,100,100,rgb(0,255,0) /edit_test/crop_green_border.jpg Mask

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).

image mask outname
/composites/f_multi.jpg (face),10,rgb(255,0,0) /edit_test/mask_red.jpg
/composites/f_multi.jpg (face),0,rgb(0,255,0) /edit_test/mask_green.jpg
/composites/f_multi.jpg (face,neck,ears),0 /edit_test/mask_face_neck_ears.jpg
/composites/f_multi.jpg (neck),0 /edit_test/mask_neck.jpg
/composites/f_multi.jpg (left_eye),0 /edit_test/mask_left_eye.jpg
/composites/f_multi.jpg (right_eye),0 /edit_test/mask_right_eye.jpg
/composites/f_multi.jpg (eyes),0 /edit_test/mask_eyes.jpg
/composites/f_multi.jpg (left_brow),0 /edit_test/mask_left_brow.jpg
/composites/f_multi.jpg (right_brow),0 /edit_test/mask_right_brow.jpg
/composites/f_multi.jpg (brows),0 /edit_test/mask_brows.jpg
/composites/f_multi.jpg (left_ear),0 /edit_test/mask_left_ear.jpg
/composites/f_multi.jpg (right_ear),0 /edit_test/mask_right_ear.jpg
/composites/f_multi.jpg (ears),0 /edit_test/mask_ears.jpg
/composites/f_multi.jpg (nose),0 /edit_test/mask_nose.jpg
/composites/f_multi.jpg (mouth),0 /edit_test/mask_mouth.jpg Sym

Symmetrise with shape and/or color, separated by a comma.

image sym outname
/composites/f_multi.jpg shape,color /edit_test/sym_shape_color.jpg
/composites/f_multi.jpg shape /edit_test/sym_shape.jpg
/composites/f_multi.jpg color /edit_test/sym_color.jpg Mirror

Mirror with TRUE, FALSE, or leave blank.

image mirror outname
/composites/f_multi.jpg TRUE /edit_test/mirror.jpg Multiple

You can apply several edits to a single image in one step.

image align resize rotate crop mask sym mirror order outname
/composites/f_multi.jpg FRL 50% 90 10,10,10,10,rgb(255,0,0) (face),0,rgb(255,255,255) shape,color FALSE /edit_test/multi_1a.jpg
/composites/f_multi.jpg FRL 50% 90 10,10,10,10,rgb(255,0,0) (face),0,rgb(255,255,255) shape,color FALSE align,resize,rotate,crop,mask,sym /edit_test/multi_1b.jpg
/composites/f_multi.jpg FRL 50% 90 10,10,10,10,rgb(255,0,0) (face),0,rgb(255,255,255) shape,color FALSE resize,rotate,crop,mask,sym,align /edit_test/multi_2.jpg
/composites/f_multi.jpg FRL 50% 90 10,10,10,10,rgb(255,0,0) (face),0,rgb(255,255,255) shape,color FALSE crop,resize,sym,align /edit_test/multi_3.jpg
/composites/f_multi.jpg 0,1,200,300,400,300,600,600 50% 90 10,10,10,10,rgb(255,0,0) (face),0,rgb(255,255,255) shape,color FALSE crop /edit_test/multi_4.jpg
/composites/f_multi.jpg 0,1,200,300,400,300,600,600 50% 90 10,10,10,10,rgb(255,0,0) (face),0,rgb(255,255,255) shape,color FALSE crop,crop /edit_test/multi_5.jpg

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[0]-x[1], 2) + pow(y[0]-y[1],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., x[0] or y[1]. You can find the point numbers by hovering over them in the Delineate window.

Allowed functions in equations are: abs, min, max, tan, sin, cos, atan, asin, acos, sqrt, pow and 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, y[151]
  • Bottom: minimum y of the adams apple points, max(y[183], y[184])
  • Left: x of left halo point outside the ear, x[147]
  • Right: x of right halo point outside the ear, x[155]

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[2]-x[3], 2) + pow(y[2]-y[3],2)) / sqrt(pow(x[6]-x[7], 2) + pow(y[6]-y[7],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.

Table 2.1: Example rows from an Lab colour file.
x y L a b
96 80 90.0460 -64.7454 54.8329
96 83 90.1418 -63.9054 53.6131
96 84 90.1522 -63.9010 54.5343
96 85 90.1522 -63.9010 54.5343
96 86 90.1522 -63.9010 54.5343
96 87 89.8794 -63.2933 53.3068
96 89 90.0148 -64.9838 54.7882
96 90 90.0041 -65.1015 55.2222
96 91 90.0148 -64.9838 54.7882

2.3.3 Image Grid

Make a 2-dimensional grid of images.

Image Grid.

Figure 2.11: Image Grid.

2.3.4 Multiple Continua

Create multiple morphing continua.

Multiple Continua.

Figure 2.12: Multiple 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.

moving gif