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

8.8 General Raster Image Attributes

The concepts of user-defined and predefined attributes are explained in Chapter 3, titled Scientific Data Sets (SD API). The GR implementation of attributes is similar to the SD implementation. Attributes are not written out to a file until access to the object the attribute is attached to is terminated.

8.8.1 Predefined GR Attributes

The GR interface library has only one predefined attribute: FILL_ATTR. This attribute defines a fill pixel, which is analogous to a fill value in the SD interface. It represents the default value that is written to each element of an image array not explicitly written to by the calling program; when only a portion of the entire image array is filled with data. This value must of the same data type as the rest of the initialized image data. The routine used to set the fill value is GRsetattr, explained in the next section.

8.8.2 Setting User-Defined Attributes: GRsetattr

Setting an attribute involves the following steps:

1. Open the file.
2. Initialize the GR interface.
3. Set the attribute.
4. Terminate access by disposing of any existing identifiers.
5. Terminate access to the GR interface.
6. Close the file.
To assign an attribute to a file, the calling program must contain the following sequence calls:

C:		gr_id = GRstart(filename, access_mode);
		status = GRsetattr(gr_id|ri_id, attr_name, data_type, count, 
			attr_value);
		status = GRend(gr_id);

FORTRAN:	 gr_id = mgstart(filename, access_mode)
		status = mgsnatt(gr_id|ri_id, attr_name, data_type, count, 
			attr_value)
		status = mgend(gr_id)

In GRsetattr the first argument can either be the id of a file, palette or raster image. The attribute will be assigned to the object referred to by this identifier. The argument attr_name contains the name of the attribute and can be no more than MAX_GR_NAME characters in length. Passing the name of an existing attribute will overwrite the value portion of that attribute.

The arguments, data_type, count and attr_value describe the right side of the label=value equation. The attr_value argument contains one or more values of the same data type. The data_type argument describes the data type for all values in the attribute and count contains the total number of values in the attribute.

As with other HDF routines that accommodate numeric and character data, the GRsetattr routine has two Fortran-77 versions: mgsnatt and mgscatt. The mgsnatt routine writes numeric attribute data and mgscatt writes character attribute data.

The parameters for GRsetattr are further described below. (See Table 8K on page 231.) Note that, because there are two Fortran-77 versions of GRsetattr, there are correspondingly two entries in the "Data Type" field of the values parameter.

EXAMPLE 9. Setting File and Image Attribute Values

The following code segment calls GRsetattr to assign file and image attributes to a general raster data set.

C:

#include "hdf.h"

main( ) 
{
	int32 gr_id, ri_id, file_id, dim_index, status;
	int32 num_values[2];

	/* Open the file. */
	file_id = Hopen("Example5.hdf", DFACC_RDWR, 0);

	/* Initialize the GR interface. */
	gr_id = GRstart(file_id);

	/* Set an attribute that describes the file contents. */
	status = GRsetattr(gr_id, "File contents", DFNT_CHAR8, 16, \
					(VOIDP)"RGB image data");

	/* Get the identifier for the first data set. */
	ri_id = GRselect(gr_id, 0);

	/* Set an attribute the specifies a valid range of values. */
	num_values[0] = 2;
	num_values[1] = 10;
	status = GRsetattr(ri_id, "Value range", DFNT_INT32, 2, \
						(VOIDP)num_values);

	/* Terminate access to the image. */
	status = GRendaccess(ri_id);

	/* Terminate access to the GR interface. */
	status = GRend(gr_id);

	/* Close the file. */
	status = Hclose(file_id);

}

FORTRAN:

	 PROGRAM SET IMAGE ATTRIBS

      integer*4 gr_id, ri_id, file_id, status
      integer num_values(2)
      integer mgstart, mgsnatt, mgselct
      integer mgendac, mgend, hopen, hclose
      integer DFACC_RDWR, DFNT_CHAR8, DFNT_INT32
      parameter (DFACC_RDWR = 3, DFNT_CHAR8 = 4, DFNT_INT32 = 24)

C     Open the file. 
      file_id = hopen(`Example5.hdf', DFACC_RDWR, 0)

C     Initialize the GR interface. 
      gr_id = mgstart(file_id)

C     Set an attribute that describes the file contents. 
      status = mgsnatt(gr_id, `File contents', DFNT_CHAR8, 16, 
     +                 `RGB image data')

C     Get the identifier for the first data set. 
      ri_id = mgselct(gr_id, 0)

C     Set an attribute the specifies a valid range of values. 
      num_values(1) = 2
      num_values(2) = 10
      status = mgsnatt(ri_id, `Value range', DFNT_INT32, 2, num_values)

C     Terminate access to the image. 
      status = mgendac(ri_id)

C     Terminate access to the GR interface. 
      status = mgend(gr_id)

C     Close the file. 
      status = hclose(file_id)

      end

8.8.3 Querying User-Defined Attributes: GRfindattr and GRattrinfo

Each attribute associated with an object has a unique attribute index, a value ranging from 0 to the total number of attributes in the object. Given a file, array or dimension id and an attribute name, GRfindattr will return a valid attribute index if the attribute exists. The attribute index can then be used to retrieve information about an attribute or its values. Given a file or array and a valid attribute index GRattrinfo returns the name, data type and count for the attribute if it exists.

The syntax for GRfindattr and GRattrinfo is as follows:

C:		status = GRfindattr(ri_id|gr_id, attr_name);
		status = GRattrinfo(ri_id|gr_id, attr_index, attr_name,
			&data_type, &count);

FORTRAN:	 status = mgfndat(ri_id|gr_id, attr_name)
		status = mgatinf(ri_id|gr_id, attr_index, attr_name,
			data_type, count);

The parameters for GRfindattr and GRattrinfo are further described below. (See Table 8K.)

8.8.4 Reading User-Defined Attributes: GRgetattr

GRgetattr reads an attribute's values. The syntax for GRgetattr is as follows:

C:		status = GRgetattr(ri_id|gr_id, attr_index, data);

FORTRAN:	status = mggnatt(ri_id|gr_id, attr_index, data)

GRgetattr takes a file, array, or dimension identifier and an attribute index specified in the attr_index parameter as input parameters and returns the attribute's values in the buffer data.

It's assumed that the buffer data, allocated to hold the attribute values, is large enough to hold the data - if not, the data read will be truncated to the size of the buffer. The size of the buffer should be at least count*DFKNTsize(number_type) bytes long. If an attribute contains multiple values, GRgetattr will return all of them. It is not possible to read a subset of values.

As with GRsetattr, GRgetattr has two Fortran-77 versions: mggnatt and mggcatt. The mggnatt routine reads numeric attribute data and mggcatt reads character attribute data.

The parameters for GRgetattr are further described in Table 8K. Note that, because there are two Fortran-77 versions of GRgetattr, there are correspondingly two entries in the "Data Type" field of the values parameter.

TABLE 8K GRsetattr, GRfindattr, GRattrinfo and GRgetattr Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

GRsetattr

(mgsnatt/mgscatt)

*_id

int32

integer

GR data set or image identifier.

attr_name

char *

character* (*)

Name assigned to the attribute.

data_type

int32

integer

Specifies the data type.

count

int32

integer

Number of values in the attribute.

values

VOIDP

<valid numeric data type>

Buffer of the data to be written.

GRfindattr

(mgfadat)

*_id

int32

integer

GR data set or image identifier.

attr_name

char *

character* (*)

Name assigned to the attribute.

GRattrinfo

(mgatinf)

*_id

int32

integer

GR data set or image identifier.

attr_index

int32

integer

Index for the attribute to be read.

attr_name

char *

character* (*)

Buffer for the name of the dimension attribute.

data_type

int32 *

integer

Buffer for the data type of the values in the attribute.

count

int32 *

integer

Buffer for the total number of values in the attribute.

GRgetattr

(mggnatt/

mggcatt)

*_id

int32

integer

GR data set or image identifier.

attr_index

int32

integer

Index for the attribute to be read.

values

VOIDP

<valid numeric data type>

Buffer for the attribute values.

EXAMPLE 10. Retrieving Image Attribute Information

The image attribute information stored in the "Example4.hdf" HDF file in Example 4 are read from the file in these examples.

C:

#include "hdf.h"

main( ) 
{

	int32 gr_id, ri_id, file_id, status;
	int32 attr_index, data_type, count; 
	char attr_name[MAX_GR_NAME];
	int8 *buffer;

	/* Open the file. */
	file_id = Hopen("Example5.hdf", DFACC_RDONLY, 0);

	/* Initialize the GR interface. */
	gr_id = GRstart(file_id);

	/* Find the file attribute named "File contents". */
	attr_index = GRfindattr(gr_id, "File contents");

	/* Get information about the file attribute. */
	status = GRattrinfo(gr_id, attr_index, attr_name, &data_type, &count);

	/* Allocate a buffer to hold the attribute data. */
	buffer = HDmalloc(count * DFKNTsize(data_type));

	/* Read the attribute data. */
	status = GRgetattr(gr_id, attr_index, buffer);

	/* Free the buffer memory. */
	HDfree(buffer);

	/* Get the identifier for the first image. */
	ri_id = GRselect(gr_id, 0);

	/* Find the data set attribute named "Value range". */
	attr_index = GRfindattr(ri_id, "Value range");

	/* Get information about the image attribute. */
	status = GRattrinfo(ri_id, attr_index, attr_name, &data_type, &count);

	/* Allocate a buffer to hold the attribute data. */
	buffer = HDmalloc(count * DFKNTsize(data_type));

	/* Read the attribute data. */
	status = GRgetattr(ri_id, attr_index, buffer);

	/* Terminate access to the array */
	status = GRendaccess(ri_id);

	/* Terminate access to the GR interface. */
	status = GRend(gr_id);

	/* Close the file */
	status = Hclose(file_id);

}

FORTRAN:

	 PROGRAM IMAGE ATTRIB INFO

      integer*4 gr_id, ri_id, file_id
      integer attr_index, data_type, count, status
      character attr_name *13
      character buffer *20

      integer mgstart, mgfndat, mgatinf, mggnatt, mgselct
      integer mgendac, mgend, hopen, hclose

C     DFACC_RDONLY is defined in hdf.h.
      integer DFACC_RDONLY
      parameter (DFACC_RDONLY = 1)

C     Open the file. 
      file_id = hopen(`Example5.hdf', DFACC_RDONLY, 0)

C     Open the file. 
      gr_id = mgstart(file_id)

C     Find the file attribute named `File contents'. 
      attr_index = mgfndat(gr_id, `File contents')

C     Get information about the file attribute. 
      status = mgatinf(gr_id, attr_index, attr_name, data_type, count)

C     Read the attribute data. 
      status = mggnatt(gr_id, attr_index, buffer)

C     Get the identifier for the first image. 
      ri_id = mgselct(gr_id, 0)

C     Find the data set attribute named "Value range". 
      attr_index = mgfndat(ri_id, `Value range')

C     Get information about the image attribute. 
      status = mgatinf(ri_id, attr_index, attr_name, data_type, count)

C     Read the attribute data. 
      status = mggnatt(ri_id, attr_index, buffer)

C     Terminate access to the array. 
      status = mgendac(ri_id)

C     Terminate access to the GR interface. 
      status = mgend(gr_id)

C     Close the file. 
      status = hclose(file_id)
      end




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

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