getROI: Get Region of Interest

In ornelles/EBImageExtra: Helper Functions for EBImage

Get Region of Interest

Description

Get a rectangular region of interest from an image.

Usage

getROI(
  img,
  x,
  y,
  x2,
  y2,
  w,
  h,
  show,
  asCorner = FALSE,
  which.corner = c("bottomleft", "topleft", "bottomright", "topright"),
  pch = 3,
  col = "magenta",
  border = col,
  lwd = 2
)

Arguments

img	An Image object
x, y	x,y coordinates of one or both corners of rectangular selection or the center of the rectangular selection or a list of corners of the selection or an object of class "Roi" with the @loc slot containing the desired coordinates (see details in Selecting the ROI below)
x2, y2	optional second pair of x and y coordinates when needed to specify the other corner of the rectangular selection
w, h	optional width and height of the rectangular selection in pixels; required if x2,y2 are missing
show	logical value to redraw the image the selection outlined by drawROI; if missing or NULL show will set to TRUE if the user interacts with the image and FALSE if no interaction is required
asCorner	logical value to use the point x,y as the corner of the selection or as the center of the selection
which.corner	identifies the corner of the rectangle specified by x,y; applies only if asCorner = TRUE
pch	plotting character used by link{locator} to indicate mouse clicks, the default value of 3 shows a small cross
col	color for plotting character used by link{locator}; use NA for no plotting character
border	border color of rectangle if show = TRUE; if not specified, the value for col is used
lwd	line width of rectangle if show = TRUE

Value

The region of interest as an Image with the added class of "Roi" and the slot "loc" holding the location of the region of interest.

Selecting the ROI

A rectangular region of interest (ROI) can be selected programmatically or interactively. The ROI is defined by a pair of points (in pixels) that define a diagonal of the region of interest. The pair of points can be specified by several means. If x is a previously defined ROI, the coordinates of this ROI will be used to get the ROI. Otherwise, the function expected four values for specifying the corner of the ROI as x,y, and x2,y2 or a list of the two points. Without these arguments, the function invokes locator to allow the user to define the ROI. The ROI will be trimmed to the dimensions allowed by the original image. The rectangle can be specified either by the center or corner(s) as describe below. The first four options require no interaction with the user and only produce an image if show = TRUE. Options 5 and 6 below require interaction with the user and produce an image if show is missing or if show = TRUE. The returned object is an Image with an additional class and slot as described in the below.

1. Roi. If x is an object of class = "Roi", the corners of the selection will be the value in the @loc slot.

2. List. If x is a list of length 2, it is assumed to hold opposite corners of the rectangular selection. This is the typical result of a call to locator(2) after having plotted the image.

3. Two Points. If values are provided for each of x,y and x2,y2, these are treated as opposite corners of the rectangular selection.

4. One Point (with width and height). A single value can be provided for each of x,y with named values for for w,h as the width and height of the rectangular selection. The point x,y is interpreted as either the center (asCorner = FALSE) or the corner of the selection (asCorner = TRUE). If asCorner = TRUE, the position of the corner is determined by the argument which.corner which can be one of "bottomleft", "topleft", "topright", or "bottomright".

5. Only width and height. If only (w,h) are provided as named arguments, locator will be used to interact with the user to identify the point needed to define the rectangular selection. The selected point is interpreted as either the center (asCorner = FALSE) or the corner of the selection (asCorner = TRUE) as described above.

6. No Points (choose opposite corners). If all of x,y, x2,y2, w,h are missing, locator will be called to let the user to select two points that define opposite corners of the rectangular selection.

Class "Roi" and "loc" slot

EBImage uses the Image class to store and process images. A region of interest is an Image object with the additional class named "Roi" and an additional attribute using the slot property of S4 objects. The new slot or attribute named "loc" holds the location of the region of interest as loc = list(x = c(x,x2), y = c(y,y2)). The attribute "loc" can be used to extract the equivalent region of interest from a related image (img2) in the following manner.

 x <- getROI(img1)
 pp <- attr(x, "loc") ## or pp <- x@loc
 y <- getROI(img2, pp)

See Also

putROI to place an ROI with scaling and drawROI to draw a frame within an image.

Examples

# Image from EBImage package
  birds <- readImage(system.file("images", "sample-color.png", package="EBImage"))

# Example specifying one point for center with fixed width and height
  roi1 <- getROI(birds, 160, 255, w = 200, h = 240)
  print(roi1@loc) # one way extract 'loc'
  roi2 <- getROI(birds, 480, 200, w = 200, h = 240)
  print(attr(roi2, "loc")) # an alternative way to extract 'loc'

# Show insets as a combined image
  plotStack(combine(roi1, roi2))

ornelles/EBImageExtra documentation built on Aug. 10, 2022, 11:44 p.m.