Skip to contents

So called 'defines' are properties that are passed along to external filters and libraries. Usually defines are used in image_read or image_write to control the image encoder/decoder, but you can also set these manually on the image object.


image_set_defines(image, defines)



magick image object returned by image_read() or image_graph()


a named character vector with extra options to control reading. These are the -define key{=value} settings in the command line tool. Use an empty string for value-less defines, and NA to unset a define.


The defines values must be a character string, where the names contain the defines keys. Each name must be of the format "enc:key" where the first part is the encoder or filter to which the key is passed. For example "png:...." defines can control the encoding and decoding of png images.

The image_set_defines function does not make a copy of the image, so the defined values remain in the image object until they are overwritten or unset.


# Write an image
x <- image_read("")
image_write(x, "frink.png")

# Pass some properties to PNG encoder
defines <- c("png:compression-filter" = "1", "png:compression-level" = "0")
image_set_defines(x, defines)
image_write(x, "frink-uncompressed.png")

# Unset properties
defines[1:2] = NA
image_set_defines(x, defines)
image_write(x, "frink-final.png")

# Compare size and cleanup"frink.png", "frink-uncompressed.png", "frink-final.png"))
#>                          size isdir mode               mtime
#> frink.png               67162 FALSE  644 2024-03-21 12:22:25
#> frink-uncompressed.png 392531 FALSE  644 2024-03-21 12:22:25
#> frink-final.png         67162 FALSE  644 2024-03-21 12:22:25
#>                                      ctime               atime uid gid uname
#> frink.png              2024-03-21 12:22:25 2024-03-21 12:22:25   0   0  root
#> frink-uncompressed.png 2024-03-21 12:22:25 2024-03-21 12:22:25   0   0  root
#> frink-final.png        2024-03-21 12:22:25 2024-03-21 12:22:25   0   0  root
#>                        grname
#> frink.png                root
#> frink-uncompressed.png   root
#> frink-final.png          root
unlink(c("frink.png", "frink-uncompressed.png", "frink-final.png"))