plotPatchesRGB {spacesRGB}

Plot Patches defined by RGB

Description

RGB patches are a very common way of comparing color renderings. This function draws rectangular patches, and can also draw triangles formed by omitting one vertex from the rectangle.

Usage

plotPatchesRGB( obj, space='sRGB', which='signal', maxColorValue=1,
                     background='gray50', shape='full', add=FALSE, labels=FALSE, ... )

Arguments

obj

an Nx3 matrix of RGBs for N patches, preferably with assigned rownames. obj can also be a data.frame containing a unique matrix column whose name starts with the string 'RGB'. If obj has columns LEFT,TOP,WIDTH,HEIGHT then these are used to place the patches, with the Y coordinate increasing going down the page. If obj has columns LEFT,BOTTOM,WIDTH,HEIGHT then these are used to place the patches, with the Y coordinate increasing going up the page. If there are no columns defining the location and size of the patches, then defaults are supplied, see Details.

space

the name of an installed RGB space. When the input RGB is linear, a transfer function of this RGB space is used to convert linear RGB to signal RGB, see Details.

which

the meaning of the RGB values in obj. Valid values are 'signal', 'scene', and 'display'. See the Figure on page 2. Partial matching is used. For the RGB processing, see Details.

maxColorValue

a positive number used for input RGB scaling, see Details

background

the color for the background behind all the patches. If it is a character string, it is passed directly to par() as parameter bg. If it is a numeric vector of length 3, it is processed just like the input RGB in obj, see Details. If it is a number, it is interpreted as graylevel, replicated to length 3, and treated as in the previous sentence.

shape

If shape='full' (the default) then the full rectangle is drawn.
If shape='half' then the rectangle is shrunk to 1/2 size, and with the same center.
If shape is one of 'left', 'right', 'bottom', or 'top' then only a half-rectangle is drawn, and keeping the specified side.
If shape is one of 'topleft', 'topright', 'bottomleft', or 'bottomright', then only a triangular half of the rectangle is drawn, and keeping the specified vertex.
If shape='hhex' then a hexagon is drawn inscribed in the rectangle with 2 horizontal opposite sides (in contact with the rectangle sides). And if the aspect ratio of the rectangle is 2:\sqrt{3} the hexagon is regular. If shape='vhex' then the inscribed rectangle has 2 vertical opposite sides.

add

if TRUE then the patches are added to an existing plot

labels

controls how the patches are labeled, using rownames(obj), or 1:N if rownames(obj) is NULL. The function used is graphics::text(). If labels=FALSE then no labels are plotted. If labels=TRUE then labels are plotted in the center of the patch when there are columns defining the location and size of the patches, and to the right of the patch otherwise.
labels can also be a character string defining the location where the labels are drawn. It can be the side of the patches, i.e. left, right, top, or bottom, or the corner of the patches, i.e. bottomleft, bottomright, topleft, or topright.

...

additional arguments passed to graphics::text(). For example: adj, cex, etc.

Details

If which='signal' then the input RGBs are converted to hex codes using rgb() using the maxColorValue argument, and the space argument is ignored.
If which='scene' or which='display' then the input linear RGBs are normalized by division by maxColorValue, and then converted to signal RGB using SignalRGBfromLinearRGB() with the space argument. The signal RGB is then converted to hex codes using rgb().

If obj is a matrix, or a data.frame without columns LEFT,TOP,WIDTH,HEIGHT, then the patches are drawn vertically stacked and abutting from top to bottom.

Value

TRUE if successful, and FALSE otherwise

See Also

SignalRGBfromLinearRGB(), installRGB(), rgb()

Examples

set.seed(0)
RGB = round( 255 * matrix( runif(6*3), 6, 3 ) )
plotPatchesRGB( RGB, max=255 )