IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Changeset 4733


Ignore:
Timestamp:
Aug 9, 2005, 7:56:30 AM (21 years ago)
Author:
eugene
Message:

opihi userguide updates

Location:
trunk/Ohana/doc/www/html
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/Ohana/doc/www/html/DVO/userguide.htm

    r4726 r4733  
    22<meta name=title content=DVO Examples>
    33<meta name=page  content=DVO Examples>
    4 
    5 <h3> User Interface </h3>
    6 
    7 The interface has an interaction similar to <tt>tcsh</tt>.  The arrows
    8 allow editing of previous commands.  You can also use emacs-like
    9 commands such as cntl-a to reach the beginning of the line and cntl-e
    10 to reach the end.  There is command and file completion: if you type
    11 part of a command (as the first thing on a line) and then type tab, it
    12 will fill in as much as possible, until the word is not unique.
    13 Typing tab twice at that point will list the possible endings.  For
    14 any but the first word on a line, the same thing will happen for the
    15 files in the current directory.  It is also possible to type just a
    16 fraction of a command, as long as it is unique.  An ambiguous command
    17 will list the possible alternatives.  For example:
    18 
    19 <pre>
    20 dvo: c
    21 ambiguous command: c ( catalog cgrid clear create cursor )
    22 </pre>
    23 
    24 The shell is an interpretive programming language.
    25 Variables are set as follows:
    26 
    27 <pre>
    28 dvo: $fred = 10
    29 </pre>
    30 
    31 Any expression within curly brackets {} is assumed
    32 to be an arithmetical expression and is evaluated before the line is
    33 executed.  For example:
    34 
    35 <pre>
    36 echo {$fred*dcos(45)}
    37 </pre>
    38 
    39 would give the response 7.07107.  There are math functions cos, sin,
    40 and tan, which operate on radian expressions, and also dcos, dsin,
    41 dtan, which operate on degree expressions.  There are also the
    42 equivalent inverse functions: eg., asin and dasin return radians and
    43 degrees, respectively.  The help section on Math defines all of the
    44 available math functions. 
    45 
    46 <h3> Miscellaneous Commands </h3>
    47 
    48 <pre>
    49 !                         -- system call
    50 ?                         -- list commands
    51 ??                        -- list variables
    52 echo                      -- type this line
    53 exec                      -- system call
    54 exit                      -- exit program
    55 help                      -- get help on a function
    56 output                    -- redirect output to file
    57 quit                      -- exit program
    58 scan                      -- scan line from keyboard or file to variable
    59 wait                      -- wait until return is typed
    60 which                     -- show command
    61 </pre>
    62 
    63 Most of these are self-explanatory.  The command ?? prints the system
    64 variables.  The <tt>help</tt> command will provide help on a single
    65 command or, without any arguments, will list all available help
    66 files (this includes general help not associated with a specific
    67 command). 
    68 
    69 <h3> Shell Programing </h3>
    70 
    71 <pre>
    72 break                     -- escape from function
    73 for                       -- loops
    74 if                        -- logical cases
    75 input                     -- read command lines from a file
    76 macro                     -- deal with the macros
    77 </pre>
    78 
    79 <p>
    80 There are several options for programming in <tt>status</tt>.  First,
    81 a file which contains a series of commands can be executed with
    82 <tt>input (filename)</tt>.  It is also possible to define macros which
    83 will behave much like regular commands.  A macro is defined by typing
    84 <tt>macro name</tt> or <tt>macro create name</tt> followed by the
    85 commands.  Arguments to the macro are assigned to the variables $1
    86 .. $N and the number of arguments is given by $0.  Macros may be
    87 defined in <tt>input</tt> files, and in fact when <tt>status</tt> is
    88 started, it loads the file <tt>~/.statusrc</tt> which may contain
    89 default macros.  Simple loops and if statements can be performed, and
    90 are quite useful for complex macros.
    91 
    92 <p>
    93 'If' statements are similar in syntax to C if statements.  Math
    94 expresions in the if statement must be contained in curly braces, as
    95 elsewhere.  Variables with string values may use the logical ==
    96 operator to test if two strings are the same.  'For' loops are quite
    97 simplistic.  The form is:
    98 
    99 <pre>
    100 for var first last delta
    101  (commands)
    102 end
    103 </pre>
    104 
    105 <p>
    106 The value of <tt>$var</tt> will start at the value <tt>first</tt> and increment by
    107 <tt>delta</tt> after each loop.  The loop will stop after <tt>$var</tt> is greater
    108 than <tt>stop</tt>.  The value <tt>delta</tt> is optional, with 1 assumed.
    109 The value of <tt>$var</tt> may be changed during the loop, and if set
    110 beyong the value of <tt>last</tt> will end the loop early. 
    111 
    112 <h3> Vector Plotting </h3>
    113 
    114 <pre>
    115 box                       -- draw a box on the plot
    116 clear                     -- erase plot
    117 create                    -- create a new vector
    118 cursor                    -- get coords from cursor
    119 grid                      -- plot cartesian grid
    120 hist                      -- create histogram from a vector
    121 labels                    -- define labels for plot
    122 limits                    -- define plot limits
    123 plot                      -- plot a pair of vectors
    124 print                     -- write vectors to file
    125 ps                        -- define labels for plot
    126 set                       -- vector math
    127 style                     -- set the style for graph plots
    128 vectors                   -- list vectors
    129 zplot                     -- plot scaled points
    130 </pre>
    131 
    132 <p>
    133 In addition to scalar variables, <tt>status</tt> can manipulate and
    134 display 1-D vector variables.  Many of the commands which extract data
    135 from the photometry database place the data in vectors as well as
    136 plotting them.  A vector can also be created based on a number
    137 sequence with the command <tt>create name Nelements start delta</tt>.
    138 The resulting vector has $Nelements$ entries, starting at a value of
    139 $start$ and running until $start + delta*Nelements$.  If $delta$ is
    140 0.0, all elements will have the value of $start$.  A histogram of a vector
    141 may be made with the command <tt>hist</tt>, which creates a new vector
    142 containing the histogram of the first vector.  The data range and bin
    143 size of the histogram are defined in same way as with create.  This
    144 makes it easy to create the index vector that goes with a histogram
    145 vector: 
    146 
    147 <pre>
    148 hist y Ny 1 100 0.1
    149 create dx 1 100 0.1
    150 </pre>
    151 
    152 <p>
    153 The above will create a histogram of y in Ny and the index in dx.
    154 Plotting this with <tt>plot dx Ny</tt> will show the histogram.
    155 
    156 <p>
    157 Vector math is performed with a command of the form <tt>set new =
    158   (expression)</tt>.  The expression is some math function employing
    159   vectors and scalars.  A complete listing of the math operators
    160   available in <tt>set</tt> can be found in the help for <tt>set</tt>.
    161 
    162 <p>
    163 Once vectors are defined, they may be plotted.  A pair of vectors can
    164 be plotted against each other if they have the same number of entries.
    165 The plotting is performed on the graphics window, Kapa.  There are
    166 actually several graphics windows available to <tt>status</tt>, any of
    167 which may be used to plot at any time.  Some of the more complex
    168 operations default to either graphics window 0 or 1, depending on the
    169 context.  Except for those functions with a pre-defined window, all
    170 plotting functions apply to the current graphics window unless an
    171 option <tt>-n N</tt> is given to specify a different window.  The
    172 plotting style is determined by the command <tt>style</tt> which can set
    173 the line width, the line type (solid, dashed, dotted, etc), the point
    174 type (box, cross, etc), the point size, the color, and whether a pair
    175 of vectors is plotted as a sequence of points, a set of connected
    176 lines, or a histogram.  Some functions which make plots use their own
    177 styles, as discussed below.  The function <tt>limits</tt> lets the user
    178 set the range of the plot axes, or check the current setting.  The
    179 command <tt>plot</tt> will plot a pair of vectors on the current graphics
    180 window using the current plotting style for that window.  The command
    181 <tt>zplot</tt> will plot a pair of vectors with the point size scaled by
    182 a third vector, with maximum and minimum point sizes representing
    183 specified values.  The <tt>cursor</tt> command goes the other way: this
    184 command puts the Kapa window in cursor mode and waits for input from
    185 Kapa.  The user can then type any alphanumeric key on the graphics
    186 windows and will be told both the pointer location (in the graphics
    187 coordinates) and will have the coordinates stored in <tt>status</tt>
    188 variables.  For example, by typing ``1'' in the sky display window,
    189 the RA and DEC of the pointer are stored in the variables <tt>$R1</tt>
    190 and <tt>$D1</tt>.  This command can be used to let the user define
    191 locations or regions of interest on the Kapa window. (Future addition:
    192 <tt>button</tt>, which does the same with the mouse buttons). 
    1934
    1945<h3> Database Functions </h3>

  • trunk/Ohana/doc/www/html/Opihi-Programs/index.htm

    r4727 r4733  
    66
    77<p>
    8 Opihi is a program to manipulate and display 1-D (vector) and 2-D
    9 (matrix) data.  Opihi has a simple command-line interaction that
    10 resembles the UNIX tcsh, but with many additional useful features.
    11 Opihi consists of several, vaguely independant portions: the
    12 command-line interpreter language (Opihi), the image display tool
    13 (Kii), the graphing tool (Kapa), and the vector and matrix
    14 manipulation commands.
    15 
    16 <h3> User Interface -- Opihi </h3>
    17 
    18 <p>
    198Opihi is a generic command-line interpreter which has been used as the
    20 front-end for Opihi, as well as other programs in the Elixir system.
    21 The interpreter has a variety of features of shell-scripting
     9front-end for Mana, DVO, and other high-level programs in the Elixir
     10system.  The interpreter has a variety of features of shell-scripting
    2211languages: if statements, for loops, macros with command-line
    2312arguments, and so forth.  The shell also allows for variables,
    2413arithmetic on variables, input from source files, and a variety of
    25 other useful tools.  I have used the Opihi shell language for several
    26 other user interface front ends, in addition to the Opihi data analysis
    27 tool: a CCD controller interface and a variable star database in the
    28 LONEOS project.  The programming structure of the Opihi front-end
    29 makes it very easy to add commands to the package; more about this
    30 later.
     14other useful tools.  Opihi has a simple command-line interaction that
     15resembles the UNIX tcsh, but with many additional useful features.  It
     16can also be used as a scripting language much like #sh/# or perl.
     17
     18<p>
     19Opihi includes tools to manipulate and display 1-D (vector) and 2-D
     20(matrix) data.  Two external programs are used to graphical display.
     21These are the image display tool (Kii), the graphing tool (Kapa), and
     22the vector and matrix manipulation commands.  Various functions are
     23available to perform math, statistical, and other operations on
     24vectors and images.
     25
     26<h3> User Interface </h3>
    3127
    3228<p>
    … …  
    3632generally be placed on one line with semi-colons as separators. 
    3733
     34The interface has an interaction similar to <tt>tcsh</tt>.  The arrows
     35allow editing of previous commands.  You can also use emacs-like
     36commands such as cntl-a to reach the beginning of the line and cntl-e
     37to reach the end.  There is command and file completion: if you type
     38part of a command (as the first thing on a line) and then type tab, it
     39will fill in as much as possible, until the word is not unique.
     40Typing tab twice at that point will list the possible endings.  For
     41any but the first word on a line, the same thing will happen for the
     42files in the current directory.  It is also possible to type just a
     43fraction of a command, as long as it is unique.  An ambiguous command
     44will list the possible alternatives.  For example:
     45
     46<pre>
     47dvo: c
     48ambiguous command: c ( catalog cgrid clear create cursor )
     49</pre>
     50
     51The shell is an interpretive programming language.
     52
     53<h3> Data Representations</h3>
     54
     55<h4> Simple Scalar Variables </h4>
     56
    3857<p>
    3958Scalar variables in Opihi are proceeded with a dollar sign ($).  A
    … …  
    4867consist of the standard math operators (+,-,*,/) as well as any
    4968already-defined variables and the functions log(), ln(), sqrt(),
    50 exp(), ten() ($10^x$), sin(), cos(), etc.  Also, if there is a pair of
    51 curly brackets {} anywhere on a command line, whatever is inside is
    52 assumed to be a math expression and evaluated as well.  This later
    53 feature allows functions of variables to be passed as arguments to
    54 Opihi functions.  Variables can be numeric or character strings.  If
     69exp(), ten() ($10^x$), sin(), cos(), etc.  Variables can be numeric or character strings.  If
    5570the shell does not understand the syntax of the line as a math
    5671expression, it is assumed to be a string.
    5772
    5873<p>
    59 Some of the programming functions are for loops and if (if else)
    60 statements.  There are no delimiting characters; ends of program
    61 blocks are defined by the word 'end'.  Syntax is rather simplistic at
    62 the moment.  For example:
     74If there is a pair of curly brackets {} anywhere on a command line,
     75whatever is inside is assumed to be a math expression and evaluated as
     76well.  This later feature allows functions of variables to be passed
     77as arguments to Opihi functions.  (see also the discussion below about
     78temporary vectors and images).
     79
     80Any expression within curly brackets {} is assumed
     81to be an arithmetical expression and is evaluated before the line is
     82executed.  For example:
     83
     84<pre>
     85echo {$fred*dcos(45)}
     86</pre>
     87
     88would give the response 7.07107.  There are math functions cos, sin,
     89and tan, which operate on radian expressions, and also dcos, dsin,
     90dtan, which operate on degree expressions.  There are also the
     91equivalent inverse functions: eg., asin and dasin return radians and
     92degrees, respectively.  The help section on Math defines all of the
     93available math functions. 
     94
     95<h4> Lists </h4>
     96
     97Opihi lists are grouped sets of scalar variables (which may be
     98strings).  A list consists of N variables with names of the form
     99<tt>name:i/#, where the value of i ranges from 0 to N-1.  In addition,
     100the list length is defined as the value #name:n/#.  Since these are
     101just informally grouped, a list may be defined by hand (ie, by
     102defining each element and the length).  There is also the command
     103#list/# which builds a list from the following lines until reaching
     104a line consisting of the single word #end/#:
     105
     106<pre>
     107list sample
     108 value 0
     109 value 1
     110 test line
     111end
     112</pre>
     113
     114will define the variables #$sample:0 - $sample:2/#, and #$sample:n/#,
     115with value of 3.
     116
     117<p>
     118The list command may also construct a list from the output of a UNIX
     119command:
     120
     121<pre>
     122list sample -x "ls /tmp"
     123</pre>
     124
     125will result in a list consisting of one entry for each file in the
     126listing. 
     127
     128<p>
     129The list command may also be used to split a string by whitespace:
     130
     131<pre>
     132list sample -split this is a test
     133</pre>
     134will result in a list with 4 elements, one for each word.
     135
     136<h4> queues </h4>
     137
     138A queue is a data construct consisting of a sequence of lines from
     139which simple selections can be made.  Data items are added and removed
     140from the queue with #queuepush/# and #queuepop/# commands which push
     141entries on the end of the queue and pop them off the beginning.  The
     142available queues may be obtained with the command #queuelist/#, and
     143the length of a specific queue may be determined with the #queuesize/#
     144command.  The contents of a queue may be printed with #queueprint/#.
     145Pushing data onto a non-existent queue will create the queue.  An
     146empty queue may be created with the command #queueinit/# and a queue
     147may be deleted with #queuedelete/#. 
     148
     149<p>
     150The #queuepush/# commands allows for additional options which modify
     151how the data is pushed on the queue.  The #-uniq/# flag specifies that
     152the queue should be search for an existing match and not add the new
     153data item if a matching item already exists.  The #-replace/# flag is
     154similar to the #-uniq/# flag, but instead the new item will replace
     155the existing match, if a match is found.  These two options have
     156identical results if the match is made based on the entire line.
     157However, they may be more usefully distinguished by specifying a
     158restriction on the match with the #-key/# flag.  This flag specified
     159which whitespace-separated element of the line to use for the match,
     160with the first element being element 0. 
     161
     162<p>
     163Numerical vectors and images (matrices) are discussed later in this
     164document.
     165
     166<h3> Flow-control block </h3>
     167<h3> Shell Programing </h3>
     168
     169<pre>
     170break                     -- escape from function
     171for                       -- loops
     172if                        -- logical cases
     173input                     -- read command lines from a file
     174macro                     -- deal with the macros
     175</pre>
     176
     177<p>
     178There are several options for programming in <tt>status</tt>.  First,
     179a file which contains a series of commands can be executed with
     180<tt>input (filename)</tt>.  It is also possible to define macros which
     181will behave much like regular commands.  A macro is defined by typing
     182<tt>macro name</tt> or <tt>macro create name</tt> followed by the
     183commands.  Arguments to the macro are assigned to the variables $1
     184.. $N and the number of arguments is given by $0.  Macros may be
     185defined in <tt>input</tt> files, and in fact when <tt>status</tt> is
     186started, it loads the file <tt>~/.statusrc</tt> which may contain
     187default macros.  Simple loops and if statements can be performed, and
     188are quite useful for complex macros.
     189
     190<p>
     191'If' statements are similar in syntax to C if statements.  Math
     192expresions in the if statement must be contained in curly braces, as
     193elsewhere.  Variables with string values may use the logical ==
     194operator to test if two strings are the same.  'For' loops are quite
     195simplistic.  The form is:
     196
     197<pre>
     198for var first last delta
     199 (commands)
     200end
     201</pre>
     202
     203<p>
     204The value of <tt>$var</tt> will start at the value <tt>first</tt> and increment by
     205<tt>delta</tt> after each loop.  The loop will stop after <tt>$var</tt> is greater
     206than <tt>stop</tt>.  The value <tt>delta</tt> is optional, with 1 assumed.
     207The value of <tt>$var</tt> may be changed during the loop, and if set
     208beyong the value of <tt>last</tt> will end the loop early. 
     209
     210
     211<p>
     212Opihi has several types of flow-control features.  These include
     213for-loops, while-loops, if-else blocks.  These blocks are defined by
     214the corresponding command (#for/#, #while/#, #if/#) and are terminated
     215with by a line with the single word #end/#. 
     216
     217<p>
     218The for loop syntax is simplistic.  The #for/# command specifies the
     219loop variable, the starting value, the ending value, and optionally
     220the delta for each loop.  The implicit loop test is always to check if
     221the loop variable is still less than the end value (or greater than if
     222the delta value is negative).  The definitions of this loop syntax and
     223the value of the list length (#$list:n/#) and the vector length
     224(#vector[]/#) make for natural loops over all elements of a list or
     225vector.  Below are a few examples:
    63226
    64227<pre>
    … …  
    66229 echo $i
    67230end
     231</pre>
     232This runs the loop with the variable #$i/# running from 1.0, 1.1, up to 9.9
     233 (inclusive).
     234
     235<pre>
     236for i 0 $list:n
     237 echo $list:$i
     238end
     239</pre>
     240This would print all the elements of the list.
     241
     242<pre>
     243for i 0 vector[]
     244 echo vector[$i]
     245end
     246</pre>
     247This would print all the elements of the vector.
     248
     249<p>
     250The if-block begins with a line of the form: #if (condition)/# and
     251ends with a single #end/#.  A line with a single #else/# specifies the
     252optional else portion of the block.  The conditional expression is a
     253valid math inequality with approximately C-syntax:
     254
     255##
     256(($i < 10) && ($i > 4))
     257/##
     258
     259The elements of the inequality may also be string comparisons.  The
     260only valid string comparisons are #==/# and #!=/#. 
     261
     262<p>
     263The while loop begins with a line of the form #while (condition)/# and
     264ends with a single #end/#.  The conditions follow the same rules as
     265the if conditional statements.
     266
     267<p>
     268*continue, break, auto-break concepts/*
     269
     270
    68271
    69272macro test
    … …  
    82285performing unix system calls (<tt>exec (command)</tt>). 
    83286
     287<h3> Miscellaneous Commands </h3>
     288
     289<pre>
     290!                         -- system call
     291?                         -- list commands
     292??                        -- list variables
     293echo                      -- type this line
     294exec                      -- system call
     295exit                      -- exit program
     296help                      -- get help on a function
     297output                    -- redirect output to file
     298quit                      -- exit program
     299scan                      -- scan line from keyboard or file to variable
     300wait                      -- wait until return is typed
     301which                     -- show command
     302</pre>
     303
     304Most of these are self-explanatory.  The command ?? prints the system
     305variables.  The <tt>help</tt> command will provide help on a single
     306command or, without any arguments, will list all available help
     307files (this includes general help not associated with a specific
     308command). 
     309
    84310<h3> 1D Data and the Graphing Window </h3>
     311
     312<h3> Vector Plotting </h3>
     313
     314<pre>
     315box                       -- draw a box on the plot
     316clear                     -- erase plot
     317create                    -- create a new vector
     318cursor                    -- get coords from cursor
     319grid                      -- plot cartesian grid
     320hist                      -- create histogram from a vector
     321labels                    -- define labels for plot
     322limits                    -- define plot limits
     323plot                      -- plot a pair of vectors
     324print                     -- write vectors to file
     325ps                        -- define labels for plot
     326set                       -- vector math
     327style                     -- set the style for graph plots
     328vectors                   -- list vectors
     329zplot                     -- plot scaled points
     330</pre>
    85331
    86332<p>
    … …  
    90336of other vectors.  For example, we could create a sine wave with the
    91337following two lines:
     338
     339<p>
     340In addition to scalar variables, <tt>status</tt> can manipulate and
     341display 1-D vector variables.  Many of the commands which extract data
     342from the photometry database place the data in vectors as well as
     343plotting them.  A vector can also be created based on a number
     344sequence with the command <tt>create name Nelements start delta</tt>.
     345The resulting vector has $Nelements$ entries, starting at a value of
     346$start$ and running until $start + delta*Nelements$.  If $delta$ is
     3470.0, all elements will have the value of $start$.  A histogram of a vector
     348may be made with the command <tt>hist</tt>, which creates a new vector
     349containing the histogram of the first vector.  The data range and bin
     350size of the histogram are defined in same way as with create.  This
     351makes it easy to create the index vector that goes with a histogram
     352vector: 
     353
     354<pre>
     355hist y Ny 1 100 0.1
     356create dx 1 100 0.1
     357</pre>
     358
     359<p>
     360The above will create a histogram of y in Ny and the index in dx.
     361Plotting this with <tt>plot dx Ny</tt> will show the histogram.
     362
     363<p>
     364Vector math is performed with a command of the form <tt>set new =
     365  (expression)</tt>.  The expression is some math function employing
     366  vectors and scalars.  A complete listing of the math operators
     367  available in <tt>set</tt> can be found in the help for <tt>set</tt>.
     368
     369<p>
     370Once vectors are defined, they may be plotted.  A pair of vectors can
     371be plotted against each other if they have the same number of entries.
     372The plotting is performed on the graphics window, Kapa.  There are
     373actually several graphics windows available to <tt>status</tt>, any of
     374which may be used to plot at any time.  Some of the more complex
     375operations default to either graphics window 0 or 1, depending on the
     376context.  Except for those functions with a pre-defined window, all
     377plotting functions apply to the current graphics window unless an
     378option <tt>-n N</tt> is given to specify a different window.  The
     379plotting style is determined by the command <tt>style</tt> which can set
     380the line width, the line type (solid, dashed, dotted, etc), the point
     381type (box, cross, etc), the point size, the color, and whether a pair
     382of vectors is plotted as a sequence of points, a set of connected
     383lines, or a histogram.  Some functions which make plots use their own
     384styles, as discussed below.  The function <tt>limits</tt> lets the user
     385set the range of the plot axes, or check the current setting.  The
     386command <tt>plot</tt> will plot a pair of vectors on the current graphics
     387window using the current plotting style for that window.  The command
     388<tt>zplot</tt> will plot a pair of vectors with the point size scaled by
     389a third vector, with maximum and minimum point sizes representing
     390specified values.  The <tt>cursor</tt> command goes the other way: this
     391command puts the Kapa window in cursor mode and waits for input from
     392Kapa.  The user can then type any alphanumeric key on the graphics
     393windows and will be told both the pointer location (in the graphics
     394coordinates) and will have the coordinates stored in <tt>status</tt>
     395variables.  For example, by typing ``1'' in the sky display window,
     396the RA and DEC of the pointer are stored in the variables <tt>$R1</tt>
     397and <tt>$D1</tt>.  This command can be used to let the user define
     398locations or regions of interest on the Kapa window. (Future addition:
     399<tt>button</tt>, which does the same with the mouse buttons). 
    92400
    93401<pre>
    … …  
    127435green, blue, and yellow overlays.
    128436
     437<h3> programming considerations </h3>
     438The programming structure of the Opihi front-end
     439makes it very easy to add commands to the package; more about this
     440later.
Note: See TracChangeset for help on using the changeset viewer.