Simplify annotation rasterization and document new arguments

Remove the unreachable small-viewport fallback, the redundant size
rounding, the duplicated magick availability check, and the unused
ht_opt$annotation_use_raster global option.

Add roxygen documentation for the six new raster arguments on
HeatmapAnnotation() and SingleAnnotation(), and a test covering
raster parameter propagation and size stability across raster_quality.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: brandonlukas

R/HeatmapAnnotation-class.R

@@ -71,6 +71,14 @@ HeatmapAnnotation = setClass("HeatmapAnnotation",
 # -width Width of the whole heatmap annotations.
 # -simple_anno_size Size of the simple annotation.
 # -simple_anno_size_adjust Whether also adjust the size of simple annotations when adjusting the whole heatmap annotation.
+# -use_raster Whether render the annotations as raster images. It helps to reduce file size when there are a huge number
+#      of columns (or rows for row annotations). The value is passed to all single annotations.
+# -raster_device Graphic device which is used to generate the raster image.
+# -raster_quality A value larger than 1.
+# -raster_device_param A list of further parameters for the selected graphic device.
+# -raster_by_magick Whether to use `magick::image_resize` to scale the image.
+# -raster_magick_filter Pass to ``filter`` argument of `magick::image_resize`. A character scalar and all possible values
+#      are in `magick::filter_types`. The default is ``"Lanczos"``.
 #
 # == details
 # For arguments ``show_legend``, ``border``, ``annotation_name_offset``, ``annotation_name_side``, ``annotation_name_rot``,
@@ -143,10 +151,6 @@ HeatmapAnnotation = function(...,
 
 	fun_args = names(as.list(environment()))
 
-	if(missing(use_raster) && !is.null(ht_opt$annotation_use_raster)) {
-		use_raster = ht_opt$annotation_use_raster
-	}
-
 	verbose = ht_opt$verbose
 
 	.Object = new("HeatmapAnnotation")
@@ -337,10 +341,10 @@ HeatmapAnnotation = function(...,
 		i_anno = i_anno + 1
 		arg_list = list(name = ag, which = which,
 				label = annotation_label[[i_anno]],
-				show_name = show_annotation_name[[i_anno]],
-				name_gp = subset_gp(annotation_name_gp, i_anno),
-	        	name_offset = annotation_name_offset[[i_anno]],
-	        	name_side = annotation_name_side[i_anno],
+				show_name = show_annotation_name[[i_anno]], 
+				name_gp = subset_gp(annotation_name_gp, i_anno), 
+	        	name_offset = annotation_name_offset[[i_anno]], 
+	        	name_side = annotation_name_side[i_anno], 
 	        	name_rot = annotation_name_rot[[i_anno]],
 	        	border = border[i_anno],
 	        	use_raster = use_raster,

R/SingleAnnotation-class.R

@@ -82,6 +82,14 @@ SingleAnnotation = setClass("SingleAnnotation",
 #        the width must be an absolute unit.
 # -height The height of the plotting region (the viewport) that the annotation is drawn. If it is a column annotation,
 #        the width must be an absolute unit.
+# -use_raster Whether render the annotation as a raster image. It helps to reduce file size when there are a
+#      huge number of columns (or rows for a row annotation).
+# -raster_device Graphic device which is used to generate the raster image.
+# -raster_quality A value larger than 1.
+# -raster_device_param A list of further parameters for the selected graphic device.
+# -raster_by_magick Whether to use `magick::image_resize` to scale the image.
+# -raster_magick_filter Pass to ``filter`` argument of `magick::image_resize`. A character scalar and all possible values
+#      are in `magick::filter_types`. The default is ``"Lanczos"``.
 #
 # == details
 # A single annotation is a basic unit of complex heatmap annotations where the heamtap annotations
@@ -591,11 +599,7 @@ SingleAnnotation = function(name, value, col, fun,
     }
 
     if(is.null(raster_device)) {
-        if(requireNamespace("Cairo", quietly = TRUE)) {
-            raster_device = "CairoPNG"
-        } else {
-            raster_device = "png"
-        }
+        raster_device = if(requireNamespace("Cairo", quietly = TRUE)) "CairoPNG" else "png"
     }
     .Object@raster_param = list(
         use_raster = use_raster,
@@ -690,9 +694,8 @@ setMethod(f = "draw",
         xscale = data_scale$x, yscale = data_scale$y))
 
     if(verbose) qqcat("execute annotation function\n")
-    use_raster = isTRUE(object@raster_param$use_raster)
-    if(use_raster) {
-        rp = object@raster_param
+    rp = object@raster_param
+    if(isTRUE(rp$use_raster)) {
         rasterize_in_viewport(
             draw_fun = function() draw(object@fun, index = index, k = k, n = n),
             raster_device = rp$raster_device,

R/global.R

@@ -209,11 +209,6 @@ ht_opt = setGlobalOptions(
 		.value = FALSE
 	),
 	"validate_names" = TRUE,
-	annotation_use_raster = list(
-		.value = NULL,
-		.class = "logical",
-		.length = 1
-	),
 	raster_temp_image_max_width = 30000,
 	raster_temp_image_max_height = 30000,
 	COLOR = c("blue", "#EEEEEE", "red")

R/utils.R

@@ -1152,12 +1152,6 @@ rasterize_in_viewport = function(draw_fun,
     vp_width_pt = ceiling(vp_width_pt * raster_quality)
     vp_height_pt = ceiling(vp_height_pt * raster_quality)
 
-    # if viewport is too small, fall back to vector
-    if(vp_width_pt < 1 || vp_height_pt < 1) {
-        draw_fun()
-        return(invisible(NULL))
-    }
-
     device_info = switch(raster_device,
         png = c("grDevices", "png", "readPNG"),
         jpeg = c("grDevices", "jpeg", "readJPEG"),
@@ -1183,8 +1177,8 @@ rasterize_in_viewport = function(draw_fun,
         }
     }
 
-    temp_image_width = as.integer(ceiling(max(vp_width_pt, 1)))
-    temp_image_height = as.integer(ceiling(max(vp_height_pt, 1)))
+    temp_image_width = as.integer(vp_width_pt)
+    temp_image_height = as.integer(vp_height_pt)
 
     if(!is.na(ht_opt$raster_temp_image_max_width)) {
         temp_image_width = min(temp_image_width, ht_opt$raster_temp_image_max_width)
@@ -1193,8 +1187,7 @@ rasterize_in_viewport = function(draw_fun,
         temp_image_height = min(temp_image_height, ht_opt$raster_temp_image_max_height)
     }
 
-    temp_dir = tempdir()
-    temp_image = tempfile(pattern = ".annotation_raster_", tmpdir = temp_dir,
+    temp_image = tempfile(pattern = ".annotation_raster_", tmpdir = tempdir(),
         fileext = paste0(".", device_info[2]))
     device_fun = getFromNamespace(raster_device, ns = device_info[1])
 
@@ -1216,9 +1209,6 @@ rasterize_in_viewport = function(draw_fun,
     dev.off2()
 
     if(raster_by_magick) {
-        if(!requireNamespace("magick", quietly = TRUE)) {
-            stop_wrap("'magick' package should be installed.")
-        }
         image = magick::image_read(temp_image)
         image = magick::image_resize(image,
             paste0(vp_width_pt, "x", vp_height_pt, "!"),

tests/testthat/testthat-annotation-raster.R

@@ -0,0 +1,40 @@
+
+context("Test annotation rasterization")
+
+test_that("raster parameters are passed down to single annotations", {
+	ha = HeatmapAnnotation(foo = 1:10, use_raster = TRUE, raster_quality = 3)
+	rp = ha@anno_list[["foo"]]@raster_param
+	expect_true(rp$use_raster)
+	expect_equal(rp$raster_quality, 3)
+
+	ha = HeatmapAnnotation(foo = 1:10)
+	expect_false(ha@anno_list[["foo"]]@raster_param$use_raster)
+})
+
+# the graphics drawn by `draw_fun` are in absolute units, so the rasterized
+# result must occupy the same area no matter how large the temporary image is
+test_that("rasterized annotation does not shrink when raster_quality increases", {
+	skip_if_not_installed("png")
+
+	filled_fraction = function(quality) {
+		f = tempfile(fileext = ".png")
+		png(f, width = 200, height = 200)
+		pushViewport(viewport(width = unit(1, "npc"), height = unit(1, "npc")))
+		rasterize_in_viewport(
+			function() grid.rect(width = unit(10, "mm"), height = unit(10, "mm"),
+				gp = gpar(fill = "red", col = NA)),
+			raster_device = "png", raster_quality = quality)
+		popViewport()
+		dev.off()
+
+		img = png::readPNG(f)
+		file.remove(f)
+		mean(img[, , 1] > 0.5 & img[, , 2] < 0.5)
+	}
+
+	q1 = filled_fraction(1)
+	q3 = filled_fraction(3)
+
+	expect_gt(q1, 0.01)
+	expect_lt(abs(q1 - q3)/q1, 0.1)
+})