DC_READ_DIB Function (Windows)

Reads data from a Device Independent Bitmap (DIB) format file into a variable.

Usage

status = DC_READ_DIB(filename, imgarr)

Input Parameters

filename — (string) The pathname and filename of the DIB file.

Output Parameters

imgarr — The variable into which the DIB image data is read. May be an array of any dimension and type; imgarr’s data type is changed to byte and then imgarr is redimensioned using information in the DIB file.

Returned Value

status — The value returned by DC_READ_DIB; expected values are:

< 0 — Indicates an error, such as an invalid filename.
0 — Indicates a successful read.

Output Keywords

Colormap — Used to specify a variable in which to place the colormap stored with the DIB image. Colormap is returned as a 2D array of long integers.

ColorsUsed — Returns the number of colors used by the bitmap image (long).

Compression — Returns the compression style used in the DIB image. Valid values are:

0 — None (no compression)
1 — Run-length encoded format for bitmaps with 8 bits per pixel
2 — Run-length encoded format for bitmaps with 4 bits per pixel

ImageHeight — Returns the DIB image height (long).

ImageWidth — Returns the DIB image width (long).

ImportantColors — Returns the number of colors that are important for the image to be displayed as it was saved (long).

XResolution — Returns the number of pixels per meter in the x direction (long).

YResolution — Returns the number of pixels per meter in the y direction (long).

Discussion

Device Independent Bitmap (DIB) is a bitmap format that is useful for transporting graphics and color table information between different devices and applications in the Windows environment. DIB files can be produced by graphics applications such as Microsoft Image Editor, Microsoft Paintbrush, and PV‑WAVE.

DC_READ_DIB imports DIB images into variables. It handles:

Opening the file.
Assigning it a logical unit number (LUN).
Closing the file when you are finished reading the data.
Automatically redimensioning the input variable.

Note: To read the contents of a DIB file directly into a graphics window without the intermediate step of having the data placed in a variable, use the function WREAD_DIB.

Example

Assume that a file called ribbons.dib contains DIB data that was exported either from PV‑WAVE or from another application. To read this data directly into a variable ribbons, enter:

status = DC_READ_DIB(!Data_dir + '/ribbons.dib', ribbons, $
   ImageWidth=xsize, ImageHeight=ysize, Colormap=colors)

The dimensions of the image array are returned in the variables xsize and ysize. DIB image colormap is returned in the 2D array variable colors.