### LISTSHOW

Reports the positions stored in a positions list

#### Description:

This application reports positions contained in a catalogue. The catalogue should have the form of a positions list as produced, for instance, by applications LISTMAKE and CURSOR. By default all positions in the catalogue are reported, but a subset may be reported by specifying a range of position identifiers  (see Parameters FIRST, LAST, and STEP).

An NDF  may be supplied (see Parameter NDF) in which case the NDF pixel values at the positions listed in the catalogue are reported, using the interpolation method specified by Parameter METHOD. The pixel values are also written to an output parameter (see Parameter PIXVALS).

Positions may be reported in a range of co-ordinate Frames  dependent on the information stored in the supplied positions list (see Parameter FRAME). The selected positions are written to an output parameter (Parameter POSNS), and may also be written to an output positions list (see Parameter OUTCAT). The formatted screen output can be saved in a logfile (see Parameter LOGFILE). The formats used to report the axis values can be controlled using Parameter STYLE.

Graphics may also be drawn marking the selected positions (see Parameters PLOT and LABEL). The supplied positions are aligned with the picture specified by Parameter NAME. If possible, this alignment occurs within the co-ordinate Frame specified using Parameter FRAME. If this is not possible, alignment may occur in some other suitable Frame. A message is displayed indicating the Frame in which alignment occurred. If the supplied positions are aligned successfully with a picture, then the range of Frames in which the positions may be reported on the screen is extended to include all those associated with the picture.

#### Usage:

listshow incat [frame] [first] [last] [plot] [device]

#### Parameters:

A string determining the co-ordinate Frame in which positions are to be stored in the output catalogue associated with Parameter OUTCAT. See Parameter FRAME for a description of the allowed values for this parameter. If a null (!) value is supplied, the positions will be stored the Frame used to specify positions within the input catalogue. [!]
The epoch at which the sky positions stored in the output catalogue were determined. It will only be accessed if an epoch value is needed to qualify the co-ordinate Frame specified by COLFRAME. If required, it should be given as a decimal-years value, with or without decimal places ("1996.8", for example). Such values are interpreted as a Besselian epoch if less than 1984.0 and as a Julian epoch otherwise.
This parameter is only accessed if Parameter PLOT is set to "Chain" or "Poly". If TRUE, polgons will be closed by joining the first position to the last position. [current value]
The NDF array component to be displayed if a non-null value is supplied for Parameter NDF. It may be "Data", "Variance", "Error", or "Quality". ["Data"]
If TRUE, a detailed description of the co-ordinate Frame in which the positions will be reported is displayed before the positions. [current value]
The graphics workstation. Only accessed if Parameter PLOT indicates that graphics are required. [current graphics device]
If an IRAS90 Sky Co-ordinate System specification is supplied (using Parameter FRAME) for a celestial co-ordinate system, then an epoch value is needed to qualify it. This is the epoch at which the supplied sky positions were determined. It should be given as a decimal years value, with or without decimal places ("1996.8" for example). Such values are interpreted as a Besselian epoch if less than 1984.0 and as a Julian epoch otherwise.
The identifier for the first position to be displayed. Positions are only displayed which have identifiers in the range given by Parameters FIRST and LAST. If a null (!) value is supplied, the value used is the lowest identifier value in the positions list. [!]
A string determining the co-ordinate Frame in which positions are to be reported. This application can report positions in any of the co-ordinate Frames stored with the positions list. The string supplied for FRAME can be one of the following.
• A domain name  such as SKY, AXIS, PIXEL.

• An integer value giving the index of the required Frame.

• An IRAS90 Sky Co-ordinate System (SCS) values such as "EQUAT(J2000)" (see SUN/163).

If a null value (!) is supplied, positions are reported in the co-ordinate Frame which was current when the positions list was created. The user is re-prompted if the specified Frame is not available within the positions list. The range of Frames available will include all those read from the supplied positions list. In addition, if a graphics device is opened (i.e. if Parameter PLOT is set to anything other than "None"), then all the Frames associated with the picture specified by Parameter NAME will also be available. [!]

This parameter is only accessed if Parameter PLOT is set to "Chain" or "Poly". It specifies whether the curves drawn between positions should be stright lines, or should be geodesic curves. In many co-ordinate Frames geodesic curves will be simple straight lines. However, in others (such as the majority of celestial co-ordinate Frames) geodesic curves will be more complex curves tracing the shortest path between two positions in a non-linear projection. [FALSE]
A catalogue containing a positions list such as produced by applications LISTMAKE and CURSOR.
A string specifying the justification to be used when displaying text strings at the supplied positions. This parameter is only accessed if Parameter PLOT is set to "Text". The supplied string should contain two characters; the first should be "B", "C", or "T", meaning bottom, centre, or top respectively. The second should be "L", "C", or "R", meaning left, centre, or right respectively. The text is displayed so that the supplied position is at the specified point within the displayed text string. [CC]
If TRUE the positions are labelled on the graphics device specified by Parameter DEVICE. The offset of the centre of each label from the corresponding position is controlled using the NumLabGap(1)  and NumLabGap(2) plotting attributes, and the appearance of the labels is controlled using attributes Colour(NumLab), Size(NumLab), etc. These attributes may be specified using Parameter STYLE. The content of the label is determined by Parameter LABTYPE. [FALSE]
Determines what sort of labels are drawn if the LABEL parameter is set TRUE. It can be either of the following.
• "ID" –- causes the integer identifier associated with each row to be used as the label for the row.

• "LABEL" –- causes the textual label associated with each row to be used as the label for the row. These strings are read from the "LABEL" column of the supplied catalogue.

If a null (!) value is supplied, a default of "LABEL" will be used if the input catalogue contains a "LABEL" column. Otherwise, a default of "ID" will be used. [!]

The identifier for the last position to be displayed. Positions are only displayed which have identifiers in the range given by Parameters FIRST and LAST. If a null (!) value is supplied, the value used is the highest identifier value in the positions list. [!]
The name of the text file in which the formatted co-ordinates of the selected positions may be stored. This is intended primarily for recording the screen output, and not for communicating positions to subsequent applications. A null string (!) means that no file is created. [!]
This parameter is only accessed if Parameter PLOT is set to "Chain" or "Mark". It specifies the type of marker with which each position should be marked, and should be given as an integer PGPLOT marker type. For instance, 0 gives a box, 1 gives a dot, 2 gives a cross, 3 gives an asterisk, 7 gives a triangle. The value must be larger than or equal to $-$31. [current value]
The method to use when sampling the input NDF (if any) specified by Parameter NDF at each of the positions in the catalogue. For details on these schemes, see the description of routine AST_RESAMPLEx in SUN/210. Note, "Nearest" is always used if Parameter COMP is "Quality" . METHOD can take the following values.
• "Bilinear" –- The displayed pixel values are calculated by bi-linear interpolation among the four nearest pixels values in the input NDF. This produces smoother output NDFs than the nearest-neighbour scheme, but is marginally slower.
• "Nearest" –- Each displayed pixel value is the value of the nearest input pixel.
• "Sinc" –- Uses the