AFNI program: 3dresample

Output of -help


3dresample - reorient and/or resample a dataset

    This program can be used to change the orientation of a dataset (via
    -orient), or the dx,dy,dz grid spacing (via -dxyz or any of
    -upsample, -downsample or -delta_scale), or change them both to
    match that of a master dataset (via the -master option).

    Note: if both -master and -dxyz are used, the dxyz values will
          override those from the master dataset.

 ** It is important to note that once a dataset of a certain grid is
    created (i.e. orientation, dxyz, field of view), if other datasets
    are going to be resampled to match that first one, then -master
    should be used, rather than repeating -dxyz.  That will guarantee
    that all grids match.

    Otherwise, even using both -orient and -dxyz, one may not be sure
    that the origin and voxel counts will match, as the are computed.

 ** Warning: this program is not meant to transform datasets between
             view types (such as '+orig' and '+tlrc') or spaces.

             For that purpose, please see 3dAllineate or 3dNwarpApply.

------------------------------------------------------------

  usage: 3dresample [options] -prefix OUT_DSET -input IN_DSET

  examples:

    3dresample -orient asl         -prefix new.asl.dset  -input old+orig
    3dresample -dxyz 1.0 1.0 0.9   -prefix new.119.dset  -input old+tlrc
    3dresample -master master+orig -prefix new.dset      -input old+orig
    3dresample -downsample 3       -prefix new.down2.nii -input old.nii
    3dresample -upsample   3       -prefix new.up2.nii   -input old.nii

  note:

    Information about a dataset's voxel size and orientation can be
    found via program 3dinfo.

------------------------------------------------------------

  terminal options: 

    -help            : show this help information

    -hist            : output the history of program changes

    -version         : show version information

  main options

    -bound_type TYPE : specify which boundary is preserved
          e.g.     -bound_type SLAB
          default: -bound_type CENT  (for delta_scale operations)
          default: -bound_type FOV   (for other operations)

      TYPE
      ----
      FOV : field of view (see 'to3d -help')
          : half a voxel outside of bounding centers (SLAB)

          The default and original use preserves the field of view when
          resampling, allowing the extents (SLABs) to grow or shrink by
          half of the difference in the dimension size (big voxels to
          small will cause the extents to expand, for example, while
          small to big will cause them to shrink).

      SLAB : extents or bounding centers (see 'to3d -help')
           : from outer voxel center to outer voxel center

          SLAB will have the opposite effect as FOV.  The extents should
          be unchanged (subject to voxel size truncation), while the FOV
          will grow or shrink in the opposite way as above.

          Note that when using SLAB, edge voxels should be mostly
          unaffected by the interpolation.

      CENT_ORIG: preserve voxel centroids (not in to3d)

          Try to preserve voxel centers when resampling.  If scaling the
          voxel sizes (up or down) by an integer, output voxels should
          be on the original grid as much as possible.

       ** If directly using -dxyz, the user should be sure the new dxyz
          values scale correctly.  Otherwise consider using -upsample,
          -downsample or -delta_scale.

          When upsampling (by a scale factor of S):

            The result should have approximately S times the number of
            voxels (in each direction), each being 1/S times as large.

            method: find maximum SLAB strictly inside original FOV

        *   For integer S, this result will include all original voxel
            centers, plus (S-1) inner centers per voxel, plus
            floor((S-e)/2) centers per side, for some epsilon, e.

          downsample (by a scale factor of S):

            The result should have approximately 1/S times the number of
            voxels (in each direction), each being S times as large.

            method: find maximum SLAB strictly inside original SLAB

        *   For integer S, this result will include only original voxel
            centers, and fewer of them.  The origin will be offset by
            half of the missing slab :
               floor(1/2 * (old_slab-new_slab)/dold + e)

          For either upsample or downsample (by an integer scalar S),
          the origin shift will be a multiple of the smaller voxel size
          (dold or dnew).

      CENT : preserve voxel centroids (not in to3d)
           : be orientation agnostic

          This is the same as CENT_ORIG, except that CENT_ORIG truncates
          toward the origin in each direction.  CENT will truncate
          towards R,A,I, making it orientation agnostic (the result
          should be independent of the orientation on disk).

          This is the default bound_type when rescaling voxels with
          -upsample, -downsample or -delta_scale (unless -bound_type
          is applied).

    -debug LEVEL     : print debug info along the way
          e.g.  -debug 1
          default level is 0, max is 2

    -dxyz DX DY DZ   : resample to new dx, dy and dz
          e.g.  -dxyz 1.0 1.0 0.9
          default is to leave unchanged

          Each of DX,DY,DZ must be a positive real number, and will be
          used for a voxel delta in the new dataset (according to any
          new orientation).

    -input IN_DSET   : required input dataset to reorient
          e.g.  -input old.dset+orig

          Specify the input dataset.

    -inset IN_DSET   : alternative to -input

    -master MAST_DSET: align dataset grid to that of MAST_DSET
          e.g.  -master master.dset+orig

          Get dxyz and orient from a master dataset.  The resulting grid
          will match that of the master.  This option can be used with
          -dxyz, but not with -orient.

    -orient OR_CODE  : reorient to new axis order.
          e.g.  -orient asl
          default is to leave unchanged

          The orientation code is a 3 character string, where the
          characters come from the respective sets:
          {A,P}, {I,S}, {L,R}

          For example OR_CODE = LPI is the standard 'neurological'
          orientation, where the x-axis runs Left-to-Right, the y-axis
          runs Posterior-to-Anterior, and the z-axis runs
          Inferior-to-Superior.

    -prefix OUT_DSET : required prefix for output dataset
          e.g.  -prefix reori.asl.pickle

          Specify the name of the output data.  To get NIFTI, simply
          include a .nii or .nii.gz suffix, as with most AFNI programs.

    -rmode RESAM     : use this resampling method
          e.g.  -rmode Linear
          default is NN (nearest neighbor)

          The resampling method string RESAM should come from the set
          {'NN', 'Li', 'Cu', 'Bk'}.  These are for 'Nearest Neighbor',
          'Linear', 'Cubic' and 'Blocky' interpolation, respectively.

          For details, go to the 'Define Datamode' panel of the afni
          GUI, click BHelp and then the 'ULay resam mode' menu.

    -upsample FAC    : upsample the voxels by factor FAC

          Upsampling the voxels makes them smaller.  This convenience
          option is equivalent to using:

             -dxyz old_dx/FAC old_dy/FAC old_dz/FAC
             -bound_type CENT

          Specifying -bound_type BBB afterwards will override the
          default 'CENT' for this option.

    -downsample FAC   : downsample the voxels by factor FAC

          Downsampling the voxels makes them larger.  This convenience
          option is equivalent to using:

             -dxyz old_dx*FAC old_dy*FAC old_dz*FAC
             -bound_type CENT

          Specifying -bound_type BBB afterwards will override the
          default 'CENT' for this option.

    -delta_scale FAC  : rescale voxels sizes by factor FAC

          This is a generalized version of -upsample/-downsample,
          included since it is actually how they are applied (and they
          are not allowed factors < 1.0).  The weirdness is since
          upsample FAC > 1 means the voxels get smaller, as 1.0/FAC.

          -delta_scale is equivalent to -downsample, and equates to: 

             -dxyz old_dx*FAC old_dy*FAC old_dz*FAC
             -bound_type CENT

          FAC overview:

                   FAC <= 0.0    : illegal
             0.0 < FAC <  1.0    : upsample (smaller voxels)
                   FAC == 1.0    : no change in voxel size
             1.0 < FAC           : downsample (larger voxels)

------------------------------------------------------------

  Author: R. Reynolds - Version 1.11 <December 15, 2025>
This page auto-generated on Wed Jan 7 07:14:03 PM EST 2026