READ_PNG

The READ_PNG routine reads the image contents of a Portable Network Graphics (PNG) file and returns the image in an IDL variable. If the image contains a palette (see QUERY_PNG), it can be returned in three IDL variables. READ_PNG supports 1, 2, 3 and 4 channel images with channel depths of 8 or 16 bits.

When an image is read, it is scaled to the sBit value, if it is provided in the file. The sBit provides the actual bit depth, which can be different from the "bit depth" byte. See www.w3.org/TR/PNG-Chunks.html for more information.

Note: IDL supports version 1.2.7 of the PNG Library.

Note: Only single channel 8-bit images may have palettes. If an 8-bit, single-channel image has index values marked as “transparent,” these can be retrieved as well.

Note: To find information about a potential PNG file before trying to read its data, use the QUERY_PNG function.

Examples

Create an RGBA (16-bits/channel) and a Color Indexed (8-bit/channel) image with a palette:

PRO ex_read_png
rgbdata = UINDGEN(4,320,240)
cidata = BYTSCL(DIST(256))
red = indgen(256)
green = indgen(256)
blue = indgen(256)
WRITE_PNG,'rgb_image.png',rgbdata
WRITE_PNG,'ci_image.png',cidata,red,green,blue
;Query and read the data
names = ['rgb_image.png','ci_image.png','unknown.png']
FOR i=0,N_ELEMENTS(names)-1 DO BEGIN
   ok = QUERY_PNG(names[i],s)
   IF (ok) THEN BEGIN
      HELP,s,/STRUCTURE
      IF (s.HAS_PALETTE) THEN BEGIN
         img = READ_PNG(names[i],rpal,gpal,bpal)
         HELP,img,rpal,gpal,bpal
      ENDIF ELSE BEGIN
         img = READ_PNG(names[i])
         HELP,img
      ENDELSE
   ENDIF ELSE BEGIN
      PRINT,names[i],' is not a PNG file'
   ENDELSE
ENDFOR
END

Syntax

Result = READ_PNG ( Filename [, R, G, B] [,/ORDER] [, /VERBOSE] [, TRANSPARENT=variable] )

READ_PNG, Filename, Image [, R, G, B] [,/ORDER] [, /VERBOSE] [, TRANSPARENT=variable]

Return Value

For 8-bit images, Result will be a two- or three-dimensional array of type byte. For 16-bit images, Result will be of type unsigned integer (UINT).

Arguments

Filename

A scalar string containing the full pathname of the PNG file to read.

Image

A named variable in which the image array will be stored, if READ_PNG is called as a procedure. For 8-bit images, Image will be a two- or three-dimensional array of type byte. For 16-bit images, Image will be of type unsigned integer (UINT).

R, G, B

Named variables that will contain the Red, Green, and Blue color vectors if a color table exists.

Keywords

ORDER

Set this keyword to indicate that the rows of the image should be read from bottom to top. The rows are read from top to bottom by default. ORDER provides compatibility with PNG files written using versions of IDL prior to IDL 5.4, which wrote PNG files from bottom to top.

VERBOSE

Set this keyword to produce additional diagnostic output during the read operation.

TRANSPARENT

Set this keyword to a named variable in which to return an array of opacity values (an opacity table) in the range of 0 to 255. A value of 0 (zero) equals full transparency (no opacity). If you specify fewer opacity values than exist in the color table, the missing values are replaced by 255. If the file does not contain an opacity table, then a scalar 0 is returned.

This keyword is valid only if Image is a single-channel (color indexed) image and the R, G, B palette is provided.

Version History

5.2	Introduced