Proposed-NAMIC-XML-CLI-Syntax-v0-2

A FRAMEWORK FOR INTEROPERABILITY OF NEURO-IMAGING SOFTWARE Revision: 0.2 Last Revised June 23, 2009 CONTRIBUTORS/COLLABORATORS • • Bennett Landman, Vanderbilt University (and Johns Hopkins University) Join this list… just e-mail me: landman@jhu.edu OPEN QUESTIONS • • How we define a syntax for output data w/ non-file based data Extension manager w/ command line arguments? REVISION HISTORY Draft 0.2: 2009.06.23 Draft 0.1: 2009.06.22 Extended definition to include parameter groups (bl) Initial revision based on 3D Slicer CLI definition (bl) CONTENTS Working Draft Page of 21 MOTIVATION Query a command line executable program with “—xml” or “—xml –language=” where language causes the documentation to be generated in one of the supported language Any number of programs may be included in the response Additional tags are allowed for all elements as long as it is “failsafe” for the calling process to ignore these tags or that these tags depend on a value of an existing tag which would cause the current “consortium” protocol definition to fail For example, tags for TCPIP base interaction may be required for a function program, but the program may not support any interfaces that have not been incorporated into the latest “consortium release” Notes on syntax: REQ= required OPT= optional ! = (if present) requires exactly + = (if present) requires at least * = (if present) may provide any number If more than one instance of a ! parameter is included, then the calling process is free to use any instance of the parameter that it chooses SYNTAX DEFINITIONS Working Draft Page of 21 A PROGRAM CAPTURES THE INFORMATION NEEDED TO DESCRIBE AND INTERACT WITH A DATA PROCESSING RESOURCE PARENT: none REQ+: Begin a new program description REQ!: Program name REQ!: Human readable short description of this program REQ+: Type of interface OPT*: Starts a group of parameters OPT*: Indicate supported language OPT!: Provide meta-information about this program Example … … … Working Draft Page of 21 A NAME PROVIDES A SHORT, DESCRIPTIVE NAME FOR THE DATA PROCESSING RESOURCE THIS STRING NEED NOT BE UNIQUE PARENT: Program Value: Text string Example Linear Tensor Estimation Working Draft Page of 21 AN INTERFACE PROVIDES A MECHANISM TO DESCRIBE HOW THE CONTROL PROGRAM MIGHT INTERACT WITH THE RESOURCE THE ATTRIBUTES FOR AN INTERFACE DEPEND ON THE TYPE (OR CLASS) OF INTERFACE PARENT: program REQ!: Base string to pass to the operating system to invoke the program OPT*: Arguments to be provided to the executable in Order OPT!: Syntax for parsing any additional arguments on the command line If not specified, defaults to GNU Example java Working Draft Page of 21 A LANGUAGE INDICATES THAT THE XML FILE CAN BE GENERATED IN AN ALTERNATIVE LANGUAGE TO THE DEFAULT ONE PARENT: program Value is a text field indicating two letter language code Example Working Draft Page of 21 A SYNTAX DEFINITION IN A “COMMAND LINE” INTERFACE INDICATES THE METHOD OF UNMARSHALLING TEXT ARGUMENTS FROM THE COMMAND LINE PARENT: interface Current options are gnu, apache, java, properties file Example Working Draft Page of 21 A PARAMETERS DEFINITION PROVIDES A LOGICAL GROUPING OF PARAMETERS PARENT: program REQ!: Unique name of this group OPT!: Suggest a label for this grouping OPT!: Suggest a separate ‘tab’ for this parameter group (integer index, 0=base tab) May be ignored OPT!: Short pure-text (not HTML) description of the parameter group OPT!: Longer, potentially HTML enabled description of the parameter group Links and page-layout may or may not be ignored during presentation OPT*: Definition of a parameter … Example Working Draft Page of 21 Working Draft Page of 21 A PARAMETER DEFINITION INDICATES A PIECE OF INFORMATION THAT IS SENT/TO/FROM THE PROGRAM OPTIONAL ARGUMENTS ARE DETERMINED BY TYPE PARENT: parameters REQ!: Unique name of this parameter w/n program OPT!: Command line flag to use if ID is not the flag May be empty to indicate that no flag should precede argument OPT!: Suggest a label for this grouping REQ!: input/output/other REQ!: Type of information embodied REQ!: (interpreted differently by class) OPT!: Default (false) Indicate whether the calling process must understand and/or provide a value for this parameter in order to call the Program OPT+: Suggested default value This may or may not de the default value which the program uses internally OPT!: Numeric order in a partially order list by which the calling process should present this parameter to the program Parameters with the same order may be presented in arbitrary order OPT!: Short pure-text (not HTML) description of the parameter, units, etc OPT!: Longer, potentially HTML enabled description of the program Links and page-layout may or may not be ignored during presentation OPT! Boolean indication as to whether the user should see this option … Example float 10 19.7 Working Draft Page 10 of 21 AN INFORMATION COLLETION PROVIDES META-INFORMATION ABOUT THIS PROGRAM PARENT: program OPT!: current version of the program OPT!: lowest version of this program for which the in/out are compatible OPT!: Short description of license (e.g., BSD, LGPL 2.1+, etc.) … IF INTERFACE= command line OPT!: Release status (string) OPT!: Date associated with program OPT+: Website/URL OPT!: Website/URL OPT!:Website/URL for license information OPT!: General package of the software OPT+: “dot” separated category hierarchy OPT+: Keyword to classify the program OPT!: Short pure-text (not HTML) description of the parameter, units, etc OPT!: Longer, potentially HTML enabled description of the program Links and page-layout may or may not be ignored during presentation OPT*: Author of program OPT!: Text acknowledgements REQ!: tag to preface data object Example TO BE DONE Working Draft Page 11 of 21 AN AUTHOR INDICATES A CONTRIBUTOR TO A PROGRAM PARENT: information REQ!: name OPT!: Contact information OPT!: URL for the contact Example bennett.landman@vanderbilt.edu http://iacl.ece.jhu.edu/~bennett Working Draft Page 12 of 21 PROPOSED PARAMETER TYPES String a Tag b Option Number a Boolean b Integer c Float d Double Vector a RGBColor Resource a Generic (File) b Directory c Image d Surface e Matrix Collection STRING No modifiers STRING.TAG No modifiers STRING.OPTION OPT!: (default false) Boolean indicator REQ+: string option NUMBER minimum maximum BOOLEAN No modifiers Working Draft Page 13 of 21 INTEGER No modifiers FLOAT No modifiers DOUBLE No modifiers VECTOR REQ!: NUMBER or NUMBER.* OPT!: (default=0=any) OPT!: (default = space) RESOURCE OPT!: URI,URL,FILE GENERIC OPT!: Indicate preferred file type and/or extension OPT+: Default to any DIRECTORY OPT!: Regular expression to select filenames within directory IMAGE SURFACE MATRIX Working Draft OPT!: Required number of dimensions (integer 1+) OPT!: List of required size for each dimension OPT!: ASCII, … Page 14 of 21 COLLECTION Working Draft OPT+: Supported types in the collection OPT!: (default = space) Page 15 of 21 SAMPLE PROGRAM DEFINTIONS FSL FLIRT Current command line “help” response: FLIRT version 5.5 Usage: flirt [options] -in -ref -out flirt [options] -in -ref -omat flirt [options] -in -ref -applyxfm -init -out Available options are: -in (no default) -ref (no default) -init (input 4x4 affine matrix) -omat (output in 4x4 ascii format) -out, -o (default is none) -datatype {char,short,int,float,double} (force output data type) -cost {mutualinfo,corratio,normcorr,normmi,leastsq,labeldiff} (default is corratio) -searchcost {mutualinfo,corratio,normcorr,normmi,leastsq,labeldiff} (default is corratio) -usesqform (initialise using appropriate sform or qform) -displayinit (display initial matrix) -anglerep {quaternion,euler} (default is euler) -interp {trilinear,nearestneighbour,sinc} (final interpolation: def - trilinear) -sincwidth (default is 7) -sincwindow {rectangular,hanning,blackman} -bins (default is 256) -dof (default is 12) -noresample (do not change input sampling) -forcescaling (force rescaling even for low-res images) -minsampling (set minimum voxel dimension for sampling (in mm)) -applyxfm (applies transform (no optimisation) - requires -init) -applyisoxfm (as applyxfm but forces isotropic resampling) -paddingsize (for applyxfm: interpolates outside image by size) -searchrx (angles in degrees: default is -90 90) -searchry (angles in degrees: default is -90 90) -searchrz (angles in degrees: default is -90 90) -nosearch (sets all angular search ranges to 0) -coarsesearch (angle in degrees: default is 60) -finesearch (angle in degrees: default is 18) -schedule (replaces default schedule) -refweight (use weights for reference volume) -inweight (use weights for input volume) -noclamp (do not use intensity clamping) -noresampblur (do not use blurring on downsampling) -2D (use 2D rigid body mode - ignores dof) -verbose (0 is least and default) -v (same as -verbose 1) -i (pauses at each stage: default is off) -version (prints version number) -help Proposed command line “ xml” response: FSL FLIRT Working Draft Page 16 of 21 in in resource.image true Input volume (no default) nii img ref input resource.image true Refvol (no default) nii img init input resource.matrx (input 4x4 affine matrix) 2 4 4 ASCII omat input resource.matrx (output in 4x4 ascii format) 2 4 4 ASCII out output resource.image Output volume– default is none nii img datatype input option (force output data type) nii img cost input option (default is corratio) nii img Working Draft Page 17 of 21 searchcost input option (default is corratio) usesqform input flag false (initialise using appropriate sform or qform) displayinit input flag false (display initial matrix) anglerep input option (default is euler) interp input option (final interpolation: def - trilinear) sincwidth input float sincwindow input option Working Draft Page 18 of 21 bins input integer number of histogram bins dof input integer number of transform dofs noresample input flag false (do not change input sampling) forcescaling input flag false (force rescaling even for low-res images) minsampling input float (set minimum voxel dimension for sampling (in mm)) applyxfm input flag false (applies transform (no optimisation) - requires -init) applyisoxfm input float (as applyxfm but forces isotropic resampling) paddingsize input integer (for applyxfm: interpolates outside image by size) searchrx input Vector 2 float min_angle - max_angle (angles in degrees: default is -90 Working Draft Page 19 of 21 90) searchry input Vector 2 float min_angle - max_angle (angles in degrees: default is -90 90) searchrz input Vector 2 float min_angle - max_angle (angles in degrees: default is -90 90) nosearch input flag false (sets all angular search ranges to 0) coarsesearch input float (angle in degrees: default is 60) finesearch input float (angle in degrees: default is 18) schedule input resource.generic (replaces default schedule) refweight input resource.image (use weights for reference volume) nii img inweight input resource.image (use weights for input volume) nii Working Draft Page 20 of 21 img noclamp input flag false (do not use intensity clamping) noresampblur input flag false (do not use blurring on downsampling) 2D input flag false (use 2D rigid body mode - ignores dof) verbose input integer 0 (0 is least and default) Working Draft Page 21 of 21