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_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_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;
}
