From 048f96f0a2c7b9303533c361b03460d72300e965 Mon Sep 17 00:00:00 2001
From: Edzer Pebesma <edzer.pebesma@uni-muenster.de>
Date: Sat, 5 Nov 2022 19:12:03 +0100
Subject: [PATCH] add suggestions to prevent visual artefacts to docs

closes #573
---
 R/plot.R          | 2 ++
 R/tidyverse.R     | 2 ++
 man/geom_stars.Rd | 2 ++
 man/plot.Rd       | 2 ++
 4 files changed, 8 insertions(+)

diff --git a/R/plot.R b/R/plot.R
index 620888fbd..02e68011e 100644
--- a/R/plot.R
+++ b/R/plot.R
@@ -33,6 +33,8 @@ make_label = function(x, i = 1) {
 #' Downsampling: a value for \code{downsample} of 0: no downsampling, 1: after every dimension value (pixel/line/band), one value is skipped (half of the original resolution), 2: after every dimension value, 2 values are skipped (one third of the original resolution), etc.
 #'
 #' To remove unused classes in a categorical raster, use the \link[base]{droplevels} function.
+#'
+#' When bitmaps show visual artefacts (Moiré effects), make sure that device \link{png} is used rather than \code{ragg::agg_png} as the latter uses antialiasing for filled polygons which causes this; see also https://github.com/r-spatial/stars/issues/573 .
 #' @export
 plot.stars = function(x, y, ..., join_zlim = TRUE, main = make_label(x, 1), axes = FALSE,
 		downsample = TRUE, nbreaks = 11, breaks = "quantile", col = grey(1:(nbreaks-1)/nbreaks),
diff --git a/R/tidyverse.R b/R/tidyverse.R
index 4251ad3eb..9ad115671 100644
--- a/R/tidyverse.R
+++ b/R/tidyverse.R
@@ -258,6 +258,8 @@ replace_na.stars_proxy = function(data, ...) {
 #' @param sf logical; if \code{TRUE} rasters will be converted to polygons and plotted using \link[ggplot2:ggsf]{geom_sf}.
 #' @param na.action function; if \code{NA} values need to be removed before plotting use the value \code{na.omit} here (only applies to objects with raster dimensions)
 #' @details \code{geom_stars} returns (a call to) either \link[ggplot2:geom_tile]{geom_raster}, \link[ggplot2]{geom_tile}, or \link[ggplot2:ggsf]{geom_sf}, depending on the raster or vector geometry; for the first to, an \link[ggplot2]{aes} call is constructed with the raster dimension names and the first array as fill variable. Further calls to \link[ggplot2:coord_fixed]{coord_equal} and \link[ggplot2]{facet_wrap} are needed to control aspect ratio and the layers to be plotted; see examples. If a \code{stars} array contains hex color values, and no \code{fill} parameter is given, the color values are used as fill color; see the example below.
+#' 
+#' If visual artefacts occur (Moiré-Effekt), then see the details section of \link{plot.stars}
 #' @export
 #' @examples
 #' system.file("tif/L7_ETMs.tif", package = "stars") %>% read_stars() -> x
diff --git a/man/geom_stars.Rd b/man/geom_stars.Rd
index 707a8699e..ea4c45693 100644
--- a/man/geom_stars.Rd
+++ b/man/geom_stars.Rd
@@ -34,6 +34,8 @@ ggplot geom for stars objects
 }
 \details{
 \code{geom_stars} returns (a call to) either \link[ggplot2:geom_tile]{geom_raster}, \link[ggplot2]{geom_tile}, or \link[ggplot2:ggsf]{geom_sf}, depending on the raster or vector geometry; for the first to, an \link[ggplot2]{aes} call is constructed with the raster dimension names and the first array as fill variable. Further calls to \link[ggplot2:coord_fixed]{coord_equal} and \link[ggplot2]{facet_wrap} are needed to control aspect ratio and the layers to be plotted; see examples. If a \code{stars} array contains hex color values, and no \code{fill} parameter is given, the color values are used as fill color; see the example below.
+
+If visual artefacts occur (Moiré-Effekt), then see the details section of \link{plot.stars}
 }
 \examples{
 system.file("tif/L7_ETMs.tif", package = "stars") \%>\% read_stars() -> x
diff --git a/man/plot.Rd b/man/plot.Rd
index 38b89143c..fd4054567 100644
--- a/man/plot.Rd
+++ b/man/plot.Rd
@@ -143,6 +143,8 @@ Downsampling: a value for \code{downsample} of 0: no downsampling, 1: after ever
 
 To remove unused classes in a categorical raster, use the \link[base]{droplevels} function.
 
+When bitmaps show visual artefacts (Moiré effects), make sure that device \link{png} is used rather than \code{ragg::agg_png} as the latter uses antialiasing for filled polygons which causes this; see also https://github.com/r-spatial/stars/issues/573 .
+
 use of an rgb color table is experimental; see https://github.com/r-spatial/mapview/issues/208
 
 when plotting a subsetted \code{stars_proxy} object, the default value for argument \code{downsample} will not be computed correctly, and has to be set manually.