XNAT Tools
XNAT Tools
Breadcrumbs

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.

Usage 


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.

Options

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

Flag

Description

-a

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

-b

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


References

The algorithm main paper: