DOC: Update ctab documentation, comments

Author: effigies

nibabel/freesurfer/io.py

@@ -333,9 +333,13 @@ def read_annot(filepath, orig_ids=False):
     Annotation file format versions 1 and 2 are supported, corresponding to
     the "old-style" and "new-style" color table layout.
 
+    Note that the output color table ``ctab`` is in RGBT form, where T
+    (transparency) is 255 - alpha.
+
     See:
      * https://surfer.nmr.mgh.harvard.edu/fswiki/LabelsClutsAnnotationFiles#Annotation
      * https://github.com/freesurfer/freesurfer/blob/dev/matlab/read_annotation.m
+     * https://github.com/freesurfer/freesurfer/blob/8b88b34/utils/colortab.c
 
     Parameters
     ----------
@@ -352,7 +356,7 @@ def read_annot(filepath, orig_ids=False):
         Annotation id at each vertex. If a vertex does not belong
         to any label and orig_ids=False, its id will be set to -1.
     ctab : ndarray, shape (n_labels, 5)
-        RGBA + label id colortable array.
+        RGBT + label id colortable array.
     names : list of str (python 2), list of bytes (python 3)
         The names of the labels. The length of the list is n_labels.
     """
@@ -397,6 +401,9 @@ def read_annot(filepath, orig_ids=False):
 def _read_annot_ctab_old_format(fobj, n_entries):
     """Read in an old-style Freesurfer color table from `fobj`.
 
+    Note that the output color table ``ctab`` is in RGBT form, where T
+    (transparency) is 255 - alpha.
+
     This function is used by :func:`read_annot`.
 
     Parameters
@@ -412,7 +419,7 @@ def _read_annot_ctab_old_format(fobj, n_entries):
     -------
 
     ctab : ndarray, shape (n_entries, 5)
-        RGBA colortable array - the last column contains all zeros.
+        RGBT colortable array - the last column contains all zeros.
     names : list of str
         The names of the labels. The length of the list is n_entries.
     """
@@ -430,7 +437,7 @@ def _read_annot_ctab_old_format(fobj, n_entries):
         name_length = np.fromfile(fobj, dt, 1)[0]
         name = np.fromfile(fobj, "|S%d" % name_length, 1)[0]
         names.append(name)
-        # read RGBA for this entry
+        # read RGBT for this entry
         ctab[i, :4] = np.fromfile(fobj, dt, 4)
 
     return ctab, names
@@ -439,6 +446,9 @@ def _read_annot_ctab_old_format(fobj, n_entries):
 def _read_annot_ctab_new_format(fobj, ctab_version):
     """Read in a new-style Freesurfer color table from `fobj`.
 
+    Note that the output color table ``ctab`` is in RGBT form, where T
+    (transparency) is 255 - alpha.
+
     This function is used by :func:`read_annot`.
 
     Parameters
@@ -454,7 +464,7 @@ def _read_annot_ctab_new_format(fobj, ctab_version):
     -------
 
     ctab : ndarray, shape (n_labels, 5)
-        RGBA colortable array - the last column contains all zeros.
+        RGBT colortable array - the last column contains all zeros.
     names : list of str
         The names of the labels. The length of the list is n_labels.
     """
@@ -480,7 +490,7 @@ def _read_annot_ctab_new_format(fobj, ctab_version):
         name_length = np.fromfile(fobj, dt, 1)[0]
         name = np.fromfile(fobj, "|S%d" % name_length, 1)[0]
         names.append(name)
-        # RGBA
+        # RGBT
         ctab[idx, :4] = np.fromfile(fobj, dt, 4)
 
     return ctab, names
@@ -489,9 +499,13 @@ def _read_annot_ctab_new_format(fobj, ctab_version):
 def write_annot(filepath, labels, ctab, names, fill_ctab=True):
     """Write out a "new-style" Freesurfer annotation file.
 
+    Note that the color table ``ctab`` is in RGBT form, where T (transparency)
+    is 255 - alpha.
+
     See:
      * https://surfer.nmr.mgh.harvard.edu/fswiki/LabelsClutsAnnotationFiles#Annotation
      * https://github.com/freesurfer/freesurfer/blob/dev/matlab/write_annotation.m
+     * https://github.com/freesurfer/freesurfer/blob/8b88b34/utils/colortab.c
 
     Parameters
     ----------
@@ -500,7 +514,7 @@ def write_annot(filepath, labels, ctab, names, fill_ctab=True):
     labels : ndarray, shape (n_vertices,)
         Annotation id at each vertex.
     ctab : ndarray, shape (n_labels, 5)
-        RGBA + label id colortable array.
+        RGBT + label id colortable array.
     names : list of str
         The names of the labels. The length of the list is n_labels.
     fill_ctab : {True, False} optional