[Top] [Prev] [Next]

7.4 Writing 24-Bit Raster Images

The DF24 programming model for writing a 24-bit raster image set is as follows:

  1. Set the interlace format if the interlacing is to be different from pixel interlacing. (optional)
  2. Set the compression type if the image is to be compressed. (optional)
  3. Write the raster data to the file.

Steps 1 and 2 can be invoked in any order, as long as they are executed before Step 3. By default, images are stored uncompressed using pixel interlacing.

7.4.1 Writing a 24-Bit Raster Image: DF24putimage and DF24addimage

To write a raster image to an HDF file, the calling program must contain one of the following function calls:

C:		status = DF24putimage(filename, image, width, height);
FORTRAN:	status = d2pimg(filename, image, width, height)
	OR
C:		status = DF24addimage(filename, image, width, height);
FORTRAN:	status = d2aimg(filename, image, width, height)
DF24putimage and DF24addimage write a 24-bit raster images to the HDF file specified by the filename parameter. When given a new file name, DF24putimage and DF24addimage create a new file and write the raster image as the first raster image in the file. If a file with the specified filename exists, DF24putimage overwrites the previous contents of the file whereas DF24addimage appends data to the end of the file.

DF24putimage and DF24addimage passes the raster data in the image parameter and the width and height of the image in the width and height parameters. The array image is assumed to be the width times the height times three bytes in length for each color component. The parameters for DF24putimage and DF24addimage are further defined below. Table 7D on page 251

TABLE 7D - DF24putimage and DF24addimage Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DF24putimage

[intn]

(d2pimg)
filename
char *
character*(*)
Name of file to store the raster image.

image
VOIDP
<valid numeric data type>
Raster image to be written.

width
int32
integer
Number of columns in the image.

height
int32
integer
Number of rows in the image.

DF24addimage

[intn]

(d2aimg)
filename
char *
character*(*)
Name of file to store the raster image.

image
VOIDP
<valid numeric data type>
Raster image to be written.

width
int32
integer
Number of columns in the image.

height
int32
integer
Number of rows in the image.

EXAMPLE 1. Writing a 24-Bit Raster Image to an HDF File

In the following examples, DF24addimage and d2aimg are used to write a 24-bit image to an HDF file named "Example1.hdf." DF24addimage assumes row-major order. Therefore, the FORTRAN-77 declaration requires the width (rows) before the height (columns), whereas the C declaration requires the height before the width. The interlace format setting is the default (pixel interlacing).

C version

FORTRAN-77 version

7.4.2 Setting the Interlace Format: DF24setil

DF24setil indicates the interlace format to be used for all subsequent write operations. DF24setil changes the default setting from pixel interlacing to the selected format. When the format is set, it acts as the default until it is reset by another call to DF24setil. To change the default interlace format , the calling program must contain the following routines:

C:		status = DF24setil(il);
		status = DF24addimage(filename, image, width, height);
FORTRAN:	status = d2setil(il)
DF24setil takes il as its only parameter. Valid values for il are DFIL_PIXEL, DFIL_LINE, and DFIL_PLANE. The parameters for DF24setil are further defined below. Table 7E on page 253

EXAMPLE 2. Writing 24-Bit Raster Images Using Scan-plane Interlacing

In the following examples, DF24addimage is used to write a 24-bit image to an HDF file called "Example2.hdf". The DF24setil function used here to change the default format setting from pixel interlacing to scan-plane interlacing.

C version

FORTRAN-77 version

7.4.3 Compressing Image Data: DF24setcompress and d2sjpeg

DF24setcompress invokes JPEG compression and sets the JPEG quality and baseline options. To store a 24-bit raster image using JPEG compression, the calling program must contain the following function calls:

C:		status = DF24setcompress(type, c_info);
		status = DF24addimage(filename, image, width, height);
FORTRAN:	status = d2scomp(type)
	OR	status = d2sjpeg(quality, baseline)
		status = d2aimg(filename, image, width, height, compress)
Notice that the calling sequence for C is different from the calling sequence for FORTRAN-77. Once it is set, the parameter type in the DF24setcompress routine, or d2scomp in FORTRAN-77, routine specifies the compression method that will be used to store the raster images. However, the c_info parameter in DF24setcompress is missing from d2scomp which is a pointer to a structure that contains information specific to the compression method indicated by the type parameter. Because data structures of variable size are not supported in FORTRAN-77, a second compression-specific routine (d2sjpeg) is required in the FORTRAN-77 calling sequence.

For more information about the c_info structure refer to Chapter 6, 8-Bit Raster Images (DFR8 API).

Default values for quality and baseline (quality=75%, baseline=on) are used if c_info is a null structure or d2sjpeg is omitted. Parameters for DF24setcompress and d24sjpeg are further described in Table 7E below.

TABLE 7E - DF24setil and DF24setcompress Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DF24setil

[intn]

(d2sil)
il
int32
integer
Interlace format to be set.

DF24setcompress

[intn]

(d2scomp)
type
int32
integer
COMP_JPEG.

c_info
comp_info *
None
Pointer to JPEG information structure.

(d2sjpeg)
quality
None
integer
JPEG compression quality specification.

baseline
None
integer
JPEG compression baseline specification.

EXAMPLE 3. Compressing and Writing a 24-Bit Raster Image

In the following examples, DF24addimage and DF24compress are used to compress a 24-bit image and write it to an HDF file named "Example2.hdf". Notice that compressing an image in C requires only one function call, whereas compressing an image using FORTRAN-77 requires two. The second FORTRAN-77 call is required because it is not valid to pass a structure as a parameter in FORTRAN-77.

C version

FORTRAN-77 version



[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.