March 1993 6.1 NCSA HDF Calling Interfaces and Utilities NCSA HDF Command Line Utilities 6.1 National Center for Supercomputing Applications March 1993 Chapter 6 NCSA HDF Command Line Utilities Chapter Overview Introduction hdfls: Listing Basic Information about an HDF file hdfed: Editing an HDF File Basics Tutorial Session hdfed with the -batch Option fptohdf: Converting Floating-Point Data to SDS and/or RIS8 Basics Notes Examples Utilities for Working with Raster Image Sets ristosds: Converting several RIS8 Images to one 3D SDS r8tohdf: Converting 8-Bit Raster Images to HDF hdftor8: Extracting 8-Bit Raster Images and Palettes from an HDF File hdfcomp: Compress 8-bit Raster Images in an HDF File. r24hdf8: Converting 24-Bit Raw Raster Images to HDF 8-Bit Raster Images hdf24hdf8: Converting 24-bit HDF image to HDF 8-Bit HDF Image paltohdf: Converting a Raw Palette to HDF hdftopal: Extracting a Palette from an HDF file hdfrseq/hdfseq: Displaying Images hdfpack: Compacting an HDF file Chapter Overview A number of HDF command line utilities are available for working with HDF files. Currently available programs are described below. Introduction The command line utilities are application programs that can be executed by entering them at the command level, just like other UNIX commands. These utilities serve two purposes: 1) They make it possible for you to perform, at the command level, common operations on HDF files for which you would normally have to write your own program. For example, the utility r8tohdf is a program that takes a raw raster image from a file and stores it in an HDF file in a raster image set. 2) They provide capabilities for doing things with HDF files that would be very difficult to do under your own program control. For example, the utility hdfseq takes a raster image from an HDF file and displays it immediately on a Sun console. In addition to the command utilities supported by NCSA, a number of user-contributed utilities have been contributed by HDF users. Although they are not supported by NCSA, these utilities are distributed by NCSA via anonymous ftp in a directory called HDF/contrib. These utilities will not be discussed in this manual. Table 6.1 lists the names and the functions of the utilities described in this chapter. The sections that follow provide descriptions and examples of these routines. Table 6.1 Scientific Dataset Routines in the HDF Library Name Function hdfls displays the tags, ref numbers, and (optionally) lengths of data elements. hdfed lets you browse in an HDF file and manipulate some of the data. fptohdf converts floating-point data to HDF floating-point data and/or 8-bit raster images. ristsds converts a series RIS8 HDF files into a single 3D SDS HDF file r8tohdf converts one or more raw 8-bit images to HDF RIS8 format and writes them to a file, possibly with palettes. hdftor8 converts images and or palettes from HDF format to raw format and stores them in two corresponding sets of files. hdfcomp compresses 8-bit raster images from an HDF file, storing them in a new HDF file. r24hdf8 converts a raw RGB 24-bit image to an 8-bit RIS8 with a palette. hdf24hdf8 quantizes a HDF RGB 24 bit "pixel" image into a 8 bit image with RGB palette and stores it as a HDF 8-bit raster image file paltohdf converts a raw palette to HDF format. hdftopal converts palette in an HDF file to raw format. hdfseq/hdfrseq displays sequences of images directly to the screen from HDF files containing raster images. hdfpack compacts an HDF file by reading in all the objects in an HDF file and writing them out to a new file. hdfls: Listing Basic Information about an HDF File The utility hdfls provides a quick look at the tags, reference numbers, and (optionally) lengths of the data elements. The syntax for hdfls is: hdfls [-o] [-l] filename -o Order: Indicates that the reference numbers are to be displayed in ascending order. -l Long format: Displays more information about the file. Example 1 A file called aa.hdf contains three items associated with a raster image: (1) the image dimensions, (2) a palette, and (3) the raster image. To display information about the contents of the file, enter: hdfls aa.hdf The following is displayed: aa.hdf: Image Dimensions-8 (Raster-8) : (tag 200) Ref nos: 1 Image Palette-8 (Raster-8) : (tag 201) Ref nos: 3 Raster Image-8 (Raster-8) : (tag 202) Ref nos: 1 To display the same information together with the length of each data element, enter: hdfls -l aa.hdf The resulting display is: aa.hdf: Image Dimensions-8 (Raster-8) : (tag 200) Ref no 1 4 bytes Image Palette-8 (Raster-8) : (tag 201) Ref no 3 768 bytes Raster Image-8 (Raster-8) : (tag 202) Ref no 1 120000 bytes hdfed: Editing an HDF File Basics The utility hdfed allows sophisticated HDF users to manipulate the elements in an HDF file. These manipulations include selecting groups and showing information about them, dumping them to the output, writing them to new files, deleting them, inserting them, replacing, say, the palette of an RIS8 group, and editing the text labels and descriptions of any element. hdfed is designed primarily for uses who need to know about HDF files at the level of individual data elements. It is not designed to provide a high-level view of the contents of an HDF file. Other tools and utilities should be used for that purpose. To use hdfed effectively you should probably have access the manual "HDF Specifications," which describes in detail the various components of an HDF file. hdfed is modeled to some extent after ed, the UNIX line editor. When you invoke hdfed, your terminal screen acts as a window into an HDF file. Your initial view of the file is as a set of tags and reference numbers. Each tag/ref combination uniquely identifies a data object in the file. hdfed will not allow the user to arbitrarily modify binary data in the file or any element, though it allows modification of tag and reference numbers within strict constraints. The user should not attempt to alter individual bytes. It is acceptable, however, to replace an element with another of the same type. For the sake of the following discussion, certain terms need to be clarified: data object or object refers to the data descriptor of an object (tag/ref/offset/length) plus the data itself. data or data element refers to the record that the data descriptor points to. For a precise description of the data that is associated with a given tag consult the manual "HDF Specifications ". group refers to a predefined collection of data objects that correspond to a particular application. For instance, a "raster image group" refers to the collection of objects that are used to store all of the information in a Raster Image Set. Once you have opened an HDF file with hdfed, you can do several things with the file, including the following: * Select an HDF object to examine more closely. * Move forward or backward among the objects in the file. * Get information about an object (tag, ref, size, label). * Display a raster image using the ICR protocol. * Display a dump of any object. * Delete an object. * Annotate an object with a label or description.. * Write an object to another HDF file. * Write a data element in its binary form to a non-HDF file. * Close the file and exit, or open a new file. hdfed also has a small set of special commands, including a conditional statement, a looping statement, an alias command and an unalias command. A simple 'help' feature also exists. The syntax for hdfed is: hdfed [filename] [-nobackup] [-batch] If filename is present, the corresponding file is opened, and a backup is made of the file. Otherwise, a file may be opened from within the editor. Options - nobackup Specifies that no backup file is to be made. If this option is omitted, a backup file is automatically created. - batch Specifies that input to hdfed is to be input via a stream of hdfed commands, rather than interactively. To receive usage information, as well as a quick list of the hdfed commands, type the command: hdfed -help While you are using the editor, you receive the prompt: he> You can now enter hdfed commands. Many hdfed commands have qualifiers, or flags. For instance the info command may optionally be followed by -all, -long, -group, or -label. All of the commands and flags can be abbreviated to the extent that their abbreviations are unique. For example -he is an ambiguous abbreviation because it could stand for either the flag -hexadecimal or the flag -help; on the other hand, the flag -hel is not ambiguous. Table 6.2 lists the hdfed commands. Table 6.2 hdfed Commands Name Function help Provide help on use of hdfed open Open HDF file close Close HDF file revert Revert to original file next Go to next object/group that satisfies predicate prev Go to previous object/group that satisfies predicate info Show information about data object dump Display data in binary, ASCII, etc. display Display a raster image using ICR put Put data element as binary into raw file putr8 Put an ris8 group into raw file getr8 Get an ris8 group from raw file delete Delete an object/group write Write an object/group to another HDF file annotate Annotate an object if Conditional statement select Loop for each object alias Set or show aliases unalias Remove an alias wait Message and wait for return To obtain information about the usage of a command, type: -help Do not just type the command and expect a help line. Some commands, such as delete, do not need any argument, so this could have unfortunate results. The commands are described in the text that follows. help Print a help screen describing the basic purpose and functionality of hdfed. open This command is described above. close [-keep] Close current open file. -keep: causes backup file not to be deleted. revert Discard all changes made in hdfed. next [] Move to the next object that satisfies the predicate. are of the general form: or simply group (as in "next group") can be any of the following: tag, ref, image_size, or label. can be any of the following: "=", "!=", ">", "<", ">=", "<=" Examples: next group next (same as "next group". "group" is the default) next tag = 720 next ref = 2 next image_size < 1000 next label = "abc" prev [] Move to the next object that satisfies the predicate. (See "next" for examples of predicates. info [-all] [-long] [-group] [-label] Show information for one data object. -all Show info for all objects in file -long Show more info -group Organize info in group(s) -label Show label if any dump [-offset ] [-length ] [-decimal|-short|-byte|-octal|-hexadecimal |-float|-double|-ascii] Display the contents of the current object in the format specified. -offset Start offset -length Length to look at -decimal Decimal format [32 bit integers] -short Decimal format [16 bit integers] -byte Decimal format [8 bit integers] -octal Octal format [Default] -hexadecimal Hexadecimal format -float Float format [32 bit floats] -double Float format [64 bit floats] -ascii Ascii format display [-position ] [-expansion ] [-large] Display image on screen. (Only works where hdfseq works.) -position Image position on console screen -expansion Image expansion factor -large Make image as large as possible put [-file ] [-verbose] Put the raw binary of this object in a file -file Out file name (default "elt#.@") -verbose Output diagnostic info putr8 [-image ] [-palette ] [-verbose] Put an r8 group into raw image and palette files -image Image file name template (default "img#.@.%") -palette Palette file name template (default "pal#") -verbose To give output of steps taken getr8 [-palette ] [- raster|-rle|-imcomp] Get a r8 group from raw files -palette Raw palette file -raster No compression (default) -rle Run-length compression delete Delete this object or group. write [-attachto ] Write an element or group into another HDF file -attachto What element to attach annotation to (ONLY for writing annotations) annotate [-label|-descriptor] [-editor ] Edit an annotation -label Edit label (default) -descriptor Edit descriptor -editor Use editor (default EDITOR env value) if [] * end Execute commands if predicates are satisfied by element select [] * end Step through all elements in the file that satisfy the predicates and execute the commands on them. wait [] Print message and then wait for user to hit return Tutorial Session Figure 6.1 contains a tutorial in the form of a session using hdfed. Examples of almost all of the commands are given below. In the following script, bold characters represent those typed by a user. Plain text characters represent characters that were printed by the computer. In some cases, ellipses ("...") are used to indicate that more information would normally be printed. Figure 6.1 Tutorial Session zaphod|2% he he> ! This is a script of a session on the HDF editor. he> ! It is meant as an example for anyone learning to use he> ! the editor. he> ! The exclamation mark in the FIRST column starts ! he> ! a comment he> help he> ! help command he> help hdfed allows sophisticated HDF users to manipulate the elements in an HDF file. These manipulations include selecting groups ... open he> ! opening a file he> he> open -help open [-nobackup] -nobackup Don't make a backup for this file. he> he> open h1 he> Figure 6.1 Tutorial Session (continued) info he> ! look into the contents of this file he> ! using info he> he> info -all -label -long (1) Version Descriptor : (Tag 30) Ref: 1, Offset: 202, Length: 92 (bytes) (2) Scientific Data : (Tag 702) Ref: 2, Offset: 294, Length: 200 (bytes) (3) Number type : (Tag 106) Ref: 2, Offset: 494, Length: 4 (bytes) (4) SciData description : (Tag 701) Ref: 2, Offset: 498, Length: 22 (bytes) (5) SciData max/min : (Tag 707) Ref: 2, Offset: 520, Length: 4 (bytes) *(6) Numeric Data Group : (Tag 720) Ref: 2, Offset: 524, Length: 12 (bytes) Label: Experiment #1 (7) Data Id Label : (Tag 104) Ref: 3, Offset: 536, Length: 17 (bytes) (8) Scientific Data : (Tag 702) Ref: 4, Offset: 553, Length: 400 (bytes) (9) Number type : (Tag 106) Ref: 4, Offset: 953, Length: 4 (bytes) (10) SciData description : (Tag 701) Ref: 4, Offset: 957, Length: 22 (bytes) (11) Numeric Data Group : (Tag 720) Ref: 4, Offset: 979, Length: 8 (bytes) Label: Experiment #2 (12) Data Id Label : (Tag 104) Ref: 5, Offset: 987, Length: 17 (bytes) he> he> info -group -all **Group 1: Numeric Data Group : (Tag 720) Ref 2 Scientific Data : (Tag 702) Ref 2 SciData description : (Tag 701) Ref 2 SciData max/min : (Tag 707) Ref 2 **Group 2: Numeric Data Group : (Tag 720) Ref 4 Scientific Data : (Tag 702) Ref 4 SciData description : (Tag 701) Ref 4 **These do not belong to any group: Version Descriptor : (Tag 30) Ref 1 Number type : (Tag 106) Ref 2 Data Id Label : (Tag 104) Ref 3 Number type : (Tag 106) Ref 4 Data Id Label : (Tag 104) Ref 5 he> next he> ! Move in the file using next and prev. prev he> ! The move direction depends on the relative positions, predicates he> ! so it is often necessary to do an 'info -all' first he> he> info -all (1) Version Descriptor : (Tag 30) Ref 1 (2) Scientific Data : (Tag 702) Ref 2 (3) Number type : (Tag 106) Ref 2 (4) SciData description : (Tag 701) Ref 2 (5) SciData max/min : (Tag 707) Ref 2 *(6) Numeric Data Group : (Tag 720) Ref 2 (7) Data Id Label : (Tag 104) Ref 3 Figure 6.1 Tutorial Session (continued) (8) Scientific Data : (Tag 702) Ref 4 (9) Number type : (Tag 106) Ref 4 (10) SciData description : (Tag 701) Ref 4 (11) Numeric Data Group : (Tag 720) Ref 4 (12) Data Id Label : (Tag 104) Ref 5 he> * he> ! The '*' in the first column marks the current he> ! position. he> ! The next and prev commands work on predicates. he> ! If I now want to move to the max/min element, he> ! I can use the 'tag=' predicate he> he> prev tag=707 he> info (5) SciData max/min (SciData) : (tag 707), Ref: 2 he> he> ! This predicate persist for next and prev. he> ! That means that if I now do another 'next' he> ! it will look for a tag=707 he> he> next Reached end of file. Not moved. he> info (5) SciData max/min : (Tag 707) Ref 2 he> he> next group he> next group he> info (11) Numeric Data Group : (Tag 720) Ref 4 he> dump he> ! to see the binary representation of this element he> he> dump 0: 257400004 257200004 he> he> dump -short 0: 702 4 701 4 he> delete he> ! deleting groups he> he> ! If an element is required by other groups it is he> ! alone. However, this is not perfect since the way he> ! group membership is determined can be pretty ad hoc he> he> delete he> ! This deletes the Scientific Data Group. he> info -all (1) Version Descriptor : (Tag 30) Ref 1 (2) Scientific Data : (Tag 702) Ref 2 (3) Number type : (Tag 106) Ref 2 (4) SciData description : (Tag 701) Ref 2 (5) SciData max/min : (Tag 707) Ref 2 (6) Numeric Data Group : (Tag 720) Ref 2 (7) Data Id Label : (Tag 104) Ref 3 (8) Number type : (Tag 106) Ref 4 (9) Data Id Label : (Tag 104) Ref 5 he> he> ! Notice that the Numeric Data Group with he> ! ref #4 is missing, and now there are only he> ! 9 objects in the file. Figure 6.1 Tutorial Session (continued) he> annotate he> ! Annotations are labels and descriptors. he> he> prev group he> info -label (6) Numeric Data Group : (Tag 720) Ref 2 Label: Experiment #1 he> annotate -editor /usr/ucb/ex "/tmp/he5091.1" 1 line, 14 characters :p Experiment #1 :s/$/ / Experiment #1 :wq "/tmp/he5091.1" 1 line, 27 characters he> info -label (6) Numeric Data Group : (Tag 720) Ref 2 Label: Experiment #1 he> write he> ! Write object or group to another HDF file he> he> write test he> he> ! Let's look at the file 'test'. he> close;open test;info -all (1) Version Descriptor : (Tag 30) Ref 1 (2) Scientific Data : (Tag 702) Ref 2 (3) Number type : (Tag 106) Ref 2 (4) SciData description : (Tag 701) Ref 2 (5) SciData max/min : (Tag 707) Ref 2 *(6) Numeric Data Group : (Tag 720) Ref 2 he> he> close; he> display he> !We will open a file with some RIS8 images. he> he> open denm.HDF he> display he> he> ! display displays the current r8 group image via ICR. he> ! I.e. if you are using NCSA Telnet on a MacII, this he> ! would display the images from denm.hdf on your screen he> ! NOTE: not guaranteed to work otherwise. he> putr8 he> ! putr8 puts an r8 group into raw files he> he> putr8 -image my_image#.@.% -palette my_palette -verbose Writing to file: my_image8.10.10 Writing to file: my_palette he> select he> ! To step through a file and, say, putr8 on all r8 he> ! groups we can use the select command he> he> select tag=306 >> putr8 -image testImages# -palette testPalettes# -verbose >> end Writing to file: testImages8 Writing to file: testPalettes8 Writing to file: testImages14 Writing to file: testPalettes14 Writing to file: testImages21 Figure 6.1 Tutorial Session (continued) Writing to file: testPalettes21 he> he> ! select and if commands take the same predicates as he> ! next and pref. There are also the predicates he> ! "succeed" and "fail" that test the return status he> ! of the last command. he> put he> ! put puts an element into a binary file he> ! This is a dumb routine and does not know about the he> ! formats of the element he> he> put -file binary# he> put -file myBinary -verbose Writing to file: myBinary he> he> ! that's it for now he> revert;close;quit zaphod|2% hdfed with the -batch Option Sometimes we want to have hdfed execute a series of commands, without waiting for a prompt between commands. This process is useful when a certain sequence of hdfed commands is commonly used, as illustrated in the following shell script: #!/bin/csh -f set file=$1 shift hdfed -batch $file -nobackup << EOF info -all -group $* close quit EOF echo "" This shell script lists information about the groups in an HDF file. The "-batch" in the line that calls hdfed tells hdfed that the edit commands are to be taken from the stream of characters beginning on the next line and ending with the EOF symbol. fptohdf: Converting Floating-Point Data to SDS and/or RIS8 Basics fptohdf is a utility that converts 32-bit floating-point arrays (from either text files or HDF float32 scientific datasets) to either HDF 8-bit raster image sets (RIS8) or HDF scientific float32 datasets (SDS), or both, and stores the results in an HDF file (see Fig. 6.2). The image can be scaled about a mean value that is provided by the user. Figure 6.2 The fptohdf Utility The syntax of fptohdf is as follows: fptohdf infile [infile ...] -o outfile [out_opts] out_opts: [[-r] [[-e|-i] ] [-p palfile] -m ] [-f] * infile is a file containing a single floating-point array in either text or HDF SDS format. If the format is text, see "Notes" below on how it must be organized. * outfile is a file containing the converted dataset in HDF format. Depending on out_opts, outfile contains a scientific dataset and/or raster image set for each of the datasets in the input files. Options -r Stores as image in raster image set in output file -e Expands float data via pixel replication to produce image (default if -I option chosen) -i Applies bilinear interpolation when expanding float data to produce image when -e or -i options are chosen, these give the resolution in pixels of the desired image -p palfile Stores palette with image; get palette from HDF file palfile. -m Causes the data to be scaled around when generating the image, according to the following formulas: newmax = mean + 0.5*max(abs(max-mean),abs(mean-min)) newmin = mean - 0.5*max(abs(max-mean),abs(mean-min)) -f Stores as scientific dataset in output file (default) Notes * Image expansion is available via either pixel replication (-e) or bilinear interpolation (-i), but not both. * If the "-i" option is chosen, the expanded image must have dimensions that are greater than or equal to the dimensions of the original dataset * An optional palette can accompany the image by loading it from an HDF file that contains a palette. * Data from several input files (one set per input file) are stored as several datasets and/or images in one output file. Alternatively, a shell script can be used to call fptohdf repeatedly to convert data from several input files to several corresponding HDF files. * If an HDF file is used for input, it must contain an SDS. The SDS need only contain a dimension record and the data, but if it also contains max and min values and/or scales for the horizontal and vertical axes, these will be used also. ("Scales" are used for determining the gaps between the points on the axes. If the gaps are all the same, a uniform scale is given, such as "1.0 2.0 3.0 ... n". In an HDF file, scales may be omitted, but in a text file (see below) they must be included.) * If a text file is used for input, it must follow the format shown in Figure 6.3. ED. NOTE: Figures are not available in this plain text version of the specification. Figure 6.3 Format Used in a Text File for Input NOTE: There are nrows vertical axis scale values and ncols horizontal axis scale values. data1, data2, etc., are the floating- point data and are assumed to be ordered by rows, left to right and top to bottom. Examples Example 1 Convert floating-point data in file f1.txt to a SDS format, and store it as an SDS in HDF file o1: fptohdf f1.txt -o o1 Example 2 Convert floating-point data in file f2 to an 8-bit raster image and store it as an RIS8 in file o2: fptohdf f2 -o o2 -r Example 3 Convert floating-point data in file f3 to RIS8 format and SDS format and store both the RIS8 and the SDS in file o3: fptohdf f3 -o o3 -r -f Example 4 Convert floating-point data in file f4 to a 500 x 600 raster image, storing the corresponding RIS8 in file o4. Also store a palette from palfile with the image: fptohdf f4 -o o4 -r -e 500 600 -p palfile Example 5 Convert floating-point data in all files whose names begin with the letter 'f ' to 500 x 600 images and store the corresponding RIS8s in file o5: fptohdf f* -o o5 -r -i 500 600 Utilities for Working with Raster Image Sets There are three utility programs for working with HDF files that contain raster image sets. These routines can be executed interactively at the command level without being embedded in programs. ristosds: Converting several RIS8 Images to one 3D SDS The utility converts a series of HDF raster image files into a single HDF 3D SDS file. Each input file contains one or more raster images. All images should be of the same dimension sizes. If there is a palette associated with the images, the palette should be included in the first HDF file. Any subsequent palettes will be ignored. The syntax for this utility is as follows: ristosds { } -o where infile is a file containing one or more 8-bit raster images sets (RIS8), and outfile is the file that will contain the 3D scientific data set (SDS). Example. A directory contains 20 files named storm001, storm002, ... storm020. Each file contains a single RIS8 with a 100x200 image. We wish to combine these 20 images into a 32-bit float SDS with dimensions 100x200x20. We can do this by executing ristosds as follows: ristosds storm*.hdf -o storm.hdf r8tohdf: Converting 8-Bit Raster Images to HDF The utility r8tohdf converts one or more raw images to HDF RIS8 format and writes them to a file. The syntax for storing one RIS8 in a file using r8tohdf is as follows: r8tohdf rows cols outfile [-p palfile] {[-c],[-r], [-i]} imf1 imf2 ... where rows and cols are the number of rows and columns, respectively, of the raster image outfile is the file that will contain the raster image set, and imf1, imf2, and so forth, are files containing 8-bit raw raster images. Options -p palfile optionally stores a file containing a palette in the RIS8. If -p is not specified, no palette is stored in the RIS8. {[-c],[-r],[-i]} optionally chooses compression by run length encoding (-c), compression by the IMCOMP method (-i), or no compression (-r). The default is -r. Example 1 A 256 x 512 byte raw raster image is contained in a file called rawras, and the palette with which it is to be used is stored in a file called mypal. To convert this information to an RIS8 without compression and store the result in a file called ras.hdf, enter: r8tohdf 256 512 ras.hdf -p mypal rawras Example 2 A 800 x 1000 byte raw raster image is stored in a file called bigpic. You want to first convert this information to an RIS8 with run length encoding for compression and no palette, and then store the result in a file called bigpic.hdf. Enter: r8tohdf 800 1000 bigpic.hdf -c bigpic Example 3 Three 300 x 400 raw images are contained in files pic1, pic2, and pic3. To convert all three files to RIS8s with imcomp compression and store them in pic.hdf, enter: r8tohdf 300 400 pic.hdf -i pic1 pic2 pic3 Example 4 A combination of different types of raster image sets is to be stored in a file called ras.hdf. The image from file rawras1 is to be stored without a palette. The images from rawras2 are to be stored with a palette that is copied from a file called mypal. The images from rawras1 and rawras2 are to be compressed using run length encoding, and rawras3 is not to be compressed. All images are 256 x 512. r8tohdf 256 512 ras.hdf -c rawras1 -p mypal rawras2 -r rawras3 hdftor8: Extracting 8-Bit Raster Images and Palettes from an HDF File The utility hdftor8 extracts the images and or palettes from an HDF file and stores them in two sets of files that contain only images and palettes, respectively. The syntax for hdftor8 is as follows: hdftor8 hdf_file [-i] [-v] [-r image_file][-p palette_file] Where hdf_file is the file to extract images and palettes from, and image_file and palette_file are basic names of the files that will contain the images and palettes. These names are extended as follows: For each image file, the filename is given the extension ".#.@.%", where # stands for the image number from the original file, @ is the x dimension of the image, and % is the y dimension of the image. For each palette file, the filename is given the extension ".#", where # stands for the palette number from the original file. If no names are given for the image file, the default name "img.#.@.%" is used, where #, @ and % are defined as in the preceding paragraph. Similarly the default name for a palette file is "pal.#". Options -i puts the program in interactive mode, so you can specify filenames interactively. -v specifies verbose mode, providing descriptive messages. -r indicates that the file whose name follows is to hold images. -p indicates that the file whose name follows is to hold palettes. Example 5 A file called denm.hdf contains three 512 x 256 images and three palettes. To extract these images and palettes and put them in separate files, enter: hdftor8 denm.hdf Six files are produced with the names img1.512.256, img2.512.256, img3.512.256, pal.1, pal.2, and pal.3. hdfcomp: Compress 8-bit raster images in an HDF file. The utility hdfcomp reads in raster-8 images from an HDF file and create a new HDF containing the images in a compressed format. Images will be appended l file. If no names are given for the image file, the default name "img.#.@.%" is used, where #, @ and % are defined as in the preceding paragraph. Similarly the default name for a palette file is "pal.#". Options -i puts the program in interactive mode, so you can specify filenames interactively. -v specifies verbose mode, providing descriptive messages. -r indicates that the file whose name follows is to hold images. -p indicates that the file whose name follows is to hold palettes. Example 5 A file called denm.hdf contains three 512 x 256 images and three palettes. To extract these images and palettes and put them in separate files, enter: hdftor8 denm.hdf Six files are produced with the names img1.512.256, img2.512.256, img3.512.256, pal.1, pal.2, and pal.3. hdfcomp: Compress 8-bit raster images in an HDF file. The utility hdfcomp reads in raster-8 images from an HDF file and create a new HDF containing the images in a compressed format. Images will be appended to the output file, if it exists. The syntax for hdfcomp is: hdfcomp outfile {[-c],[-r],[-i]} imagefile... {[-c],[-r],[-i]} imagefile outfile file to store compressed images in imagefile file containing an HDF image Options: -r Store without compression (default) -c Store using RLE compression -i Store using IMCOMP compression (requires a palette in the HDF file) Example. A directory contains 20 files named storm001, storm002, ... storm020. Each file contains a single 8-bit image.. We wish to compress these 20 images using run-length encoding and store them in a single file called allcomp.hdf. We can do this by executing hdfcomp as follows: hdfcomp allcomp.hdf -c storm*.hdf r24hdf8: Converting 24-bit Raw Raster Image to HDF 8-Bit Raster Images The command line utility r24hdf8 quantizes a raw RGB 24-bit pixel image into an 8-bit image with a 256-color palette and stores both the palette and image in an HDF file. The syntax for r24hdf8 is: r24hdf8 x_dim y_dim r24_file hdf8_file x_dim is the x dimension of the image (horizontal size). y_dim is the y dimension of the image (vertical size). r24_file is a file containing the raw RGB 24 bit image. The order of pixels is left to right and top to bottom. Each pixel is three contiguous bytes: red byte, green byte, and blue byte. Use filter ptox to convert from "planar" to "pixel" where planar means all red bytes for the whole image, followed by all green bytes for the whole image, followed by all blue bytes for the whole image. hdf8_file is the output file, is an HDF file with one 8-bit raster image set; i.e. 8-bit image, dimensions, and RGB palette. hdf24hdf8: Converting 24-bit HDF image to HDF 8- Bit HDF Image The utility hdf24hdf8 quantizes a HDF RGB 24 bit "pixel" image into a 8 bit image with 256-color palette and stores both the palette and image in an HDF file. The syntax for hdf24hdf8 is: hdf24hdf8 r24_file hdf8_file r24_file is the input file, an HDF file containing the HDF RGB 24-bit raster image hdf8_file is the output file containing one 8-bit RIS with an RGB palette. paltohdf: Converting a Raw Palette to HDF paltohdf converts a raw palette to HDF format. The incoming palette is assumed to have 768 bytes organized in the following order: 256 red values, 256 green values, and 256 blue values. The palette in the HDF file will have the RGB values interlaced: RGB RGB RGB... This is standard HDF format for 8-bit palettes. The syntax for paltohdf is: paltohdf rawpalfile hdffile rawpalfile is a 768-byte input file with the red, green, and blue components stored as described above. hdffile, the output file, is an HDF file. If hdffile does not exist, it is created and the palette is added to it. If it already exists, the palette is appended to it. hdftopal: Extracting a palette from an HDF file hdftopal converts a palette from an HDF file to a raw palette in a raw palette file. The outgoing palette will have 768 bytes: first 256 red values, then 256 greens, then 256 blues. The syntax for hdftopal is: hdftopal hdffile rawpalfile hdffile, the input file, is an HDF file containing a palette. rawpalfile is a 768-byte output file with the red, green, and blue components stored as described above. hdfrseq and hdfseq: Displaying Images The utilities hdfseq and hdfrseq display sequences of images, one after the other, from files containing raster image sets. Although hdfseq and hdfrseq perform essentially the same function, the situations in which they are used are different. hdfseq displays images on a Sun-3 console and on any SGI IRIS that has gllib, when those images are stored at the Sun 3 or IRIS workstation. When hdfseq executes on a file, it causes the raster image to be displayed immediately on the console. hdfrseq performs the same operation, only remotely, via a terminal emulator such as Telnet 2.3 or Teltool 1.2. (The "r" in hdfrseq stands for remote.) When hdfrseq executes on a file, it converts the image from RIS8 format to NCSA's ICR (interactive color raster) format and sends it to the receiving terminal. ICR is a protocol that is easy to transmit to a remote display station. If the receiving software on the display station can decipher the ICR protocol, it displays the image on the console. In a typical application, the display station would be running a program, such as NCSA Telnet (Version 2.3 or later) or NCSA Teltool (Version 1.2 or later), that understands ICR and immediately converts the incoming stream to a screen display. The syntax for hdfseq is: hdfseq [-s] [-l] [-p xloc yloc] [-e expansion] file1 file2 ... file1, file2, and so forth are HDF files that contain raster image sets. Only one image is displayed per file. If more than one file is listed, the corresponding images are displayed in sequence, that is, in the order in which the files are listed. Each new image overwrites the preceding image on the screen. Options -s single step through the images. Once an image is displayed, it remains on the screen until you press RETURN to display the next image or enter Q to quit. -l makes the image as large as possible on the screen. -p xloc yloc places the upper left corner of the display at position (xloc, yloc) on the screen. -e expansion expands the image by the expansion factor specified by expansion. The syntax for hdfrseq is exactly the same. Example 6 Five images are stored in RIS8 form in the files star1, star2, star3, star4, and star5. You want to use hdfrseq to display all five images, in sequence, but with a pause between them. To make them appear on screen three times their normal size, enter: hdfrseq -s -e 3 star1 star2 star3 star4 star5 hdfpack: Compacting an HDF file The utility hdfpack compacts an HDF file by reading in all the data elements in the file and writing them out to a new file. hdfpack [-i | -b] [-d#] [-t#] -b Don't coalesce linked-block elements -i Interactive mode; prompt for each linked-block element -d# Force the output file to have # DDs per DD block -t# Force output file to have # linked blocks per table entry Only one of options b and i can be specified. Examples To compact the file aa.hdf and put the result in aa.pck, enter hdfpack aa.cdf aa.pck Suppose the file bb.hdf contains elements stored as sequences of linked blocks. To compact this file but leave the linked-block elements intact, and put the result in bb.blk, enter hdfpack -b bb.hdf bb.blk