STScI Logo

polymark noao.digiphot.apphot


NAME · USAGE · PARAMETERS · DESCRIPTION · CURSOR_COMMANDS · OUTPUT
EXAMPLES · BUGS · SEE_ALSO

NAME

polymark -- create or review polygon and coordinate lists for input to the polyphot task

USAGE

polymark image

PARAMETERS

images
The list of input images used to define the polygons.
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.
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.
icommands = ""
The image cursor or image cursor command file.
gcommands = ""
The graphics cursor or graphics cursor command file.
wcsin = ")_.wcsin", wcsout = ")_.wcsout"
The coordinate system of the input coordinates read from or written to coords and polygons . 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.
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).
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.
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.
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.
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.
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.
graphics = ")_.graphics"
The standard graphics device.
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.

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 polygons and center positions file coords , 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 polygons or coords are assumed to be in coordinate system defined by wcsin . 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 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 polygons or coords are in the coordinate system defined by wcsout . 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 mosaic pieces with coordinates in the parent image must use the "tv" or "physical" coordinate systems.

If cache 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.

CURSOR COMMANDS

The following interactive keystroke and colon commands are available.

	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

OUTPUT

A sample polygons file and accompanying coordinates file is listed below.

	# 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
	;

	# 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
	;

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.

	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

2. Repeat the previous example using an image section.

	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

3. Repeat example 1 using a contour plot instead of the image display.

	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

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.

SEE ALSO

polyphot


Search Form · STSDAS