magimageWCS: Tan Gnomonic WCS Image Decoration

In magicaxis: Pretty Scientific Plotting with Minor-Tick and Log Minor-Tick Support

Tan Gnomonic WCS Image Decoration

Description

These functions add various WCS information to R images. It is particularly designed to work in unison with magimage that is used extensively in the wider ProFit package.

Usage

magimageWCS(image, header, n, grid.col = "grey", grid.lty = 2, grid.lwd = 0.5,
lab.col = "green", coord.type = "sex", margin = TRUE, loc.diff = c(0, 0),
xlab = "Right Ascension", ylab = "Declination", mgp = c(2, 0.5, 0), mtline = 2,
position = "topright", com.col = "green", com.length = 0.05, coord.axis = 'auto',
pretty = 'auto', CRVAL1 = 0, CRVAL2 = 0, CRPIX1 = 0, CRPIX2 = 0, CD1_1 = 1, CD1_2 = 0,
CD2_1 = 0, CD2_2 = 1, CTYPE1 = 'RA--TAN', CTYPE2 = 'DEC--TAN', ...)

magimageWCSRGB(R, G, B, header_out, Rheader, Gheader, Bheader, dowarp='auto',
direction = "auto", boundary = "dirichlet", interpolation = "cubic", n, grid.col='grey',
grid.lty=2, grid.lwd=0.5, lab.col='green', coord.type='sex', margin=TRUE, loc.diff=c(0,0),
xlab='Right Ascension', ylab='Declination', mgp=c(2,0.5,0), mtline=2, position='topright',
com.col="green", com.length=0.05, coord.axis='auto', pretty='auto', CRVAL1=0, CRVAL2=0,
CRPIX1=0, CRPIX2=0, CD1_1=1, CD1_2=0, CD2_1=0, CD2_2=1, CTYPE1 = 'RA--TAN',
CTYPE2 = 'DEC--TAN', ...)

magimageWCSGrid(header, n, grid.col = "grey", grid.lty = 1, grid.lwd = 1,
coord.type = "sex", loc.diff = c(0, 0), pretty= 'auto', CRVAL1 = 0, CRVAL2 = 0,
CRPIX1 = 0, CRPIX2 = 0, CD1_1 = 1, CD1_2 = 0, CD2_1 = 0, CD2_2 = 1, CTYPE1 = 'RA--TAN',
CTYPE2 = 'DEC--TAN', ...)

magimageWCSLabels(header, n, lab.col = "green", coord.type = "sex", margin = TRUE,
loc.diff = c(0, 0), xlab = "Right Ascension", ylab = "Declination", mgp = c(2, 0.5, 0),
mtline = 2, coord.axis='auto', pretty= 'auto', CRVAL1 = 0, CRVAL2 = 0, CRPIX1 = 0,
CRPIX2 = 0, CD1_1 = 1, CD1_2 = 0, CD2_1 = 0, CD2_2 = 1, CTYPE1 = 'RA--TAN',
CTYPE2 = 'DEC--TAN', ...)

magimageWCSCompass(header, position = "topright", com.col = "green", com.length = 0.05, 
loc.diff = c(0, 0), CRVAL1 = 0, CRVAL2 = 0, CRPIX1 = 0, CRPIX2 = 0, CD1_1 = 1, CD1_2 = 0,
CD2_1 = 0, CD2_2 = 1, CTYPE1 = 'RA--TAN', CTYPE2 = 'DEC--TAN', ...)

Arguments

image	Numeric matrix; required, the image we want to decorate. If image is a list as created by readFITS, read.fits of magcutoutWCS then the image part of the list is parsed to image and the correct header part is parsed to header.
header	Full FITS header in table or vector format. Legal table format headers are provided by the read.fitshdr function or the hdr list output of read.fits in the astro package; the hdr output of readFITS in the FITSio package or the header output of magcutoutWCS. If a header is provided then key words will be taken from here as a priority. Missing header keywords are printed out and other header option arguments are used in these cases.
R	Numeric matrix; containing the red colour values to be plotted (NAs are allowed). If R is a list as created by readFITS, read.fits of magcutoutWCS then the image part of the list is parsed to R and the correct header part is parsed to Rheader.
G	Numeric matrix; containing the green colour values to be plotted (NAs are allowed). If G is a list as created by readFITS, read.fits of magcutoutWCS then the image part of the list is parsed to G and the correct header part is parsed to Gheader.
B	Numeric matrix; containing the blue colour values to be plotted (NAs are allowed). If B is a list as created by readFITS, read.fits of magcutoutWCS then the image part of the list is parsed to B and the correct header part is parsed to Bheader.
header_out	Full FITS header in table or vector format. This is the target WCS projection that the RGB image will be mapped onto. Legal table format headers are provided by the read.fitshdr function or the hdr list output of read.fits in the astro package; the hdr output of readFITS in the FITSio package or the header output of magcutoutWCS. If a header is provided then key words will be taken from here as a priority. Missing header keywords are printed out and other header option arguments are used in these cases.
Rheader	Full R FITS header in table or vector format. It is usually easier to include the header with the R list input as described above.
Gheader	Full G FITS header in table or vector format. It is usually easier to include the header with the G list input as described above.
Bheader	Full B FITS header in table or vector format. It is usually easier to include the header with the B list input as described above.
dowarp	Image warping flag, either TRUE, FALSE or 'auto' (default). If TRUE then the images will be warped onto the header_out WCS scheme, if FALSE they will not be (which will break if the WCSs are not truly the same and the iamges are pixel matched). 'auto' tries to detect if the headers are all the same, and if they are then it will set dowarp=FALSE, otherwise it will set to TRUE. This can be fooled by small (and unimportant) differences in the headers, e.g. they have different SWarp dates etc, since it just checks if the text differs anywhere.
direction	Only used if re-mapping via magwarp. "auto" (default), "forward" or "backward", see imwarp. Since it is usally better to go from the higher resolution image and map this onto the lower resolution grid, "auto" selects the better direction given the pixel scales recovered from the header information.
boundary	Only used if re-mapping via magwarp. Boundary conditions: "dirichlet", "neumann", "periodic" (default "dirichlet"), see imwarp
interpolation	Only used if re-mapping via magwarp. "nearest", "linear", "cubic" (default "linear"), see imwarp
n	The target number of major-axis sub-divisions. Will not necessarily be achieved.
grid.col	The colour of the overlaid grid lines.
grid.lty	The line type of the overlaid grid lines.
grid.lwd	The line width of the overlaid grid lines.
lab.col	The colour of the labels when margin=FALSE.
coord.type	Should the labels be drawn using degrees (deg) or colon delimited sexigesimal (sex).
margin	Should the labels be drawn in the outer margin region (default).
loc.diff	The pixel offset to apply. Only relevant if the image being plotted is a cutout from within a FITS legal image.
xlab	x axis name. If left as default either H:M:S or D:M:S (coord.type='sex') or deg (coord.type='deg') will be appended.
ylab	y axis name. If left as default either H:M:S or D:M:S (coord.type='sex') or deg (coord.type='deg') will be appended.
mgp	The margin line (in mex units) for the axis title, axis labels and axis line. This has different (i.e. prettier) defaults than R of c(2,0.5,0) rather than c(3,1,0). This pushes the numbers and labels nearer to the plot compared to the defaults. For margin=FALSE mgp = -mgp - 3, which has the effect of shifting the tick labels nicely inside the margin.
mtline	Number of lines separating axis name from axis. For margin=FALSE mtline = -mtline, which has the effect of shifting the axis labels nicely inside the margin.
coord.axis	Integer vector; specifies whether the RA and Dec axes should be 1 or 2 (i.e. x or y axis). The default 'auto' tries to guess based on the header information (and this usually works okay). Otherwise coord.axis=c(1,2) would be sensible for a N/S vertical aligend frame and coord.axis=c(2,1) would be sensible for a E/W vertically aligned frame. When the orientation is between the two then it is not always obvious which will work better.
pretty	If 'auto' then it will try to compute the prettiest grid and label scaling *usually this is pretty good). Otherwise set to 1 to be degrees major ticks, 60 for minutes (DMS or HMS) and 3600 for seconds (DMS or HMS).
position	Relative position of the compass bar. This argument is used like the 'legend' function. Specify one of 'bottom', 'bottomleft', 'left', 'topleft', 'top', 'topright', 'right', 'bottomright' and 'centre'.
com.col	Colour of the compass.
com.length	Length of the edges of the arrow head.
CRVAL1	FITS header CRVAL1 for the CTYPE1 projection system. This is the RA in degrees at the location of CRPIX1.
CRVAL2	FITS header CRVAL2 for the CTYPE2 projection system. This is the Dec in degrees at the location of CRPIX2.
CRPIX1	FITS header CRPIX1 for the CTYPE1 projection system. This is the x pixel value at the location of CRVAL1.
CRPIX2	FITS header CRPIX2 for the CTYPE2 projection system. This is the y pixel value at the location of CRVAL2.
CD1_1	FITS header CD1_1 for the CTYPE1 projection system. Change in CTYPE1 in degrees along x-Axis.
CD1_2	FITS header CD1_2 for the CTYPE1 projection system. Change in CTYPE1 in degrees along y-Axis.
CD2_1	FITS header CD2_1 for the CTYPE2 projection system. Change in CTYPE2 in degrees along x-Axis.
CD2_2	FITS header CD2_2 for the CTYPE2 projection system. Change in CTYPE2 in degrees along y-Axis.
CTYPE1	The RA projection system type. Either 'RA–TAN' for Tan Gnomonic (default), or 'RA–SIN' for Sine Orthographic. 'RA–NCP' is approximated by Sine Orthographic with a warning. Over-ridden by the FITS header.
CTYPE2	The DEC projection system type. Either 'DEC–TAN' for Tan Gnomonic (default), or 'DEC–SIN' for Sine Orthographic. 'DEC–NCP' is approximated by Sine Orthographic with a warning. Over-ridden by the FITS header.
...	These are parsed to magimage, (magimageWCS), magimageRGB, (magimageWCSRGB), lines (magimageWCSGrid), axis (magimageWCSLabels) or arrows (magimageWCSCompass).

Details

Most people will be content to use the higher level magimageWCS function, which calls (in order) magimage, magimageWCSGrid, magimageWCSLabels and magimageWCSCompass.

magimageWCSRGB can be used in a few different ways, but the recommended route is to supply combined image and header list objects to the R, G and B arguments. If header_out is not supplied then by default it will project the three images onto the first available WCS header it finds searching R, G and B in order. If you are happy to map the colour image into the R WCS then you do not need to supply header_out at all. Note if image remapping is required (the images are different sizes or the headers differ) then the imager library will need to be installed in order to use magwarp.

Value

Outputs the final image list containing x,y and z (magimageWCS) or R/G/B (magimageWCSRGB). Generally run for the side effect of producing rapid and well-scaled image plots.

Note

For convenience users can use the header outputs produced by both the readFITS and astro package.

By R convention the bottom-left part of the bottom-left pixel when plotting the image matrix is c(0,0) and the top-right part of the bottom-left pixel is c(1,1), i.e. the mid-point of pixels are half integer values in x and y. This differs to the FITS convention of pixel mid points being integer values. As such the R [x,y] = FITS [x-0.5,y-0.5]. This rarely matters too much in practice, but for accurate overlays you will want to get it right.

Author(s)

Aaron Robotham

See Also

magimage, magcutoutWCS, radec2xy, xy2radec

Examples

## Not run: 
image=readFITS(system.file("extdata", 'VIKING/mystery_VIKING_Z.fits', package="ProFound"))

#Convenient image plotting for lists containing headers:

magimageWCS(image$imDat, header=image$hdr)
magimageWCS(image)

#First using the outer margins for tick labels:

par(mar=c(3.1,3.1,1.1,1.1))
magimageWCS(image)
magimageWCS(image, coord.type='deg')

#Now removing the margins and putting labels inside the image:

par(mar=c(0,0,0,0))
magimageWCS(image, margin=FALSE)
magimageWCS(image, margin=FALSE, coord.type='deg')

#We can make a WCS colour image of mismatched images:

VISTA_K=readFITS(system.file("extdata", 'VISTA_K.fits', package="magicaxis"))
VST_r=readFITS(system.file("extdata", 'VST_r.fits', package="magicaxis"))
GALEX_NUV=readFITS(system.file("extdata", 'GALEX_NUV.fits', package="magicaxis"))

magimageWCSRGB(VISTA_K, VST_r, GALEX_NUV)
magimageWCSRGB(VISTA_K, VST_r, GALEX_NUV, saturation=0.5)

#To make direct magimageRGB plots of the outputs you must turn off magmap scaling:

temp=magimageWCSRGB(VISTA_K, VST_r, GALEX_NUV)
magimageRGB(R=temp$R, G=temp$G, B=temp$B, magmap=FALSE)

#We can map onto various WCS schemes easily too:

magimageWCSRGB(VISTA_K, VST_r, GALEX_NUV, VISTA_K$hdr)
magimageWCSRGB(VISTA_K, VST_r, GALEX_NUV, VST_r$hdr)
magimageWCSRGB(VISTA_K, VST_r, GALEX_NUV, GALEX_NUV$hdr)

## End(Not run)

magicaxis documentation built on March 18, 2022, 6:27 p.m.