Skip to main content
Skip table of contents

mask_face usage manual

Version Release Notes

First version: 08.24.2012
Current version: 10.15.2018

New in version 12.27.2017:

  • A version that works using Matlab Runtime Environment (no Matlab license required) is released.
  • Fixes to work correctly on Ubuntu machines

New in version 01.24.2014:

  • Reworked the structure of the script into procedure-based
  • The script now accepts multiple scans to process with the same parameters.
  • The following modes of face masking are allowed by script
    1. based on FSL-coregistered coordinates file (generated by fsl after coregistration)
    2. based on supplied ROI coordinate file
    3. based on explicitly supplied ROI coordinates
    4. based on the reference scan
  • each masking region requires a separate run of mask_surf_auto.m
  • 3D snapshots
  • tweaked brain mask application to exclude more boundary voxels
  • better support of anisotropic voxels
  • added ear masking
  • major updates to the face masking xnat pipeline:
    • new parameters:
      • ref: reference scan
      • use_manual_roi: signal that manual ROI will be used instead of auto-registration.
      • rois: specification of manual ROI’s
      • dirs: ROI normal direction (s)
    • step 0: scan lists are converted to be used with xnat2loc
    • step 1: xnat2loc is now used to download and process DICOM scans instead of XNATRestClient.
    • new face masking script takes a list of scans, reference and ROI parameters as input.


mask_face <image>[,<image>..] [options]

The first argument must list one or more MR head image files. If more than one image is specified, you must also specify one of them as reference with -r option. The reference image will be used for spatial co-registration with an atlas, and others will use the reference facial mask.

By default, the input is the DICOM directory of a single series. You can also supply images in Analyze/NIFTI (.hdr/.img pair) format by adding -a option. The output and input formats are the same.


For the complete set of options, run mask_face without parameters.

-aRequired if you are supplying images in Analyze/NIFTI (.hdr/.img pair) format
-m <method>

Method used (coating, blur, normfilter, all):

  • coating: sets all voxels in the face layer to the single average intensity
  • blur: performs the entire volume blur, and limit the effect to the facial region
  • normfilter: (recommended) a fine-tuned method that will preserve most of the intensity distribution
  • all: produces output by all three methods
-t <threshold>

Mask threshold: Threshold is selected automatically (recommended), but can be changed with this option

-s <grid_step>Grid Step: Larger grid step will result in coarser looking 3D renderings, and tends to modify more voxels outside of the immediate near-surface
-v <#>

Control the amount of intermediate output:

  • 0: only saves the resulting output
  • 2: will generate the 3D volumes for boundary layer, boundary mask, and “flattened” face (both blurred and unblurred)
-bGenerate the brain mask used by FSL's bet algorithm prior to face masking and use it to exclude brain voxels from modification
-e <#>

Controls ear-masking.

  • 1: Mask ears
-um <#>

Toggles the use of manual ROI coordinates

  • 1: Use manual ROI coordinates specified with either -roi and -ver or -rf
-r <image>Required if more than one image is being defaced. The reference image will be used for spatial co-registration with an atlas, and others will use the reference facial mask. (Use the highest quality image for your reference.)


The algorithm main paper:

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.