path: root/pkg/images/tv/doc/tvmark.hlp

.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