Write a bitmap image in PNG format

Create a PNG image from an array or matrix.

writePNG(image, target = raw(), dpi = NULL, asp = NULL,
         text = NULL, metadata = NULL)

Arguments

image: image represented by a real matrix or array with values in the range of 0 to 1. Values outside this range will be clipped. The object must be either two-dimensional (grayscale matrix) or three dimensional array (third dimension specifying the plane) and must have either one (grayscale), two (grayscale + alpha), three (RGB) or four (RGB + alpha) planes. (For alternative image specifications see details)
target: Either name of the file to write, a binary connection or a raw vector (raw() - the default - is good enough) indicating that the output should be a raw vector.
dpi: optional, if set, must be a numeric vector of length 1 or 2 specifying the resolution of the image in DPI (dots per inch) for x and y (in that order) - it is recycled to length 2.
asp: optional, if set, must be a numeric scalar specifying the aspect ratio (x / y). dpi and asp are mutually exclusive, speciyfing both is an error.
text: optional, named character vector of entries that will be saved in the text chunk of the PNG. Names are used as keys. Note that the "R.metadata" key is reserved for internal use - see below
metadata: optional, an R object that will be serialized into the "R.metadata" text key

Value

Either NULL if the target is a file or a raw vector containing the compressed PNG image if the target was a raw vector.

Details

writePNG takes an image as input and compresses it into PNG format. The image input is usually a matrix (for grayscale images - dimensions are width, height) or an array (for color and alpha images - dimensions are width, height, planes) of reals. The planes are interpreted in the sequence red, green, blue, alpha.

Alternative representation of an image is of nativeRaster class which is an integer matrix with each entry representing one pixel in binary encoded RGBA format (as used internally by R). It can be obtained from readPNG using native = TRUE.

Finally, writePNG also supports raw array containing the RGBA image as bytes. The dimensions of the raw array have to be planes, width, height (because the storage is interleaved). Currently only 4 planes (RGBA) are supported and the processing is equivalent to that of a native raster.

The result is either stored in a file (if target is a file name), in a raw vector (if target is a raw vector) or sent to a binary connection.

If either dpi or asp is set, the sPHy chunk is generated based on that information. Note that not all image viewers interpret this setting, and even fewer support non-square pixels.

Author

Simon Urbanek

Note

Currently writePNG only produces 8-bit, deflate-compressed, non-quantized, non-interlaced images. Note in particular that readPNG can read 16-bit channels but storing them back using writePNG will strip the 8 LSB (irrelevant for display purposes but possibly relevant for use of PNG in signal-processing if the input is truly 16-bit wide).

Examples

# read a sample file (R logo)
img <- readPNG(system.file("img","Rlogo.png",package="png"))
# write the image into a raw vector
r <- writePNG(img)
# read it back again
img2 <- readPNG(r)
# it better be the same
identical(img, img2)
#> [1] TRUE
# try to write a native raster
img3 <- readPNG(system.file("img","Rlogo.png",package="png"), TRUE)
r2 <- writePNG(img3)
img4 <- readPNG(r2, TRUE)
identical(img3, img4)
#> [1] TRUE

## text and metadata
r <- writePNG(img, text=c(source=R.version.string),
     metadata=sessionInfo())
img5 <- readPNG(r, info=TRUE)
attr(img5, "info")
#> $dim
#> [1] 100  76
#> 
#> $bit.depth
#> [1] 8
#> 
#> $color.type
#> [1] "RGBA"
#> 
#> $text
#>                                               source 
#> "R Under development (unstable) (2022-11-28 r83388)" 
#> 
attr(img5, "metadata")
#> R Under development (unstable) (2022-11-28 r83388)
#> Platform: x86_64-pc-linux-gnu (64-bit)
#> Running under: Debian GNU/Linux 11 (bullseye)
#> 
#> Matrix products: default
#> BLAS:   /www/rforge/sys/debian-11/usr/R/4.3/lib/libRblas.so
#> LAPACK: /www/rforge/sys/debian-11/usr/R/4.3/lib/libRlapack.so
#> 
#> locale:
#>  [1] LC_CTYPE=C.UTF-8       LC_NUMERIC=C           LC_TIME=C.UTF-8       
#>  [4] LC_COLLATE=C           LC_MONETARY=C.UTF-8    LC_MESSAGES=C.UTF-8   
#>  [7] LC_PAPER=C.UTF-8       LC_NAME=C              LC_ADDRESS=C          
#> [10] LC_TELEPHONE=C         LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C   
#> 
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] png_0.1-8
#> 
#> loaded via a namespace (and not attached):
#>  [1] vctrs_0.5.1       httr_1.4.4        cli_3.4.1         knitr_1.41       
#>  [5] rlang_1.0.6       xfun_0.35         purrr_0.3.5       textshaping_0.3.6
#>  [9] glue_1.6.2        rprojroot_2.0.3   htmltools_0.5.3   ragg_1.2.4       
#> [13] fansi_1.0.3       rmarkdown_2.18    evaluate_0.18     tibble_3.1.8     
#> [17] fastmap_1.1.0     yaml_2.3.6        lifecycle_1.0.3   memoise_2.0.1    
#> [21] whisker_0.4       compiler_4.3.0    fs_1.5.2          downlit_0.4.2    
#> [25] pkgconfig_2.0.3   rstudioapi_0.14   systemfonts_1.0.4 digest_0.6.30    
#> [29] R6_2.5.1          utf8_1.2.2        curl_4.3.3        pillar_1.8.1     
#> [33] magrittr_2.0.3    tools_4.3.0       withr_2.5.0       xml2_1.3.3       
#> [37] pkgdown_2.0.6     cachem_1.0.6      desc_1.4.2