magcutout: Image Cutout Utility

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

Image Cutout Utility

Description

Function to subset raw images/matrices.

Usage

magcutout(image, loc = dim(image)/2, box = c(100, 100), shiftloc = FALSE, paddim = TRUE,
  padval = NA, plot = FALSE, ...)

Arguments

image	Numeric matrix; required, the image we want to cutout. If image is a path to an fst format file then the cutout can be done on disk directly.
loc	Numeric vector; the [x,y] location where we want to cutout the image.
box	Numeric vector; the dimensions of the box to cut out from image centred on loc. For magcutout the box unit is always pixels.
shiftloc	Logical; should the cutout centre shift from loc away from the image edge if the desired box size extends beyond the edge of the image?
paddim	Logical; should the cutout dimensions be padded with with value of padval for data outside the image boundary (TRUE)? If FALSE the dimensions will truncate when the edge of the input image has been reached.
padval	Numeric scalar; the value to use for padding if paddim=TRUE.
plot	Logical; should a magimage plot of the output be generated?
...	Dots are parsed to magimage.

Details

This function is on a level trivial, since it is easy to subset matrices and therefore images within R. However magcutout tracks important properties of the subset region that makes it easy to track its location with respect to the original matrix/image. Also, it allows direct plotting of the resultant cutout with the most appropriate image functions. In many cases these functions will be used purely for their plotting side effects.

The shiftloc and paddim control the behaviour of the function in the non-trivial case when the desired box size extendeds beyond the edge of the image. If shiftloc is FALSE (the default behaviour), the cutout is guaranteed to be centred on the pixel specified by loc. Then, if paddim is FALSE, the cutout extends only as far as possible until it reaches the edge of the image; otherwise if paddim is TRUE the cutout image is padded with NAs in regions outside the supplied image (the default behaviour). If shiftloc is TRUE, the centre of the cutout will be shifted. In this case, if paddim is FALSE, the cutout will extend at most half of the supplied box size from the given loc; otherwise if paddim is TRUE the cutout will be expanded until it reaches the desired box size or spans the entire image.

Note that if shiftloc is TRUE and paddim is FALSE, the cutout can be larger than box; otherwise, the cutout is guaranteed to be no larger than the specified box size.

Value

A list containing:

image	Numeric matrix; the cutout region of interst centred around loc.
loc	The new loc vector that tranforms the input loc x and y location to the new cutim coordinates. This is in ProFit coordinates, so these values can be used when, e.g., constructing a ProFit modellist structure.
loc.orig	The original location is provided by the input loc.
loc.diff	The x and y offsets of the cutout compared to the original image, where loc + loc.diff = loc.orig exactly.
xsel	Integer vector; the extracted x pixels from the original image that form cutim.
ysel	Integer vector; the extracted y pixels from the original image that form cutim.

Note

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 (see Examples).

It is ambiguous what the desired outcome is in some cutting scenarios, e.g. what should be returned if a 3x3 cutout is requested at the "centre" of a 8x8 image? For this reason, and to avoid unexpected results due to numerical precision, you should only cut out even pixel dimensions if integer pixel coordinates are provided, and odd pixel dimensions if half-integer pixel coordinates are provided. Regardless, the loc and loc.orig outputs will always help you locate the absolute coordinates of your desired cut out centre in both the cut out and the original image coordinate system.

Author(s)

Aaron Robotham & Dan Taranu

Examples

temp=matrix(1:121,11)

#The central value is at:

temp[6,6]

print(magcutout(temp, dim(temp)/2, box=c(3,3))$image)

#Given we cutout around the centre of the central pixel [5.5,5.5], the new centre
#relative to the cutout image output should be at [1.5,1.5]:

print(magcutout(temp, dim(temp)/2, box=c(3,3))$loc.orig)
print(magcutout(temp, dim(temp)/2, box=c(3,3))$loc)

asgr/magicaxis documentation built on Oct. 21, 2024, 7:40 p.m.