Merge pull request #666 from effigies/fix/annot_labels

FIX: Annotation labels are packed RGB, not RGBA

Author: effigies

nibabel/freesurfer/io.py

@@ -81,24 +81,24 @@ def _read_volume_info(fobj):
     return volume_info
 
 
-def _pack_rgba(rgba):
-    """Pack an RGBA sequence into a single integer.
+def _pack_rgb(rgb):
+    """Pack an RGB sequence into a single integer.
 
     Used by :func:`read_annot` and :func:`write_annot` to generate
     "annotation values" for a Freesurfer ``.annot`` file.
 
     Parameters
     ----------
-    rgba : ndarray, shape (n, 4)
-        RGBA colors
+    rgb : ndarray, shape (n, 3)
+        RGB colors
 
     Returns
     -------
     out : ndarray, shape (n, 1)
         Annotation values for each color.
     """
-    bitshifts = 2 ** np.array([[0], [8], [16], [24]], dtype=rgba.dtype)
-    return rgba.dot(bitshifts)
+    bitshifts = 2 ** np.array([[0], [8], [16]], dtype=rgb.dtype)
+    return rgb.dot(bitshifts)
 
 
 def read_geometry(filepath, read_metadata=False, read_stamp=False):
@@ -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.
     """
@@ -384,7 +388,7 @@ def read_annot(filepath, orig_ids=False):
             ctab, names = _read_annot_ctab_new_format(fobj, -n_entries)
 
     # generate annotation values for each LUT entry
-    ctab[:, [4]] = _pack_rgba(ctab[:, :4])
+    ctab[:, [4]] = _pack_rgb(ctab[:, :3])
 
     if not orig_ids:
         ord = np.argsort(ctab[:, -1])
@@ -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
@@ -523,8 +537,8 @@ def write_string(s):
 
         # Generate annotation values for each ctab entry
         if fill_ctab:
-            ctab = np.hstack((ctab[:, :4], _pack_rgba(ctab[:, :4])))
-        elif not np.array_equal(ctab[:, [4]], _pack_rgba(ctab[:, :4])):
+            ctab = np.hstack((ctab[:, :4], _pack_rgb(ctab[:, :3])))
+        elif not np.array_equal(ctab[:, [4]], _pack_rgb(ctab[:, :3])):
             warnings.warn('Annotation values in {} will be incorrect'.format(
                 filepath))
 

nibabel/freesurfer/tests/test_io.py

@@ -16,7 +16,7 @@
 
 from .. import (read_geometry, read_morph_data, read_annot, read_label,
                 write_geometry, write_morph_data, write_annot)
-from ..io import _pack_rgba
+from ..io import _pack_rgb
 
 from ...tests.nibabel_data import get_nibabel_data, needs_nibabel_data
 from ...fileslice import strided_scalar
@@ -236,8 +236,7 @@ def test_read_write_annot():
     # Generate the annotation values for each LUT entry
     rgbal[:, 4] = (rgbal[:, 0] +
                    rgbal[:, 1] * (2 ** 8) +
-                   rgbal[:, 2] * (2 ** 16) +
-                   rgbal[:, 3] * (2 ** 24))
+                   rgbal[:, 2] * (2 ** 16))
     annot_path = 'c.annot'
     with InTemporaryDirectory():
         write_annot(annot_path, labels, rgbal, names, fill_ctab=False)
@@ -287,8 +286,7 @@ def test_write_annot_fill_ctab():
         rgbal = np.hstack((rgba, np.zeros((nlabels, 1), dtype=np.int32)))
         rgbal[:, 4] = (rgbal[:, 0] +
                        rgbal[:, 1] * (2 ** 8) +
-                       rgbal[:, 2] * (2 ** 16) +
-                       rgbal[:, 3] * (2 ** 24))
+                       rgbal[:, 2] * (2 ** 16))
         with clear_and_catch_warnings() as w:
             write_annot(annot_path, labels, rgbal, names, fill_ctab=False)
         assert_true(
@@ -307,7 +305,7 @@ def gen_old_annot_file(fpath, nverts, labels, rgba, names):
         dt = '>i'
         vdata = np.zeros((nverts, 2), dtype=dt)
         vdata[:, 0] = np.arange(nverts)
-        vdata[:, [1]] = _pack_rgba(rgba[labels, :])
+        vdata[:, [1]] = _pack_rgb(rgba[labels, :3])
         fbytes = b''
         # number of vertices
         fbytes += struct.pack(dt, nverts)