annotation_transparent_text {plothelper} | R Documentation |
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 |
alpha |
it is only used
when |
operator |
the argument used by
|
interpolate |
when |
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
|
place |
position adjustment used by
|
label_trim |
whether to trim |
bg_trim |
whether to 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 |
height |
the height of the
text rectangle. It will be passed
to |
res |
resolution in pixels which will be passed
to |
... |
arguments which will be passed to
|
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"
. Supposewidth = 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 ofbg
when the latter is a magick object.(5)
height = NULL
, the default. Now height is computed automatically. Ifbg
is a magick object, the width and height of the image will be used. Ifbg
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
# 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