Function: DRAWAXIS Purpose: Label an axis with (transformed) coordinates Category: PHYSICAL COORDINATES, PLOTTING File: drawaxis.c Author: M.G.R. Vogelaar Updates: Aug 10, 1993: VOG, Document created. Oct 10, 1994: VOG, Replaced 'X' option by new 'I' and 'A' options (decouple tick marks and labels ) Dec 16, 1994: VOG, Implemented 'e' option for a coordinate grid overlay. Some minor changes. Mar 30, 1995: VOG, New function 'getminors'. Mar 6, 1996: VOG, Removed bug in 'getminors' if step < 1 Aug 12, 1997: VOG, Adapted for AITOFF projection Aug 12, 1999: VOG, Changed default center for offset axis to grid center (instead of PC at grid 0). Sep 7, 2003: VOG, Try to get axis name from header if axis is of parameter type. Jun 27, 2005: VOG, Change correction for crpix in function proco_correct. Definition now the same as in cotrans and gdsbox (NINT, not floor). Apr 14, 2009: VOG, -Changed definition of macro NINT so that is uses floor(). Change is necessary for consistency with other routines that proces coordinates. -Removed bug. procoXoff, procoYoff were set to 0.0 in loop. So always one of them was 0.0. Now initialization is done outside loop. Mouse positions now comparable to axis labels for non-integer CRPIX. Use: INTEGER DRAWAXIS ( OPTIONS, INPUT CHARACTER*(*) MARGIN, INPUT DOUBLE PRECISION ARRAY (2) SCALE, INPUT DOUBLE PRECISION ARRAY (2) ORIGMM, INPUT DOUBLE PRECISION ARRAY (2) BOX, INPUT DOUBLE PRECISION ARRAY (2) SETEXIST, INPUT LOGICAL SETIN, INPUT CHARACTER*(*) SUBIN, INPUT INTEGER LDEV, INPUT INTEGER TICKSIZE, INPUT DOUBLE PRECISION START, INPUT CHARACTER*(*) DELTA, INPUT CHARACTER*(*) MINORS, INPUT INTEGER AXFORMAT, INPUT CHARACTER*(*) AXLOGS, INPUT DOUBLE ARRAY AXLOGLEN INPUT INTEGER CGSTEP, INPUT DOUBLE PRECISION AXTITLE, OUTPUT CHARACTER*(*) TITLEXY, OUTPUT DOUBLE PRECISION ARRAY (8) TITLE_ID ) OUTPUT CHARACTER*(*) DRAWAXIS One axis will be plotted and labeled with coordinates If successful, the routine returns the length of a default title created by the routine. Otherwise it returns: -1 Something wrong with your box -2 No axis was specified -3 The conversion to hour, min, sec is not possible -4 No transformation possible for this spatial map -5 Your start position is not within range of axis -6 Axis has no length. -7 Subset dimension not 1 or 2. -8 Cannot convert START. -9 Cannot convert DELTA. -55 Unknown DELTAUNITS to convert from -56 Unknown (axis) units to convert to -57 Both DELTAUNITS and axis units are unknown -58 DELTAUNITS and header are incompatible. OPTIONS String with one or more characters of: B = Plot Bottom axis R = Plot Right axis L = Plot Left axis T = Plot Top axis W = Label current axis with untransformed World coordinates P = Label current axis with transformed Physical coordinates, SETIN and SUBIN must be part of the input. If axis are spatial and rotated, plot offsets only. O = Plot Offsets. Label START with zero. Plot labels at separation DELTA F = Calculate coordinates in FITS way, i.e. Xphys = CRVAL + Xgrid * CDELT I00 or I10, I01, I11 Plot/do not plot tIcks in(out)side frame on == 1, off == 0 inside == 1, outside == 0 A00 or A10, A01, A11 Plot/do not plot lAbels in(out)side frame on == 1, off == 0 inside == 1, outside == 0 Z Plot labels as 10**(World coordinate). MARGIN Space in mm in x and y direction for labels. SCALE Scale in x and y direction in grids/mm ORIGMM Origin x, y of the plot in mm. This is the location of the first position in BOX. (!) Note that the same SCALE and ORIGIN applies to all axes. BOX Box in world coordinates (if the axis is part a set, the world coordinates are grids). The axis range of the current axis will be extracted from these numbers. If you want coordinate transformations: SETEXIST Set/subset is given SETIN Name of set (set must exist) or an empty string. SUBIN Coordinate word of the subset for which an axis should be plotted. Subset dimension can be 1 or 2. LDEV Device to which output is directed. (See also anyout.dc2) About the labels: TICKSIZE Size of the label ticks in mm. If TICKSIZE is smaller than 0, a default size of 1/3 of the character height is used. START Start writing labels at this point. The string is converted to a position (Gipsy syntax for positions). If the string is an empty string, a suitable default will be calculated. DELTA Plot major ticks with separation DELTA, start at START. If the input string is empty, a suitable default will be calculated. If SETIN is specified, the value of DELTA can be given in (some) units. MINORS Number of minor tick intervals(!). If the input value is negative, a default value will be calculated. AXFORMAT AXFORMAT is a string used as format template. Also the formats hms/dms can be used. In these formats, a capital has a special meaning. AXLOGS Array containing numbers to label logarithmic values. e.g. 1 3 6 will plot the labels ... 0.1 at position log(0.1) 0.3 " " log(0.3) ... 60 " " log(60) ... AXLOGLEN Length of the AXLOGS array. If length equal to zero only logarithmic labels 10^n are plotted (n integer) CGSTEP Step size in grids between sample positions used to plot a coordinate grid. Output: AXTITLE A default title. If there was no set specified, this title is an empty string. The maximum length of a default string is 256. TITLEXY Suggested x,y of title. The title must be plotted in the the calling environment after correction for the character height of the title. The array has 8 elements. Element 1&2 for the bottom axis, 3&4 for the right axis, 5&6 for the top axis and 7&8 for the left axis. TITLE_ID One of the characters B,R,T,L for axis identification. Description: The routine DRAWAXIS plots one axis. The range of an axis is given in BOX. BOX has four numbers: x,y of lower left position and x,y of upper right position. The numbers are the world coordinates of the axis. If a set is given, this box is the range in grids to be plotted (and automatically also the range in physical coordinates). If the routine was successful, it will return a default title AXTITLE if a set was given. In TITLEXY a default position in mm of this title is returned in a special position in the TITLEXY array. The TITLEXY array has 8 elements. Element 1&2 for the bottom axis, 3&4 for the right axis, 5&6 for the top axis and 7&8 for the left axis. If there is not an input set, the title will be an empty string, but a default position is available. This is a position just outside the range of the plotted labels and it must be corrected in the calling environment for the character height of the title. The title always belongs to an axis, therefore also an identification, TITLE_ID (one of the characters B,T,R,L), is returned. If the routine encounters an error it will return with a negative number in DRAWAXIS. The list of errors is given above. The values for the default title position will be blank. The axis that must be plotted is specified in OPTIONS. This is a string with at least one character (one of B(ottom), R(ight), L(eft) or T(op)). If you want to plot world (grid) coordinates along an axis, include W(orld coordinate labels and if you want to plot transformed physical coordinates, include P(hysical axis). If you want physical coordinates that are not transformed with build in coordinate transformation but are calculated with the FITS formula: phys = CRVAL + grid * CDELT use option F(its). Note that CRVAL must be a position INSIDE your box, otherwise you will not get any labels. Axis labels (World or Physical positions) are plotted outside the box, unless you included the character I(nside box labeling). The characters can be in upper or lower case. Only one axis is plotted in one call. If you want no ticks and labels but only the axis itself to be plotted, give one of the axis characters B,T,R,L, but not a 'P' or 'W'. If coordinates in offset are wanted, include the character O(ffset). If rotation is detected, and physical coordinates are wanted then the offset mode is selected automatically. The offset then is in units of DELTAUNITS. If the start position for an offset is not given, the physical value of the reference pixel (from the set header) is taken if option 'P' is used, else, the world coordinate of the center (boxlo+boxhi)/2 is used as starting point. If the starting point is not within the axis range, no labels are plotted and an error code is returned. If an inset is given, coordinate transformation (between grids and physical coordinates) is possible with option 'P', else the option 'P' will have the same result as option 'W'. For the (internal) transformation of world coordinates to mm, a scale and origin is needed. SCALE has two values: first value is a scale in grids/mm in x direction, second value is a scale in grids/mm in y direction. ORIGMM has also two values indicating x,y in mm of the origin of your plot. To create more space between plot and axes, use MARGIN. MARGIN has two values indicating a margin in mm in x and y direction. This margin if often used as space for labels if labels has to be plotted inside the given box. For the transformation of grids to physical coordinates, a set must be part of the input. The information that is needed can be obtained by a call to GDSINP. SETIN is the name of set. SUBIN is the coordinate word of the subset for which an axis should be plotted. If you do not want or need these transformation, supply an empty string for SETIN. Then the value for SUBIN can be a dummy. There is a lot of flexibility in plotting the ticks and labels. TICKSIZE is the size of the label ticks in mm. If TICKSIZE is blank, a default size of 1/3 of the character height is used. The size of the minor ticks are 0.5 times the size major ticks. The routine starts writing a label at START. If on input the value of start is equal to blank (a floating or a double blank) a suitable default will be calculated. If SETIN is specified, the value of START can be given in some units. These units are compared to the units of the current axis found in the header. Conversion is possible if the units are compatible. A list of units can be found in $gip_sub/factor.c Major ticks have separation DELTA. If DELTA is equal to blank (a floating or a double blank) a suitable default will be calculated. If SETIN is specified, the value of DELTA can be given in units of DELTAUNITS. The number of minor tick intervals (!) is controlled by MINORS. If the value is a blank, a default value will be calculated. The labels can be formatted with AXFORMAT. AXFORMAT is a string used as format template. If the string is an empty string, a general format will be used for numerical labels and if a set was given, The hms format will be used for a longitude axis (if equatorial) and the dms format will be used for a latitude axis. The hms/dms formats may include a precision in seconds for example hms.ss will give the seconds with two digits accuracy. If no dot was included the routine calculates the precision itself. An uppercase character in the format results in fixing the corresponding digits, i.e. 'axformat hMS' always displays the minutes and seconds. For more information about numerical formats, see example and documentation $gip_sub/printusing.dc2. Other options: The 'O' option plots Offsets. It labels the position START with zero, and plots labels at separation DELTA. 'F' is used to do all position calculations according to FITS with the simple transformation: Xphys = CRVAL + Xgrid * CDELT Also the FITS transformation starts at the user given position to plot its first label. The default start position for FITS offsets is the center of your map. The options 'I' and 'A' are for tIckmarks and lAbels. The letter is followed by one or two digits. The first digit is 0 if tick mark or label must NOT be plotted and unequal to 0 if it must be plotted. The second digit is 0 if the tick mark or label is to be plotted outside the frame and 1 if it is to be plotted inside the frame. The default is I11A10 i.e. the tick marks are plotted inside the frame and the labels are plotted outside the frame. The 'Z' option plots labels as 10**(World/physical coordinate). The array AXLOGS contains the labels. The drawaxis routine calculates the corresponding positions and plots the labels. If the length of the array is 0, the default labels ... 0.01 0.1 1 10 100 ... are plotted. If you want more labels between these, specify an AXLOGS array with values >=1 and < 10. E.g. if AXLOGS contains 1 2 5 7, you will get labels: ... 0.01 0.02 0.05 0.07 0.1 0.2 0.5 0.7 1 2 5 7 ... The 'E' option extends the ticks until a border of the box is reached. With this option it is possible to plot a coordinate grid overlay. Examples: AXFORMAT examples: Note: The underscore character indicates a space. string | number | result | remark ==============|============|=============|=============================== +eeeeee.eeee | 43345.5436 | +4.3346e+04 | exp. format, signed conversion gggg.ggggg | 34.43 | _____34.430 | field width is 10 +ffff.ff | 23.456 | __+23.46 | signed conversion -ffff | 345.87 | 346 | left justified -+ffff.fff | 34.43 | +34.430 | left justified signed conv. eee.eeee | 234.43 | ________* | field width too small ffff.ff | blank | _______b | input was a blank hms | 45 | 3h0m0s | program determines precision hms.ss | 45 | 3h0m0.00s | 2 digits in precision hms. | 45 | 3h0m0s | 0 digits in precision dms | 45 | 45o0' | program determines precision Note: To be able to use the entire plot device and address positions in millimeter, use something like the next C code: mm = 2; nx1 = 0.0, nx2 = 1.0, ny1 = 0.0, ny2 = 1.0; pgsvp_c( &nx1, &nx2, &ny1, &ny2 ); pgqvp_c( &mm, x1mm, x2mm, y1mm, y2mm ); pgswin_c( x1mm, x2mm, y1mm, y2mm );