Initial commit

1 files changed, 430 insertions, 0 deletions

diff --git a/noao/digiphot/apphot/doc/polymark.hlp b/noao/digiphot/apphot/doc/polymark.hlp
new file mode 100644
index 00000000..e88bc089
--- /dev/null
+++ b/noao/digiphot/apphot/doc/polymark.hlp
@@ -0,0 +1,430 @@
+.help polymark May00 noao.digiphot.apphot
+.ih
+NAME
+polymark -- create or review polygon and coordinate lists for input to the
+polyphot task
+.ih
+USAGE
+polymark image
+.ih
+PARAMETERS
+.ls images
+The list of input images used to define the polygons.
+.le
+.ls coords = "default"
+The input / output center positions file. The center positions for each
+polygonal aperture are read from or written to coords. There may more than one
+center position per polygon. Center positions are written to coords 1 center
+position per line. When the current polygon changes POLYMARK inserts a line
+containing a single ';' after the last center position. If coords is
+"default", "dir$default" or a directory specification then a center position
+file name of the form dir$root.extension.version is constructed, where dir is
+the directory, root is the root image name, extension is "coo" and version is
+the next available version of the file. 
+.le
+.ls polygons = "default"
+The name of the polygons file. The vertices of each polygon  are read from or
+written to the polygons file. The polygons file contains a list of the
+polygon vertices. Each vertex list is terminated by a line containing a  ';'
+after the last vertex. If polygons is "default", "dir$default" or a directory
+specification then an output name of the form dir$root.extension.version is
+constructed, where dir is the directory, root is the root image name, extension
+is "ver" and the version is next available version of the file. The number of
+polygon files must be equal to the number of image files.
+.le
+.ls icommands = ""
+The image cursor or image cursor command file.
+.le
+.ls gcommands = ""
+The graphics cursor or graphics cursor command file.
+.le
+.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout"
+The coordinate system of the input coordinates read from or written
+to \fIcoords\fR and \fIpolygons\fR. The image header coordinate system is
+used to transform from the input coordinate system to the "logical" pixel
+coordinate system used internally, and from the internal "logical" pixel
+coordinate system to the output coordinate system. The input coordinate
+system options are "logical", tv", "physical", and "world". The output
+coordinate system options are "logical", "tv", and "physical". The image
+cursor coordinate system is assumed to be the "tv" system.
+.ls logical
+Logical coordinates are pixel coordinates relative to the current image.
+The  logical coordinate system is the coordinate system used by the image
+input/output routines to access the image data on disk. In the logical
+coordinate system the coordinates of the first pixel of a  2D image, e.g.
+dev$ypix  and a 2D image section, e.g. dev$ypix[200:300,200:300] are
+always (1,1).
+.le
+.ls tv
+Tv coordinates are the pixel coordinates used by the display servers. Tv
+coordinates  include  the effects of any input image section, but do not
+include the effects of previous linear transformations. If the input
+image name does not include an image section, then tv coordinates are
+identical to logical coordinates.  If the input image name does include a
+section, and the input image has not been linearly transformed or copied from
+a parent image, tv coordinates are identical to physical coordinates.
+In the tv coordinate system the coordinates of the first pixel of a
+2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300]
+are (1,1) and (200,200) respectively.
+.le
+.ls physical
+Physical coordinates are pixel coordinates invariant  with respect to linear
+transformations of the physical image data.  For example, if the current image
+was created by extracting a section of another image,  the  physical
+coordinates of an object in the current image will be equal to the physical
+coordinates of the same object in the parent image,  although the logical
+coordinates will be different.  In the physical coordinate system the
+coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D
+image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200)
+respectively.
+.le
+.ls world
+World coordinates are image coordinates in any units which are invariant
+with respect to linear transformations of the physical image data. For
+example, the ra and dec of an object will always be the same no matter
+how the image is linearly transformed. The units of input world coordinates
+must be the same as those expected by the image header wcs, e. g.
+degrees and degrees for celestial coordinate systems.
+.le
+The wcsin and wcsout parameters default to the values of the package
+parameters of the same name. The default values of the package parameters
+wcsin and wcsout are "logical" and "logical" respectively.
+.le
+.ls cache = ")_.cache"
+Cache the image pixels in memory. Cache may be set to the value of the apphot
+package parameter (the default), "yes", or "no". By default cacheing is 
+disabled.
+.le
+.ls graphics = ")_.graphics"
+The standard graphics device.
+.le
+.ls display = ")_.display"
+The default display device.  Display may be set to the apphot package
+parameter value (the default), "yes", or "no.  By default graphics overlay is
+disabled.  Setting display to one of "imdr", "imdg", "imdb", or "imdy" enables
+graphics overlay with the IMD graphics kernel.  Setting display to
+"stdgraph" enables POLYMARK to work interactively from a contour plot.
+.le
+
+.ih
+DESCRIPTION
+
+POLYMARK creates and / or displays center position and polygons files
+suitable for input to POLYPHOT. For each image in the input list POLYMARK
+creates a polygons file \fIpolygons\fR and center positions file \fIcoords\fR, 
+if these do not already exist. The format of the polygons and center
+position files is described in the OUTPUT section. 
+
+Polygonal apertures are defined and drawn on the image display using
+the image display cursor and then shifted to the desired center
+using the image display cursor. At any point in the marking process
+the user may rewind the polygon and coordinate file and draw the previously
+defined polygons on the display.
+
+The coordinates read from \fIpolygons\fR or  \fIcoords\fR are assumed to be
+in coordinate system defined by \fIwcsin\fR. The options are "logical", "tv",
+"physical", and "world" and the transformation from the input coordinate
+system to the internal "logical" system is defined by the image coordinate
+system.  The simplest default is the "logical" pixel system. Users working on
+with image sections but importing pixel coordinate lists generated from the
+parent image must use the "tv" or "physical" input coordinate systems.
+Users importing coordinate lists in world coordinates, e.g. ra and dec,
+must use the "world" coordinate system and may need to convert their
+equatorial coordinate units from hours and degrees to degrees and degrees first.
+
+The coordinates written to \fIpolygons\fR or \fIcoords\fR are in the coordinate
+system defined by \fIwcsout\fR. The options are "logical", "tv", and
+"physical". The simplest default is the "logical" system. Users
+wishing to correlate the output coordinates of objects measured in
+image sections or mosaic pieces with coordinates in the parent
+image must use the "tv" or "physical" coordinate systems.
+
+If \fIcache\fR is yes and the host machine physical memory and working set size
+are large enough, the input image pixels are cached in memory. If cacheing
+is enabled and POLYMARK is run interactively the first measurement will appear
+to take a long time as the entire image must be read in before the measurement
+is actually made. All subsequent measurements will be very fast because POLYMARK
+is accessing memory not disk. The point of cacheing is to speed up random
+image access by making the internal image i/o buffers the same size as the
+image itself. However if the input object lists are sorted in row order and
+sparse cacheing may actually worsen not improve the execution time. Also at
+present there is no point in enabling cacheing for images that are less than
+or equal to 524288 bytes, i.e. the size of the test image dev$ypix, as the
+default image i/o buffer is exactly that size. However if the size of dev$ypix
+is doubled by converting it to a real image with the chpixtype task then the
+effect of cacheing in interactive is can be quite noticeable if measurements
+of objects in the top and bottom halfs of the image are alternated.
+.ih
+CURSOR COMMANDS
+
+The following interactive keystroke and colon commands are available.
+
+.nf
+	Interactive Keystroke Commands
+
+?	Print help
+:	Colon commands 
+d	Plot radial profile of star near cursor
+g	Define the current polygonal aperture
+f	Draw the current polygon on the display
+spbar	Draw the current polygon on the display, output the polygon
+r	Rewind the polygon list
+m	Draw the next polygon in the polygon list on the display
+l	Draw all the remaining polygons in the list on the display
+q	Exit
+
+	Colon commands
+
+:m [n]	Draw the next [nth] polygon in the polygon list on the display
+.fi
+
+.ih
+OUTPUT
+
+A sample polygons file and accompanying coordinates file is listed below.
+
+.nf
+	# Sample Polygons File (2 polygons)
+
+	200.5  200.5
+	300.5  200.5
+	300.5  300.5
+	200.5  300.5
+	;
+	100.4  100.4
+	120.4  100.4
+	120.4  120.4
+	100.4  120.4
+	;
+.fi
+
+.nf
+	# Sample Coordinates File (2 groups, 1 for each polygon)
+
+	123.4  185.5
+	110.4  130.4
+	150.9  200.5
+	;
+	85.6   35.7
+	400.5  300.5
+	69.5   130.5
+	;
+.fi
+
+.ih
+EXAMPLES
+
+1. Create a coordinate list and polygon file using the image display and
+image display cursor. Use polymark to both create and display the 
+polygon and polygon center lists.
+
+.nf
+	ap> display dev$ypix 1 fi+ 
+
+	... display the image
+
+	ap> polymark dev$ypix display=imdg
+
+	... type ? for an optional help page 
+
+	... type g to enter the "define a polygon" menu
+	... move the cursor to the first vertex, tap the space bar
+	    to mark the vertex, and repeat for each vertex
+	... type q to quit the "define a polygon" menu
+	... mark each vertex only once, POLYPHOT will close the
+	    polygon for you
+
+	... move the cursor to the desired polygon center and
+	    tap the space bar to record the polygon
+	... repeat for all desired polygon centers
+
+	... type g to define the next polygon
+	... move the cursor to the first vertex, tap the space bar
+	    to mark the vertex and repeat for each vertex
+	... type q to quit the polygon menu
+	... mark each vertex only once, POLYPHOT will close the
+	    polygon for you
+
+	... move the cursor to the desired polygon center and
+	    tap the space bar
+	... repeat for all desired polygon centers
+
+	... type q to quit and q to confirm the quit
+
+	... output will appear in ypix.coo.1 and ypix.ver.1
+
+
+	ap> display dev$ypix 2 fi+ 
+
+	... display the image
+
+	ap> polymark dev$ypix coords=ypix.coo.1 polygons=ypix.ver.1 \
+	    display=imdg
+
+	... type m to mark the first polygon / polygon center on the display
+
+	... type m to mark the next polygon / polygon center on the display
+
+	... type l to mark the remaining polygons
+
+	... type q to quit and q to confirm the quit
+
+
+	ap> display dev$ypix 2 fi+ 
+
+	... redisplay the image
+
+	ap> polymark dev$ypix coords="" polygons=ypix.ver.1 \
+	    display=imdg
+
+	... type l to mark the polygon list, note that since there is
+	    no coords file the polygons are not shifted
+
+	... type q to quit and q to confirm the quit
+.fi
+
+
+2. Repeat the previous example using an image section.
+
+.nf
+	ap> display dev$ypix[150:450,150:450] 1 fi+ 
+
+	... display the image
+
+
+	ap> polymark dev$ypix[150:450,150:450]] display=imdg wcsout=tv
+
+	... type ? for an optional help page 
+
+	... type g to enter the "define a polygon" menu
+	... move the cursor to the first vertex, tap the space bar
+	    to mark the vertex, and repeat for each vertex
+	... type q to quit the "define a polygon" menu
+	... mark each vertex only once, POLYPHOT will close the
+	    polygon for you
+
+	... move the cursor to the desired polygon center and
+	    tap the space bar to record the polygon
+	... repeat for all desired polygon centers
+
+	... type g to define the next polygon
+	... move the cursor to the first vertex, tap the space bar
+	    to mark the vertex and repeat for each vertex
+	... type q to quit the polygon menu
+	... mark each vertex only once, POLYPHOT will close the
+	    polygon for you
+
+	... move the cursor to the desired polygon center and
+	    tap the space bar
+	... repeat for all desired polygon centers
+
+	... type q to quit and q to confirm the quit
+
+	... output will appear in ypix.coo.2 and ypix.ver.2
+
+
+	ap> display dev$ypix[150:450,150:450] 2 fi+ 
+
+	... display the image
+
+
+	ap> polymark dev$ypix[150:450,150:450] coords=ypix.coo.2 \
+            polygons=ypix.ver.2 display=imdg wcsin=tv
+
+	... type m to mark the first polygon / polygon center on the display
+
+	... type m to mark the next polygon / polygon center on the display
+
+	... type l to mark the remaining polygons
+
+.fi
+
+
+3. Repeat example 1 using a contour plot instead of the image display.
+
+.nf
+	ap> show stdimcur
+
+	... record the default value of stdimcur
+
+	ap> set stdimcur = stdgraph
+
+	... define the image cursor to be the graphics cursor
+
+	ap> contour dev$ypix
+
+	... draw a contour plot on the screen
+
+	ap> contour dev$ypix >G ypix.plot1
+
+	... store the contour plot of dev$ypix in the file ypix.plot1
+
+	ap> polymark dev$ypix display=stdgraph
+
+	... type g to enter the define a polygon menu
+	... move the cursor to the first vertex, tap the space bar
+	    to mark the vertex, and repeat for each vertex
+	... type q to quit the define a polygon menu
+	... mark each vertex only once, POLYPHOT will close the
+	    polygon for you
+
+	... move the cursor to the desired polygon center and
+	    tap the space bar to record the polygon
+	... repeat for all desired polygon centers
+
+	... type g to define the next polygon
+	... move the cursor to the first vertex, tap the space bar
+	    to mark the vertex and repeat for each vertex
+	... type q to quit the define a polygon menu
+	... mark each vertex only once, POLYPHOT will close the
+	    polygon for you
+
+	... move the cursor to the desired polygon center and
+	    tap the space bar
+	... repeat for all desired polygon centers
+
+	... type r to rewind the coordinate and polygon lists
+
+	... type :.read ypix.plot1 to reread the contour plot
+
+	... type l to display all the polygons ...
+
+	... type q to quit and q again to confirm the  quit
+
+	... output will appear in ypix.ver.3 and ypix.coo.3
+
+	ap> contour dev$ypix
+
+	... redraw the contour plot
+
+	ap> polymark dev$ypix coords="ypix.coo.3" polygons=ypix.ver.3 \
+	    display=stdgraph
+
+	ap> set stdimcur = <default>
+
+	... reset the value of the stdimcur parameter
+.fi
+
+.ih
+BUGS
+
+It is the responsibility of the user to make sure that the image displayed
+in the image display is the same as the image specified by the image parameter.
+
+Commands which draw to the image display are disabled by default.  To enable
+graphics overlay on the image display, set the display parameter to "imdr",
+"imdg", "imdb", or "imdy" to get red, green, blue or yellow overlays. It
+may be necessary to run gflush and to redisplay the image to get the overlays
+position correctly.
+
+There are no restrictions on the shape of the polygon but the vertices
+must be listed in order either clockwise or counterclockwise in the
+polygons file.
+
+It is not necessary to close the polygon when drawing on the display.
+POLYMARK will complete the polygon for you.
+
+.ih
+SEE ALSO
+polyphot
+.endhelp