Reference Guide > D Routines > DC_READ_24_BIT Function
  

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:
1. Opening the file.
2. Assigning it a logical unit number (LUN).
3. 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:
 
Table 5-1: 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.
 
See Also
DC_ERROR_MSG, DC_WRITE_24_BIT
For more information about 24-bit (binary) data and for more information about image interleaving options, see the PV‑WAVE Programmer’s Guide.

Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.