3dNwarpFuncs


Usage: 3dNwarpFuncs [options]

This program reads in a nonlinear 3D warp (from 3dQwarp, etc.) and
computes some functions of the displacements.  See the OPTIONS below
for information on what can be computed.

OPTIONS:
--------
 -nwarp  www  = 'www' is the name of the 3D warp dataset
                (this is a mandatory option!)
               ++ This can be computed on the fly, as in 3dNwarpApply.

 -prefix ppp  = 'ppp' is the name of the new output dataset

 -bulk        = Compute the (fractional) bulk volume change.
               ++ e.g., Jacobian determinant minus 1.
 -shear       = Compute the shear energy.
 -vorticity   = Compute the vorticity enerty.

If none of '-bulk', '-shear', or '-vorticity' are given, then '-bulk'
will be assumed.

NOTES:
------
Denote the displacement vector field (warp) by
   [ p(x,y,z) , q(x,y,z) , r(x,y,z) ]
Define the Jacobian matrix by

      [ 1+dp/dx   dp/dy    dp/dz  ]   [ Jxx Jxy Jxz ]
  J = [  dq/dx   1+dq/dy   dq/dz  ] = [ Jyx Jyy Jyz ]
      [  dr/dx    dr/dy   1+dr/dz ]   [ Jzx Jzy Jzz ]

* The '-bulk' output is the determinant of this matrix (det[J]), minus 1.
* It measures the amount of volume distortion.

* The '-shear' output is the sum of squares of the J matrix elements --
  which equals the sum of squares of its eigenvalues -- divided by
  det[J]^(2/3), then minus 3.
* It measures the amount of shearing distortion (normalized by the amount
  of volume distortion).

* The '-vorticity' output is the sum of squares of the skew part of
  the J matrix = [ Jxy-Jyx , Jxz-Jzx , Jyz-Jzy ], divided by det[J]^(2/3).
* It measures the amount of twisting distortion (also normalized).

* All 3 of these functions are dimensionless.

* The penalty used in 3dQwarp is a combination of the bulk, shear,
  and vorticity functions.

++ Compile date = Sep 17 2020 {AFNI_20.2.18:linux_ubuntu_16_64}