@SUMA_Make_Spec_FS fails with FreeSurferColorLUT.txt read error

AFNI Message Board
1

Hello,
I noticed the following errors when running @SUMA_Spec_FS to convert Freesurfer outputs into AFNI/SUMA format.
I ran @SUMA_Make_Spec_FS like this:

@SUMA_Make_Spec_FS    \
  -NIFTI       \
  -use_mgz     \
  -sid ${id}   \
  -fspath ${fs_dir}

I got the following errors, which seem to suggest a problem reading the FreeSurfer color table (FreeSurferColorLUT.txt):

Setting -FScmaprange to [13100 13199]
--     Error SUMA_readFScolorLUT (SUMA_Surface_IO.c:1982):
Failed to read r
--     Error SUMA_readFSannot (SUMA_Surface_IO.c:2259):
Failed to read FS color table /Applications/freesurfer/8.1.0/FreeSurferColorLUT.txt
--     Error FSread_annot (SUMA_FSread_annot.c:421):
Failed reading annotation file (or output file exists)
++     Notice FSread_annot (SUMA_FSread_annot.c:298 @14:15:54):
Guessed FS annot version of 2009
++     Notice FSread_annot (SUMA_FSread_annot.c:312 @14:15:54):
Guessed right hemisphere
++     Notice FSread_annot (SUMA_FSread_annot.c:333 @14:15:54):
Using /Applications/freesurfer/8.1.0/FreeSurferColorLUT.txt
++     Notice FSread_annot (SUMA_FSread_annot.c:348 @14:15:54):
Setting -FScmaprange to [14100 14199]
--     Error SUMA_readFScolorLUT (SUMA_Surface_IO.c:1982):
Failed to read r
--     Error SUMA_readFSannot (SUMA_Surface_IO.c:2259):
Failed to read FS color table /Applications/freesurfer/8.1.0/FreeSurferColorLUT.txt
--     Error FSread_annot (SUMA_FSread_annot.c:421):
Failed reading annotation file (or output file exists)

Although these errors are shown, the @SUMA_Make_Spec_FS's process appears to complete without stopping.
Also, I checked the first few lines of FreeSurferColorLUT.txt, and it seems that its format is correct.


#No. Label Name:                            R   G   B   A

0   Unknown                                 0   0   0   0
1   Left-Cerebral-Exterior                  70  130 180 0
2   Left-Cerebral-White-Matter              245 245 245 0
3   Left-Cerebral-Cortex                    205 62  78  0
4   Left-Lateral-Ventricle                  120 18  134 0

My FreeSurfer version is 8.1.0, and AFNI is:
Precompiled binary macos_13_ARM: Sep 17 2025 (Version AFNI_25.2.13).

Could these errors be related to my laptop environment, or could there be a problem with the FreeSurferColorLUT.txt file?

Thank you in advance.

Nori

2

Hi, Nori-

Fascinating. And the numbers there do seem to match with a quick scan of this FreeSurferColorLUT reference file online.

Just to check, does that file exist in that place on that system? That is, does this produce an error or not:

ls /Applications/freesurfer/8.1.0/FreeSurferColorLUT.txt

?

--pt

3

Hi, thank you for your reply.

Yes. When I ran the command you shared, it returned the expected file path of the color table file like this:

ls /Applications/freesurfer/8.1.0/FreeSurferColorLUT.txt
/Applications/freesurfer/8.1.0/FreeSurferColorLUT.txt

Nori

4

Hi, Nori-

I have just looked into this a little bit.

When I run your @SUMA_Make_Spec_FS command (having FreeSurfer ver=8.1.0 loaded), I do get the same error message, even when I don't use -use_mgz, which I don't normally do. While this error is most non-fatal, when I run a diff on the outputs from an earlier run I had, in this case I do not have the following files:

lh.aparc.a2009s.annot.1D.cmap
lh.aparc.a2009s.annot.1D.roi
lh.aparc.a2009s.annot.niml.dset
rh.aparc.a2009s.annot.1D.cmap
rh.aparc.a2009s.annot.1D.roi
rh.aparc.a2009s.annot.niml.dset
std.141.lh.aparc.a2009s.annot.niml.dset
std.141.rh.aparc.a2009s.annot.niml.dset
std.60.lh.aparc.a2009s.annot.niml.dset
std.60.rh.aparc.a2009s.annot.niml.dset

For whatever reason, the issue seems to be related to the FreeSurfer version that is being used. When I run the same command with FreeSurfer ver=7.4.1, I do not get any errors. (This had been the previous version of FS that I had used, and I had not seen these errors, and I did get the above *cmap, *roi, *dset, files.)

I am not sure exactly what has changed between FS 7.4.1 and 8.1.0, but apparently something has. The @SUMA_Make_Spec_FS command does use some FS commands, like mris_convert.

So, I don't have a fix, but I have a better idea of what is happening and where it is affected.

--pt

5

Hi, pt-

Thank you for looking into the issue and for the update.
It's helpful for me to know that the problem may be related to the FreeSurfer version.
I'd appreciate it if you could let me know when any updates or possible solutions are available.

Nori

6

Hi, Nori-

I think I might have found the issue. The FreeSurfer file "FreeSurferColorLUT_8.1.0.txt" typically has the following structure, of a number, a label, and 4 color values (R G B A), like this at the start of the file:

#No. Label Name:                            R   G   B   A

0   Unknown                                 0   0   0   0
1   Left-Cerebral-Exterior                  70  130 180 0
2   Left-Cerebral-White-Matter              245 245 245 0
3   Left-Cerebral-Cortex                    205 62  78  0
4   Left-Lateral-Ventricle                  120 18  134 0
5   Left-Inf-Lat-Vent                       196 58  250 0
6   Left-Cerebellum-Exterior                0   148 0   0

That is the case for FreeSurferColorLUT_7.4.1.txt all the way through. However, FreeSurferColorLUT_8.1.0.txt has a chunk with an extra column of numbers here:

# sclimbic
819 Left-HypoThal-noMB           0  80   0 0 2
820 Right-HypoThal-noMB         15 165   15 0 2
821 Left-Fornix                  0 255 255 0 3
822 Right-Fornix                27 187 253 0 3 
843 Left-MammillaryBody        178 255  80 0 2
844 Right-MammillaryBody        25 246  80 0 2
853 Mid-AntCom                  60  58 210 0 3
865 Left-Basal-Forebrain       170  85   0 0 2
866 Right-Basal-Forebrain      139  69  19 0 2
869 Left-SeptalNuc             255 170 255 0 2
870 Right-SeptalNuc            191 127 191 0 2

This breaks the readability of this file with AFNI's FSread_annot, at present. I will reach out to the FreeSurfer folks for more guidance, and possibly a more permanent fix.

I don't have an elegant/quick fix at the moment.

Thanks for bringing this up.

--pt

7

Hi again, Nori-

I have heard back (quickly) from the FreeSurfer developers. It seems that indeed an extra column of numbers was included for this subset of regions in the version-specific FreeSurferColorLUT_8.1.0.txt text file.

There is a new version of FreeSurfer, ver=8.2.0, that should not have this issue, so updating your FreeSurfer version should fix this problem.

Or, if you are not wanting to update your version, you should be able to edit the current text file, to remove that last column (which is the extra info), and hence be:

# sclimbic
819 Left-HypoThal-noMB           0  80   0 0
820 Right-HypoThal-noMB         15 165   15 0
821 Left-Fornix                  0 255 255 0
822 Right-Fornix                27 187 253 0
843 Left-MammillaryBody        178 255  80 0
844 Right-MammillaryBody        25 246  80 0
853 Mid-AntCom                  60  58 210 0
865 Left-Basal-Forebrain       170  85   0 0
866 Right-Basal-Forebrain      139  69  19 0
869 Left-SeptalNuc             255 170 255 0
870 Right-SeptalNuc            191 127 191 0

Please let us know how it goes.

--pt

8

Hi, pt

Thank you for sharing the update!
I will first try editing the current FreeSurferColorLUT.txt.
If I need to revise a lot, I will update my Freesurfer.
I will let you know when I have any results.

Nori

9

Hi, Nori-

Sounds like a plan. When I ran it, I just needed to edit the 11 lines shown above. Please let us know if it seems like any other editing would need to be done.

Thanks,
pt

10

Hi, pt

I edited the 11 lines of FreeSurferColorLUT.txt you shared, and @Make_SUMA_Spec_FS ran successfully without any errors.
Thank you very much for your help!

Nori

1 Like