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

6.4 Writing 8-Bit Raster Images

The DFR8 programming model for writing an 8-bit raster image sets is as follows:

1. Set the compression type if the image is to be compressed. (optional)
2. Identify the palette if one is to be stored with the image. (optional)
3. Write the raster data to the file.
The two optional steps can be invoked in any order, as long as they are executed before Step 3. By default, images are stored uncompressed with no associated palette.

6.4.1 Storing a Raster Image: DFR8putimage and DFR8addimage

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

C:		status = DFR8putimage(filename, image, width, height, compress);
FORTRAN:	status = d8pimg(filename, image, width, height, compress)

OR

C:		status = DFR8addimage(filename, image, width, height, compress);
FORTRAN:	status = d8aimg(filename, image, width, height, compress)

DFR8putimage and DFR8addimage write an 8-bit raster image to an HDF file named by the filename parameter. When given a new filename, DFR8putimage and DFR8addimage create a new file and write the raster image as the first raster image in the file. When given an existing filename, DFR8putimage overwrites the file whereas DFR8addimage appends data to the end of the file.

In the DFR8putimage and DFR8addimage functions, the raster data is passed in the image parameter and the width and height of the image are passed in the width and height parameters. The compression algorithm used to store the image is passed in the compress parameter. Valid compress values include COMP_NONE, COMP_RLE, COMP_JPEG and COMP_IMCOMP. COMP_NONE represents no compression (storage only), COMP_RLE represents run-length encoding, COMP_JPEG represents JPEG compression and COMP_IMCOMP represents IMCOMP encoding.

Parameters for DFR8putimage and DFR8addimage are further described below. (See Table 6C on page 173.)

TABLE 6C DFR8putimage and DFR8addimage Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFR8putimage

(d8pimg)

and

DFR8addimage

(d8aimg)

filename

char *

character* (*)

Name of file the raster image will be stored in.

image

VOIDP

<valid numeric data type>

Image data array.

width

int32

integer

Number of columns in the raster image.

height

int32

integer

Number of rows in the raster image.

compress

int16

integer

Compression type.

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

In the following code examples, DFR8addimage and d8aimg are used to write an 8-bit image to a file named "Example1.hdf". Note that the order in which the dimensions for the image array are declared differs between C and Fortran-77.

C:

#include "hdf.h"

#define WIDTH 5
#define HEIGHT 6

main( )
{

	/* Initialize the image array */
	static uint8 raster_data[HEIGHT][WIDTH] = 
		{ 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 };

	intn status;

 
	/* Write the 8-bit raster image to file */
	status = DFR8addimage("Example1.hdf", raster_data, 
					WIDTH, HEIGHT, 0);

}

FORTRAN:

	 PROGRAM RASTER8      

      character*1 raster_data(5,6)
      integer retn, d8aimg

      integer*4 WIDTH, HEIGHT
      parameter(WIDTH = 5, HEIGHT = 6)

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 /

C     Write the 8-bit raster image to the file
      retn = d8aimg('Example1.hdf', raster_data, WIDTH, HEIGHT, 0)

      end

6.4.2 Adding a Palette to an RIS8 Object: DFR8setpalette

DFR8setpalette identifies the palette to be used for the subsequent write operations. It may be used to assign a palette to a single image or several images. After a palette has been set, it acts as the current palette until it is replaced by another call to DFR8setpalette. To create a raster image set containing a palette, the calling program must contain the following:

C:		status = DFR8setpalette(palette);

 		status = DFR8addimage(filename, image, width, height, compress);

FORTRAN: status = d8spal(palette) status = d8aimg(filename, image, width, height, compress)

DFR8setpalette takes palette as its only parameter. To set the default palette to "no palette", pass NULL as the palette parameter. DFR8setpalette is further defined in the following table.

TABLE 6D DFR8setpalette Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFR8setpalette

(d8spal)

palette

uint8 *

character* (*)

Palette to be assigned.

EXAMPLE 2. Writing a Palette and an Image in RIS8 Format

These examples demonstrate how a palette stored in the array colors and the raw image stored in the 20 x 20 array picture is written to a RIS8 object. The image is not compressed and, in these examples, uninitialized. The raster image set is stored as the first image in "Example2.hdf". Note that because DFR8putimage recreates the file, anything previously contained in this file will be erased.

C:

#include "hdf.h"

#define WIDTH 20
#define HEIGHT 20

main( )
{
	uint8 colors[256*3], picture[HEIGHT][WIDTH];
	uint8 i, j;
	int16 status;

	/* Initialize image arrays. */
	for (j = 0; j < WIDTH; j++) {
		for (i = 0; i < HEIGHT; i++) 
			picture[j][i] = 1;
      }

	/* Set the current palette. */
	status = DFR8setpalette(colors);

	/* Write the image data to the file. */
	status = DFR8putimage("Example2.hdf", picture, WIDTH,
					HEIGHT, COMP_NONE);

}

FORTRAN:

	 PROGRAM WRITE UNCOMPRESSED RIS8

      integer   d8spal, d8pimg, status, i, j
      integer   colors(768)
      integer*4   WIDTH, HEIGHT, COMP_NONE
      parameter (COMP_NONE = 0,
     +           WIDTH = 20,
     +           HEIGHT = 20)
      integer   picture(WIDTH, HEIGHT)

C     Initialize the image data.
      do 20 j = 1, WIDTH
       do 10 i = 1, HEIGHT
          picture(j, i) = 1
10     continue
20    continue

C     Set the current palette.
      status = d8spal(colors)

C     Write the image data to the file.
      status = d8pimg('Example2.hdf', picture, WIDTH, HEIGHT,
     +                COMP_NONE)

      end


6.4.3 Compressing 8-Bit Raster Image Data: DFR8setcompress

The compression type is determined by the tag passed as the fifth argument in calls to the DFR8putimage and DFR8addimage routines. DFR8setcompress is currently required only to reset the default JPEG compression options. However, future versions of this routine will support additional compression schemes.

To set non-default compression parameters, the calling program should contain the following sequence of routines:

C:		status = DFR8setcompress(type, c_info);

 		status = DFR8addimage(filename, image, width, height, compress);

FORTRAN: status = d8scomp(type) <compression-specific code>

status = d8aimg(filename, image, width, height, compress)

Notice that the calling sequence for C differs from the calling sequence for Fortran-77. Once the compression is set, the parameter type in the DFR8setcompress routine, or d8scomp in Fortran-77, specifies the compression method that will be used when storing the raster images. However, the c_info parameter, which is a pointer to a structure that contains information specific to the compression scheme indicated by the type parameter in DFR8setcompress, is missing from d8scomp. Because data structures of variable size are not supported in Fortran-77, another routine specific to the compression library is required in the Fortran-77 calling sequence.

The c_info union is described in Chapter 3, titled Scientific Data Sets (SD API). The values contained in this union are passed into the d8sjpeg Fortran-77-specific routine.

Parameters for DFR8setcompress and d8sjpeg are further described in Table 6E below.

TABLE 6E DFR8setcompress Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFR8setcompress

(d8scomp)

type

int32

integer

Compression method.

c_info

comp_info *

None

Pointer to JPEG information structure.

d8sjpeg

quality

none

integer

JPEG quality factor.

baseline

none

integer

JPEG baseline.

EXAMPLE 3. Writing a Set of Compressed 8-Bit Raster Images

These examples contain a series of calls in which four 20 x 20 images are written to the same file. The first two use palette paletteA and are compressed using the RLE method; the third and fourth use palette paletteB and are not compressed.

C:

#include "hdf.h"

#define WIDTH 20
#define HEIGHT 20

main ( )
{
	uint8 paletteA[256*3], paletteB[256*3];
	uint8 picture1[HEIGHT][WIDTH], picture2[HEIGHT][WIDTH];
	uint8 picture3[HEIGHT][WIDTH], picture4[HEIGHT][WIDTH];
	uint8 i, j;
	int16 status;
    
	/* Initialize image arrays. */
	for (j = 0; j < WIDTH; j++) {
		for (i = 0; i < HEIGHT; i++) {
			picture1[j][i] = 1;
			picture2[j][i] = 1;
			picture3[j][i] = 1;
			picture4[j][i] = 1;
		}
	}

	/* Set the first palette. */
	status = DFR8setpalette(paletteA);
    
	/* Write the compressed image data to the HDF file. */
	status = DFR8putimage("Example3.hdf", (VOIDP)picture1, WIDTH, HEIGHT, \
					COMP_RLE);
	status = DFR8addimage("Example3.hdf", (VOIDP)picture2, WIDTH, HEIGHT, \
					COMP_RLE);
    
	/* Set the second palette. */
	status = DFR8setpalette(paletteB);
    
	/* Write the uncompressed image data to the HDF file. */
	status = DFR8addimage("Example3.hdf", (VOIDP)picture3, WIDTH, HEIGHT, \
					COMP_NONE);
	status = DFR8addimage("Example3.hdf", (VOIDP)picture4, WIDTH, HEIGHT, \
					COMP_NONE);

}

FORTRAN:

	PROGRAM WRITE IMAGE SETS

      integer d8spal, d8pimg, d8aimg, status
      integer*4 COMP_RLE, COMP_NONE, WIDTH, HEIGHT
      parameter (COMP_RLE = 11,
     +           COMP_NONE = 0,
     +           WIDTH = 20,
     +           HEIGHT = 20)

      integer paletteA(768), paletteB(768)
      integer picture1(WIDTH, HEIGHT), picture2(WIDTH, HEIGHT)
      integer picture3(WIDTH, HEIGHT), picture4(WIDTH, HEIGHT)

C     Initialize the image data.
      do 20 j = 1, WIDTH
       do 10 i = 1, HEIGHT
        picture1(j, i) = 1
        picture2(j, i) = 1
        picture3(j, i) = 1
        picture4(j, i) = 1
10     continue
20    continue

C     Set the first palette.
      status = d8spal(paletteA)

C     Write the compressed image data to the HDF file.
      status = d8pimg('Example3.hdf', picture1, WIDTH, HEIGHT, 
     +               COMP_RLE)
      status = d8aimg('Example3.hdf', picture2, WIDTH, HEIGHT, 
     +               COMP_RLE)

C     Set the second palette.
      status = d8spal(paletteB)

C     Write the uncompressed image data to the HDF file.
      status = d8aimg('Example3.hdf', picture3, WIDTH, HEIGHT, 
     +               COMP_NONE)
      status = d8aimg('Example3.hdf', picture4, WIDTH, HEIGHT, 
     +               COMP_NONE)

      end


EXAMPLE 4. Compressing and Writing a 8-Bit Raster Image

In the following examples, DFR8addimage and DFR8compress are used to compress an 8-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 = DFR8setcompress(COMP_JPEG, &compress_info);

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

}

FORTRAN:

	 PROGRAM COMPRESS RIS8

      integer d8aimg, d8scomp, d8sjpeg, status
      integer*4 WIDTH, HEIGHT, PIXEL_DEPTH, COMP_JPEG

C     COMP_JPEG is defined in hcomp.h.
      parameter(WIDTH = 3,
     +          HEIGHT = 5,
     +          COMP_JPEG = 1,
     +          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 = d8scomp(COMP_JPEG)

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

C     Write the 8-bit image data to the HDF file.
      status = d8aimg('Example2.hdf', raster_data, WIDTH, HEIGHT,
     +              COMP_JPEG)

      end

6.4.4 Specifying the Reference Number of an RIS8: DFR8writeref

DFR8writeref specifies the reference number of the image to be written when DFR8addimage or DFR8putimage is called. Use the following calling sequence to invoke DFR8writeref:

C:		status = DFR8writeref(filename, ref);

 		status = DFR8addimage(filename, image, width, height, compress);

FORTRAN: status = d8wref(filename, ref) status = d8aimg(filename, image, width, height, compress)

DFR8writeref assigns the reference number passed in the ref parameter to the next image the file specified by the filename parameter. If the value of ref is the same as the reference number of an existing RIS8, the existing raster image data will be overwritten. The parameters for DFR8writeref are further described below. (See Table 6F.)

It is unlikely that you will need this routine, but if you do, use it with caution. It is not safe to assume that a reference number indicates the file position of the corresponding image as there is no guarantee that reference numbers appear in sequence in an HDF file.

TABLE 6F DFR8writeref Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFR8writeref

(d8wref)

filename

char *

character* (*)

Name of the HDF file containing the raster image.

ref

uint16

integer

Reference number for next call to DFR8getimage.



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

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