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.

Usage

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 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"))