= NAME =

 

mri_convert  

= SYNOPSIS =

 

mri_convert [options] <in volume> <out volume>  

= DESCRIPTION =

 

 mri_convert is a general purpose utility for converting between different file formats. The file type can be specified in two ways. First, mri_convert will try to figure it out on its own from the format of the file name (eg, files that end in .img are assumed to be in spm analyze format). Second, the user can explicity set the type of file using --in_type and/or --out_type.



Legal values for --in_tye (-it) and --out_type (-ot) are listed under optional flagged arguments.



A note on specifying orientation:



Do not use this to try to change the orientation for FSL. This is only to be used when the orientation information in the input file is *wrong*. If it is correct, this will make it wrong! If you are having problems with fslview displaying your data, consult the FSL website for methods to reorient.



Ideally, the orientation information is derived from a DICOM file so that you have some confidence that it is correct. It is generally pretty easyto determine which direction Anterior/Posterior or Inferior/Superior are. Left/Right is very difficult. However, if you have some way of knowing which direction is which, you can use these options to incorporate this information into the header of the output format. For analyze files, it will be stored in the output.mat file. For NIFTI, it is stored as the qform matrix. For bshort/bfloat, it is stored in the .bhdr file. For mgh/mgz it is internal.

First of all, determining and setting the orientation is hard. Don't fool yourself into thinking otherwise. Second, don't think you are going to learn all you need to know from this documentation. Finally, you risk incorporating a left-right flip in your data if you do it incorrectly. OK, there are two ways to specify this information on the command-line.

(1) explicitly specify the direction cosines with -iid, -ijd, -ikd. If you don't know what a direction cosine is, don't use this method.

(2) specify an orientation string with --in_orientation  ostring and --out_orientation ostring

Supply the orientation information in the form of an orientation string  (ostring). The ostring is three letters that roughly describe how the volume  is oriented. This is usually described by the direction cosine information  as originally derived from the dicom but might not be available in all data  sets. You'll have to determine the correct ostring for your data.  The first  character of ostring determines the direction of increasing column.  The second character of ostring determines the direction of increasing row.  The third  character of ostring determines the direction of increasing slice.  Eg, if the volume is axial starting inferior and going superior the slice is oriented such that nose is pointing up and the right side of the subject is on the left side of the image, then this would correspond to LPS, ie,  as the column increases, you move to the patients left; as the row increases, you move posteriorly, and as the slice increases, you move superiorly. Valid letters are L, R, P, A, I, and S. There are 48 valid combinations (eg, RAS LPI, SRI). Some invalid ones are DPS (D is not a valid letter), RRS (can't specify R twice), RAP (A and P refer to the same axis). Invalid combinations are detected immediately, an error printed, and the program exits. Case-insensitive. Note: you can use tkregister2 to help determine the correct orientation string.  

= POSITIONAL ARGUMENTS =

 
 ArgumentExplanation||
  ||involume||in volume||
  ||outvolume||out volume||
 
   

= REQUIRED-FLAGGED ARGUMENTS =

 

=== None ===

   

= OPTIONAL-FLAGGED ARGUMENTS =

 
 ArgumentExplanation||
  ||-ro, --read_only||  ||
  ||-nw, --no_write ||  ||
  ||-ii, --in_info||  ||
  ||-oi, --out_info||  ||
  ||-is, --in_stats||print statistics on input volume||
  ||-os, --out_stats||print statistics on output volume||
  ||-im, --in_matrix||  ||
  ||-om, --out_matrix||  ||
  ||--upsample N <size>||Reduce voxel size by a factor of N in all dimensions||
  ||-iis, --in_i_size <size>||  ||
  ||-ijs, --in_j_size <size>||  ||
  ||-iks, --in_k_size <size>||  ||
  ||--force_ras_good ||use default when orientation info absent||
  ||-iid, --in_i_direction <R direction> <A direction> <S direction>||  ||
  ||-ijd, --in_j_direction <R direction> <A direction> <S direction>||  ||
  ||-ikd, --in_k_direction <R direction> <A direction> <S direction>||  ||
  ||--in_orientation orientation-string||see SPECIFYING THE ORIENTATION||
  ||-ic, --in_center <R coordinate> <A coordinate> <S coordinate>||  ||
  ||-dic, --delta_in_center <dR coordinate> <dA coordinate> <dS coordinate>||  ||
  ||--sphinx||change orientation info to sphinx||
  ||-oni, -oic, --out_i_count <count>||  ||
  ||-onj, -ojc, --out_j_count <count>||  ||
  ||-onk, -okc, --out_k_count <count>||  ||
  ||-vs, --voxsize <size_x> <size_y> <size_z>||specify the size (mm) - useful for upsampling or downsampling||
  ||-ds, --downsample <ds_x> <ds_y> <ds_z>||specify the downsampling or upsampling factor||
  ||-ois, --out_i_size <size>||  ||
  ||-ojs, --out_j_size <size>||  ||
  ||-oks, --out_k_size <size>||  ||
  ||-oid, --out_i_direction <R direction> <A direction> <S direction>||  ||
  ||-ojd, --out_j_direction <R direction> <A direction> <S direction>||  ||
  ||-okd, --out_k_direction <R direction> <A direction> <S direction>||  ||
  ||--out_orientation orientation-string||see SETTING ORIENTATION||
  ||-oc, --out_center <R direction> <A direction> <S direction>||  ||
  ||-odt, --out_data_type <uchar|short|int|float>||  ||
  ||--bfile-little-endian||write out bshort/bfloat files in little endian||
  ||--in_stats_table||input data is a stats table as produced

      by asegstats2table or aparcstats2table||
  ||--out_stats_table||output data is a stats table (use --like to pass template table for measure, columns and rows header)||
  ||-rt, --resample_type <interpolate|weighted|nearest|cubic>||default is interpolate||
  ||--no_scale flag <-ns>||1 = dont rescale values for COR||
  ||-nc --nochange||don't change type of input to that of template||
  ||-tr TR||TR in msec||
  ||-te TE||TE in msec||
  ||-TI TI||TI in msec (note upper case flag)||
  ||-flip_angle flip angle ||angle in radians ||
  ||--autoalign mtxfile ||text file with autoalign matrix ||
 
 

=== APPLYING TRANSFORMS (INCLUDING TALAIRACH)  ===

  
 ArgumentExplanation||
  ||--apply_transform xfmfile (-T or -at) ||apply tranform given by xfm or m3z files ||
  ||  ||The volume can be resampled into another space by supplying a transform using the -apply_transform flag. This reads the transform file and applies the transform (when --apply_inverse_transform is used, the transform is inverted and then applied). An example of a transform file is talairach.xfm as found in subjectid/mri/transforms. To convert a subject's orig volume to talairach space, execute the following lines: 

    cd subjectid/mri 

    mkdir talairach 

    mri_convert orig.mgz --apply_transform transforms/talariach.xfm 

       -oc 0 0 0   orig.talairach.mgz 

 

This properly accounts for the case where the input volume does not have it's coordinate center at 0. 

To evaluate the result, run: 

   tkmedit -f $SUBJECTS_DIR/talairach/mri/orig.mgz 

      -aux orig.talairach.mgz 

 

The main and aux volumes should overlap very closely. If they do not, use tkregister2 to fix it (run tkregister --help for docs).||
  ||--apply_inverse_transform xfmfile (-ait) ||apply inverse of tranform given by xfm or m3z files ||
  ||--devolvexfm subjectid||  ||
  ||--like name||output is embedded in a volume like name, or in stats-table like name (measure, columns, rows)||
  ||--crop <x> <y> <z> ||crop to 256 around center (x,y,z) ||
  ||--cropsize <dx> <dy> <dz>||crop to size <dx, dy, dz>||
  ||--cutends ncut ||remove ncut slices from the ends||
  ||--slice-crop s_start s_end ||keep slices s_start to s_end||
  ||--slice-reverse ||reverse order of slices, update vox2ras||
  ||--nslices-override nslices ||Use this number of slices when converting DICOM mosaics||
  ||--slice-bias alpha ||apply half-cosine bias field||
  ||--fwhm fwhm ||smooth input volume by fwhm mm||
 
 

=== SPECIFYING THE INPUT AND OUTPUT FILE TYPES

Legal values for --in_type (-it) and --out_type (-ot) are:  ===

  
 ArgumentExplanation||
  ||cor||MGH-NMR COR format (deprecated)||
  ||mgh||MGH-NMR format||
  ||mgz||MGH-NMR gzipped (compressed) mgh format||
  ||minc||MNI's Medical Imaging NetCDF format (output may not work)||
  ||analyze||3D analyze (same as spm)||
  ||analyze4d||4D analyze ||
  ||spm||SPM Analyze format (same as analyze and analyze3d)||
  ||ge||GE Genesis format (input only)||
  ||gelx||GE LX (input only)||
  ||lx||same as gelx||
  ||ximg||GE XIMG variant (input only)||
  ||siemens||Siemens IMA (input only)||
  ||dicom||generic DICOM Format (input only)||
  ||siemens_dicom||Siemens DICOM Format (input only)||
  ||afni||AFNI format||
  ||brik||same as afni||
  ||bshort||MGH-NMR bshort format||
  ||bfloat||MGH-NMR bfloat format||
  ||sdt||Varian (?)||
  ||outline||MGH-NMR Outline format||
  ||otl||same as outline||
  ||gdf||GDF volume (requires image stem for output; use -gis)||
  ||nifti1||NIfTI-1 volume (separate image and header files)||
  ||nii||NIfTI-1 volume (single file)

if the input/output has extension .nii.gz, then compressed is used||
 
 

=== CONVERTING TO SPM-ANALYZE FORMAT

Converting to SPM-Analyze format can be done in two ways, depending upon whether a single frame or multiple frames are desired. For a single frame, simply specify the output file name with a .img extension, and mri_convert will save the first frame into the file. For multiple frames, specify the base as the output file name and add --out_type spm. This will save each frame as baseXXX.img where XXX is the three-digit, zero-padded frame number. Frame numbers begin at one. By default, the width the of zero padding is 3. This can be controlled with --in_nspmzeropad N where N is the new width. ===

  
 ArgumentExplanation||
  ||--ascii||save output as ascii. This will be a data file with a single column of data. The fastest dimension will be col, then row,then slice, then frame.||
  ||--ascii+crsf||same as --ascii but includes col row slice and frame||
  ||-r, --reorder  olddim1 olddim2 olddim3||  ||
  ||-r4,--reorder4 olddim1 olddim2 olddim3 olddim4||Reorders axes such that olddim1 is the new column dimension,olddim2 is the new row dimension, olddim3 is the new slice, and olddim4 is the new frame dimension. 

     Example: 2 1 3 will swap rows and cols. 

  If using -r4, the output geometry will likely be wrong. It is best to re-run mri_convert and specify a correctly oriented volume through the --in_like option.  ||
  ||--invert_contrast threshold||All voxels in volume greater than threshold are replaced with 255-value. Only makes sense for 8 bit images. Only operates on the first frame. ||
  ||-i, --input_volume||  ||
  ||-o, --output_volume||  ||
  ||-c, --conform||conform to 1mm voxel size in coronal||
  ||  ||slice direction with 256^3 or more||
  ||-cm, --conform_min||conform to the src min direction size ||
  ||-cs, --conform_size size_in_mm||conform to the size given in mm ||
  ||-po, --parse_only||  ||
  ||-is, --in_stats||  ||
  ||-os, --out_stats||  ||
  ||-ro, --read_only||  ||
  ||-nw, --no_write||  ||
  ||-sn, --subject_name||  ||
  ||-rl, --reslice_like||  ||
  ||-tt, --template_type <type> (see above)||  ||
  ||--split ||split output frames into separate output files.||
  ||  ||Example: mri_convert a.nii b.nii --split will create b0000.nii b0001.nii b0002.nii ... ||
  ||--erode-seg Nerodes||Erode segmentation boundaries Nerode times (based on 6 nearest neighbors)||
  ||--dil-seg Ndilations||Dilate segmentation boundaries Ndilate times (based on 6 nearest neighbors) to fill seg=0 voxels||
  ||--dil-seg-mask mask||Dilate segmentation boundaries to fill mask||
  ||-f,  --frame frameno [...]||keep only 0-based frame number(s)||
  ||--mid-frame||keep only the middle frame||
  ||--nskip n||skip the first n frames||
  ||--ndrop n||drop the last n frames||
  ||--fsubsample start delta end||frame subsampling (end = -1 for end)||
  ||-sc, --scale factor ||input intensity scale factor||
  ||-osc, --out-scale factor||output intensity scale factor||
  ||-il, --in_like||  ||
  ||-roi||  ||
  ||-fp, --fill_parcellation||  ||
  ||-sp, --smooth_parcellation||  ||
  ||-zo, --zero_outlines||  ||
  ||-cf, --color_file||  ||
  ||-nt, --no_translate||  ||
  ||--status||status file for DICOM conversion||
  ||--sdcmlist||list of DICOM files for conversion||
  ||-ti, --template_info||dump info about template||
  ||-gis <gdf image file stem>||  ||
  ||-cg, --crop_gdf||apply GDF cropping||
  ||-zgez, --zero_ge_z_offset||set c_s=0 (appropriate for dicom \"files from GE machines with isocenter scanning)||
  ||-nozgez, --no_zero_ge_z_offset||don't set c_s=0, even if a GE volume||
  ||--sphinx||reorient to sphinx the position. This function is applicable when the input geometry information is correct but the  subject was in the scanner in the 'sphinx' position (ie, AP in line with the bore) instead of head-first-supine (HFS). This is often the case with monkeys. Note that the assumption is that the geometry information in the input file is otherwise accurate. ||
 
   

= OUTPUTS =

 
 OutputExplanation||
  ||outvolume||output volume||
 
   

= EXAMPLE 1 =

 

APPLYING TRANSFORMS (INCLUDING TALAIRACH)

The volume can be resampled into another space by supplying a transform using the --apply_transform flag. This reads the transform file and applies the transform (when --apply_inverse_transform is used, the transform is inverted and then applied). An example of a transform file is talairach.xfm as found in subjectid/mri/transforms. To convert a subject's orig volume to talairach space, execute the following lines: 

* cd subjectid/mri mkdir talairach mri_convert --apply_transform transforms/talariach.xfm --devolvexfm subjectid --ic 0 0 0 orig talairach

This properly accounts for the case where the input volume does not have it's coordinate center at 0.To evaluate the result, run:

* tkmedit -f $SUBJECTS_DIR/talairach/mri/orig -aux talairach 

The main and aux volumes should overlap very closely. If they do not, use tkregister2 to fix it (run tkregister --help for docs).  

= EXAMPLE 2 =

 

From the subject directory: mri_convert -at mri/transforms/talairach_one.m3z mri/norm.mgz mri/norm_transformed_by_gca_one.mgz  

= BUGS =

 

None  

= REPORTING =

 

Report bugs to <freesurfer@nmr.mgh.harvard.edu>  

= SEE-ALSO =

 

mris_convert