The HDF Group

HDF Reference Manual


[DFR8 Interface][Top]


DFR8addimage/d8aimg

intn DFR8addimage(char *filename, VOIDP image, int32 width, int32 height, uint16 compress)

filename
IN:
Name of the file
image
IN:
Array containing the image data
width
IN:
Number of columns in the image
height
IN:
Number of rows in the image
compress
IN:
Type of compression to use, if any

Purpose
Appends the RIS8 for the image to the file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DFR8addimage is functionally equivalent to DFR8putimage, except that DFR8putimage cannot append image data; it only overwrites.

FORTRAN
integer function d8aimg(filename, image, width, height, compress)
 
character*(*) filename, image
 
integer width, height
 
integer compress

[DFR8 Interface][Top]


DFR8getdims/d8gdims

intn DFR8getdims(char *filename, int32 *width, int32 *height, intn *ispalette)

filename
IN:
Name of the HDF file
width
OUT:
Number of columns in the next image in the file
height
OUT:
Number of rows in the next image in the file
ispalette
OUT:
Indicator of the existence of a palette

Purpose
Opens the file, finds the next image, retrieves the dimensions of the image, and determines whether there is a palette associated with the image.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DFR8getdims retrieves the dimensions of the image and indicates whether a palette is associated and stored with the image. If the file is being opened for the first time, DFR8getdims returns information about the first image in the file. If an image has already been read, DFR8getdims finds the next image. Thus, images are read in the same order in which they were written to the file.
 
Normally, DFR8getdims is called before DFR8getimage so that if necessary, space allocations for the image and palette can be checked, and the dimensions can be verified. If this information is already known, DFR8getdims need not be called.
 
Valid values of ispalette are: 1 if there is a palette, or 0 if not.

FORTRAN
integer function d8gdims(filename, width, height, ispalette)
 
character*(*) filename
 
integer width, height
 
integer ispalette

[DFR8 Interface][Top]


DFR8getimage/d8gimg

intn DFR8getimage(char *filename, uint8 *image, int32 width, int32 height, uint8 *palette)

filename
IN:
Name of the file
image
OUT:
Buffer for the returned image
width
IN:
Width of the image data buffer
height
IN:
Height of the image data buffer
palette
OUT:
Palette data

Purpose
To retrieve the image and its palette, if it is present, and store them in the specified arrays.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
In C, if palette is NULL, no palette is loaded, even if one is stored with the image. In FORTRAN-77, an array must be allocated to store the palette, even if no palette is expected to be stored. If the image in the file is compressed, DFR8getimage automatically decompresses it. If DFR8getdims has not been called, DFR8getimage finds the next image in the same way that DFR8getdims does.
 
The width and height parameters specify the number of columns and rows, respectively, in the array which you've allocated in memory to store the image. The image may be smaller than the allocated space.
 
The order in which you declare dimensions is different between C and FORTRAN-77. Ordering varies because FORTRAN-77 arrays are stored in column-major order, while C arrays are stored in row-major order. (Row-major order implies that the horizontal coordinate varies fastest). When d8gimg reads an image from a file, it assumes row-major order. The FORTRAN-77 declaration that causes an image to be stored in this way must have the width as its first dimension and the height as its second dimension. To take this into account as you read image in your program, the image must be built "on its side".

FORTRAN
integer function d8gimg(filename, image, width, height, palette)
 
character*(*) filename, image, palette
 
integer width, height

[DFR8 Interface][Top]


DFR8getpalref

intn DFR8getpalref(uint16 *pal_ref)

pal_ref
OUT:
Reference number of the palette

Purpose
Retrieves the reference number of the palette associated with the last image accessed.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
Make certain that DFR8getdims is called before DFR8getpalref.

[DFR8 Interface][Top]


DFR8lastref/d8lref

uint16 DFR8lastref( )

Purpose
Retrieves the last reference number written to or read from an RIS8.
Return value
Returns a non-zero reference number if successful and FAIL (or 0) otherwise.
Description
This routine is primarily used for attaching annotations to images and adding images to vgroups. DFR8lastref returns the reference number of last raster image set read or written.

FORTRAN
integer function d8lref( )

[DFR8 Interface][Top]


DFR8nimages/d8nims

intn DFR8nimages(char *filename)

filename
IN:
Name of the HDF file

Purpose
Retrieves the number of 8-bit raster images stored in the specified file.
Return value
Returns the number of raster images in the file if successful and FAIL (or -1) otherwise.

FORTRAN
integer function d8nims(filename)
 
character*(*) filename

[DFR8 Interface][Top]


DFR8putimage/d8pimg

intn DFR8putimage(char *filename, VOIDP image, int32 width, int32 height, uint16 compress)

filename
IN:
Name of the file to store the raster image in
image
IN:
Array with image to put in file
width
IN:
Number of columns in the image
height
IN:
Number of rows in the image
compress
IN:
Type of compression used, if any

Purpose
Writes the RIS8 for the image as the first image in the file, overwriting any information previously in the file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The compress parameter identifies the method to be used for compressing the data, if any. If IMCOMP compression is used, the image must include a palette.
 
DFR8putimage overwrites any information that exists in the HDF file. To write an image to a file by appending it, rather than overwriting it, use DFR8addimage.
 
 
In FORTRAN-77, the dimensions of the image array must be the same as the dimensions of the image itself.
 
The order in which dimensions are declared is different between C and FORTRAN-77. Ordering varies because FORTRAN-77 arrays are stored in column-major order, while C arrays are stored in row-major order. (Row-major order implies that the horizontal coordinate varies fastest). When DFR8putimage writes an image to a file, it assumes row-major order. The FORTRAN-77 declaration that causes an image to be stored in this way must have the width as its first dimension and the height as its second dimension, the reverse of the way it is done in C. To take this into account as you build your image in your FORTRAN-77 program, the image must be built "on its side".

FORTRAN
integer function d8pimg(filename, image, width, height, compress)
 
character*(*) filename, image
 
integer width, height, compress

[DFR8 Interface][Top]


DFR8readref/d8rref

intn DFR8readref(char *filename, uint16 ref)

filename
IN:
Name of the file
ref
IN:
Reference number for next DFR8getimage

Purpose
Specifies the reference number of the image to be read when DFR8getimage is next called.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DFR8readref is usually used in conjunction with DFANlablist, which returns a list of labels for a given tag together with their reference numbers. It provides, in a sense, a random access to images. There is no guarantee that reference numbers appear in sequence in an HDF file; therefore, it is not safe to assume that a reference number is the index of an image.

FORTRAN
integer function d8rref(filename, ref)
 
character*(*) filename
 
integer ref

[DFR8 Interface][Top]


DFR8restart/d8first

intn DFR8restart( )

Purpose
Causes the next get command to read from the first raster image set in the file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.

FORTRAN
integer function d8first( )

[DFR8 Interface][Top]


DFR8setcompress/d8scomp

intn DFR8setcompress(int32 type, comp_info *cinfo)

type
IN:
Type of compression
cinfo
IN:
Pointer to compression information structure

Purpose
Sets the compression type to be used when writing the next 8-bit raster image.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
This routine provides a method for compressing the next raster image written. The type can be one of the following values: COMP_NONE, COMP_JPEG, COMP_RLE, COMP_IMCOMP. COMP_NONE is the default for storing images if this routine is not called, therefore images are not compressed by default. COMP_JPEG compresses images with a JPEG algorithm, which is a lossy method. COMP_RLE uses lossless run-length encoding to store the image. COMP_IMCOMP uses a lossy compression algorithm called IMCOMP, and is included for backward compatibility only.
 
The comp_info union contains algorithm-specific information for the library routines that perform the compression and is defined in the hcomp.h header file as follows (refer to the header file for inline documentation):
 
typedef union tag_comp_info
{
struct
{
intn quality;
intn force_baseline;
} jpeg;
struct
{
int32 nt;
intn sign_ext;
intn fill_one;
intn start_bit;
intn bit_len;
} nbit;
struct
{
intn skp_size;
} skphuff;
struct
{
intn level;
} deflate;
}
comp_info;

 
This union is defined to provide future expansion, but is currently only used by the COMP_JPEG compression type. A pointer to a valid comp_info union is required for all compression types other than COMP_JPEG, but the values in the union are not used. The comp_info union is declared in the header file hdf.h and is shown here for informative purposes only, it should not be re-declared in a user program.
 
For COMP_JPEG compression, the quality member of the jpeg structure must be set to the quality of the stored image. This number can vary from 100, the best quality, to 0, terrible quality. All images stored with COMP_JPEG compression are stored in a lossy manner, even images stored with a quality of 100. The ratio of size to perceived image quality varies from image to image, some experimentation may be required to determine an acceptable quality factor for a given application. The force_baseline parameter determines whether the quantization tables used during compression are forced to the range 0-255. It should normally be set to 1 (forcing baseline results), unless special applications require non-baseline images to be used.
 
If the compression type is JPEG, d8scomp defines the default JPEG compression parameters to be used. If these parameters must be changed later, the d8sjpeg routine must be used. (Refer to the Reference Manual page on d8sjpeg).

FORTRAN
integer function d8scomp(type)
 
integer type

[DFR8 Interface][Top]


d8scomp

integer d8scomp(integer quality, integer baseline)

quality
IN:
JPEG quality specification
baseline
IN:
JPEG baseline specification

Purpose
Fortran-specific routine that sets the parameters needed for the JPEG algorithm.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
d8sjpeg changes the JPEG compression parameter settings set in the d8scomp routine.

[DFR8 Interface][Top]


d8sjpeg

integer d8sjpeg(integer quality, integer baseline)

quality
IN:
JPEG quality specification
baseline
IN:
JPEG baseline specification

Purpose
Fortran-specific routine that sets the parameters needed for the JPEG algorithm.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
d8sjpeg changes the JPEG compression parameter settings set in the d8scomp routine.

[DFR8 Interface][Top]


DFR8setpalette/d8spal

intn DFR8setpalette(uint8 *palette)

palette
IN:
Palette data

Purpose
Indicate which palette, if any, is to be used for subsequent image sets.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The specified palette remains the default palette until changed by a subsequent call to DFR8setpalette.

FORTRAN
integer function d8spal(palette)
 
character*(*) palette

[DFR8 Interface][Top]


DFR8writeref/d8wref

intn DFR8writeref(char *filename, uint16 ref)

filename
IN:
Name of the HDF file
ref
IN:
Reference number for next call to DFR8putimage or DFR8addimage

Purpose
Specifies the reference number of the image to be written when DFR8addimage or DFR8putimage is next called.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
It is unlikely that you will need this routine, but if you do, use it with caution. There is no guarantee that reference numbers appear in sequence in an HDF file; therefore, it is not safe to assume that a reference number is the index of an image. In addition, using an existing reference number will overwrite the existing 8-bit raster image data.

FORTRAN
integer function d8wref(filename, ref)
 
character*(*) filename
 
integer ref

 


HDF4.2r4 - February 2009
Copyright
The HDF Group
www.hdfgroup.org
The HDF Group