Set encoder defines

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)

Arguments

image

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

defines

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.

Details

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.

See also

Other image: _index_, analysis, animation, attributes(), color, composite, device, edges, editing, effects(), fx, geometry, morphology, ocr, options(), painting, segmentation, transform(), video

Examples

# Write an image
x <- image_read("https://jeroen.github.io/images/frink.png")
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
file.info(c("frink.png", "frink-uncompressed.png", "frink-final.png"))
#>                          size isdir mode               mtime
#> frink.png               67162 FALSE  644 2025-05-13 19:44:19
#> frink-uncompressed.png 392531 FALSE  644 2025-05-13 19:44:20
#> frink-final.png         67162 FALSE  644 2025-05-13 19:44:20
#>                                      ctime               atime       uid
#> frink.png              2025-05-13 19:44:19 2025-05-13 19:44:19 707801213
#> frink-uncompressed.png 2025-05-13 19:44:20 2025-05-13 19:44:20 707801213
#> frink-final.png        2025-05-13 19:44:20 2025-05-13 19:44:20 707801213
#>                              gid      uname      grname
#> frink.png              707801639 elizabethb datascience
#> frink-uncompressed.png 707801639 elizabethb datascience
#> frink-final.png        707801639 elizabethb datascience
unlink(c("frink.png", "frink-uncompressed.png", "frink-final.png"))