DC_READ_24_BIT Function

Reads a 24-bit image file.

Usage

status = DC_READ_24_BIT(filename, imgarr)

Input Parameters

filename — A string containing the pathname and filename of the 24-bit image file.

Output Parameters

imgarr — The byte array into which the 24-bit image data is read. Must be a 3-dimensional byte array. Either the first or last dimension of the array is 3; see the Discussion section for more details.

Returned Value

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

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

Keywords

Org — Organization (in the file) of the 24-bit image data. Allowed values are:

0 — Pixel interleaving (RGB triplets).
1 — Image interleaving (separate planes).
If not provided, 0 (pixel interleaving) is assumed.

XSize — The width (size in the x-direction) of imgarr. The width is computed and returned in XSize if imgarr is not explicitly dimensioned. XSize is returned as an integer.

YSize — The height (size in the y-direction) of imgarr. The height is computed and returned in YSize if imgarr is not explicitly dimensioned. YSize is returned as an integer.

Discussion

DC_READ_24_BIT handles many steps that you have to do yourself when using other PV‑WAVE functions and procedures. These steps include:

Opening the file.
Assigning it a logical unit number (LUN).
Closing the file when you are done reading the data.

When choosing the value for the Org keyword, be sure to select an organization that matches the file, even if it is the opposite of that used in the variable. In other words, if the data in the file is pixel interleaved, specify Org=0, and if the data is image interleaved, specify Org=1.

The way the data is read into the variable depends primarily on the dimensions that the variable was given when it was created. Consequently, an image interleaved file can be read into a pixel interleaved variable, and vice versa. So, if you want the data in the variable organized differently than it was organized in the file, pre-dimension the import variable before calling DC_READ_24_BIT. Dimension the variable with a width w and a height h that matches those shown in the table later in this section.

Dimensionality of the Import Variable

If the dimensions of the byte array imgarr are not known, DC_READ_24_BIT makes a “best guess” about the width, height, and depth of the image. It guesses by checking the number of bytes in the file and comparing that number to the number of bytes associated with the common image sizes:

Common Image Sizes
Image Width	Image Height	Image Depth
640	480	3
640	512	3
128	128	3
256	256	3
512	512	3
1024	1024	3

If no match is found, DC_READ_24_BIT resorts to assuming that the image is square, and returns XSize and YSize as the square root of the number of bytes in the file, divided by 3.

PV‑WAVE uses the following guidelines to dimension imgarr:

Pixel Interleaving — Dimension imgarr as 3 × w × h, where w and h are the width and length of the image in pixels.
Image Interleaving — Dimension imgarr as w × h × 3, where w and h are the width and length of the image in pixels.

Note: You do not need to explicitly dimension imgarr, but if your image data is not one of the standard sizes (e.g., 3-by-512-by-512 or 640-by-480-by-3), you will get more predictable results if you dimension imgarr yourself.

Example

If the file denver24.img contains a 196608 byte 24-bit image-interleaved image, the function call:

status = DC_READ_24_BIT(!Dir + '/demo/gallery3/data/denver24.img', $
   denver24, Org=1, XSize=xdim, YSize=ydim)

reads the file denver24.img, creates a 256-by-256-by-3 image-interleaved byte array named denver24, and returns xdim and ydim as 256.