From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 pkg/images/tv/doc/tvmark.hlp | 405 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 405 insertions(+)
 create mode 100644 pkg/images/tv/doc/tvmark.hlp

(limited to 'pkg/images/tv/doc/tvmark.hlp')

diff --git a/pkg/images/tv/doc/tvmark.hlp b/pkg/images/tv/doc/tvmark.hlp
new file mode 100644
index 00000000..b6611b22
--- /dev/null
+++ b/pkg/images/tv/doc/tvmark.hlp
@@ -0,0 +1,405 @@
+.help tvmark Dec89 images.tv
+.ih
+NAME
+tvmark -- mark objects on the image display 
+.ih
+USAGE
+tvmark frame coords
+.ih
+PARAMETERS
+.ls frame
+The frame or image plane number of the display to be marked. 
+.le
+.ls coords 
+The text file containing the coordinates of objects to be
+marked, one object per line with x and y in columns 1 and 2 respectively.
+An optional label may be read out of the third column.
+If \fIcoords\fR = "", the coordinate file is undefined.
+.le
+.ls logfile = ""
+The text file in which image cursor commands typed in interactive mode
+are logged. If \fIlogfile\fR = "" no commands are logged.
+If automatic logging is enabled, all cursor commands
+are logged, otherwise the user must use the interactive keep keystroke
+command to select specific cursor commands for logging.
+Commands are not logged in non-interactive mode.
+.le
+.ls autolog = no
+Automatically log all cursor commands in interactive mode.
+.le
+.ls outimage = ""
+The name of the output snapshot image.
+If tvmark is run in non-interactive mode and no command file is specified,
+a copy of the frame buffer
+is automatically written to the IRAF image \fIoutimage\fR after tvmark
+terminates execution.
+If \fIoutimage\fR = "" no output image is written.
+In interactive mode or in non-interactive mode if a command file
+is specified, the user can make snapshots of the frame buffer
+with the interactive colon  write command.  In this case the name of the output
+snapped image will be in order of priority, the name specified
+by the user in the colon write ommand,  "outimage.snap.version",  or,
+"imagename.snap.version".
+.le
+.ls deletions = ""
+The extension of the output file containing objects which were deleted
+from the coordinate file in interactive or command file mode.
+By default no output deletions file is written.
+If \fIdeletions\fR is not equal to the null string (""), then deleted
+objects are written to a file called \fIcoords.deletions\fR. For
+example if \fIcoords\fR = "nite1" and \fIdeletions\fR = "del", then the
+deletions file will be called "nite1.del".
+.le
+.ls commands = ""
+The text file containing the marking commands.
+In interactive mode if \fIcommands\fR = "", 
+\fIcommands\fR is the image cursor.  In non-interactive mode
+cursor commands may be read from a text file, by setting \fIcommands\fR =
+"textfile".  This file may be a user
+created command file, or the \fIlogfile\fR from a previous run of tvmark.
+If \fIcommands\fR = "" in non-interactive mode, the default mark is drawn
+on the display at the positions of all the objects in \fIcoords\fR.
+.le
+.ls mark = "point"
+The default mark type.  The options are:
+.ls point
+A point.  To ensure legibility \fIpoint\fR is actually a square dot whose
+size is specified by \fIpointsize\fR.
+.le
+.ls plus
+A plus sign.  The shape of the plus sign is determined by the raster font
+and its size is specified by \fItxsize\fR.
+.le
+.ls cross
+An x.  The shape of the x is determined by the raster font and its size is
+is specified by \fItxsize\fR.
+.le
+.ls circle
+A set of concentric circles whose radii are specified by the \fIradii\fR
+parameter.  The radii are in image pixel units.  If the magnifications
+used by display are not equal in x and y circles will become ellipses
+when drawn.
+.le
+.ls rectangle
+A set of concentric rectangles whose lengths and width/length ratio are
+specified by the \fIlengths\fR parameter.  The lengths are specified in
+image pixel units.  If the magnifications used by the display are not
+equal in x and y then squares will become rectangles when drawn.
+.le
+.le
+.ls radii = "0"
+If the default mark type is "circle" than concentric circles of radii
+"r1,r2,...rN" are drawn around each selected point.
+.le
+.ls lengths = "0"
+if the default mark type is "rectangle" then concentric rectangles of
+length and width / length ratio "l1,l2,...lN ratio" are drawn around
+each selected point.  If ratio is not supplied, it defaults to 1.0
+and squares are drawn.
+.le
+.ls font = "raster"
+The name of the font.  At present only a simple raster font is supported.
+.le
+.ls color = 255
+The numerical value or  color of the marks drawn.
+Any number between 0 and 255 may be specified.
+The meaning of the color is device dependent.
+In the current version of the Sun/IRAF IMTOOL numbers between 202
+and 217 may be used to display graphics colors.  The current color
+assignments for IMTOOL are summarized later in this help page.
+.le
+.ls label = no
+Label the marked coordinates with the string in the third column of
+the text file \fIcoords\fR.  \fIlabel\fR overrides \fInumber\fR.
+.le
+.ls number = no
+Label the marked objects with their sequence number in the coordinate
+list \fIcoords\fR.
+.le
+.ls nxoffset = 0, nyoffset = 0
+The x and y offset in display pixels of the numbers to be drawn.
+Numbers are drawn by default with the lower left corner of the first
+digit at the coordinate list position.
+.le
+.ls pointsize = 3
+The size of the default mark type "point". Point size will be rounded up
+to the nearest odd number.
+.le
+.ls txsize = 1
+The size of text, numbers and the plus and cross marks to be written.
+The size is in font units which are 6 display pixels wide and 7 display 
+pixels high.
+.le
+.ls tolerance = 1.5
+Objects marked by the cursor for deletion from the coordinate list
+\fIcoords\fR must be less than or equal to \fItolerance\fR pixels
+from the cursor position to be deleted. If 1 or more objects
+is closer than \fItolerance\fR, the closest object is deleted.
+.le
+.ls interactive = no
+Interactive mode.
+.le
+.ih
+DESCRIPTION
+TVMARK marks objects on the display by writing directly into
+the frame buffer specified by \fIframe\fR.  TVMARK can draw on
+any devices supported by the IRAF \fIdisplay\fR program.
+After marking, the
+contents of the frame buffer may be written out to the IRAF image
+\fIoutimage\fR.  The output image is equal in size and intensity
+to the contents of the frame buffer displayed at the time of writing.
+
+In interactive mode objects to be marked may be selected interactively
+using the image cursor or read from the text file \fIcoords\fR.
+Objects in the coordinate list
+may be selected individually by number,
+in groups by specifying a range of numbers, or the entire list may
+be read.  New objects may be added to the list interactively
+using the append keystroke command.  In batch mode cursor commands
+may be read from a text file by setting \fIcommands\fR to the name
+of the text file.  This may be a user created file of cursor
+commands or a log file from a previous interactive run of TVMARK.
+If no command file is specified then all the objects in the coordinate
+list are marked with the default mark type /fImark/fR.
+
+The mark commands entered in interactive mode can be saved in the text
+file \fIlogfile\fR.  If \fIautolog\fR
+is enabled and \fIlogfile\fR is defined all cursor commands
+are automatically logged.  If \fIautolog\fR is turned off then the user
+can select which commands are to be logged interactively using the
+interactive keep keystroke.
+
+The default mark type are currently "none", "point", "plus", "cross",
+"circle", a
+list of concentric circles, and "rectangles", a list of concentric rectangles.
+The size of the "point" mark is set using the parameter \fIpointsize\fR
+while the sizes of the "plus" and "cross" mark types are set by the
+\fItxsize\fR parameter.  Txsize is in font units which for the simple raster
+font currently implemented is six display pixels in x and seven display 
+pixels in y.
+The \fIradii\fR and \fIlengths\fR parameters
+describe the concentric circles and concentric rectangles to be drawn
+respectively.
+If \fInumber=yes\fR then objects in the coordinate list will be automatically
+numbered as well as marked.  The position of the number can be altered
+with the \fInxoffset\fR and \fInyoffset\fR parameters.
+
+In interactive mode tvmark maintains a scratch buffer.  The user opens
+the scratch buffer by issuing a save command which saves the current
+contents of the frame buffer in a temporary IRAF image.
+The user can continue marking and if unsatisfied with the results
+restore the last saved copy of the frame buffer with the restore
+command. Subsections of the saved frame buffer can be restored to the
+current frame buffer with the erase keystroke command.
+Finally a snapshot of the frame buffer can be saved permanently by
+using the write command. These snapped images can be redisplayed
+by setting the display task parameter \fIztrans\fR = "none".
+.ih
+CURSOR COMMANDS
+
+.nf
+              Interactive TVMARK Keystroke/Colon Commands
+
+The following keystroke commands are available.
+
+    ?	    Print help
+    +       Mark the cursor position with +
+    x       Mark the cursor position with x
+    .       Mark the cursor position with a dot
+    c       Draw defined concentric circles around the cursor position
+    r       Draw defined concentric rectangles around the cursor position
+    s	    Draw line segments, 2 keystrokes
+    v       Draw a circle, 2 keystrokes
+    b       Draw a rectangle, 2 keystrokes
+    f       Draw filled rectangle, 2 keystrokes
+    e	    Mark region to be erased and restored, 2 keystrokes
+
+    -       Move to previous object in the coordinate list
+    m       Move to next object in the coordinate list
+    p	    Mark the previous object in the coordinate list
+    n       Mark next object in the coordinate list	
+    l	    Mark all the objects in the coordinate list
+    o       Rewind the coordinate list
+    a       Append object at cursor position to coordinate list and mark
+    d	    Delete object nearest the cursor position in the coordinate list
+	    and mark
+
+    k       Keep last cursor command
+    q       Exit tvmark
+
+The following colon commands are available.
+
+   :show		     List the tvmark parameters
+   :move N	       	     Move to Nth object in coordinate list
+   :next N M                 Mark objects N to M in coordinate list
+   :text      [string]       Write text at the cursor position
+   :save		     Save the current contents of frame buffer
+   :restore                  Restore last saved frame buffer
+   :write     [imagename]    Write the contents of frame buffer to an image
+
+The following parameters can be shown or set with colon commands.
+
+   :frame             [number]
+   :outimage	      [imagename]
+   :coords	      [filename]
+   :logfile	      [filename]
+   :autolog           [yes/no]
+   :mark              [point|line|circle|rectangle|cross|plus]
+   :radii             [r1,...,rN]
+   :lengths           [l1,...,lN] [width]
+   :font	      [raster]
+   :color             [number]
+   :number            [yes/no]
+   :label	      [yes/no]
+   :txsize	      [1,2,..]
+   :pointsize	      [1,3,5...]
+.fi
+
+.ih
+CURRENT IMTOOL COLORS
+
+.nf
+	  0 = sunview background color (normally white)
+      1-200 = frame buffer data values, windowed
+	201 = cursor color (white)
+
+	202 = black
+	203 = white
+	204 = red
+	205 = green
+	206 = blue
+	207 = yellow
+	208 = cyan
+	209 = magenta
+	210 = coral
+	211 = maroon
+	212 = orange
+	213 = khaki
+	214 = orchid
+	215 = turquoise
+	216 = violet
+	217 = wheat
+
+    218-254 = reserved for use by other windows
+	255 = black (sunview foreground color)
+.fi
+
+.ih
+EXAMPLES
+1. Display an image,  mark all the objects in the coordinate file 
+m92.coo.1 with red dots, and save the contents of the frame buffer
+in the iraf image m92r.snap. Redisplay the marked image.
+
+.nf
+    cl> display m92r 1
+    cl> tvmark 1 m92.coo.1 outimage=m92r.snap col=204
+    cl> display m92r.snap 2 ztrans="none"
+.fi
+
+2. Execute the same command only number the objects in the coordinate
+list instead of marking them.
+
+.nf
+    cl> display m92r 1
+    cl> tvmark 1 m92.coo.1 outimage=m92r.snap mark=none\
+    >>>   number+ col=204
+    cl> display m92r.snap 2 ztrans="none"
+.fi
+
+3. Display an image and draw concentric circles with radii of 5, 10 and
+20 pixels corresponding to an aperture radius and inner and outer
+sky annulus around the objects in the coordinate list. 
+
+.nf
+    cl> display m92r 1
+    cl> tvmark 1 m92.coo.1 mark=circle radii="5,10,20" col=204
+.fi
+
+4. Display an image, mark objects in a coordinate list with dots
+and append new objects to the coordinate file.
+
+.nf
+    cl> display m92r 1
+
+    cl> tvmark 1 m92.coo.1 interactive+
+	... type q to quit the help menu ...
+	... type :number yes to turn on numbering ...
+	... type l to mark all objects in the coordinate file
+	... move cursor to desired unmarked objects and type a
+	... type :write to take a snap shot of the frame buffer
+	... type q to quit
+.fi
+
+5. Make a finder chart of a region containing 10 stars by drawing
+a box around the field, marking each of the 10 stars with a dot,
+labeling each with an id and finally labeling the whole field.
+Save all the keystroke commands in a log file.
+
+.nf
+    cl> display m92r 1 log=m92r.log auto+
+
+    cl> tvmark 1 "" interactive+
+
+	... type q to quit the help menu ...
+
+	... to draw a box around the finder field move the cursor to the
+	    lower left corner of the finder field and type b, move the
+	    cursor the upper right corner of the field and type b again
+
+	... to mark and label each object move to the position of the
+	    object and type ., next move slightly away from the object
+	    and type :text id 
+
+	... to label the chart with a title first type :txsize 2 for
+	    bigger text then move the cursor to the position where
+	    the title should begin and type :text title
+
+	... save the marked image with :write
+
+	... type q to quit the program
+.fi
+
+6. Edit the log file created above to remove any undesired commands
+and rerun tvmark redirecting cursor input to the log file.
+
+.nf
+    cl> display m92r 1
+    cl> tvmark 1 "" commands=logfile inter-
+.fi
+
+7. Draw a box on the display with a lower left corner of 101,101 and an
+upper right corner of 200,200 using a simple cursor command file.
+Note than in interactive mode the b key is the one that draws a box.
+
+.nf
+The command file contains the following 3 lines
+
+    101.0 101.0 101 b
+    200.0 200.0 101 b
+    200.0 200.0 101 q
+
+    cl> display m92r 1
+    cl> tvmark 1 "" commands=commandfile inter-
+.fi
+.ih
+BUGS
+Tvmark is a prototype task which can be expected to undergo considerable
+modification and enhancement in the future. The current version of this
+task does not produce publication quality graphics.
+In particular aliasing is easily visible in the code which draws circles
+and lines.
+
+Input from the coordinate list is sequential. No attempt has been made
+to arrange the objects to be marked in order for efficiency of input and
+output.
+
+Note that the move command does not currently physically move the image
+cursor. However the next mark drawn will be at the current coordinate
+list position.
+
+Users may wish to disable the markcur option in the imtool setup window
+before running tvmark.
+.ih
+SEE ALSO
+display, imedit, imexamine
+.endhelp
-- 
cgit 

