DOC: Add a new section in the Nifti images user doc page specifying how the

sform/qform codes are initialised.

Author: pauldmccarthy

doc/source/nifti_images.rst

@@ -281,6 +281,61 @@ the sform: ``get_qform()``, ``set_qform()``.
 The qform also has a corresponding ``qform_code`` with the same interpretation
 as the `sform_code`.
 
+Default sform and qform codes
+=============================
+
+If you create a new image, e.g.:
+
+>>> data = np.random.random((20, 20, 20))
+>>> xform = np.eye(4) * 2
+>>> img = nib.nifti1.Nifti1Image(data, xform)
+
+The sform and qform codes will be initialised to 2 (aligned) and 0 (unknown)
+respectively:
+
+>>> img.get_sform(coded=True)
+(array([[ 2.,  0.,  0.,  0.],
+        [ 0.,  2.,  0.,  0.],
+        [ 0.,  0.,  2.,  0.],
+        [ 0.,  0.,  0.,  1.]]), array(2, dtype=int16))
+>>> img.get_qform(coded=True)
+(None, 0)
+
+This is based on the assumption that the affine you specify for a newly
+created image will align the image to some known coordinate system. According
+to the `NIfTI specification <nifti1>`_, the qform is intended to encode a
+transformation into scanner coordinates - for a programmatically created
+image, we have no way of knowing what the scanner coordinate system is;
+furthermore, the qform cannot be used to store an arbitrary affine transform,
+as it is unable to encode shears. So the provided affine will be stored in the
+sform, and the qform will be left uninitialised.
+
+If you create a new image and specify an existing header, e.g.:
+
+>>> example_ni1 = os.path.join(data_path, 'example4d.nii.gz')
+>>> n1_img = nib.load(example_ni1)
+>>> new_header = header=n1_img.header.copy()
+>>> new_data = np.random.random(n1_img.shape[:3])
+>>> new_img = nib.nifti1.Nifti1Image(data, None, header=new_header)
+
+Then the newly created image will inherit the same sform and qform codes that
+are in the provided header. However, if you create a new image with both an
+affine and a header specified, e.g.:
+
+>>> xform = np.eye(4)
+>>> new_img = nib.nifti1.Nifti1Image(data, xform, header=new_header)
+
+Then the sform and qform codes will *only* be preserved if the provided affine
+is the same as the affine in the provided header. If the affines do not match,
+the sform and qform codes will be set to their default values of 2 and 0
+respectively. This is done on the basis that, if you are changing the affine,
+you are likely to be changing the space to which the affine is pointing. So
+the original sform and qform codes can no longer be assumed to be valid.
+
+If you wish to set the sform and qform affines and/or codes to some other
+value, you can always set them after creation using the ``set_sform`` and
+``set_qform`` methods, as described above.
+
 The fall-back header affine
 ===========================