iNCSA HDF Calling Interfaces and Utilities

Table of Contentsi

National Center for Supercomputing Applications

November 1989









Table of Contents




Introduction
Overview  xi
What Is HDF?  xi
Differences Between HDF 2.0 and HDF 3.0  xi
System Requirements  xii
Use of This Manual  xii
Manual Contents  xii
Form of Presentation  xiii
Further Reading  xv
Chapter 1NCSA HDF Basics
Chapter Overview  1.1
What Is Hierarchical Data Format?  1.1
Why Was HDF Created?  1.1
NCSA HDF Application Software  1.3
NCSA Scientific Visualization Software and HDF  1.4
HDF Calling Interfaces  1.4
HDF Utilities  1.5
Getting Started with HDF  1.5
Examples  1.6
Writing an HDF 8-Bit Raster Image 
Set  1.6
Writing an HDF Scientific Dataset  1.7
FORTRAN and C  1.8
FORTRAN Stubs  1.8
Data Type Anomalies  1.9
Case Sensitivity  1.9
Name Length  1.9
Header Files  1.9
FORTRAN 77 and K & RŐs C  1.10
HDF Without FORTRAN  1.10
How to Get HDF  1.11

Chapter 2Storing Raster Images
Chapter Overview  2.1
Header Files  2.1
Raster Image Sets  2.1
Reasons to Use Raster Image Sets  2.2
8-Bit Raster Image Sets  2.3
Compression Schemes  2.4
Writing 8-Bit Raster Images to a File  2.5
Reading 8-Bit Raster Images from a 
File  2.8
24-Bit Raster Image Sets  2.11
Interlace Schemes  2.11
Compression Schemes  2.13
Writing 24-Bit Raster Images to a File  2.13
Reading 24-Bit Raster Images from a 
File  2.14
Sample Programs  2.18
A FORTRAN Program to Copy a RIS8 from One File to Another  2.18
A C Program to Convert a Raw Palette and Raw Raster Image to HDF RIS8 Format  2.18
C Functions to Convert Floating-Point Data to 8-Bit Raster Data  2.20
Chapter 3Storing Palettes
Chapter Overview  3.1
HDF 8-Bit Palettes  3.1
Writing Palettes to a File  3.2
Reading Palettes from a File  3.3
Other Palette Routines  3.4
Chapter 4Storing Rectangular Gridded Arrays of
Scientific Data
Chapter Overview  4.1
Scientific Datasets  4.1
Reasons to Use Scientific Datasets  4.3
Header File  4.4
Writing Scientific Datasets to a File  4.4
The ŇSetÓ Routines:  Preparing to Write Scientific Datasets  4.5
Writing Scientific Datasets to a File  4.8
Writing Parts of a Scientific Dataset  4.11
Reading Scientific Datasets from a File  4.14
Getting the Dimensions of a Scientific Dataset  4.14
Reading an Entire Scientific Dataset  4.15
Getting Other Information About 
SDSs  4.16
Reading Parts of a Scientific Dataset  4.19
How SDS Routines Store and Convert 
Scientific Data  4.21
How HDF Normally Stores Arrays  4.21
How HDF Normally Represents 
Numbers  4.21
DFSDsettype:  Setting Scientific Dataset
Attributes  4.22
Sample Programs  4.23
A FORTRAN Program  4.23
A C Program  4.26
Chapter 5Annotating Data Objects and Files
Chapter Overview  5.1
Annotation Tags  5.1
The Annotation Interface  5.2
Writing Annotations to a File  5.3
Reading Annotations from a File  5.5
Getting Annotation Information from a File  5.8
Listing All Labels for a Given Tag  5.9
Chapter 6General Purpose HDF Routines
Chapter Overview  6.1
Introduction  6.1
Header Files  6.2
Opening and Closing Files  6.3
Finding Tags, Refs, and Element Lengths  6.4
Storing and Retrieving Entire Data Elements  6.6
Reading or Writing Part of a Data Element  6.8
Manipulating Data Descriptors (DDs)  6.11
Miscellaneous  6.13
Chapter 7NCSA HDF Command Line Utilities
Chapter Overview  7.1
Introduction  7.1
hdfls:  Listing Basic Information about an 
HDF  7.2
hdfed:  Editing an HDF File  7.3
Basics  7.3
Tutorial Session  7.5
hdfed with the -batch Option  7.11
fptohdf:  Converting Floating-Point Data to SDS and/or RIS8  7.11
Basics  7.11
Notes  7.13
Examples  7.13
Utilities for Working with Raster Image 
Sets  7.14
r8tohdf:  Converting 8-bit Raster Images to HDF  7.14
hdftor8:  Extracting 8-bit Raster Images and Palettes from an HDF File  7.15
r24tohdf:  Converting 24-bit Raster Images to HDF 8-Bit Raster Images 7.16
paltohdf:  Converting a Raw Palette to HDF  7.17
hdftopal:  Extracting a Palette from an HDF file  7.17
hdfrseq/hdfseq:  Displaying Images  7.17

Chapter 8Error Handling in HDF
Chapter Overview  8.1
Error Handling in HDF  8.1
Appendix ANCSA HDF Tags
Overview  A.1
Tag Types and Descriptions  A.1
Appendix BHeader Files
Appendix CEight-Character FORTRAN Names
Appendix DPublic HDF Directories on NCSA Computers
Appendix ERoutine Lists
Raster Image Routines  E.1
Palette Routines  E.2
Annotations Routines  E.2
Scientific Dataset Routines  E.3
General Purpose Routines  E.4
Utility Routines  E.5
Appendix FNCSA HDF README Files on Anonymous FTP

Figures and Tables
Figure I.1Reading and Entering a Command 
Line  xv
Figure 1.1HDF:  A File Format for Scientific Data in a Distributed Environment   1.1
Figure 1.2HDF File with Scientific Dataset  1.3
Figure 1.3HDF Software in an Integrated Computing Environment  1.4
Figure 2.1Two Raster Image Sets in an HDF 
File  2.3
Figure 2.2Storing an RIS8  2.7
Figure 2.3Storing Multiple RIS8s in a Single 
File  2.7
Figure 2.4Reading an RIS8:  Dimensions and Presence or Palette Known  2.9
Figure 2.5Reading an RIS8:  Dimensions and Presence of Palette Not Known  2.10
Figure 2.6Scan-Plane Interlace  2.12
Figure 2.7Storing an RIS24 Using Pixel 
Interlace  2.14
Figure 2.8Storing Multiple RIS24s in a Single File  2.14
Figure 2.9Reading an RIS24:  Dimensions and Interlace Known  2.16
Figure 2.10Reading an RIS24:  Dimensions and Interlace Not Known  2.17
Figure 2.11FORTRAN Program to Copy an RIS8 from One File to Another  2.18
Figure 2.12C Program Dealing with Raster Image Sets  2.19
Figure 2.13Converting Floating-Point Data to 
RIS8  2.20
Figure 3.1Writing a Palette to a File  3.3
Figure 3.2Reading the First Available Palette  3.4
Figure 4.1HDF File with Scientific Dataset  4.2
Figure 4.2Storing Just Scientific Data  4.10
Figure 4.3Storing Scientific Data with Associated Information  4.11
Figure 4.4Reading in a Dataset  4.18
Figure 4.5Reading Multiple Scientific Datasets from a Single File of Unknown Size  4.19
Figure 4.6FORTRAN Program Dealing with Scientific Datasets  4.24
Figure 4.7C Program Dealing with Scientific Datasets  4.27
Figure 5.1Example of an Annotation  5.2
Figure 5.2Adding Annotations to a Scientific 
Dataset  5.4
Figure 5.3Getting Annotations from a Scientific Dataset  5.7
Figure 5.4Getting Last Reference Number 
Written  5.8
Figure 5.5Getting a list of Labels from a File  5.10
Figure 7.1Tutorial Session  7.5
Figure 7.2The ftptohdf Utility  7.12
Figure 7.3Format Used in a Text File for Input  7.13
Figure B.1FORTRAN Header File:  dfF.h  B.2
Figure B.2C Header File:  df.h  B.4
Figure F.1README.FIRST  F.1
Figure F.2README.NCSA.For HDF Users of NCSA Computers  F.4
Figure F.3INSTALL:  Compiling the HDF 
Source  F.5
Figure F.4README.NEW.DIR.STRUCT. New Directory Structure for HDF Version 3.0. on Anonymous FTP  F.8

Table I.1Meaning of Entry Format Notations  xiv
Table 2.1Raster Image Set Routines in the HDF Library  2.1
Table 2.2Compression Scheme Codes  2.4
Table 2.3Interlace Scheme Codes  2.11
Table 3.1Palette I/O Routines in the HDF 
Library  3.2
Table 4.1Scientific Dataset Routines in the HDF Library  4.2
Table 5.1Long and Short Names for Annotation Routines  5.3
Table 6.1General Purpose Routines in the HDF Library  6.1
Table 7.1Scientific Dataset Routines in the HDF Library  7.1
Table A.1HDF Tags  A.2
Table C.1Long and Short Version FORTRAN Names  C.1
Table D.1Pathnames of NCSA HDF 
Directories  D.1