Program: ELLPROF Purpose: Create an output set with profiles extracted from an input set at positions in subsets that are either 1) defined by ellipses, 2) entered manually or 3) entered with the graphics cursor. Category: ANALYSIS, PROFILES, VELOCITY-FIELDS, PLOTTING File: ellprof.c Author: M.G.R. Vogelaar Keywords: **TABSET= Name of set with table to display: [SKIP] You can display a table with ellipse parameters generated in a previous run of ELLPROF. The table is stored in the header of the output set that was created. INSET= Give input set (, subsets): Maximum number of subsets is 2048. Dimension of subset(s) must be 2. Dimension of set must be at least 3. PROFAXIS= Give name of profile axis: [Next available axis] This keyword is only asked if the dimension of the set is greater than 3 (the ambiguous case). If the set dimension is 3 then the profile axis is always the only axis that does not belong to the input subsets. BOX= Give box in ..... [entire subset] OVERLAY= Overlay positions in GIDS? [Y]/N With OVERLAY=Y it is possible to overlay ellipses and/or sample positions in GIDS. The overlay option must also be set if you want to generate positions with the graphics cursor. If GIDS is not running or it is running with an incompatible image then OVERLAY=Y will spawn task VIEW. The INSET= keyword is not cancelled so the program VIEW starts GIDS and displays what's in INSET= (you can also expect VIEWs' keywords CLIP= and NEXT=). SAMPLES= 1) Ellipse(s), 2) Manual, 3) Cursor: [1]/2/3 or, if GIDS is not available: 1) Ellipse(s), 2) Manual: [1]/2 (SAMPLES=1) Generate sample positions on an ellipse and specify keywords CENTRE=, UNITS=, MAJOR=, INCL=, PA=, and RANGE= to define the ellipse. (SAMPLES=2) Get the positions manually (for example with recall files). (SAMPLES=3). Get the positions from GIDS with the graphics cursor. For options 2 and 3, it is possible to generate positions (INTERPOS=Y) between input positions, so that the generated positions have distance DELTA= in units given by UNITS=. Image values are interpolated for non- integer grid positions. Positions outside BOX= generate blanks. The ellipse keywords: ===================== CENTRE= Give central position of ellipses: [x,y] Input is a position in grids or physical coordinates. If a transformation from physical values to grids is possible then x,y is the projection centre (0,0) in grids (corresponding to the transformed CRVAL header values). Else, x,y is the centre of the map. UNITS= Give units for axis length: [header units] The units must be the header units or units that the program can convert to these header units. The units can be abbreviated as long as the input is unambiguous. Valid input is also GRIDS or PIXELS. Then the lengths are all given in grids. If a conversion is possible, MAJOR= (Rad.#) Give length of MAJOR axes in "units": [end loop] # is the number of the current radius. The keywords MAJOR=, INCL= and PA= are all asked in a loop which is aborted if carriage return is pressed for MAJOR=. The max. number of radii that can be specified in ONE(!) MAJOR= keyword is restricted (max 128). This construct- ion enables you to specify the axes, inclinations and position angles in one keyword, or to enter them using a Hermes recall file. For each radius, one output subset is created. INCL= Give inclinations (deg) of these ellipses: or, if number of entered major axes is 1: Give inclination (deg) of this ellipse: The inclination in degrees determines the length of the minor axis: minor = major*cos(INCL=). If you give less inclinations than radii in MAJOR=, the missing inclinations are copied from the last one. PA= Give P.A. (deg) of these ellipses: or, if number of entered major axes is 1: Give P.A. (deg) of this ellipse: If possible (both subset axes are spatial), the program automatically corrects this angle if the y-axis of your map does not align with the direction of the north (i.e. header says: CROTA <> 0). It is assumed that the spatial latitude axis carries the rotation information. If nothing is found in the header, 0 degrees is assumed. If you give less angles than radii in MAJOR=, the missing angles are copied from the last one. RANGE= Give sample angles 'start,end,step' (deg): [0 360 2] Define the sample positions on the ellipse. The start and end angles are wrt. the position of the major axis. The end angle is NOT included. The third value is the step size in degrees. The step is a constant angle along the ellipse (not along the enclosing circle). IPOLSIZE= Enter (odd) size in x & y of interpolation matrix: [7 7] Usually positions are non integer. Therefore an interpolation must be applied using neighbouring pixels. The interpolation is a spline interpolation. First the rows in the matrix are interpolated for the non integer x position and with the results a spline interpolation is applied for the non integer y of a position. The sizes must be odd numbers and cannot exceed the size of your map. The interpolation function can deal with blank values. Manual or cursor input: ====================== INTERPOS= Interpolate between input positions? Y/[N] INTERPOS=N: The positions entered manually or with the cursor are the sample positions. INTERPOS=Y: Use the positions entered manually or with the cursor as begin and end points of lines along which positions are interpolated so that the separations between these generated positions equals DELTA= DELTA= Give step size for interpolation in units: Give separation between positions along a line between two input positions in units of UNITS=. If the entered value is less than or equal to 0, there is no inter- polation of positions. **COLOUR= Marker colour (number or abbrv. name): [red] The positions pointed by the graphics cursor will be marked in this colour. The colour is entered as a number between 1 and 15 (see notes) or as a string which represent a colour. The colours are listed in the description. Colour strings can be abbreviated. Example: Set marker colour to yellow: COLOUR=7 COLOUR=Yellow COLOUR=yel XY= Give Position x, y: [end loop] In manual mode (SAMPLE=2), you enter positions in either grids or physical coordinates. This keyword can be used together with a Hermes recall file. The keyword is asked in a loop which is aborted by pressing carriage return. Examples: XY=10 20 Position in GRIDS. XY=* 10 12 8 * -67 8 9.6 Physical coordinates for spatial map in HMS DMS format in epoch given by the header. MORE= Continue with another subset with samples? Y/[N] You can create another output subset with profiles if you use MORE=Y. Then you re-enter the loop with XY=. The number of XY= positions is now limited by the first loop. If less are entered, profiles with blanks are generated. FILENAME= Give name of ASCII file: [No file] Write positions generated with SAMPLES=2 or SAMPLES=3 to a file on disk. If a transformation to physical coordinates is possible, write these coordinates also. OVERWRITE= File exists, ok to overwrite? [Y]/N Only prompted if FILENAME= is an existing file. The output set: ============== OUTSET= Give name of output set: The output set has at least 3 axes. The first is a new axis called PARAM-THETA with length equal to the number of selected positions. The second axis is the profile axis of the input set and the third axis is a new axis PARAM-RADIUS with length equal to the number of radii for the ellipse option or equal to the number of sample sessions (MORE=) for the manual or cursor options. Other (non subset) axes are copied from the input set. The axis names of the output set are displayed in the log-file. DELETE= Delete this set? [NO] If OUTSET= already exists, you delete this set with DELETE=Y. With DELETE=NO, you are prompted with OUTSET= again. Description: INTRODUCTION ============ Program ELLPROF has two functions. First: It creates an output set with profiles with starting points at (SAMPLES=1) positions on a user given ellipse, at (SAMPLES=2) positions entered by the user or (SAMPLES=3) at positions entered with the graphics cursor. Second, ELLPROF reads a GDS table from the header of a set previously made by ELLPROF with option SAMPLES=1. The ellipse characteristics are displayed if you started ELLPROF with TABSET=. CONSTRUCTION OF THE OUTPUT SET ============================== The set from which you want to extract profiles is INSET= and must be at least 3-dimensional. This set must be given as a number of two-dimensional subsets. Examples: 1) Set AURORA has axis RA, DEC, FREQ and you want to define ellipses in the RA-DEC plane, then INSET=AURORA FREQ 2) Set NGCX has axes RA, DEC, FREQ, PARAM and you want to define ellipses in the RA-DEC plane, then INSET=NGCX FREQ PARAM. This defines RA-DEC subsets in both FREQ and PARAM directions. In this last example it is not clear whether you want profiles in the FREQ or PARAM direction. In such cases you are prompted with keyword PROFAXIS= If you enter PROFAXIS=FREQ, then the profiles are taken in the FREQ direction. The subsets are repeated in the PARAM direction. The output set given with OUTSET= is a new set with axes: 1) PARAM-THETA 2) The profile axis 3) PARAM-RADIUS 4) A copy of all remaining axes in INSET= which are not part of the subsets and are not defined as the profile axis. For the second example an output set gets the axes: PARAM-THETA FREQ PARAM-RADIUS PARAM. The meaning of THETA and RADIUS is different for the options SAMPLES=1 and SAMPLES=2,3. The range of the PARAM-THETA axis is 1..n where n is the number of sample positions. The range of the PARAM-RADIUS axis is 1..m where m is the number of defined ellipses for SAMPLES=1 or the number of sample sessions (keyword MORE=) for SAMPLES=2 or 3 (manual or cursor input). It is possible to write only a part of the profile to the output set, e.g. INSET=NGCX FREQ 2:60 PARAM will write frequencies 2 to 60 to the output. However the length of the profile axis will remain the same as in the input set. GENERATION OF SAMPLE POSITIONS ============================== 1) Ellipse(s): There are 3 options for the position input. If SAMPLES=1 the positions are generated on an ellipse with centre CENTRE=. Input can be either in grids or in physical coordinates. Before giving the lengths of the major axes you see keyword UNITS=. This keyword has a default equal to the header units if the units of both subset axes are equal. Otherwise the default units are GRIDS. If you want to work in grids whatever the default is, use UNITS=GRIDS or UNITS=PIXELS. The units that you enter can be abbreviated as long as it is unambiguous. For example: if header units is DEGREE then the following units are allowed: UNITS= (degrees) UNITS=DE (degrees) UNITS=ARCM (minutes of arc) UNITS=ARCS (seconds of arc) After valid input of units unequal to grids, the screen displays the conversion between units and grids vv. The major axis (MAJOR=) is given in units of UNITS=. The number of radii given with MAJOR= sets the number of output subset. There is one subset for each radius. The inclination (INCL=) in degrees determines the length of the minor axis. The position angle (PA= in degrees) of the major axis of a galaxy is defined as the angle taken in anti-clockwise direction between the north direction in the sky and the major axis of the receding half of that galaxy (Rots 1975) astron, astrophys 45, 43. The keywords MAJOR=, INCL= and PA= are prompted in a loop to enable the use of a 'recall' file. However, per MAJOR= keyword it is possible to give a maximum of 128 radii at once. But the other loop keywords INCL= and PA= expect as many numbers as radii in MAJOR=. Missing numbers will be copied from the last one. The upper limit for the total number of radii is restricted by memory only. Finally the keyword RANGE= sets the ellipse sampling. It RANGE= accepts 3 numbers. First and second numbers are angles in degrees with respect to the position angle of the major axis. Sampling starts at the first angle and ends at the last. The last angle is not included. The third number is a step size in degrees. 2) manual input: For the manual or cursor input of positions, there are two options. The first option (INTERPOS=N) uses the positions entered by the user. If INTERPOS=Y, the entered positions are used to generate positions each separated DELTA= units (as in UNITS=) on an imaginary line through all the entered points, so the entered points need not to be part of the generated positions. For SAMPLES=2, the manual input, positions are entered with XY= (one position x, y per keyword). The keyword is prompted in a loop, so a recall file with positions can be used. The positions can be entered as grids or physical coordinates using prefixes as: U Numbers in header units * for RA or DEC in resp. HMS and DMS in EPOCH of set *1950 for RA or DEC in resp. HMS and DMS in EPOCH 1950.0 *xxxx.x for RA or DEC in resp. HMS and DMS in EPOCH xxxx.x G Galactic longitude or latitude in degrees E Ecliptic longitude or latitude in degrees S Supergalactic longitude or latitude in degrees Physical coordinates are transformed for the first input subset only. For the manual input the loop is aborted if carriage return is pressed. NOTE: Positions outside the box in BOX= do not participate! 3) cursor: With the cursor it is possible to enter positions with the left button or any keyboard key except 'Q'/'q'. The input loop is aborted if the right button is pressed or keyboard key 'Q' or 'q'. You can continue with entering more positions with MORE=Y. The first set of profiles is put into the first subset of the output, the second set in the second subset, etc. The maximum number of entered or interpolated positions in the first run is limited by memory only. In later runs it is limited by the number of positions of the first run. For both manual and cursor input, there is a possibility to write the used positions to an ASCII file on disk. You are prompted with FILENAME= which expects a file name or carriage return if you do not want to write to disk. For each output subset a header is written with the subset number. Then 2 or 4 columns with data follow. The first column in the file is a grid position in X direction, the second is a grid position in Y direction. If a transformation to header units is possible, then also these transformed physical coordinates are written where both columns are prefixed with a 'U' to indicate that the units are header units (in most cases: DEGREE). NOTE: Positions outside the box in BOX= do not participate! USING GIDS FOR OVERLAYS ======================= It is possible to overlay the defined ellipses and/or to plot the input sample positions on a subset displayed in GIDS (OVERLAY=Y). If OVERLAY=Y and and GIDS is not started or GIDS displays an incompatible set then the task VIEW is spawned with set specification equal to INSET= (keyword is not cancelled by ELLPROF). VIEW can ask keywords CLIP= and NEXT=. Keyword NEXT= allows you to browse through the subsets. In an overlay, a frame is plotted for the box as found in GIDS. Also two lines with length as given in BOX= are plotted through the centre of the map. If you cannot read the labels, use the zoom option in GIDS to rescale and rerun ELLPROF. For option SAMPLES=1, also the direction of the north is plotted. (the North arrow is an indication whether your map is rotated or not, the rotation is given by CROTA in the header) and all the specified ellipses are plotted including the major axis. If the pixel aspect ratio is not equal to 1 (CDELTs in header are unequal), you get a warning that the plotted angles are not factuous because you are introducing a compression in x or y direction. The position of the major axis does not coincide with the major axis of the (contorted) plotted ellipse. INTERPOLATION OF POSITIONS FOR IMAGE DATA ========================================= Ellipse sample positions or positions entered manually or with the cursor, usually do not coincide with the centre of a grid. Therefore an interpolation of image data is performed. Image data is taken from the input set at the four integer neighbouring positions of an input position. If all positions are within the input box (BOX=) and all image data is not blank then a bilinear interpolation is applied. For three valid neighbours, a plane is constructed to do the interpolation and for two positions, the interpolation is linear. MINIMUM/MAXIMUM UPDATE OF THE OUTPUT ==================================== The header values DATAMIN, DATAMAX, and BLANKS are updated in the output set after a call to task MNMX. The log file will show you the calculated values. GIPSY LOG FILE USE OF HERMES OUTPUT LEVEL ========================================= The information that ELLPROF generates can be controlled by setting the Hermes output level. If the level is NORMAL (usually the default) information is written to terminal and log file, warnings are written to the terminal and debug information is not displayed. If the level is set to EXPERT, all kind of information and warnings will not be displayed. With level TEST, also debug information is written to the terminal. UNITS RECOGNIZED BY GIPSY ========================= DEGREE ARCSEC ARCMIN RADIAN CIRCLE METER ANGSTROM NM MICRON MM CM INCH FOOT YARD M KM MILE PC KPC MPC TICK SECOND MINUTE HOUR DAY YEAR HZ KHZ MHZ GHZ M/S MM/S CM/S KM/S K MK JY MJY TAU INPUT FOR COLOUR KEYWORD ======================== index name ============================================= 0 Background 1 Default (Black if background is white) 2 Red 3 Green 4 Blue 5 Cyan 6 Magenta 7 Yellow 8 Orange 9 Green + Yellow 10 Green + Cyan 11 Blue + Cyan 12 Blue + Magenta 13 Red + Magenta 14 Dark Gray 15 Light Gray Notes: If you started GIDS on another machine than the one on which you run CURSOR, then cursor actions can be very slow! Example: ....... Updates: Jan 10, 1995: VOG, Document created. Jul 07, 1999: VOG, Improved interpolation in data by using a 2d-spline interpolation in 'getipval'.