[Top] [Prev] [Next] [Bottom]

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. (See Table 7D on page 189.)

TABLE 7D DF24putimage and DF24addimage Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DF24putimage

(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

(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:

#include "hdf.h"

#define WIDTH 5
#define HEIGHT 6
#define PIXEL_DEPTH 3

main( )
{

	/* Initialize the image array. */
	static uint8 raster_data[HEIGHT][WIDTH][PIXEL_DEPTH] =
	{  1, 2, 3,  4, 5, 6,  7, 8, 9,  10,11,12,  13,14,15,  
	  16,17,18, 19,20,21, 22,23,24,  25,26,27,  28,29,30,  
	  31,32,33, 34,35,36, 37,38,39,  40,41,42,  43,44,45,  
	  46,47,48, 49,50,51, 52,53,54,  55,56,57,  58,59,60,  
	  61,62,63, 64,65,66, 67,68,69,  70,71,72,  73,74,75,  
	  76,77,78, 79,80,81, 82,83,84,  85,86,87,  88,89,90 };
    intn status;

	/* Write the 24-bit raster image to the HDF file. */
	status = DF24addimage("Example1.hdf", (VOIDP)raster_data, WIDTH, \
			   			  HEIGHT);

}

FORTRAN:

	 PROGRAM WRITE RIS24

      integer status, d2aimg 
      integer*4 WIDTH, HEIGHT, PIXEL_DEPTH
      parameter (WIDTH = 5,
     +         HEIGHT = 6, 
     +         PIXEL_DEPTH = 3) 

      character raster_data(PIXEL_DEPTH, WIDTH, HEIGHT)

C     Initialize the image array.
      data raster_data 
     +     /  1, 2, 3,  4, 5, 6,  7, 8, 9,  10,11,12,  13,14,15,  
     +     16,17,18, 19,20,21, 22,23,24,  25,26,27,  28,29,30, 
     +     31,32,33, 34,35,36, 37,38,39,  40,41,42,  43,44,45, 
     +     46,47,48, 49,50,51, 52,53,54,  55,56,57,  58,59,60, 
     +     61,62,63, 64,65,66, 67,68,69,  70,71,72,  73,74,75, 
     +     76,77,78, 79,80,81, 82,83,84,  85,86,87,  88,89,90 /

C     Write the 24-bit raster image to the file.
      status = d2aimg('Example1.hdf', raster_data, WIDTH, 
     +                HEIGHT)

      end

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) status = d2aimg(filename, image, width, height)

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. (See Table 7E on page 192.)

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:

#include "hdf.h"
#include "hcomp.h"

#define WIDTH 5
#define HEIGHT 6
#define PIXEL_DEPTH 3

main( )
{

	/* Initialize the image array. */
	static uint8 raster_data[HEIGHT][WIDTH][PIXEL_DEPTH] = 
	{  1, 2, 3,  4, 5, 6,  7, 8, 9,  10,11,12,  13,14,15,  
	16,17,18, 19,20,21, 22,23,24,  25,26,27,  28,29,30,  
	31,32,33, 34,35,36, 37,38,39,  40,41,42,  43,44,45,  
	46,47,48, 49,50,51, 52,53,54,  55,56,57,  58,59,60,  
	61,62,63, 64,65,66, 67,68,69,  70,71,72,  73,74,75,  
	76,77,78, 79,80,81, 82,83,84,  85,86,87,  88,89,90 };
	intn status;

	/* Change interlace from pixel to scan-plane. */
	status = DF24setil(DFIL_PLANE); 

	/* Write the 24-bit image data to file. */
	status = DF24addimage("Example2.hdf", (VOIDP)raster_data, 
					WIDTH, HEIGHT);

}

FORTRAN:

	 PROGRAM CHANGE INTERLACE

      integer status, d2aimg, d2setil 
      integer*4 WIDTH, HEIGHT, PIXEL_DEPTH, DFIL_PLANE
      parameter (WIDTH = 5,
     +    HEIGHT = 6, 
     +    PIXEL_DEPTH = 3, 
     +    DFIL_PLANE = 2) 

      integer raster_data(PIXEL_DEPTH, WIDTH, HEIGHT)

C     Initialize the image array.
      data raster_data 
     + /  1, 2, 3,  4, 5, 6,  7, 8, 9,  10,11,12,  13,14,15,  
     +  16,17,18, 19,20,21, 22,23,24,  25,26,27,  28,29,30, 
     +  31,32,33, 34,35,36, 37,38,39,  40,41,42,  43,44,45, 
     +  46,47,48, 49,50,51, 52,53,54,  55,56,57,  58,59,60, 
     +  61,62,63, 64,65,66, 67,68,69,  70,71,72,  73,74,75, 
     +  76,77,78, 79,80,81, 82,83,84,  85,86,87,  88,89,90  /

C     Change interlace from pixel to scan plane.
      status = d2setil(DFIL_PLANE)

C     Write the 24-bit raster image to the file.
      status = d2aimg('Example2.hdf', raster_data, WIDTH, 
     +                 HEIGHT)

      end

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, titled 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

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DF24setil

(d2sil)

il

int32

integer

Interlace format to be set.

DF24setcompress

(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:

#include "hdf.h"
#include "hcomp.h"

#define WIDTH 3
#define HEIGHT 5
#define PIXEL_DEPTH 3

main( )
{
	/* Initialize the image array. */
	static uint8 raster_data[HEIGHT][WIDTH][PIXEL_DEPTH] = 
		{  1, 2, 3,  4, 5, 6,  7, 8, 9,  
		  10,11,12, 13,14,15, 16,17,18, 
		  19,20,21, 22,23,24, 25,26,27,  
		  28,29,30, 31,32,33, 34,35,36,  
		  37,38,39, 40,41,42, 43,44,45 }; 
	static comp_info compress_info;
	intn status;

	/* Initialize JPEG compression structure. */
	compress_info.jpeg.quality = 60;
	compress_info.jpeg.force_baseline = 1;

	/* Set JPEG compression for storing the image. */
	status = DF24setcompress(COMP_JPEG, &compress_info);

	/* Write the 24-bit image data to file. */
	status = DF24addimage("Example2.hdf", (VOIDP)raster_data, 
					WIDTH, HEIGHT);

}

FORTRAN:

	 PROGRAM COMPRESS RIS24

      integer d2aimg, d2scomp, d2sjpeg, status
      integer*4 WIDTH, HEIGHT, PIXEL_DEPTH
      parameter(WIDTH = 3,
     +          HEIGHT = 5,
     +          PIXEL_DEPTH = 3)
      character raster_data(PIXEL_DEPTH, WIDTH, HEIGHT) 

C     Initialize the image array.
      data raster_data 
     + /  1, 2, 3,  4, 5, 6,  7, 8, 9,  
     +   10,11,12, 13,14,15, 16,17,18, 
     +   19,20,21, 22,23,24, 25,26,27,  
     +   28,29,30, 31,32,33, 34,35,36,  
     +   37,38,39, 40,41,42, 43,44,45  /

C     Set compression.
      status = d2scomp(COMP_JPEG)

C     Set JPEG parameters to quality = 60, and turn compatibility on.
      status = d2sjpeg(60, 1)

C     Write the 24-bit image data to the HDF file.
      status = d2aimg('Example2.hdf', raster_data, WIDTH, HEIGHT)
      end



[Top] [Prev] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.