The HDF Group

HDF Reference Manual

Version 4.2.12


[DF24 Interface][Top]


DF24addimage/d2aimg

intn DF24addimage(char *filename, VOIDP image, int32 width, int32 height)

filename
IN:
Name of the file
image
IN:
Pointer to the image array
width
IN:
Number of columns in the image
height
IN
Number of rows in the image

Purpose
Writes a 24-bit image to the specified file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DF24addimage appends a 24-bit raster image set to the file. Array image is assumed to be width x height x 3 bytes. In FORTRAN-77, the dimensions of the array image must be the same as the dimensions of the image data.
 
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 last coordinate varies fastest).
 
When DF24addimage 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. In other words, the image must be built "on its side".

FORTRAN
integer function d2aimg(filename, image, width, height)
 
character*(*) filename
 
<valid numeric data type> image
 
integer width, height

[DF24 Interface][Top]


DF24getdims/d2gdims

intn DF24getdims (char *filename, int32 *width, int32 *height, intn *interlace_mode)

filename
IN:
Name of the file
width
OUT:
Width of the image
height
OUT:
Height of the image
interlace_mode
OUT:
File interlace mode of the image

Purpose
Retrieves dimensions and interlace storage scheme of next image.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DF24getdims retrieves the dimensions and interlace of the image. If the file is being opened for the first time, DF24getdims returns information about the first image in the file. If an image has already been read, DF24getdims finds the next image. In this way, images are read in the same order in which they were written to the file.
 
If the dimensions and interlace of the image are known beforehand, there is no need to call DF24getdims. Simply allocate arrays with the proper dimensions for the image and invoke DF24getimage to read the images. If, however, you do not know the values of width and height, you must call DF24getdims to get them and then use them to determine the amount of memory to allocate for the image buffer.
 
Successive calls to DF24getdims and DF24getimage retrieve all of the images in the file in the sequence in which they were written.
 
The interlace mode codes are: 0 for pixel interlacing, 1 for scan-line interlacing and 2 for scan-plane interlacing.

FORTRAN
integer function d2gdims(filename, width, height, interlace_mode)
 
character*(*) filename
 
integer width, height, interlace_mode

[DF24 Interface][Top]


DF24getimage/d2gimg

intn DF24getimage(char *filename, VOIDP image, int32 width, int32 height)

filename
IN:
Name of the HDF file
image
OUT:
Pointer to image buffer
width
IN:
Number of columns in the image
height
IN:
Number of rows in the image

Purpose
Retrieves an image from the next 24-bit raster image set.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DF24getimage retrieves the image and stores it in an array. If DF24getdims has not been called, DF24getimage finds the next image in the same way that DF24getdims does.
 
The amount of space allocated for the image should be width x height x 3 bytes.
 
To specify that the next call to DF24getimage should read the raster image using an interlace other than the interlace used to store the image in the file, first call DF24reqil.

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

[DF24 Interface][Top]


DF24lastref/d2lref

uint16 DF24lastref( )

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

FORTRAN
integer function d2lref( )

[DF24 Interface][Top]


DF24nimages/d2nimg

intn DF24nimages(char *filename)

filename
IN:
Name of the file

Purpose
Counts the number of 24-bit raster images contained in an HDF file.
Return value
Returns the number of 24-bit images in the file if successful and FAIL (or -1) otherwise.
Description
DF24nimages counts the number of 24-bit images stored in the file.

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

[DF24 Interface][Top]


DF24putimage/d2pimg

intn DF24putimage(char *filename, VOIDP image, int32 width, int32 height)

filename
IN:
Name of the file
image
IN:
Pointer to the image array
width
IN:
Number of columns in the image
height
IN:
Number of rows in the image

Purpose
Writes a 24-bit image as the first image in the file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The array image is assumed to be width x height x 3 bytes. DF24putimage overwrites any information that exists in the HDF file. To append a new image to a file instead of overwriting an existing file, use DF24addimage.

FORTRAN
integer function d2pimg(filename, image, width, height)
 
character*(*) filename
 
<valid numeric data type> image
 
integer width, height

[DF24 Interface][Top]


DF24readref/d2rref

intn DF24readref(char *filename, uint16 ref)

filename
IN:
Name of the file
ref
IN:
Reference number for the next call to DF24getimage

Purpose
Specifies the reference number of the next image to be read when DF24getimage is next called.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DF24readref is commonly used in conjunction with DFANlablist, which returns a list of labels for a given tag together with their reference numbers. It provides a means of non-sequentially accessing 24-bit raster images in a file.
 
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 d2rref(filename, ref)
 
character*(*) filename
 
integer ref

[DF24 Interface][Top]


DF24reqil/d2reqil

intn DF24reqil (intn il)

il
IN
Memory interlace of the next image read

Purpose
Specifies the interlace mode for the next call to DF24getimage will use.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
Regardless of what interlace scheme is used to store the image, DF24reqil causes the image to be loaded into memory and be interlaced according to the specification of il.
 
Because a call to DF24reqil may require a substantial reordering of the data, slower I/O performance could result than would be achieved if no change in interlace were requested.
 
The interlace mode codes are: 0 for pixel interlacing,1 for scan-line interlacing and 2 for scan-plane interlacing.

FORTRAN
integer function d2reqil(il)
 
integer il

[DF24 Interface][Top]


DF24restart/d2first

intn DF24restart( )

Purpose
Specifies that the next 24-bit image read from the file will be the first one rather than the 24-bit image following the one most recently read.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.

FORTRAN
integer function d2first( )

[DF24 Interface][Top]


DF24setcompress/d2scomp

intn DF24setcompress(int32 type, comp_info *cinfo)

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

Purpose
Set the type of compression to use when writing the next 24-bit raster image.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
This routines 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:
 
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. The force_baseline parameter 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, d2scomp defines the default JPEG compression parameters to be used. If these parameters must be changed later, the d2sjpeg routine must be used. (See the Reference Manual entry for d2sjpeg)

FORTRAN
integer function d2scomp(type)
 
integer type

[DF24 Interface][Top]


d2scomp

integer d2scomp(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.

[DF24 Interface][Top]


d2sjpeg

integer d2sjpeg(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
d2sjpeg changes the JPEG compression parameter settings set in the d2scomp routine.

[DF24 Interface][Top]


DF24setdims/d2sdims

intn DF24setdims(int32 width, int32 height)

width
IN:
Number of columns in the image
height
IN:
Number or rows in the image

Purpose
Set the dimensions of the next image to be written to a file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.

FORTRAN
integer function d2sdims(width, height)
 
integer width, height

[DF24 Interface][Top]


DF24setil/d2setil

intn DF24setil(intn il)

il
IN:
Interlace mode

Purpose
Specifies the interlace mode to be used on subsequent writes.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DF24setil sets the interlace mode to be used when writing out the raster image set for a 24-bit image by determining the interlace mode of the image data in memory. If DF24setil is not called, the interlace mode is assumed to be 0.
 
The interlace mode codes are: 0 for pixel interlacing, 1 for scan-line interlacing and 2 for scan-plane interlacing.

FORTRAN
integer function d2setil(il)
 
integer il


HDF 4.2.12 - June 2016
Copyright
The HDF Group
www.hdfgroup.org
The HDF Group