plothelper (version 0.1.9)

annotation_transparent_text: Layer for Transparent Text

Description

Suppose there is a colored rectangle with some texts and you want the texts to be transparent so that the colors of the background can be seen. Now you can use this function. The function can be used as a ggplot layer or a generator of image. NOTE: when the function is used as a layer, it uses ggplot2::annotation_raster to do the drawing, so you must set limits for the x axis and the y axis. See examples.

Usage

annotation_transparent_text(
  label,
  xmin,
  xmax,
  ymin,
  ymax,
  bg = "black",
  alpha = 0.5,
  operator = "out",
  interpolate = TRUE,
  result_interpolate = TRUE,
  expand = c(0.05, 0.05),
  family = "SimHei",
  fontface = 1,
  reflow = FALSE,
  place = "center",
  label_trim = NULL,
  bg_trim = NULL,
  result = c("layer", "magick"),
  width = 800,
  height = NULL,
  res = 72,
  ...
)

Arguments

label

the text.

xmin

the left side of the rectangle.

xmax

the right side of the rectangle.

ymin

the bottom side of the rectangle.

ymax

the top side of the rectangle.

bg

the colors of the rectangle. It can be a character vector of colors, a matrix of colors, an object of raster class or even a image read into R through magick::image_read. Default is color black.

alpha

it is only used when bg is a character vector. Default is 0.5.

operator

the argument used by magick::image_composite. It should be "out" (default) or "in". The former makes the texts transparent, the latter creates shading texts.

interpolate

when bg is a matrix, a image or a raster, this parameter is used and will be passed to ggplot2::annotation_raster to draw a colored rectangle. Default is TRUE.

result_interpolate

whether to use interpolate in the final result. Default is TRUE.

expand

sometimes it is needed to slightly expand the x position and y position to put the text so that they can be shown nicely. It should be two values used by x and y respectively. Default is 0.05 and 0.05.

family

family of text. Default is SimHei which ensures that Chinese texts can be shown. However, you can change it to others, e. g., sans, serif, mono.

fontface

fontface.

reflow

whether to change lines automatically. It will be passed to ggfittext::geom_fit_text. Default is FALSE.

place

position adjustment used by ggfittext:;geom_fit_text. The value is one of "center", "middle" (= "center"), "topleft", "top", "topright", "right", "bottomright", "bottom", "bottomleft", "left".

label_trim

whether to trim label. The default is NULL which means no trimming. But if you want to remove all edges around label, you should give label_trim a value which will be passed to magick::image_trim. However, most of the time you do not need this parameter.

bg_trim

whether to trim bg. Most of the time we do want to trim it. However, the magick::image_trim function sometimes trims wrongly. So you can turn it off. NOTE: the default value of bg_trim is NULL, which means DO NOT TRIM.

result

when it is "layer", the function can be used as a ggplot layer. When it is "magick", the result is only an image which is created by the magick package.

width

the width of the text rectangle. It will be passed to magick::image_graph. Most of the time you do not need to modify this. Default is 800.

height

the height of the text rectangle. It will be passed to magick::image_graph. Default is NULL, which means it will be computed automatically. DO SEE Details below to learn how to handle this parameter.

res

resolution in pixels which will be passed to magick::image_graph. Default is 72.

...

arguments which will be passed to ggfittex::geom_fit_text. Most often used are angle (0 to 360), lineheight.

Details

height can be used in the following ways:

• (1) an integer which will be directly passed to magick::image_graph.

• (2) a character-like integer, e.g., height = "0.5". Suppose width = 400, the height that will be used is 400*0.5 = 200. This effectively prevents the image from becoming too large.

• (3) height = "coord_fixed". the ratio between height and width will be (ymax-ymin)/(xmax-xmin).

• (4) height = "image". the width and height will be the width and height of bg when the latter is a magick object.

• (5) height = NULL, the default. Now height is computed automatically. If bg is a magick object, the width and height of the image will be used. If bg is not a magick object, a ratio is computed first, ratio = (ymax-ymin)/(xmax-xmin). if the ratio is larger than 5 or smaller than 0.2, then height will be width*5 or width*0.2; else, the height will be treated in the same way as in (3) above. All these works are needed to prevent the image from becoming too large.

Examples

# NOT RUN {
# Example 1
m=matrix(rainbow(7), nrow=1)
ggplot()+coord_fixed()+
	xlim(0, 7)+ylim(-2, 4)+theme_void()+
	annotation_raster(
		raster=m, 
		xmin=0, ymin=-3, 
		xmax=7, ymax=5, 
		interpolate=TRUE
	)+
	annotation_transparent_text(
		label="R\nDATA\nVISUALIZATION", 
		xmin=0, xmax=7, 
		ymin=-1, ymax=3, 
		family="sans", fontface=2, alpha=0.8, 
		place="left", expand=c(0.08, 0.02)
	)
# 
# Example 2, this time the result is only an image.
tt=annotation_transparent_text(
	label="abcdefg", 
	xmin=1, xmax=8, 
	ymin=1, ymax=4, 
	alpha=0.6, 
	result="magick"
)
#
# Example 3, the rectangle is a matrix.
m=colorRampPalette(c("yellow", "purple"))(10)
ggplot()+coord_fixed(expand=FALSE)+
	theme(panel.background=element_rect(fill="red"))+
	annotation_transparent_text(
		label="hehehaha", 
		xmin=1, xmax=8, 
		ymin=1, ymax=4, 
		bg=m, alpha=1
	)
#
# Example 4, height is too large.
# Now you should explicitly set 
# width and height, otherwise, the 
# characters will become too flat.
x=c(0, 5, 10)
y=c(0, 500, 1000)
ggplot()+ylim(0, 4000)+
	geom_point(aes(x, y))+
	annotation_transparent_text(label="ha ha\nhe he", 
		xmin=0, xmax=10, ymin=1000, ymax=4000, bg="black", 
		width=300, height=150
	) # do not set height=NULL here
# }