void usage_SurfInfo (SUMA_GENERIC_ARGV_PARSE *ps)
{
static char FuncName[]={"usage_SurfInfo"};
char * s = NULL, *sio=NULL, *st = NULL, *sts = NULL;
int i;
SUMA_ENTRY;
s = SUMA_help_basics();
sio = SUMA_help_IO_Args(ps);
printf ( "\n"
"Usage: SurfInfo [options] <surface> \n"
" surface: A surface specified in any of the methods \n"
" shown below.\n"
" Optional Params:\n"
" -detail DETAIL: 1 = calculate surface metrics.\n"
" -debug DEBUG: Debugging level (2 turns LocalHead ON)\n"
" Specific Info: Using any of these options outputs values\n"
" only for the specified parameters.\n"
" -N_Node: Number of nodes\n"
" -N_FaceSet or -N_Tri: Number of triangles.\n"
" -COM: Center of mass\n"
" \n"
" -quiet: Do not include name of parameter in output.\n"
" -sep SEP: Use string SEP to separate parameter values.\n"
" Default is ' ; '\n"
"%s"
"%s"
"\n", sio, s);
SUMA_free(s); s = NULL; SUMA_free(st); st = NULL;
SUMA_free(sio); sio = NULL;
s = SUMA_New_Additions(0, 1); printf("%s\n", s);SUMA_free(s); s = NULL;
printf(" Ziad S. Saad SSCC/NIMH/NIH [email protected] \n");
exit(0);
}
void usage_SpharmReco (SUMA_GENERIC_ARGV_PARSE *ps)
{
static char FuncName[]={"usage_SpharmReco"};
char * s = NULL, *sio=NULL, *st = NULL, *sts = NULL;
int i;
s = SUMA_help_basics();
sio = SUMA_help_IO_Args(ps);
printf (
"\n"
"Spherical Harmonics Reconstruction from a set of harmonics \n"
"and their corresponding coefficients.\n"
"\n"
"Usage: \n"
" SpharmReco <-i_TYPE S> <-l L>\n"
" <-bases_prefix BASES>\n"
" <-coef BETA.0> <-coef BETA.1> ...\n"
" [<-prefix PREFIX>] [<-o_TYPE SDR> ...]\n"
" [-debug DBG] [-sigma s]\n"
"Input:\n"
" -i_TYPE SURF: SURF is a surface that is only used to provide\n"
" the topology of the mesh (the nodes' connections)\n"
" -l L: Decomposition order\n"
" -bases_prefix BASES_PREFIX: Files containing the bases functions (spherical\n"
" harmonics). See SpharmDeco for generating these\n"
" files.\n"
" -coef COEF.n: BETA.n is the coefficients file that is used to recompose \n"
" the nth data column. These files are created with SpharmDeco.\n"
" You can specify N coefficient files by repeating the \n"
" option on command line. If N is a multiple \n"
" of three AND you use -o_TYPE option, then each three \n"
" consecutive files are considered to form the XYZ coordinates\n"
" of a surface. See sample commands in @Spharm.examples \n"
" -prefix PREFIX: Write out the reconstructed data into dataset PREFIX. \n"
" the output dataset contains N columns; one for each of the\n"
" COEF.n files.\n"
" -o_TYPE SDR: Write out a new surface with reconstructed coordinates.\n"
" This requires N to be a multiple of 3, so 6 -coef options\n"
" will result in 2 surfaces written to disk. The naming of the\n"
" surfaces depends on the number of -o_TYPE options used, much \n"
" like in SpharmDeco\n"
" -debug DBG: Debug levels (1-3)\n"
" -sigma s: Smoothing parameter (0 .. 0.001) which weighs down the \n"
" contribution of higher order harmonics.\n"
"\n"
"-----------------------------------------------------------------------\n"
" For more detail, references, and examples, see script @Spharm.examples \n"
"-----------------------------------------------------------------------\n"
"\n"
"%s"
"%s"
"\n", sio, s);
SUMA_free(s); s = NULL; SUMA_free(st);
st = NULL; SUMA_free(sio); sio = NULL;
s = SUMA_New_Additions(0, 1); printf("%s\n", s);SUMA_free(s); s = NULL;
printf(" Ziad S. Saad SSCC/NIMH/NIH [email protected] \n");
exit(0);
}
void usage_Test_DSET_IO ()
{/*Usage*/
char *sb=NULL;
sb = SUMA_help_basics();
printf ("\n"
"Usage: \n"
"%s"
"\n", sb);
SUMA_free(sb);
exit (0);
}/*Usage*/
void usage_SUMA_SampBias (SUMA_GENERIC_ARGV_PARSE *ps)
{
static char FuncName[]={"usage_SUMA_SampBias"};
char * s = NULL, *sio=NULL, *st = NULL, *sts = NULL;
s = SUMA_help_basics();
sio = SUMA_help_IO_Args(ps);
printf (
"\nUsage:\n"
" SampBias -spec SPECFILE -surf SURFNAME -plimit limit -dlimit limit -out FILE\n"
"\n"
" Mandatory parameters:\n"
" -spec SpecFile: Spec file containing input surfaces.\n"
" -surf SURFNAME: Name of input surface \n"
" -plimit limit: maximum length of path along surface in mm.\n"
" default is 50 mm\n"
" -dlimit limit: maximum length of euclidean distance in mm.\n"
" default is 1000 mm\n"
" -out FILE: output results in .1D format.\n"
" -prefix PREFIX: output results into a proper surface-based\n"
" dataset. A more modern version of -out.\n"
"\n"
" NOTE: FILE and PREFIX (below) have differing numbers\n"
" of columns.\n"
"\n"
" -segdo SEGDO: Output a displayable object file that contains\n"
" segments between paired nodes.\n"
" See 'Ctrl+Alt+s' in SUMA's interactive help\n"
" Example:\n"
" SampBias -i std12.lh.smoothwm.asc \\\n"
" -segdo std12.sampbias.lh \\\n"
" -prefix std12.sampbias.lh \n"
"\n"
"\n"
"%s"
"%s"
"\n",
ps->hverb > 1 ? sio:"Use -help for more detail.\n",
ps->hverb > 1 ? s:"");
if (s) SUMA_free(s); s = NULL;
if (st) SUMA_free(st); st = NULL;
if (sio) SUMA_free(sio); sio = NULL;
#if 0
s = SUMA_New_Additions(0, 1); printf("%s\n", s);SUMA_free(s); s = NULL;
#endif
printf(" blame Ziad S. Saad SSCC/NIMH/NIH [email protected] \n");
return ;
}
void usage_SurfMatch (SUMA_GENERIC_ARGV_PARSE *ps, int detail)
{
static char FuncName[]={"usage_SurfMatch"};
char * s = NULL, *sio=NULL, *st = NULL, *sts = NULL;
int i;
s = SUMA_help_basics();
sio = SUMA_help_IO_Args(ps);
printf (
"\n"
"Usage: SurfMatch <-i_TYPE BASE> <-i_TYPE INSURF> <-prefix PREFIX> \n"
" [-sv SURF_VOL] [-warp WARP]\n"
" -i_TYPE BASE: BASE is the reference surface to which nodes will be\n"
" registered. The BASE surface is the first surface on the\n"
" command line.\n"
" -i_TYPE INSURF: Surface whose nodes will be affine transformed as to\n"
" minimize their shortest distance to BASE.\n"
" -depthlimit DL: Exclude from cost computations nodes in INSURF that \n"
" are more than DL from the top node along the principal\n"
" direction closest to the Z axis.\n"
" -reduce_ref RED: Reduce first mesh to speed up computations.\n"
" If RED is between 0 and 1.0, then the new surface\n"
" will approximately have RED * N_Nodes\n"
" If RED > 1.0 then RED is the approximate number of\n"
" nodes in the reduced mesh.\n"
" -warp WARP: Set the type of affine warp allowed. \n"
" Choose from the following:\n"
" sho: For shift only.\n"
" sro: For shift + rotate\n"
" srs: For shift + rotate + scale\n"
/* " aff: For affine general.\n" */
" -city: Use City Block instead of Euclidian distance\n"
"\n"
/* Need an option that just takes point, not necessarily a second
surface.
Need an option to provide cmask */
"Example:\n"
" SurfMatch -i std.6rh.pial.asc -i std.6lh.pial.asc -warp sro\n"
" suma -onestate -i std.6rh.pial.asc -i std.6lh.pial.asc \\\n"
" -i SurfMatch.gii \n"
"\n");
SUMA_free(s); s = NULL; SUMA_free(st); st = NULL;
SUMA_free(sio); sio = NULL;
printf(" Ziad S. Saad SSCC/NIMH/NIH [email protected] \n");
exit(0);
}
void usage_3dBRAIN_VOYAGERtoAFNI (SUMA_GENERIC_ARGV_PARSE *ps)
{
static char FuncName[]={"usage_3dBRAIN_VOYAGERtoAFNI"};
char * s = NULL, *sio=NULL, *st = NULL, *sts = NULL;
int i;
s = SUMA_help_basics();
sio = SUMA_help_IO_Args(ps);
printf ( "\n"
"Usage: 3dBRAIN_VOYAGERtoAFNI <-input BV_VOLUME.vmr> \n"
" [-bs] [-qx] [-tlrc|-acpc|-orig] [<-prefix PREFIX>]\n"
" \n"
" Converts a BrainVoyager vmr dataset to AFNI's BRIK format\n"
" The conversion is based on information from BrainVoyager's\n"
" website: www.brainvoyager.com. \n"
" Sample data and information provided by \n"
" Adam Greenberg and Nikolaus Kriegeskorte.\n"
"\n"
" If you get error messages about the number of\n"
" voxels and file size, try the options below.\n"
" I hope to automate these options once I have\n"
" a better description of the BrainVoyager QX format.\n"
"\n"
" Optional Parameters:\n"
" -bs: Force byte swapping.\n"
" -qx: .vmr file is from BrainVoyager QX\n"
" -tlrc: dset in tlrc space\n"
" -acpc: dset in acpc-aligned space\n"
" -orig: dset in orig space\n"
" If unspecified, the program attempts to guess the view from\n"
" the name of the input.\n"
"%s"
"%s"
"\n", sio, s);
SUMA_free(s); s = NULL; SUMA_free(st); st = NULL;
SUMA_free(sio); sio = NULL;
s = SUMA_New_Additions(0, 1); printf("%s\n", s);SUMA_free(s); s = NULL;
printf(" Ziad S. Saad SSCC/NIMH/NIH [email protected] \n");
exit(0);
}
void SUMA_ScaleToMap_usage ()
{
static char FuncName[]={"SUMA_ScaleToMap_usage"};
char * s = NULL;
SUMA_ENTRY;
s = SUMA_help_basics();
fprintf (SUMA_STDOUT,
"\nUsage: ScaleToMap <-input IntFile icol vcol> \n"
" [-cmap MapType] [-cmapfile Mapfile] [-cmapdb Palfile] [-frf] \n"
" [-clp/-perc_clp clp0 clp1] [-apr/-anr range]\n"
" [-interp/-nointerp/-direct] [-msk msk0 msk1] [-nomsk_col]\n"
" [-msk_col R G B] [-br BrightFact]\n"
" [-h/-help] [-verb] [-showmap] [-showdb]\n"
"\n"
" -input IntFile icol vcol: input data.\n"
" Infile: 1D formatted ascii file containing node values\n"
" icol: index of node index column \n"
" (-1 if the node index is implicit)\n"
" vcol: index of node value column.\n"
" Example: -input ValOnly.1D -1 0 \n"
" for a 1D file containing node values\n"
" in the first column and no node indices.\n"
" Example: -input NodeVal.1D 1 3\n"
" for a 1D file containing node indices in\n"
" the SECOND column and node values in the \n"
" FOURTH column (index counting begins at 0)\n"
" -v and -iv options are now obsolete.\n"
" Use -input option instead.\n"
" -cmap MapName: (optional, default RGYBR20) \n"
" choose one of the standard colormaps available with SUMA:\n"
" RGYBR20, BGYR19, BW20, GRAY20, MATLAB_DEF_BYR64, \n"
" ROI64, ROI128\n"
" You can also use AFNI's default paned color maps:\n"
" The maps are labeled according to the number of \n"
" panes and their sign. Example: afni_p10\n"
" uses the positive 10-pane afni colormap.\n"
" afni_n10 is the negative counterpart.\n"
" These maps are meant to be used with\n"
" the options -apr and -anr listed below.\n"
" You can also load non-default AFNI colormaps\n"
" from .pal files (AFNI's colormap format); see option\n"
" -cmapdb below.\n"
" -cmapdb Palfile: read color maps from AFNI .pal file\n"
" In addition to the default paned AFNI colormaps, you\n"
" can load colormaps from a .pal file.\n"
" To access maps in the Palfile you must use the -cmap option\n"
" with the label formed by the name of the palette, its sign\n"
" and the number of panes. For example, to following palette:\n"
" ***PALETTES deco [13]\n"
" should be accessed with -cmap deco_n13\n"
" ***PALETTES deco [13+]\n"
" should be accessed with -cmap deco_p13\n"
" -cmapfile Mapfile: read color map from Mapfile.\n"
" Mapfile:1D formatted ascii file containing colormap.\n"
" each row defines a color in one of two ways:\n"
" R G B or\n"
" R G B f \n"
" where R, G, B specify the red, green and blue values, \n"
" between 0 and 1 and f specifies the fraction of the range\n"
" reached at this color. THINK values of right of AFNI colorbar.\n"
" The use of fractions (it is optional) would allow you to create\n"
" non-linear color maps where colors cover differing fractions of \n"
" the data range.\n"
" Sample colormap with positive range only (a la AFNI):\n"
" 0 0 1 1.0\n"
" 0 1 0 0.8\n"
" 1 0 0 0.6\n"
" 1 1 0 0.4\n"
" 0 1 1 0.2\n"
" Note the order in which the colors and fractions are specified.\n"
" The bottom color of the +ve colormap should be at the bottom of the\n"
" file and have the lowest +ve fraction. The fractions here define a\n"
" a linear map so they are not necessary but they illustrate the format\n"
" of the colormaps.\n"
" Comparable colormap with negative range included:\n"
" 0 0 1 1.0\n"
" 0 1 0 0.6\n"
" 1 0 0 0.2\n"
" 1 1 0 -0.2\n"
" 0 1 1 -0.6\n"
" The bottom color of the -ve colormap should have the \n"
" lowest -ve fraction. \n"
" You can use -1 -1 -1 for a color to indicate a no color\n"
" (like the 'none' color in AFNI). Values mapped to this\n"
" 'no color' will be masked as with the -msk option.\n"
" If your 1D color file has more than three or 4 columns,\n"
" you can use the [] convention adopted by AFNI programs\n"
" to select the columns you need.\n"
" -frf: (optional) first row in file is the first color.\n"
" As explained in the -cmapfile option above, the first \n"
" or bottom (indexed 0 )color of the colormap should be \n"
" at the bottom of the file. If the opposite is true, use\n"
" the -frf option to signal that.\n"
" This option is only useful with -cmapfile.\n"
" -clp/-perc_clp clp0 clp1: (optional, default no clipping)\n"
" clips values in IntVect. if -clp is used then values in vcol\n"
" < clp0 are clipped to clp0 and > clp1 are clipped to clp1\n"
" if -perc_clp is used them vcol is clipped to the values \n"
" corresponding to clp0 and clp1 percentile.\n"
" The -clp/-prec_clp options are mutually exclusive with -apr/-anr.\n"
" -apr range: (optional) clips the values in IntVect to [0 range].\n"
" This option allows range of colormap to be set as in AFNI, \n"
" with Positive colorbar (Pos selected).\n"
" This option is mutually exclusive with -clp/-perc_clp).\n"
" set range = 0 for autoranging.\n"
" If you use -apr and your colormap contains fractions, you\n"
" must use a positive range colormap.\n"
" -anr range: (optional) clips the values in IntVect to [-range range].\n"
" This option allows range of colormap to be set as in AFNI, \n"
" with Negative colorbar (Pos NOT selected).\n"
" This option is mutually exclusive with -clp/-perc_clp).\n"
" set range = 0 for autoranging.\n"
" If you use -anr and your colormap contains fractions, you\n"
" must use a negative range colormap.\n"
" -interp: (default) use color interpolation between colors in colormap\n"
" If a value is assigned between two colors on the colorbar,\n"
" it receives a color that is an interpolation between those two colors.\n"
" This is the default behaviour in SUMA and AFNI when using the continuous\n"
" colorscale. Mutually exclusive with -nointerp and -direct options.\n"
" -nointerp: (optional) turns off color interpolation within the colormap\n"
" Color assigniment is done a la AFNI when the paned colormaps are used.\n"
" Mutually exclusive with -interp and -direct options.\n"
" -direct: (optional) values (typecast to integers) are mapped directly\n"
" to index of color in color maps. Example: value 4 is assigned\n"
" to the 5th (index 4) color in the color map (same for values\n"
" 4.2 and 4.7). This mapping scheme is useful for ROI indexed type\n"
" data. Negative data values are set to 0 and values >= N_col \n"
" (the number of colors in the colormap) are set to N_col -1\n"
" -msk_zero: (optional) values that are 0 will get masked no matter\n"
" what colormaps or mapping schemes you are using. \n"
" AFNI masks all zero values by default.\n"
" -msk msk0 msk1: (optinal, default is no masking) \n"
" Values in vcol (BEFORE clipping is performed) \n"
" between [msk0 msk1] are masked by the masking color.\n"
" -msk_col R G B: (optional, default is 0.3 0.3 0.3) \n"
" Sets the color of masked voxels.\n"
" -nomsk_col: do not output nodes that got masked.\n"
" It does not make sense to use this option with\n"
" -msk_col.\n"
" -br BrightFact: (optional, default is 1) \n"
" Applies a brightness factor to the colors \n"
" of the colormap and the mask color.\n"
" -h or -help: displays this help message.\n"
"\n"
" The following options are for debugging and sanity checks.\n"
" -verb: (optional) verbose mode.\n"
" -showmap: (optional) print the colormap to the screen and quit.\n"
" This option is for debugging and sanity checks.\n"
" You can use MakeColorMap in Usage3 to write out a colormap\n"
" in its RGB form.\n"
" -showdb: (optional) print the colors and colormaps of AFNI\n"
" along with any loaded from the file Palfile.\n"
"%s"
"\n", s);
SUMA_free(s); s = NULL;
s = SUMA_New_Additions(0, 1); printf("%s\n", s);SUMA_free(s); s = NULL;
fprintf (SUMA_STDOUT, " Ziad S. Saad SSCC/NIMH/NIH [email protected] \n"
" July 31/02 \n"
"\n");
SUMA_RETURNe;
}
void SUMA_usage (SUMA_GENERIC_ARGV_PARSE *ps, int detail)
{/*Usage*/
char *sb = NULL, *sio = NULL, *ssym=NULL;
ssym = SUMA_help_SPEC_symbolic();
sb = SUMA_help_basics();
sio = SUMA_help_IO_Args(ps);
printf (
"\nUsage: \n"
" Mode 0: Just type suma to see some toy surface and play\n"
" with the interface. Some surfaces are generated\n"
" using T. Lewiner's MarchingCubes library. \n"
" Use '.' and ',' keys to cycle through surfaces.\n"
"\n"
" Mode 1: Using a spec file to specify surfaces\n"
" suma -spec <Spec file> \n"
" [-sv <SurfVol>] [-ah AfniHost]\n"
"\n"
" Mode 2: Just show me the money\n"
" suma <-i SomeSurface> \n"
" [-sv <SurfVol>] [-ah AfniHost]\n"
"\n"
"\n%s", detail ? "":"use -h or -help for more help detail.\n");
if (detail) {
printf (
" Mode 1:\n"
" -spec <Spec file>: File containing surface specification. \n"
" This file is typically generated by \n"
" @SUMA_Make_Spec_FS (for FreeSurfer surfaces) or \n"
" @SUMA_Make_Spec_SF (for SureFit surfaces). \n"
" The Spec file should be located in the directory \n"
" containing the surfaces.\n"
"%s\n"
" [-sv <SurfVol>]: Anatomical volume used in creating the surface \n"
" and registerd to the current experiment's anatomical \n"
" volume (using @SUMA_AlignToExperiment). \n"
" This parameter is optional, but linking to AFNI is \n"
" not possible without it.If you find the need for it \n"
" (as some have), you can specify the SurfVol in the \n"
" specfile. You can do so by adding the field \n"
" SurfaceVolume to each surface in the spec file. \n"
" In this manner, you can have different surfaces using\n"
" different surface volumes.\n"
" [-ah AfniHost]: Name (or IP address) of the computer running AFNI. \n"
" This parameter is optional, the default is localhost.\n"
" When both AFNI and SUMA are on the same computer, \n"
" communication is through shared memory. \n"
" You can turn that off by explicitly setting AfniHost\n"
" to 127.0.0.1\n"
" [-niml]: Start listening for communications with NIML-formatted elements.\n"
" Environment variable SUMA_START_NIML can also be used to start\n"
" listening.\n"
" [-noniml]: Do not start listening for communications with NIML-formatted\n"
" elements, even if env. SUMA_START_NIML is set to YES\n"
"\n"
" Mode 2: Using -t_TYPE or -t* options to specify surfaces on command line.\n"
" -sv, -ah, -niml and -dev are still applicable here. This mode \n"
" is meant to simplify the quick viewing of a surface model.\n"
" suma [-i_TYPE surface] [-t* surface] \n"
" Surfaces specified on command line are place in a group\n"
" called 'DefGroup'.\n"
" If you specify nothing on command line, you will have a random\n"
" surface created for you. Some of these surfaces are generated\n"
" using Thomas Lewiner's sample volumes for creating isosurfaces.\n"
" See suma -sources for a complete reference.\n"
"\n"
"%s"
"\n"
" Modes 1 & 2: You can mix the two modes for loading surfaces but the -sv\n"
" option may not be properly applied.\n"
" If you mix these modes, you will have two groups of\n"
" surfaces loaded into SUMA. You can switch between them\n"
" using the 'Switch Group' button in the viewer controller.\n"
"\n"
"%s"
/*" [-iodbg] Trun on the In/Out debug info from the start.\n"
" [-memdbg] Turn on the memory tracing from the start.\n" */
" [-visuals] Shows the available glxvisuals and exits.\n"
" [-brethren_windows] For Testing Only. Show a listing of windows possibly \n"
" related to AFNI and SUMA.\n"
" [-version] Shows the current version number.\n"
" [-environment] Shows a list of all environment variables, \n"
" their default setting and your current setting.\n"
" The output can be used as a new .sumarc file.\n"
" Since it takes into consideration your own settings\n"
" this command can be used to update your .sumarc \n"
" regularly with a csh command like this:\n"
"\n"
" suma -environment > ~/sumarc && \\\n"
" cp ~/.sumarc ~/.sumarc-bak ; \\\n"
" mv ~/sumarc ~/.sumarc\n"
"\n"
"\n"
" [-drive_com DRIVE_SUMA_COM]: Drive suma with command DRIVE_SUMA_COM,\n"
" which has the same syntax that you would use for DriveSuma.\n"
" For instance:\n"
"\n"
" suma -i ld120 -drive_com '-com surf_cont -view_surf_cont y'\n"
" or \n"
" suma -drive_com '-com viewer_cont -key 'F12' -com kill_suma'\n"
"\n"
" You can use repeated instances of -drive_com to have a series\n"
" of commands that get executed in the order in which they appear\n"
" on the command line.\n"
"\n"
"\n"
"%s",
(detail > 1) ? ssym:" use -help for more detail on loading template surfaces with symbolic notation\n" ,
(detail > 1) ? sio:" use -help for more detail on input options\n" ,
(detail > 1) ? sb:" use -help for more detail on basic options\n",
(detail > 1) ? get_np_help():
" use -help for more detail on communication ports\n");
if (detail > 1) { printf(
"-help_interactive: Write the help for interactive usage into file\n"
" Mouse_Keyboard_Controls.txt\n"
"-help_sphinx_interactive HOUT: Write the help for interactive usage into \n"
" SPHINX formatted file HOUT"
"See DriveSuma's -write_*_help options for more\n"
"-test_help_string_edit: Show example of help string editing and quit\n"
"-test_help_string_edit_web: Like its prefix, but nicer for webpage.\n");
}
if (detail > 1) { printf(
" [-list_ports] List all port assignments and quit\n"
" [-port_number PORT_NAME]: Give port number for PORT_NAME and quit\n"
" [-port_number_quiet PORT_NAME]: Same as -port_number but writes out \n"
" number only\n"
" [-dev]: Allow access to options that are not well polished for\n"
" mass consuption.\n"
" [-fake_cmap]: Use X11 to render cmap. This is only needed to get colorbar\n"
" to appear when the frame is automatically captured by SUMA\n"
" for making documentation. This option has no other use.\n"
" [-update_env] Performs the set operations detailed under -environment\n"
" [-default_env] Output hard coded default environment values, ignoring\n"
" user settings.\n"
" [-latest_news] Shows the latest news for the current \n"
" version of the entire SUMA package.\n"
" [-all_latest_news] Shows the history of latest news.\n"
" [-progs] Lists all the programs in the SUMA package.\n"
" [-motif_ver] Displays the linked version of Motif.\n"
" [-sources] Lists code sources used in parts of SUMA.\n"
" [-help_nido] Help message for displayable objects of type NIDO\n"
"\n"
" For help on interacting with SUMA, press 'ctrl+h' with the mouse \n"
" pointer inside SUMA's window.\n"
" For more help: http://afni.nimh.nih.gov/pub/dist/edu/latest/suma/suma.pdf\n"
"\n"
" If you can't get help here, please get help somewhere.\n"
); }
}
SUMA_free(sb); SUMA_free(sio); SUMA_free(ssym);
if (detail) {
SUMA_Version(NULL);
printf ("\n"
"\n Ziad S. Saad SSCC/NIMH/NIH [email protected] \n\n");
}
return;
}/*Usage*/
void usage_SurfToSurf (SUMA_GENERIC_ARGV_PARSE *ps, int detail)
{
static char FuncName[]={"usage_SurfToSurf"};
char * s = NULL, *sio=NULL, *st = NULL, *sts = NULL;
int i;
s = SUMA_help_basics();
sio = SUMA_help_IO_Args(ps);
printf (
"\n"
"Usage: SurfToSurf <-i_TYPE S1> [<-sv SV1>]\n"
" <-i_TYPE S2> [<-sv SV1>]\n"
" [<-prefix PREFIX>]\n"
" [<-output_params PARAM_LIST>]\n"
" [<-node_indices NODE_INDICES>]\n"
" [<-proj_dir PROJ_DIR>]\n"
" [<-data DATA>]\n"
" [<-node_debug NODE>]\n"
" [<-debug DBG_LEVEL>]\n"
" [-make_consistent]\n"
" [<-dset DSET>]\n"
" [<-mapfile MAP_INFO>]\n"
" \n"
" This program is used to interpolate data from one surface (S2)\n"
" to another (S1), assuming the surfaces are quite similar in\n"
" shape but having different meshes (non-isotopic).\n"
" This is done by projecting each node (nj) of S1 along the normal\n"
" at nj and finding the closest triangle t of S2 that is intersected\n"
" by this projection. Projection is actually bidirectional.\n"
" If such a triangle t is found, the nodes (of S2) forming it are \n"
" considered to be the neighbors of nj.\n"
" Values (arbitrary data, or coordinates) at these neighboring nodes\n"
" are then transfered to nj using barycentric interpolation or \n"
" nearest-node interpolation.\n"
" Nodes whose projections fail to intersect triangles in S2 are given\n"
" nonsensical values of -1 and 0.0 in the output.\n"
"\n"
" Mandatory input:\n"
" Two surfaces are required at input. See -i_TYPE options\n"
" below for more information. \n"
"\n"
" Optional input:\n"
" -prefix PREFIX: Specify the prefix of the output file.\n"
" The output file is in 1D format at the moment.\n"
" Default is SurfToSurf\n"
" -output_params PARAM_LIST: Specify the list of mapping\n"
" parameters to include in output\n"
" PARAM_LIST can have any or all of the following:\n"
" NearestTriangleNodes: Use Barycentric interpolation (default)\n"
" and output indices of 3 nodes from S2\n"
" that neighbor nj of S1\n"
" NearestNode: Use only the closest node from S2 (of the three \n"
" closest neighbors) to nj of S1 for interpolation\n"
" and output the index of that closest node.\n"
" NearestTriangle: Output index of triangle t from S2 that\n"
" is the closest to nj along its projection\n"
" direction. \n"
" DistanceToSurf: Output distance (signed) from nj, along \n"
" projection direction to S2.\n"
" This is the parameter output by the precursor\n"
" program CompareSurfaces\n"
" ProjectionOnSurf: Output coordinates of projection of nj onto \n"
" triangle t of S2.\n"
" NearestNodeCoords: X Y Z coordinates of closest node on S2\n"
" Data: Output the data from S2, interpolated onto S1\n"
" If no data is specified via the -data option, then\n"
" the XYZ coordinates of SO2's nodes are considered\n"
" the data.\n"
" -data DATA: 1D file containing data to be interpolated.\n"
" Each row i contains data for node i of S2.\n"
" You must have one row for each node making up S2.\n"
" In other terms, if S2 has N nodes, you need N rows\n"
" in DATA. \n"
" Each column of DATA is processed separately (think\n"
" sub-bricks, and spatial interpolation).\n"
" You can use [] selectors to choose a subset \n"
" of columns.\n"
" If -data option is not specified and Data is in PARAM_LIST\n"
" then the XYZ coordinates of SO2's nodes are the data.\n"
" -dset DSET: Treat like -data, but works best with datasets, preserving\n"
" header information in the output.\n"
" -dset and -data are mutually exclusive.\n"
" Also, -dset and parameter Data cannot be mixed.\n"
" -node_indices NODE_INDICES: 1D file containing the indices of S1\n"
" to consider. The default is all of the\n"
" nodes in S1. Only one column of values is\n"
" allowed here, use [] selectors to choose\n"
" the column of node indices if NODE_INDICES\n"
" has multiple columns in it.\n"
" -proj_dir PROJ_DIR: 1D file containing projection directions to use\n"
" instead of the node normals of S1.\n"
" Each row should contain one direction for each\n"
" of the nodes forming S1.\n"
" -closest_possible OO: Flag allowing the substitution of the projection\n"
" result with the closest node that could be found\n"
" along any direction.\n"
" 0: Don't do that, direction results only.\n"
" 1: Use closest node if projection fails to hit target\n"
" 2: Use closest node if it is at a closer distance.\n"
" 3: Use closest and don't bother with projections.\n"
" -make_consistent: Force a consistency check and correct triangle \n"
" orientation of S1 if needed. Triangles are also\n"
" oriented such that the majority of normals point\n"
" away from center of surface.\n"
" The program might not succeed in repairing some\n"
" meshes with inconsistent orientation.\n"
" -mapfile MAP_INFO: Use the mapping from S2 to S1 that is stored in\n"
" MAP_INFO. MAP_INFO is a file containing the mapping\n"
" parameters between surfaces S2 and S1. \n"
" It is generated automatically by SurfToSurf when \n"
" -mapfile is not used, and saved under PREFIX.niml.M2M.\n"
" Reusing the MAP_INFO file allows for faster execution\n"
" of SurfToSurf the next time around, assuming of course\n"
" that the two surfaces involved are the same, and that \n"
" only the input data differs.\n"
" MAP_INFO is also generated by MapIcosahedron.\n"
"\n"
"%s"
"%s"
"\n", sio, s);
SUMA_free(s); s = NULL; SUMA_free(st); st = NULL; SUMA_free(sio); sio = NULL;
s = SUMA_New_Additions(0, 1); printf("%s\n", s);SUMA_free(s); s = NULL;
printf(" Ziad S. Saad SSCC/NIMH/NIH [email protected] \n"
" Shruti Japee LBC/NIMH/NIH [email protected] \n");
exit(0);
}
void usage_SUMA_SurfClust (int detail)
{
static char FuncName[]={"usage_SUMA_SurfClust"};
char * s = NULL;
s = SUMA_help_basics();
printf (
"\nUsage: A program to perform clustering analysis surfaces.\n"
" SurfClust <[-spec SpecFile -surf_A insurf] [-i insurf]> \n"
" <-input inData.dset dcol_index> \n"
" <-rmm rad>\n"
" [-amm2 minarea]\n"
" [-n minnodes]\n"
" [-prefix OUTPREF] \n"
" [-out_clusterdset] [-out_roidset] \n"
" [-out_fulllist]\n"
" [-sort_none | -sort_n_nodes | -sort_area]\n"
"\n"
" The program can outputs a table of the clusters on the surface,\n"
" a mask dataset formed by the different clusters and a clustered\n"
" version of the input dataset.\n"
"\n"
" Mandatory parameters:\n"
" Surface Input can be done with:\n"
" -spec SpecFile: The surface spec file.\n"
" -surf_A insurf: The input surface name.\n"
" or with:\n"
" -i insurf: With insurf being the full name of the surface.\n"
"\n"
" -input inData.dset dcol_index: The input dataset\n"
" and the index of the\n"
" datacolumn to use\n"
" (index 0 for 1st column).\n"
" Values of 0 indicate \n"
" inactive nodes.\n"
" -rmm rad: Maximum distance between an activated node\n"
" and the cluster to which it belongs.\n"
" Distance is measured on the surface's graph (mesh).\n"
" If you want the distance to be in number of edges,\n"
" set rad to -N for an N edge max distance.\n"
" For example -rmm -2 means that nodes connected\n"
" by 1 or two edges are in a cluster.\n"
"\n"
" Optional Parameters:\n"
" -thresh_col tcolind: Index of thresholding column.\n"
" Default is column 0.\n "
" -thresh tval: Apply thresholding prior to clustering.\n"
" A node n is considered if thresh_col[n] >= tval.\n"
" -athresh tval: Apply absolute thresholding prior to clustering.\n"
" A node n is considered if | thresh_col[n] | >= tval.\n"
" -ir_range R0 R1: Apply thresholding in range.\n"
" A node n is considered if \n"
" thresh_col[n] >= R0 && thresh_col[n] <= R1\n"
" -ex_range R0 R1: Apply thresholding outside of range.\n"
" A node n is considered if \n"
" thresh_col[n] < R0 || thresh_col[n] > R1\n"
" -amm2 minarea: Do not output results for clusters having\n"
" an area less than minarea. \n"
" If minarea < 0 AND -n is not set (or < 0)\n"
" then minnodes = -minarea . See option -n below.\n"
" -n minnodes: Do not output results for clusters having\n"
" less nodes than minnodes.\n"
" minnodes can get set with negative minarea above.\n"
" -prefix OUTPREF: Prefix for output.\n"
" Default is the prefix of \n"
" the input dataset.\n"
" If this option is used, the\n"
" cluster table is written to a file called\n"
" OUTPREF_ClstTable_rXX_aXX.1D. Otherwise the\n"
" table is written to stdout. \n"
" You can specify the output format by adding\n"
" extensions to OUTPREF. For example, \n"
" OUTPREF.1D.dset will force the output to be \n"
" in the .1D format. \n"
" See ConvertDset for many more format options.\n"
" -out_clusterdset: Output a clustered version of inData.1D \n"
" preserving only the values of nodes that \n"
" belong to clusters that passed the rmm and amm2\n"
" conditions above.\n"
" The clustered dset's prefix has\n"
" _Clustered_rXX_aXX affixed to the OUTPREF\n"
" -out_roidset: Output an ROI dataset with the value\n"
" at each node being the rank of its\n"
" cluster. The ROI dataset's prefix has\n"
" _ClstMsk_rXX_aXX affixed to the OUTPREF\n"
" where XX represent the values for the\n"
" the -rmm and -amm2 options respectively.\n"
" The program will not overwrite pre-existing\n"
" dsets.\n"
" -prepend_node_index: Force the output dataset to have node\n"
" indices in column 0 of output. Use this option\n"
" if you are parsing .1D format datasets.\n"
" -out_fulllist: Output a value for all nodes of insurf.\n"
" This option must be used in conjuction with\n"
" -out_roidset and/or out_clusterdset.\n"
" With this option, the output files might\n"
" be mostly 0, if you have small clusters.\n"
" However, you should use it if you are to \n"
" maintain the same row-to-node correspondence\n"
" across multiple datasets.\n"
" -sort_none: No sorting of ROI clusters.\n"
" -sort_n_nodes: Sorting based on number of nodes\n"
" in cluster.\n"
" -sort_area: Sorting based on area of clusters \n"
" (default).\n"
" -update perc: Pacify me when perc of the data have been\n"
" processed. perc is between 1%% and 50%%.\n"
" Default is no update.\n"
" -no_cent: Do not find the central nodes.\n"
" Finding the central node is a \n"
" relatively slow operation. Use\n"
" this option to skip it.\n"
" -cent: Do find the central nodes (default)\n"
"\n"
" The cluster table output:\n"
" A table where ach row shows results from one cluster.\n"
" Each row contains 13 columns: \n"
" Col. 0 Rank of cluster (sorting order).\n"
" Col. 1 Number of nodes in cluster.\n"
" Col. 2 Total area of cluster. Units are the \n"
" the surface coordinates' units^2.\n"
" Col. 3 Mean data value in cluster.\n"
" Col. 4 Mean of absolute data value in cluster.\n"
" Col. 5 Central node of cluster (see below).\n"
" Col. 6 Weighted central node (see below).\n"
" Col. 7 Minimum value in cluster.\n"
" Col. 8 Node where minimum value occurred.\n"
" Col. 9 Maximum value in cluster.\n"
" Col. 10 Node where maximum value occurred.\n"
" Col. 11 Variance of values in cluster.\n"
" Col. 12 Standard error of the mean ( sqrt(variance/number of nodes) ).\n"
" Col. 13 = Minimum |value|\n"
" Col. 14 = |Minimum| node\n"
" Col. 15 = Maximum |value|\n"
" Col. 16 = |Maximum| node\n"
" Col. 17 = Center of Mass x\n"
" Col. 18 = Center of Mass y\n"
" Col. 19 = Center of Mass z\n"
" Col. 20 = Centroid x\n"
" Col. 21 = Centroid y\n"
" Col. 22 = Centroid z\n"
" The CenterNode n is such that: \n"
" ( sum (Uia * dia * wi) ) - ( Uca * dca * sum (wi) ) is minimal\n"
" where i is a node in the cluster\n"
" a is an anchor node on the surface\n"
" sum is carried over all nodes i in a cluster\n"
" w. is the weight of a node \n"
" = 1.0 for central node \n"
" = value at node for the weighted central node\n"
" U.. is the unit vector between two nodes\n"
" d.. is the distance between two nodes on the graph\n"
" (an approximation of the geodesic distance)\n"
" If -no_cent is used, CenterNode columns are set to 0.\n"
"\n"
"%s"
"\n"
, s);
/* Can use -O2_NR, -O2 and -Oll to try different implementations
of the cluster building function. -O2 and -Oll are recursive and
work well for small clusters, a catastrophy for large clusters.
-O2_NR is fast and reliable. */
SUMA_free(s); s = NULL;
s = SUMA_New_Additions(0, 1); printf("%s\n", s);SUMA_free(s); s = NULL;
printf(" Ziad S. Saad SSCC/NIMH/NIH [email protected] \n");
exit (0);
}
void usage_SUMA_SurfQual (SUMA_GENERIC_ARGV_PARSE *ps, int detail)
{
static char FuncName[]= {"usage_SUMA_SurfQual"};
char * s = NULL, *sio=NULL;
s = SUMA_help_basics();
sio = SUMA_help_IO_Args(ps);
printf (
"\nUsage: A program to check the quality of surfaces.\n"
" SurfQual <-spec SpecFile> <-surf_A insurf> <-surf_B insurf> ...\n"
" <-sphere> [-self_intersect] [-prefix OUTPREF] \n"
"\n%s", detail ? "":"use -h or -help for more help detail.\n");
if (detail) {
printf (
" Mandatory parameters:\n"
" -spec SpecFile: Spec file containing input surfaces.\n"
" -surf_X: Name of input surface X where X is a character\n"
" from A to Z. If surfaces are specified using two\n"
" files, use the name of the node coordinate file.\n"
" Mesh winding consistency and 2-manifold checks are performed\n"
" on all surfaces.\n"
" Optional parameters:\n"
" -summary: Provide summary of results to stdout\n"
" -self_intersect: Check if surface is self intersecting.\n"
" This option is rather slow, so be patient.\n"
" In the presence of intersections, the output file\n"
" OUTPREF_IntersNodes.1D.dset will contain the indices\n"
" of nodes forming segments that intersect the surface.\n"
" Most other checks are specific to spherical surfaces (see option below).\n"
" -sphere: Indicates that surfaces read are spherical.\n"
" With this option you get the following output.\n"
" - Absolute deviation between the distance (d) of each\n"
" node from the surface's center and the estimated\n"
" radius(r). The distances, abs (d - r), are \n"
" and written to the file OUTPREF_Dist.1D.dset .\n"
" The first column represents node index and the \n"
" second is the absolute distance. A colorized \n"
" version of the distances is written to the file \n"
" OUTPREF_Dist.1D.col (node index followed \n"
" by r g b values). A list of the 10 largest absolute\n"
" distances is also output to the screen.\n"
" - Also computed is the cosine of the angle between \n"
" the normal at a node and the direction vector formed\n"
" formed by the center and that node. Since both vectors\n"
" are normalized, the cosine of the angle is the dot product.\n"
" On a sphere, the abs(dot product) should be 1 or pretty \n"
" close. Nodes where abs(dot product) < 0.9 are flagged as\n"
" bad and written out to the file OUTPREF_BadNodes.1D.dset .\n"
" The file OUTPREF_dotprod.1D.dset contains the dot product \n"
" values for all the nodes. The files with colorized results\n"
" are OUTPREF_BadNodes.1D.col and OUTPREF_dotprod.1D.col .\n"
" A list of the bad nodes is also output to the screen for\n"
" convenience. You can use the 'j' option in SUMA to have\n"
" the cross-hair go to a particular node. Use 'Alt+l' to\n"
" have the surface rotate and place the cross-hair at the\n"
" center of your screen.\n"
" NOTE: For detecting topological problems with spherical\n"
" surfaces, I find the dot product method to work best.\n"
" Optional parameters:\n"
" -prefix OUTPREF: Prefix of output files. If more than one surface\n"
" are entered, then the prefix will have _X added\n"
" to it, where X is a character from A to Z.\n"
" THIS PROGRAM WILL OVERWRITE EXISTING FILES.\n"
" Default prefix is the surface's label.\n"
"\n"
" Comments:\n"
" - The colorized (.col) files can be loaded into SUMA (with the 'c' \n"
" option. By focusing on the bright spots, you can find trouble spots\n"
" which would otherwise be very difficult to locate.\n"
" - You should also pay attention to the messages output when the \n"
" surfaces are being loaded, particularly to edges (segments that \n"
" join 2 nodes) are shared by more than 2 triangles. For a proper\n"
" closed surface, every segment should be shared by 2 triangles. \n"
" For cut surfaces, segments belonging to 1 triangle only form\n"
" the edge of that surface.\n"
" - There are no utilities within SUMA to correct these defects.\n"
" It is best to fix these problems with the surface creation\n"
" software you are using.\n"
" - Some warnings may be redundant. That should not hurt you.\n"
"%s"
"\n"
"%s"
"\n", (detail > 1) ? sio : "Use -help for I/O and miscellaneous options." ,
(detail > 1) ? s : "");
}
if (sio) SUMA_free(sio);
s = NULL;
if (s) SUMA_free(s);
s = NULL;
if (detail) {
s = SUMA_New_Additions(0, 1);
printf("%s\n", s);
SUMA_free(s);
s = NULL;
printf(" Ziad S. Saad SSCC/NIMH/NIH [email protected] \n");
}
return;
}
void usage_SUMA_getPatch (SUMA_GENERIC_ARGV_PARSE *ps, int detail)
{
static char FuncName[]={"usage_SUMA_getPatch"};
char * s = NULL, *sio=NULL;
s = SUMA_help_basics();
sio = SUMA_help_IO_Args(ps);
printf (
"\nUsage:\n"
" SurfPatch <-spec SpecFile> <-surf_A insurf> <-surf_B insurf> ...\n"
" <-input nodefile inode ilabel> <-prefix outpref> \n"
" [-hits min_hits] [-masklabel msk] [-vol] [-patch2surf]\n"
" [-vol_only] [-coord_gain] [-check_bowtie] [-fix_bowtie] \n"
" [-ok_bowtie] [-adjust_contour] [-do-not-adjust_contour] \n"
" [-stiched_surface SURF] \n"
"\n%s", detail ? "":"use -h or -help for more help detail.\n");
if (detail) {
printf (
"Usage 1:\n"
" The program creates a patch of surface formed by nodes \n"
" in nodefile.\n"
" The program can also be used to calculate the volume between the same patch\n"
" on two isotopic surfaces. See -vol option below.\n"
"\n"
" -spec SpecFile: Spec file containing input surfaces.\n"
" -surf_X: Name of input surface X where X is a character\n"
" from A to Z. If surfaces are specified using two\n"
" files, use the name of the node coordinate file.\n"
" -input nodefile inode ilabel: \n"
" nodefile is the file containing nodes defining the patch.\n"
" inode is the index of the column containing the nodes\n"
" ilabel is the index of the column containing labels of\n"
" the nodes in column inode. If you want to use\n"
" all the nodes in column indode, then set this \n"
" parameter to -1 (default). \n"
" If ilabel is not equal to 0 then the corresponding \n"
" node is used in creating the patch.\n"
" See -masklabel option for one more variant.\n"
" -prefix outpref: Prefix of output patch. If more than one surface\n"
" are entered, then the prefix will have _X added\n"
" to it, where X is a character from A to Z.\n"
" Output format depends on the input surface's.\n"
" With that setting, checking on pre-existing files\n"
" is only done before writing the new patch, which is\n"
" annoying. You can set the output type ahead of time\n"
" using -out_type option. This way checking for \n"
" pre-existing output files can be done at the outset.\n"
" -vol: Calculate the volume formed by the patch on surf_A and\n"
" and surf_B. For this option, you must specify two and\n"
" only two surfaces with surf_A and surf_B options.\n"
" -vol_only: Only calculate the volume, don't write out patches.\n"
" See also -fix_bowtie option below.\n"
"\n"
" ** If you are more interested in the volume attributed to one node, or a \n"
" set of nodes, between two isotopic surfaces, you are much better off \n"
" using SurfMeasures' -node_volg option. SurfMeasures has an efficient \n"
" implementation of the Gauss Theorem based volume estimation.\n"
"\n"
" -out_type TYPE: Type of all output patches, regardless of input \n"
" surface type.\n"
" Choose from: FreeSurfer, SureFit, 1D and Ply.\n"
" -hits min_hits: Minimum number of nodes specified for a triangle\n"
" to be made a part of the patch (1 <= min_hits <= 3)\n"
" default is 2.\n"
" -masklabel msk: If specified, then only nodes that are labeled with\n"
" with msk are considered for the patch.\n"
" This option is useful if you have an ROI dataset file\n"
" and whish to create a patch from one out of many ROIs\n"
" in that file. This option must be used with ilabel \n"
" specified (not = -1)\n"
" -patch2surf: Turn surface patch into a surface where only nodes used in\n"
" forming the mesh are preserved.\n"
" -check_bowtie: Check if the patch has a section hanging by one node to\n"
" the rest of the mesh. Think of a patch made of two \n"
" triangles that are connected at one node only. \n"
" Think Bowtie. Bowties should not occur if original \n"
" surface is 2 manifold and min_hits == 1\n"
" -check_bowtie is the default when -vol or -vol_only \n"
" are used. Volume computation will fail in the presence\n"
" of bowties.\n"
" -fix_bowtie: Modify patch to eliminate bowties. This only works if \n"
" min_hits is > 1. The repair is done by relaxing min_hits\n"
" at the node(s) where the bowtie happens.\n"
" -ok_bowtie: Do not check for, or fix bowties. \n"
" Default when -vol* are not used.\n"
" -adjust_contour: Once the patch is created, shrink its contours at nodes\n"
" that were not in nodefile (non-selected).\n"
" Each non-selected node is moved to the center of mass\n"
" of itself and neighboring selected nodes.\n"
" This adjustment might make sense when min_hits < 3\n"
" \n"
" -do-not-adjust_contour: Do not adjust contrours.\n"
" This is the default.\n"
" -stiched_surface STICHED: Write out the stiched surface used to\n"
" calculate the volume. \n"
" If -adjust_contour is used, this option also\n"
" writes out a file that shows which \n"
" nodes on the original surface were adjusted.\n"
" The first column in the node number. The 2nd\n"
" contains the number of selected nodes that \n"
" neighbored non-selected nodes in the patch.\n"
" -coord_gain GAIN: Multiply node coordinates by a GAIN.\n"
" That's useful if you have a tiny patch that needs\n"
" enlargement for easier viewing in SUMA.\n"
" Although you can zoon over very large ranges in SUMA\n"
" tiny tiny patches are hard to work with because\n"
" SUMA's parameters are optimized to work with objects\n"
" on the order of a brain, not on the order of 1 mm.\n"
" Gain is applied just before writing out patches.\n"
" -flip_orientation: Change orientation of triangles before writing\n"
" surfaces.\n"
" -verb VERB: Set verbosity level, 1 is the default.\n"
"\n"
" Example 1: Given an ROI, a white matter and a gray matter surface\n"
" calculate the volume of cortex enclosed by the roi on\n"
" both surfaces.\n"
" Assume you have the spec file and surfaces already. You can\n"
" get the same files from the SUMA directory in the AFNI \n"
" workshop SUMA's archive which you can get with: \n"
" curl -O http://afni.nimh.nih.gov/pub/dist/edu/data/SUMA_demo.tgz\n"
"\n"
" Draw an ROI on the surface and save it as: lh.manualroi.1D.roi\n"
"\n"
" To calculate the volume and create a enclosing surface:\n"
" SurfPatch -spec DemoSubj_lh.spec \\\n"
" -sv DemoSubj_SurfVol+orig \\\n"
" -surf_A lh.smoothwm \\\n"
" -surf_B lh.pial \\\n"
" -prefix lh.patch \\\n"
" -input lh.manualroi.1D.roi 0 -1 \\\n"
" -out_type fs \\\n"
" -vol \\\n"
" -adjust_contour \\\n"
" -stiched_surface lh.stiched \\\n"
" -flip_orientation \n"
"\n"
" Example 2: If you want to voxelize the region between the two surfaces\n"
" you can run the following on the output.\n"
" 3dSurfMask -i lh.stiched.ply \\\n"
" -prefix lh.closed -fill_method SLOW \\\n"
" -grid_parent DemoSubj_SurfVol+orig.HEAD \n"
" 3dSurfMask will output a dataset called lh.closed.d+orig which\n"
" contains the signed closest distance from each voxel to the \n"
" surface. Negative distances are outside the surface.\n"
"\n"
" To examine the results:\n"
" suma -npb 71 -i lh.stiched.ply -sv DemoSubj_SurfVol+orig. &\n"
" afni -npb 71 -niml -yesplugouts & \n"
" DriveSuma -npb 71 -com viewer_cont -key 't' \n"
" plugout_drive -npb 71 \\\n"
" -com 'SET_OVERLAY lh.closed.d' \\\n"
" -com 'SET_FUNC_RANGE A.3' \\\n"
" -com 'SET_PBAR_NUMBER A.10' \\\n"
" -com 'SET_DICOM_XYZ A. 10 70 22 '\\\n"
" -quit\n"
"\n"
"%s"
"\n"
"%s"
"\n", (detail > 1) ? sio : "Use -help for I/O and miscellaneous options." ,
(detail > 1) ? s : "");
}
if (sio) SUMA_free(sio); s = NULL;
if (s) SUMA_free(s); s = NULL;
if (detail) {
s = SUMA_New_Additions(0, 1); printf("%s\n", s);SUMA_free(s); s = NULL;
printf(" Ziad S. Saad SSCC/NIMH/NIH [email protected] \n");
}
return;
}
void usage_SUMA_ConvexHull (SUMA_GENERIC_ARGV_PARSE *ps)
{
static char FuncName[]={"usage_SUMA_ConvexHull"};
char * s = NULL, *sio=NULL;
int i;
s = SUMA_help_basics();
sio = SUMA_help_IO_Args(ps);
printf (
"\n"
"Usage: A program to find the convex hull, or perform a delaunay triangulation\n"
" of a set of points.\n"
" This program is a wrapper for the qhull, and qdelaunay programs.\n"
" see copyright notice by running suma -sources.\n"
"\n"
" ConvexHull \n"
" usage 1: < -input VOL >\n"
" < -isoval V | -isorange V0 V1 | -isocmask MASK_COM >\n"
" [<-xform XFORM>]\n"
" usage 2: < i_TYPE input surface >\n"
" [<-sv SURF_VOL>]\n"
" usage 3: < -input_1D XYZ >\n"
" [<-q_opt OPT>]\n"
" common optional:\n"
" [< -o_TYPE PREFIX>]\n"
" [< -debug DBG >]\n"
"\n"
" Mandatory parameters, choose one of three usage modes:\n"
" Usage 1:\n"
" You must use one of the following two options:\n"
" -input VOL: Input AFNI (or AFNI readable) volume.\n"
" You must use one of the following iso* options:\n"
" -isoval V: Create isosurface where volume = V\n"
" -isorange V0 V1: Create isosurface where V0 <= volume < V1\n"
" -isocmask MASK_COM: Create isosurface where MASK_COM != 0\n"
" For example: -isocmask '-a VOL+orig -expr (1-bool(a-V))' \n"
" is equivalent to using -isoval V. \n"
" NOTE: -isorange and -isocmask are only allowed with -xform mask\n"
" See -xform below for details.\n"
"\n"
" Usage 2:\n"
" -i_TYPE SURF: Use the nodes of a surface model\n"
" for input. See help for i_TYPE usage\n"
" below.\n"
"\n"
" Usage 3:\n"
" -input_1D XYZ: Construct the triangulation of the points\n"
" contained in 1D file XYZ. If the file has\n"
" more than 3 columns, use AFNI's [] selectors\n"
" to specify the XYZ columns.\n"
" -q_opt OPT: Meshing option OPT can be one of.\n"
" convex_hull: For convex hull of points (default)\n"
" triangulate_xy: Delaunay triangulation using x y coords\n"
"\n"
" These three options are only useful with -q_opt triangulate_xy\n"
" -proj_xy: Project points onto plane whose normal is the third principal \n"
" component. Then rotate projection so that plane in parallel to\n"
" Z = constant.\n"
" -orig_coord: Use original coordinates when writing surface, not\n"
" transformed ones.\n"
" -these_coords COORDS.1D: Use coordinates in COORDS.1D when \n"
" writing surface.\n"
"\n"
" Optional Parameters:\n"
" Usage 1 only:\n"
" -xform XFORM: Transform to apply to volume values\n"
" before searching for sign change\n"
" boundary. XFORM can be one of:\n"
" mask: values that meet the iso* conditions\n"
" are set to 1. All other values are set\n"
" to -1. This is the default XFORM.\n"
" shift: subtract V from the dataset and then \n"
" search for 0 isosurface. This has the\n"
" effect of constructing the V isosurface\n"
" if your dataset has a continuum of values.\n"
" This option can only be used with -isoval V.\n"
" none: apply no transforms. This assumes that\n"
" your volume has a continuum of values \n"
" from negative to positive and that you\n"
" are seeking to 0 isosurface.\n"
" This option can only be used with -isoval 0.\n"
" Usage 2 only:\n"
" -sv SURF_VOL: Specify a surface volume which contains\n"
" a transform to apply to the surface node\n"
" coordinates prior to constructing the \n"
" convex hull.\n"
" All Usage:\n"
" -o_TYPE PREFIX: prefix of output surface.\n"
" where TYPE specifies the format of the surface\n"
" and PREFIX is, well, the prefix.\n"
" TYPE is one of: fs, 1d (or vec), sf, ply.\n"
" Default is: -o_ply \n"
"\n"
"%s\n"
"\n"
/*" -debug DBG: debug levels of 0 (default), 1, 2, 3.\n"
" This is no Rick Reynolds debug, which is oft nicer\n"
" than the results, but it will do.\n"
"\n" */
"%s"
"\n", sio, s);
SUMA_free(s); s = NULL; SUMA_free(sio); sio = NULL;
s = SUMA_New_Additions(0, 1); printf("%s\n", s);SUMA_free(s); s = NULL;
printf(" Ziad S. Saad SSCC/NIMH/NIH [email protected] \n");
exit (0);
}
void SUMA_MakeColorMap_usage ()
{
static char FuncName[]={"SUMA_MakeColorMap_usage"};
char * s = NULL;
SUMA_ENTRY;
s = SUMA_help_basics();
fprintf (SUMA_STDOUT,
"\n"
"Usage1: \n"
"MakeColorMap <-fn Fiducials_Ncol> [-pos] [-ah prefix] [-h/-help]\n"
" Creates a colormap of N colors that contains the fiducial colors.\n"
" -fn Fiducials_Ncol: Fiducial colors and their indices in the color\n"
" map are listed in file Fiducials_Ncol.\n"
" Each row contains 4 tab delimited values:\n"
" R G B i\n"
" R G B values are between 0 and 1 and represent the \n"
" i-th color in the colormap. i should be between 0 and\n"
" N-1, N being the total number of colors in the colormap.\n"
"\n"
"Usage2: \n"
"MakeColorMap <-f Fiducials> <-nc N> [-sl] [-ah prefix] [-h/-help]\n"
" Creates a colormap of N colors that contains the fiducial colors.\n"
" -f Fiducials: Fiducial colors are listed in an ascii file Fiducials. \n"
" Each row contains 3 tab delimited R G B values between 0 and 1.\n"
" -nc N: Total number of colors in the color map.\n"
" -sl: (optional, default is NO) if used, the last color in the Fiducial \n"
" list is omitted. This is useful in creating cyclical color maps.\n"
"\n"
"Usage3: \n"
"MakeColorMap <-std MapName>\n"
" Returns one of SUMA's standard colormaps. Choose from:\n"
" rgybr20, ngray20, gray20, bw20, bgyr19, \n"
" matlab_default_byr64, roi128, roi256, roi64\n"
" or if the colormap is in a .pal file: \n"
"MakeColorMap -cmapdb Palfile -cmap MapName\n"
"\n"
"Usage4:\n"
"MakeColorMap <-fscolut lbl0 lbl1> \n"
" [<-fscolutfile FS_COL_LUT>]\n"
" Create AFNI/SUMA colormaps of FreeSurfer colors\n"
" indexed between lbl0 and lbl1. \n"
" -fscolut lbl0 lbl1: Get colors indexed between\n"
" lbl0 and lbl1, non existing\n"
" integer labels are given a \n"
" gray color. Use -fscolut -1 -1 to\n"
" get all the colors and labels.\n"
" -fscolutfile FS_COL_LUT: Use color LUT file FS_COL_LUT\n"
" Default is to use \n"
" $FREESURFER_HOME/FreeSurferColorLUT.txt\n"
" -show_fscolut: Show all of the LUT\n"
"\n"
"Common options to all usages:\n"
" -ah prefix: (optional, Afni Hex format.\n"
" default is RGB values in decimal form)\n"
" use this option if you want a color map formatted to fit \n"
" in AFNI's .afnirc file. The colormap is written out as \n"
" prefix_01 = #xxxxxxx \n prefix_02 = #xxxxxxx\n etc...\n"
" -ahc prefix: optional, Afni Hex format, ready to go into.\n"
" pbardefs.h \n"
" -h or -help: displays this help message.\n"
" -flipud: Flip the map upside down. If the colormap is being \n"
" created for interactive loading into SUMA with the 'New'\n"
" button from the 'Surface Controller' you will need\n"
" to flip it upside down. \n"
" -usercolutfile USER_COL_LUT: A user's own color lookup file.\n"
" The format of the file is similar to FreeSurfer's ColorLUT.txt\n"
" It is an ascii file whith each line containing the following:\n"
" Key R G B A Label\n"
" With Key being an integer color/region identifier,\n"
" Label is the string identifier and R,G,B,A are the colors \n"
" and alpha values either between 0 and 1, or 0 and 255.\n"
" Alpha values are ignored at the moment, but they must be \n"
" in the file.\n"
" -suma_cmap: write colormap in SUMA's format\n"
" -sdset DSET: Add colormap to surface-based dataset DSET, making it a\n"
" Labeled data set, which gets special treatment in SUMA.\n"
" A labeled data set can only have one value per node.\n"
" -sdset_prefix DSET_PREF: Prefix of dset for writing labeled version\n"
" of DSET. Without it, the new name is based on\n"
" DSET's name\n"
"\n"
"Example Usage 1: Creating a colormap of 20 colors that goes from \n"
"Red to Green to Blue to Yellow to Red.\n"
"\n"
" The file FidCol_Nind contains the following:\n"
" 1 0 0 0\n 0 1 0 5\n 0 0 1 10\n 1 1 0 15\n 1 0 0 19\n"
"\n"
" The following command will generate the RGB colormap in decimal form:\n"
" MakeColorMap -fn FidCol_Nind \n"
"\n"
" The following command will generate the colormap and write it as \n"
" an AFNI color palette file:\n"
" MakeColorMap -fn FidCol_Nind -ah TestPalette > TestPalette.pal\n"
"\n"
"Example Usage 2: Creating a cyclical version of the colormap in usage 1:\n"
"\n"
" The file FidCol contains the following:\n"
" 1 0 0\n 0 1 0\n 0 0 1\n 1 1 0\n 1 0 0\n"
"\n"
" The following command will generate the RGB colormap in decimal form:\n"
" MakeColorMap -f FidCol -sl -nc 20 \n"
"\n"
"Example Usage 3: \n"
" MakeColorMap -std ngray20 \n"
"\n"
"Example Usage 4: \n"
" MakeColorMap -fscolut 0 255\n"
"\n"
"Example Usage 5: Make your own colormap and add it to a surface-based dset\n"
" Say you have your own color lookup table formatted much like FreeSurfer's\n"
" color lookup files. The content of this sample colut.txt file is:\n"
" #integer label String Label R G B A\n"
" 1 Big_House 0.3 0.1 1 1\n"
" 2 Small_Face 1 0.2 0.4 1\n"
" 3 Electric 1 1 0 1\n"
" 4 Atomic 0.1 1 0.3 1\n"
"\n"
" The command to create a SUMA formatted colormap would be:\n"
" MakeColorMap -usercolutfile colut.txt -suma_cmap toylut \n"
"\n"
" You can attach the colormap to a surface-based datatset with \n"
" ConvertDset's -labelize option, or you can also do it here in one\n"
" pass with:\n"
" MakeColorMap -usercolutfile colut.txt -suma_cmap toylut \\\n"
" -sdset you_look_marvellous.niml.dset\n"
"\n"
"Adding a new colormap into AFNI:"
"To read in a new colormap into AFNI, either paste the contents of \n"
"TestPalette.pal in your .afnirc file or read the .pal file using \n"
"AFNI as follows:\n"
"1- run afni\n2- Define Function --> right click on Inten (over colorbar) \n"
" --> Read in palette (choose TestPalette.pal)\n"
"3- set the #colors chooser (below colorbar) to 20 (the number of colors in \n"
" TestPalette.pal).\n"
"%s",s);
SUMA_free(s); s = NULL;
s = SUMA_New_Additions(0, 1); printf("%s\n", s);SUMA_free(s); s = NULL;
fprintf (SUMA_STDOUT, " Ziad S. Saad & Rick R. Reynolds SSCC/NIMH/NIH [email protected] Tue Apr 23 14:14:48 EDT 2002\n\n");
SUMA_RETURNe;
}
void usage_SUMA_ConvertSurface (SUMA_GENERIC_ARGV_PARSE *ps, int detail)
{/*Usage*/
static char FuncName[]={"usage_SUMA_ConvertSurface"};
char * s = NULL, *sio=NULL;
s = SUMA_help_basics();
sio = SUMA_help_IO_Args(ps);
printf (
"\n"
"Usage: ConvertSurface <-i_TYPE inSurf> <-o_TYPE outSurf> \n"
" [<-sv SurfaceVolume [VolParam for sf surfaces]>] \n"
" [-tlrc] [-MNI_rai/-MNI_lpi][-xmat_1D XMAT]\n"
" reads in a surface and writes it out in another format.\n"
" Note: This is a not a general utility conversion program. \n"
" Only fields pertinent to SUMA are preserved.\n"
"\n%s", detail ? "":"use -h or -help for more help detail.\n");
if (detail) {
printf (
"%s"
"\n"
" Alternate GIFTI output qualifiers:\n"
" You can alternately set gifti data arrays encoding with:\n"
" -xml_ascii: For ASCII (human readable)\n"
" -xml_b64: For Base64 (more compact)\n"
" -xml_b64gz: For Base64 GZIPPED (most compact, needs gzip libraries)\n"
" If AFNI_NIML_TEXT_DATA environment variable is set to YES, the\n"
" the default is -xml_ascii, otherwise it is -xml_b64\n"
"\n"
" -orient_out STR: Output coordinates in STR coordinate system. \n"
" STR is a three character string following AFNI's \n"
" naming convention. The program assumes that the \n"
" native orientation of the surface is RAI, unless you \n"
" use the -MNI_lpi option. The coordinate transformation\n"
" is carried out last, just before writing the surface \n"
" to disk.\n"
" -native: Write the output surface in the coordinate system native to its\n"
" format.\n"
" Option makes sense for BrainVoyager, Caret/SureFit and \n"
" FreeSurfer surfaces.\n"
" But the implementation for Caret/Surefit is not finished yet \n"
" (ask if needed).\n"
" -make_consistent: Check the consistency of the surface's mesh (triangle\n"
" winding). This option will write out a new surface \n"
" even if the mesh was consistent.\n"
" See SurfQual -help for mesh checks.\n"
" -flip_orient: Flip the winding of the triangles\n"
" -radial_to_sphere rad: Push each node along the center-->node direction\n"
" until |center-->node| = rad.\n"
" -acpc: Apply acpc transform (which must be in acpc version of \n"
" SurfaceVolume) to the surface vertex coordinates. \n"
" This option must be used with the -sv option.\n"
" -tlrc: Apply Talairach transform (which must be a talairach version of \n"
" SurfaceVolume) to the surface vertex coordinates. \n"
" This option must be used with the -sv option.\n"
" -MNI_rai/-MNI_lpi: Apply Andreas Meyer Lindenberg's transform to turn \n"
" AFNI tlrc coordinates (RAI) into MNI coord space \n"
" in RAI (with -MNI_rai) or LPI (with -MNI_lpi)).\n"
" NOTE: -MNI_lpi option has not been tested yet (I have no data\n"
" to test it on. Verify alignment with AFNI and please report\n"
" any bugs.\n"
" This option can be used without the -tlrc option.\n"
" But that assumes that surface nodes are already in\n"
" AFNI RAI tlrc coordinates .\n"
" NOTE: The vertex coordinates coordinates of the input surfaces are only\n"
" transformed if -sv option is used. If you do transform surfaces, \n"
" take care not to load them into SUMA with another -sv option.\n"
"\n"
" -patch2surf: Change a patch, defined here as a surface with a mesh that\n"
" uses only a subset of the full nodelist, to a surface\n"
" where all the nodes in nodelist are used in the mesh.\n"
" Note that node indices will no longer correspond between\n"
" the input patch and the output surface.\n"
" -merge_surfs: Merge multitudes of surfaces on the command line into one\n"
" big surface before doing anything else to the surface.\n"
" This is for the moment the only option for which you \n"
" should specify more than one input surface on the command\n"
" line. For example:\n"
" ConvertSurface -i lh.smoothwm.gii -i rh.smoothwm.gii \\\n"
" -merge_surfs -o_gii lrh.smoothwm.gii\n"
"\n"
#if 1
" Options for coordinate projections:\n"
" -node_depth DEPTHPREF: Project all coordinates onto the principal \n"
" direction and output of depth/height of each\n"
" node relative to the outlying projection point.\n"
" This option is processed right before -pc_proj, \n"
" should that option also be requested.\n"
" This option outputs file DEPTHPREF.pcdepth.1D.dset\n"
" which contains node index, followed by depth, then \n"
" height of node. See also same option in SurfPatch\n"
"\n"
" -pc_proj ONTO PREFIX: Project coordinates onto ONTO, where ONTO is one \n"
" of the parameters listed below.\n"
" ONTO values for plane projections along various normals:\n"
" PC0_plane = normal is 1st principal vector\n"
" PC1_plane = normal is 2nd principal vector\n"
" PC2_plane = normal is 3rd principal vector\n"
" PCZ_plane = normal is component closest to Z axis\n"
" PCY_plane = normal is component closest to Y axis\n"
" PCX_plane = normal is component closest to X axis\n"
" ONTO values for line projections:\n"
" PC0_dir = project along 1st principal vector\n"
" PC1_dir = project along 2nd principal vector\n"
" PC2_dir = project along 3rd principal vector\n"
" PCZ_dir = project along component closest to Z axis\n"
" PCY_dir = project along component closest to Y axis\n"
" PCX_dir = project along component closest to X axis\n"
" PREFIX is used to form the name of the output file containing \n"
" the projected coordinates. File PREFIX.xyzp.1D.coord\n"
" contains the projected coordinates.\n"
" Note: This is the last operation to be performed by this program, \n"
" and no surfaces are written out in the end.\n"
"\n"
#endif
" Options for applying arbitrary affine transform:\n"
" [xyz_new] = [Mr] * [xyz_old - cen] + D + cen\n"
" -xmat_1D mat: Apply transformation specified in 1D file mat.1D.\n"
" to the surface's coordinates.\n"
" [mat] = [Mr][D] is of the form:\n"
" r11 r12 r13 D1\n"
" r21 r22 r23 D2\n"
" r31 r32 r33 D3\n"
" or\n"
" r11 r12 r13 D1 r21 r22 r23 D2 r31 r32 r33 D3\n"
" -ixmat_1D mat: Same as xmat_1D except that mat is replaced by inv(mat)\n"
" NOTE: For both -xmat_1D and -ixmat_1D, you can replace mat with \n"
" one of the special strings:\n"
" 'RandShift', 'RandRigid', or 'RandAffine' which would create\n"
" a transform on the fly. \n"
" You can also use 'NegXY' to flip the sign of X and Y \n"
" coordinates.\n"
" -seed SEED: Use SEED to seed the random number generator for random\n"
" matrix generation\n"
" -XYZscale sX sY sZ: Scale the coordinates by sX sY sZ.\n"
" This option essentially turns sX sY sZ.\n"
" into a -xmat_1D option. So you cannot mix\n"
" and match.\n"
" -xcenter x y z: Use vector cen = [x y z]' for rotation center.\n"
" Default is cen = [0 0 0]'\n"
" -polar_decomp: Apply polar decomposition to mat and preserve\n"
" orthogonal component and shift only. \n"
" For more information, see cat_matvec's -P option.\n"
" This option can only be used in conjunction with\n"
" -xmat_1D\n"
"\n"
"%s"
"\n", (detail > 1) ? sio : "Use -help for I/O and miscellaneous options." ,
(detail > 1) ? s : "");
}/*Usage*/
if (sio) SUMA_free(sio); s = NULL;
if (s) SUMA_free(s); s = NULL;
if (detail) {
s = SUMA_New_Additions(0, 1); printf("%s\n", s);SUMA_free(s); s = NULL;
printf ("\t\t Ziad S. Saad SSCC/NIMH/NIH [email protected] \n");
}
return;
}
