Custom crosshair label and background dset in SUMA

Dear AFNI/SUMA experts,

SUMA seems to use a default annotation dset (aparc.a2009s.annot), so that an anatomical label is displayed for each surface vertex, both in the main window and in Xhair Info panel of Surface Controller.

I would like to use another annotation dset for this purpose. (Q1) How can I change which dset to use? (apart from replacing aparc.a2009s.annot.niml.dset with my own file to trick SUMA)

I notice that aparc.a2009s.annot and Convexity (presumably from sulc.gii.dset) are selected as background dset by default. A related question is (Q2) how can I change these background (bk) dset? (Load Dset button can only load dset as foreground (fg) dset)

Many thanks!

The annotation is set in the spec file, so you would need to change that there. Alternatively, load the dataset from the surface object controller or from the command line or script with DriveSuma.


Consider a common way of running suma, by using a *.spec file to specify available dsets for browsing-- the following is the example script “run.suma.00.both.141” in the Bootcamp data (AFNI_data6/FT_analysis/FT/SUMA/):

suma -onestate -spec std.141.FT_both.spec -sv FT_SurfVol.nii &

If you search for “annot” in that *.spec file, you will see its role as the “LabelDset”

	SurfaceFormat = ASCII
	SurfaceType = GIFTI
	SurfaceName = ././std.141.lh.smoothwm.gii
	LocalDomainParent = ././SAME
	LabelDset = ././std.141.lh.aparc.a2009s.annot.niml.dset
	SurfaceState = std.smoothwm
	EmbedDimension = 3
	Anatomical = Y
	LocalCurvatureParent = ././SAME

In order to generate more annot files, I think you use this opt when running @SUMA_Make_Spec_FS:

-extra_annot_labels L1 L2 ...  : convert extra annot files into ROI dsets
          e.g. -extra_annot_labels aparc

          FS typically outputs annotaion files:
          from each of which Make_Spec extracts a colormap, ROI and a
          displayable surface dataset.

          Use this option to specify other labels to extract.

          If LABEL is specified, then expected annotation files will be:

Dear Danial and Paul,

Thank you very much for pointing out the LabelDset field in the *.spec file, which is exactly what I want.
With some trial-and-errors, I was able to display HCP-MMP1 ( annotation in SUMA. In case someone search for this in the future, I read out the color table from the lh.HCP-MMP1.annot, manually generated a lh.HCP-MMP1.ctab file, then called FSread_annot -input lh.HCP-MMP1.annot -FSversion 2009 -FScmap lh.HCP-MMP1.ctab -FScmaprange 0 180 -dset lh.HCP-MMP1.annot.niml.dset, and substituted the LabelDset in the *.spec file.

The remaining questions are:

  1. I’m not sure why FSread_annot cannot read out the color table from lh.HCP-MMP1.annot by itself.
  2. Can we specify more than one LabelDset in *.spec? Simply duplicate the row doesn’t work for sure.

@Danial, I guess both the GUI and DriveSuma can only load foreground dset, but not background dset like Convexity and aparc.a2009s? Can we load a background dset into SUMA?
@Paul, I didn’t find the -extra_annot_labels option in @SUMA_Make_Spec_FS online doc or source (Version AFNI_19.0.24 ‘Tiberius’).


The -extra_annot_labels option got added in February of 2020—now in the reign of Emperor Titus—and your current version is from the first quarter of 2019 (nearly 2 years ago). How would you feel about updating your AFNI:

@update.afni.binaries -d

? There are probably other improvements/fixes/etc. that would be beneficial to have.

Also, this might be helpful about driving SUMA:
Though, indeed, it focuses on the overlay part. Some tutorial information on visualizing ROIs directly:


There is no control for the background dataset other than turning the background colors on or off with a simulated keypress ‘b’. You can control all foreground datasets and add more.

Thank you for your answers! Even knowing sth cannot be done make me feel more comfortable than keep puzzling:P

I’ll check those tutorial videos. Very grateful for your effort to make them freely available on youtube.