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.

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.

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

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.

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.

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.

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.

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

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.

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.

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
	/composites/m_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.

2.2.3.1 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

2.2.3.2 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

2.2.3.3 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

2.2.3.4 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

2.2.3.5 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

2.2.3.6 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

2.2.3.7 Mirror

Mirror with TRUE, FALSE, or leave blank.

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

2.2.3.8 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)
```
abs(max(x[113],x[112],x[114])-min(x[110],x[111],x[109]))/abs(y[90]-min(y[20],y[25]))
```
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