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:
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
For more information about 24-bit (binary) data and for more information about image interleaving options, see the PV‑WAVE Programmer’s Guide.
