Help description for sct_image -setorient is misleading

[joshuacwnewton]

The help description for -setorient says the following:

ORIENTATION OPERATIONS:
  -getorient            Get orientation of the input image (default: False)
  -setorient {RIP,LIP,RSP,LSP,RIA,LIA,RSA,LSA,IRP,ILP,SRP,SLP,IRA,ILA,SRA,SLA,RPI,LPI,RAI,LAI,RPS,LPS,RAS,LAS,PRI,PLI,ARI,ALI,PRS,PLS,ARS,ALS,IPR,SPR,IAR,SAR,IPL,SPL,IAL,SAL,PIR,PSR,AIR,ASR,PIL,PSL,AIL,ASL}
                        Set orientation of the input image (only modifies the header).
  -setorient-data {RIP,LIP,RSP,LSP,RIA,LIA,RSA,LSA,IRP,ILP,SRP,SLP,IRA,ILA,SRA,SLA,RPI,LPI,RAI,LAI,RPS,LPS,RAS,LAS,PRI,PLI,ARI,ALI,PRS,PLS,ARS,ALS,IPR,SPR,IAR,SAR,IPL,SPL,IAL,SAL,PIR,PSR,AIR,ASR,PIL,PSL,AIL,ASL}
                        Set orientation of the input image's data (does NOT modify the header, but the data). Use with care !

However, -setorient doesn't only modify the header. It modifies the data array, too:

spinalcordtoolbox/spinalcordtoolbox/image.py

Lines 1072 to 1092 in 03eadb0

	# axes inversion (flip)
	data = im_src_data[::inversion[0], ::inversion[1], ::inversion[2]]
	# axes manipulations (transpose)
	if perm == [1, 0, 2]:
	data = np.swapaxes(data, 0, 1)
	elif perm == [2, 1, 0]:
	data = np.swapaxes(data, 0, 2)
	elif perm == [0, 2, 1]:
	data = np.swapaxes(data, 1, 2)
	elif perm == [2, 0, 1]:
	data = np.swapaxes(data, 0, 2) # transform [2, 0, 1] to [1, 0, 2]
	data = np.swapaxes(data, 0, 1) # transform [1, 0, 2] to [0, 1, 2]
	elif perm == [1, 2, 0]:
	data = np.swapaxes(data, 0, 2) # transform [1, 2, 0] to [0, 2, 1]
	data = np.swapaxes(data, 1, 2) # transform [0, 2, 1] to [0, 1, 2]
	elif perm == [0, 1, 2]:
	# do nothing
	pass
	else:
	raise NotImplementedError()

Which makes sense, I think? If you're reorienting an image, you want the header metadata to correspond to the data array; you can't update one without also updating the other.

This came up when responding to a question on the forum: https://forum.spinalcordmri.org/t/rpi-orientation-issue/848

[jcohenadad]

Which makes sense, I think?

Yes, I agree with you. I wrongly wrote the text "only modifies the header" as I was looking at the help of fslorient which mentions that note at the end:

julien-macbook:~ $ fslorient 
Usage: fslorient <main option> <filename>

  where the main option is one of:
    -getorient             (prints FSL left-right orientation)
    -getsform              (prints the 16 elements of the sform matrix)
    -getqform              (prints the 16 elements of the qform matrix)
    -setsform <m11 m12 ... m44>  (sets the 16 elements of the sform matrix)
    -setqform <m11 m12 ... m44>  (sets the 16 elements of the qform matrix)
    -getsformcode          (prints the sform integer code)
    -getqformcode          (prints the qform integer code)
    -setsformcode <code>   (sets sform integer code)
    -setqformcode <code>   (sets qform integer code)
    -copysform2qform       (sets the qform equal to the sform - code and matrix)
    -copyqform2sform       (sets the sform equal to the qform - code and matrix)
    -deleteorient          (removes orient info from header)
    -forceradiological     (makes FSL radiological header)
    -forceneurological     (makes FSL neurological header - not Analyze)
    -swaporient            (swaps FSL radiological and FSL neurological)

       Note: the stored data order is never changed here - only the header info.
       To change the data storage use fslswapdim.

But it's clear that sct_image -setorient is more the equivalent of fslswapdim.

Thank you for catching that!