home *** CD-ROM | disk | FTP | other *** search
/ Encyclopedia of Graphics File Formats Companion / GFF_CD.ISO / formats / hdf / spec / hdf3_2_6.txt < prev    next >
Text File  |  1994-06-01  |  40KB  |  1,269 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. March 1993
  8.  
  9.                                                                 
  10.  
  11.  
  12.  
  13.  
  14. 6.1    NCSA HDF Calling Interfaces and Utilities
  15.  
  16. NCSA HDF Command Line Utilities    6.1
  17.  
  18. National Center for Supercomputing Applications
  19.  
  20. March 1993
  21.  
  22.                                                                 
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29. Chapter 6    NCSA HDF Command Line Utilities
  30.  
  31.  
  32.  
  33. Chapter Overview
  34.  
  35. Introduction
  36. hdfls:  Listing Basic Information about an HDF file
  37. hdfed:  Editing an HDF File
  38. Basics
  39. Tutorial Session
  40. hdfed with the -batch Option
  41. fptohdf:  Converting Floating-Point Data to SDS and/or RIS8
  42. Basics
  43. Notes
  44. Examples
  45. Utilities for Working with Raster Image Sets
  46. ristosds:  Converting several RIS8 Images to one 3D SDS
  47. r8tohdf:  Converting 8-Bit Raster Images to HDF
  48. hdftor8:  Extracting 8-Bit Raster Images and Palettes from an HDF File
  49. hdfcomp:  Compress 8-bit Raster Images in an HDF File.
  50. r24hdf8:  Converting 24-Bit Raw Raster Images to HDF 8-Bit Raster Images
  51. hdf24hdf8:  Converting 24-bit HDF image to HDF 8-Bit HDF Image
  52. paltohdf:  Converting a Raw Palette to HDF
  53. hdftopal:  Extracting a Palette from an HDF file
  54. hdfrseq/hdfseq:  Displaying Images
  55. hdfpack: Compacting an HDF file
  56.  
  57.  
  58.  
  59. Chapter Overview
  60.  
  61. A number of HDF command line utilities are available for working 
  62. with HDF files. Currently available programs are described below.
  63.  
  64.  
  65. Introduction
  66.  
  67. The command line utilities are application programs that can be 
  68. executed by entering them at the command level, just like other 
  69. UNIX commands. These utilities serve two purposes:
  70.  
  71. 1) They make it possible for you to perform, at the command 
  72. level, common operations on HDF files for which you would 
  73. normally have to write your own program. For example, the 
  74. utility r8tohdf is a program that takes a raw raster image from a 
  75. file and stores it in an HDF file in a raster image set.
  76.  
  77. 2) They provide capabilities for doing things with HDF files 
  78. that would be very difficult to do under your own program 
  79. control. For example, the utility hdfseq takes a raster image 
  80. from an HDF file and displays it immediately on a Sun console.
  81.  
  82. In addition to the command utilities supported by NCSA, a number 
  83. of user-contributed utilities have been contributed by HDF users.  
  84. Although they are not supported by NCSA, these utilities are 
  85. distributed by NCSA via anonymous ftp in a directory called 
  86. HDF/contrib.  These utilities will not be discussed in this manual.
  87.  
  88. Table 6.1 lists the names and the functions of the utilities 
  89. described in this chapter. The sections that follow provide 
  90. descriptions and examples of these routines.
  91.  
  92. Table 6.1    Scientific Dataset Routines in the HDF Library
  93.  
  94. Name    Function
  95.  
  96. hdfls    displays the tags, ref numbers, and (optionally) lengths of 
  97.     data elements.
  98.  
  99. hdfed    lets you browse in an HDF file and manipulate some of the data. 
  100.  
  101. fptohdf    converts floating-point data to HDF floating-point data 
  102.     and/or 8-bit raster images.
  103.  
  104. ristsds    converts a series RIS8 HDF files into a single 3D SDS HDF file
  105.  
  106. r8tohdf    converts one or more raw 8-bit images to HDF RIS8 format and 
  107.     writes them to a file, possibly with palettes.
  108.  
  109. hdftor8    converts images and or palettes from HDF format to raw format 
  110.     and stores them in two corresponding sets of files.
  111.  
  112. hdfcomp    compresses 8-bit raster images from an HDF file, storing 
  113.     them in a new HDF file.
  114.  
  115. r24hdf8    converts a raw RGB 24-bit image to an 8-bit RIS8 with a palette.
  116.  
  117. hdf24hdf8 quantizes a HDF RGB 24 bit "pixel" image into a 
  118.     8 bit image with RGB palette and stores it as a HDF 8-bit 
  119.     raster image file
  120.  
  121. paltohdf converts a raw palette to HDF format.
  122.  
  123. hdftopal converts palette in an HDF file to raw format.
  124.  
  125. hdfseq/hdfrseq    displays sequences of images directly to the screen     
  126.     from  HDF files containing raster images.
  127.  
  128. hdfpack    compacts an HDF file by reading in all the objects in an 
  129.     HDF file and writing them out to a new file.
  130.  
  131.  
  132. hdfls:   Listing Basic Information about an HDF File
  133.  
  134. The utility hdfls provides a quick look at the tags, reference 
  135. numbers, and (optionally) lengths of the data elements. The syntax 
  136. for hdfls is:
  137.  
  138. hdfls [-o] [-l] filename
  139.  
  140.  
  141. -o    Order: Indicates that the reference numbers are to be 
  142. displayed in ascending order.
  143.  
  144. -l    Long format: Displays more information about the file.
  145.  
  146.  
  147. Example 1
  148.  
  149. A file called aa.hdf contains three items associated with a raster 
  150. image:  (1) the image dimensions, (2) a palette, and (3) the raster 
  151. image. To display information about the contents of the file, enter:
  152.  
  153. hdfls aa.hdf
  154.  
  155.  
  156. The following is displayed:
  157.  
  158. aa.hdf:
  159. Image Dimensions-8  (Raster-8)  : (tag 200)
  160.     Ref nos: 1
  161. Image Palette-8     (Raster-8)  : (tag 201)
  162.     Ref nos: 3
  163. Raster Image-8      (Raster-8)  : (tag 202)
  164.     Ref nos: 1
  165.  
  166.  
  167. To display the same information together with the length of each 
  168. data element, enter:
  169.  
  170. hdfls -l aa.hdf
  171.  
  172.  
  173. The resulting display is:
  174.  
  175. aa.hdf:
  176. Image Dimensions-8  (Raster-8)  : (tag 200)
  177.         Ref no      1          4 bytes
  178.  
  179. Image Palette-8     (Raster-8)  : (tag 201)
  180.         Ref no      3        768 bytes
  181.  
  182. Raster Image-8      (Raster-8)  : (tag 202)
  183.         Ref no      1     120000 bytes
  184.  
  185.  
  186. hdfed:   Editing an HDF File
  187.  
  188. Basics
  189.  
  190. The utility hdfed allows sophisticated HDF users to manipulate 
  191. the elements in an HDF file. These manipulations include 
  192. selecting groups and showing information about them, dumping 
  193. them to the output, writing them to new files, deleting them, 
  194. inserting them, replacing, say, the palette of an RIS8 group, and 
  195. editing the text labels and descriptions of any element.
  196.  
  197. hdfed  is designed primarily for uses who need to know about HDF 
  198. files at the level of individual data elements.  It is not designed to 
  199. provide a high-level view of the contents of an HDF file.  Other 
  200. tools and utilities should be used for that purpose.  To use hdfed 
  201. effectively you should probably have access the manual "HDF 
  202. Specifications," which describes in detail the various components 
  203. of an HDF file.
  204.  
  205. hdfed is modeled to some extent after ed, the UNIX line editor. 
  206. When you invoke hdfed, your terminal screen acts as a window 
  207. into an HDF file. Your initial view of the file is as a set of tags and 
  208. reference numbers. Each tag/ref combination uniquely identifies a 
  209. data object in the file. 
  210.  
  211. hdfed will not allow the user to arbitrarily modify binary data in 
  212. the file or any element, though it allows modification of tag and 
  213. reference numbers within strict constraints.  The user should not 
  214. attempt to alter individual bytes.  It is acceptable, however, to 
  215. replace an element with another of the same type.
  216.  
  217. For the sake of the following discussion, certain terms need to be 
  218. clarified:
  219.  
  220. data object  or object refers to the data descriptor of an object 
  221. (tag/ref/offset/length) plus the data itself. 
  222.  
  223. data  or data element  refers to the record that the data descriptor 
  224. points to.  For a precise description of the data that is 
  225. associated with a given tag consult the manual "HDF 
  226. Specifications ". 
  227.  
  228. group refers to a predefined collection of data objects that 
  229. correspond to a particular application. For instance, a "raster 
  230. image group" refers to the collection of objects that are used to 
  231. store all of the information in a Raster Image Set.
  232.  
  233. Once you have opened an HDF file with hdfed, you can do several 
  234. things with the file, including the following:
  235.  
  236. *  Select an HDF object to examine more closely.
  237. *  Move forward or backward among the objects in the file.
  238. *  Get information about an object (tag, ref, size, label).
  239. *  Display a raster image  using the ICR protocol.
  240. *  Display a dump of any object.
  241. *  Delete an object.
  242. *  Annotate an object with a label or description..
  243. *  Write an object to another HDF file.
  244. *  Write a data element in its binary form to a non-HDF file.
  245. *  Close the file and exit, or open a new file.
  246.  
  247. hdfed also has a small set of special commands, including a 
  248. conditional statement, a looping statement, an alias command and 
  249. an unalias command. A simple 'help' feature also exists.
  250.  
  251. The syntax for hdfed is:
  252.  
  253. hdfed [filename] [-nobackup] [-batch]
  254.  
  255.  
  256.  
  257. If filename is present, the corresponding file is opened, and a 
  258. backup is made of the file. Otherwise, a file may be opened from 
  259. within the editor. 
  260.  
  261.  
  262. Options
  263.  
  264. - nobackup
  265.     Specifies that no backup file is to be made. If this option
  266.     is omitted, a backup file is automatically created.
  267.  
  268. - batch    
  269.     Specifies that input to hdfed is to be input via a stream of
  270.     hdfed commands, rather than interactively.
  271.  
  272. To receive usage information, as well as a quick list of the hdfed 
  273. commands, type the command:
  274.  
  275. hdfed -help
  276.  
  277.  
  278. While you are using the editor, you receive the prompt:
  279.  
  280. he>
  281.  
  282.  
  283. You can now enter hdfed commands. 
  284.  
  285. Many hdfed commands have qualifiers, or flags. For instance the 
  286. info command may optionally be followed by  -all, -long, 
  287. -group, or -label. 
  288.  
  289. All of the commands and flags can be abbreviated to the extent 
  290. that their abbreviations are unique. For example -he is an 
  291. ambiguous abbreviation because it could stand for either the flag 
  292. -hexadecimal or the flag -help; on the other hand, the flag 
  293. -hel is not ambiguous.
  294.  
  295.  
  296. Table 6.2 lists the hdfed commands.  
  297.  
  298. Table 6.2    hdfed Commands
  299.  
  300. Name    Function
  301.  
  302. help    Provide help on use of hdfed
  303. open    Open HDF file
  304. close    Close HDF file
  305. revert    Revert to original file
  306. next    Go to next object/group that satisfies predicate
  307. prev    Go to previous object/group that satisfies 
  308.     predicate
  309. info    Show information about data object
  310. dump    Display data in binary, ASCII, etc.
  311. display    Display a raster image using ICR
  312. put    Put data element as binary into raw file
  313. putr8    Put an ris8 group into raw file
  314. getr8    Get an ris8 group from raw file
  315. delete    Delete an object/group
  316. write    Write an object/group to another HDF file
  317. annotate    Annotate an object
  318. if    Conditional statement
  319. select    Loop for each object
  320. alias    Set or show aliases
  321. unalias    Remove an alias
  322. wait    Message and wait for return
  323.  
  324. To obtain information about the usage of a command, type:
  325.  
  326. <command> -help
  327.  
  328.  
  329. Do not just type the command and expect a help line. Some 
  330. commands, such as delete, do not need any argument, so this could 
  331. have unfortunate results. The commands are described in the text 
  332. that follows.
  333.  
  334. help
  335.  
  336. Print a help screen describing the basic purpose and 
  337. functionality of hdfed.
  338.  
  339. open
  340.  
  341. This command is described above.
  342.  
  343. close [-keep]
  344.  
  345. Close current open file.
  346. -keep:    causes backup file not to be deleted.
  347.  
  348. revert
  349.  
  350. Discard all changes made in hdfed.
  351.  
  352. next [<predicates>]
  353.  
  354. Move to the next object that satisfies the predicate.
  355.  
  356. <predicates> are of the general form:
  357.     <item> <comparator> <value>
  358.     or simply group (as in "next group")
  359.  
  360. <item> can be any of the following:
  361.         tag, ref, image_size,  or label.
  362.  
  363. <comparator> can be any of the following:
  364.         "=", "!=", ">", "<", ">=", "<="
  365.  
  366. Examples: 
  367.     next group
  368.     next     (same as "next group". "group" is the default)
  369.     next tag = 720
  370.     next ref = 2
  371.     next image_size < 1000
  372.     next label = "abc"
  373.  
  374. prev [<predicates>]
  375.  
  376. Move to the next object that satisfies the predicate.  (See "next" 
  377. for examples of predicates.
  378.  
  379. info [-all] [-long] [-group] [-label]
  380.  
  381. Show information for one data object.
  382. -all    Show info for all objects in file
  383. -long     Show more info
  384. -group     Organize info in group(s)
  385. -label    Show label if any
  386.  
  387. dump [-offset <offset>] [-length <len>]
  388.  
  389. [-decimal|-short|-byte|-octal|-hexadecimal
  390. |-float|-double|-ascii]
  391. Display the contents of the current object in the format 
  392. specified.
  393. -offset     Start offset
  394. -length     Length to look at
  395. -decimal    Decimal format [32 bit integers]
  396. -short     Decimal format   [16 bit integers]
  397. -byte     Decimal format    [8 bit integers]
  398. -octal     Octal format [Default]
  399. -hexadecimal    Hexadecimal format
  400. -float     Float format   [32 bit floats]
  401. -double    Float format  [64 bit floats]
  402. -ascii    Ascii format
  403.  
  404. display [-position <xpos> <ypos>] 
  405.  
  406. [-expansion <exp>] [-large]
  407. Display image on screen. (Only works where hdfseq works.)
  408. -position      Image position on console screen
  409. -expansion      Image expansion factor
  410. -large     Make image as large as possible
  411.  
  412. put [-file <file>] [-verbose]
  413.  
  414. Put the raw binary of this object in a file
  415. -file     Out file name (default "elt#.@")
  416. -verbose     Output diagnostic info
  417.  
  418. putr8 [-image <img>] [-palette <pal>] [-verbose]
  419.  
  420. Put an r8 group into raw image and palette files
  421. -image     Image file name template (default "img#.@.%")
  422. -palette     Palette file name template (default "pal#")
  423. -verbose     To give output of steps taken
  424.  
  425. getr8 <image> <xdim> <ydim> [-palette <palette>] [-
  426.  
  427. raster|-rle|-imcomp]
  428. Get a r8 group from raw files
  429. -palette    Raw palette file
  430. -raster    No compression (default)
  431. -rle    Run-length compression
  432.  
  433. delete
  434.  
  435. Delete this object or group.
  436.  
  437. write <file> [-attachto <atag> <aref>]
  438.  
  439. Write an element or group into another HDF file
  440. -attachto    What element to attach annotation to
  441.         (ONLY for writing annotations)
  442.  
  443. annotate [-label|-descriptor] [-editor <editor>]
  444.  
  445. Edit an annotation
  446. -label    Edit label (default)
  447. -descriptor    Edit descriptor
  448. -editor    Use editor (default EDITOR env value)
  449.  
  450. if [<predicates>]
  451.  
  452.     <commands>*
  453.  
  454. end
  455.  
  456. Execute commands if predicates are satisfied by element
  457.  
  458. select [<predicates>]
  459. <commands>*
  460. end
  461.  
  462. Step through all elements in the file that satisfy the predicates 
  463. and execute the commands on them.
  464.  
  465. wait [<message>]
  466.  
  467. Print message and then wait for user to hit return
  468.  
  469.  
  470. Tutorial Session
  471.  
  472. Figure 6.1 contains a tutorial in the form of a session using hdfed. 
  473. Examples of almost all of the commands are given below. In the 
  474. following script, bold characters represent those typed by a user. 
  475. Plain text characters represent characters that were printed by 
  476. the computer.  In some cases, ellipses ("...") are used to indicate 
  477. that more information would normally be printed.
  478.  
  479. Figure 6.1    Tutorial Session
  480.  
  481.     zaphod|2% he
  482.     he> ! This is a script of a session on the HDF editor.
  483.     he> ! It is meant as an example for anyone learning to use 
  484.     he> ! the editor.
  485.     he> ! The exclamation mark in the FIRST column starts 
  486. !    he> ! a comment
  487.     he> 
  488. help    he> ! help command
  489.     he> help
  490.     hdfed allows sophisticated HDF users to manipulate the 
  491.     elements in an HDF file. These manipulations include selecting groups 
  492.     ...
  493. open    he> ! opening a file
  494.     he> 
  495.     he> open -help
  496.     open <file> [-nobackup]
  497.     -nobackup    Don't make a backup for this file.
  498.     he> 
  499.     he> open h1
  500.     he> 
  501.  
  502. Figure 6.1    Tutorial Session (continued)
  503. info    he> ! look into the contents of this file
  504.     he> ! using info
  505.     he> 
  506.     he> info -all -label -long
  507.      (1)    Version Descriptor            : (Tag 30)
  508.             Ref: 1, Offset: 202, Length: 92 (bytes)
  509.      (2)    Scientific Data               : (Tag 702)
  510.             Ref: 2, Offset: 294, Length: 200 (bytes)
  511.      (3)    Number type                   : (Tag 106)
  512.             Ref: 2, Offset: 494, Length: 4 (bytes)
  513.      (4)    SciData description           : (Tag 701)
  514.             Ref: 2, Offset: 498, Length: 22 (bytes)
  515.      (5)    SciData max/min               : (Tag 707)
  516.             Ref: 2, Offset: 520, Length: 4 (bytes)
  517.     *(6)    Numeric Data Group            : (Tag 720)
  518.             Ref: 2, Offset: 524, Length: 12 (bytes)
  519.             Label: Experiment #1
  520.      (7)    Data Id Label                 : (Tag 104)
  521.             Ref: 3, Offset: 536, Length: 17 (bytes)
  522.      (8)    Scientific Data               : (Tag 702)
  523.             Ref: 4, Offset: 553, Length: 400 (bytes)
  524.      (9)    Number type                   : (Tag 106)
  525.             Ref: 4, Offset: 953, Length: 4 (bytes)
  526.      (10)   SciData description           : (Tag 701)
  527.             Ref: 4, Offset: 957, Length: 22 (bytes)
  528.      (11)   Numeric Data Group            : (Tag 720)
  529.             Ref: 4, Offset: 979, Length: 8 (bytes)
  530.             Label: Experiment #2
  531.      (12)   Data Id Label                 : (Tag 104)
  532.             Ref: 5, Offset: 987, Length: 17 (bytes)
  533.     he>
  534.     he> info -group -all
  535.     **Group 1:
  536.             Numeric Data Group            : (Tag 720) Ref 2
  537.             Scientific Data               : (Tag 702) Ref 2
  538.             SciData description           : (Tag 701) Ref 2
  539.             SciData max/min               : (Tag 707) Ref 2
  540.     **Group 2:
  541.             Numeric Data Group            : (Tag 720) Ref 4
  542.             Scientific Data               : (Tag 702) Ref 4
  543.             SciData description           : (Tag 701) Ref 4
  544.     
  545.     **These do not belong to any group:
  546.             Version Descriptor            : (Tag 30) Ref 1
  547.             Number type                   : (Tag 106) Ref 2
  548.             Data Id Label                 : (Tag 104) Ref 3
  549.             Number type                   : (Tag 106) Ref 4
  550.             Data Id Label                 : (Tag 104) Ref 5
  551.     he> 
  552. next    he> ! Move in the file using next and prev.
  553. prev    he> ! The move direction depends on the relative positions,
  554. predicates he> ! so it is often necessary to do an 'info -all' first
  555.     he> 
  556.     he> info -all
  557.      (1)    Version Descriptor            : (Tag 30) Ref 1
  558.      (2)    Scientific Data               : (Tag 702) Ref 2
  559.      (3)    Number type                   : (Tag 106) Ref 2
  560.      (4)    SciData description           : (Tag 701) Ref 2
  561.      (5)    SciData max/min               : (Tag 707) Ref 2
  562.     *(6)    Numeric Data Group            : (Tag 720) Ref 2
  563.      (7)    Data Id Label                 : (Tag 104) Ref 3
  564.  
  565. Figure 6.1    Tutorial Session (continued)
  566.  
  567.      (8)    Scientific Data               : (Tag 702) Ref 4
  568.      (9)    Number type                   : (Tag 106) Ref 4
  569.      (10)   SciData description           : (Tag 701) Ref 4
  570.      (11)   Numeric Data Group            : (Tag 720) Ref 4
  571.      (12)   Data Id Label                 : (Tag 104) Ref 5
  572.     he> 
  573. *    he> ! The '*' in the first column marks the current
  574.     he> ! position.
  575.     he> ! The next and prev commands work on predicates.
  576.     he> ! If I now want to move to the max/min element,
  577.     he> ! I can use the 'tag=' predicate
  578.     he> 
  579.     he> prev tag=707
  580.     he> info 
  581.      (5) SciData max/min     (SciData)   : (tag 707), Ref: 2
  582.     he> 
  583.     he> ! This predicate persist for next and prev. 
  584.     he> ! That means that if I now do another 'next'
  585.     he> ! it will look for a tag=707
  586.     he> 
  587.     he> next
  588.     Reached end of file. Not moved.
  589.     he> info
  590.      (5)   SciData max/min               : (Tag 707) Ref 2
  591.     he> 
  592.     he> next group
  593.     he> next group
  594.     
  595.     he> info
  596.      (11)   Numeric Data Group            : (Tag 720) Ref 4
  597.     he> 
  598. dump    he> ! to see the binary representation of this element
  599.     he> 
  600.     he> dump 
  601.     0:  257400004  257200004
  602.     he> 
  603.     he> dump -short
  604.     0:        702          4        701          4
  605.     he> 
  606. delete    he> ! deleting groups
  607.     he> 
  608.     he> ! If an element is required by other groups it is
  609.     he> ! alone.  However, this is not perfect since the way
  610.     he> ! group membership is determined can be pretty ad hoc
  611.     he> 
  612.     he> delete
  613.     he> ! This deletes the Scientific Data Group.
  614.     he> info -all
  615.      (1)    Version Descriptor            : (Tag 30) Ref 1
  616.      (2)    Scientific Data               : (Tag 702) Ref 2
  617.      (3)    Number type                   : (Tag 106) Ref 2
  618.      (4)    SciData description           : (Tag 701) Ref 2
  619.      (5)    SciData max/min               : (Tag 707) Ref 2
  620.      (6)    Numeric Data Group            : (Tag 720) Ref 2
  621.      (7)    Data Id Label                 : (Tag 104) Ref 3
  622.      (8)    Number type                   : (Tag 106) Ref 4
  623.      (9)    Data Id Label                 : (Tag 104) Ref 5
  624.     he> 
  625.     he> ! Notice that the Numeric Data Group with 
  626.     he> ! ref #4 is missing, and now there are only
  627.     he> ! 9 objects in the file.
  628.  
  629. Figure 6.1    Tutorial Session (continued)
  630.  
  631.     he> 
  632. annotate    he> ! Annotations are labels and descriptors.
  633.     he> 
  634.     he> prev group
  635.     he> info -label
  636.      (6)    Numeric Data Group            : (Tag 720) Ref 2
  637.             Label: Experiment #1
  638.     he> annotate -editor /usr/ucb/ex
  639.     "/tmp/he5091.1" 1 line, 14 characters
  640.     :p
  641.     Experiment #1
  642.     :s/$/ <more stuff>/
  643.     Experiment #1 <more stuff>
  644.     :wq
  645.     "/tmp/he5091.1" 1 line, 27 characters
  646.     he> info -label
  647.      (6)    Numeric Data Group            : (Tag 720) Ref 2
  648.             Label: Experiment #1 <more stuff>
  649.     he> 
  650. write    he> ! Write object or group to another HDF file
  651.     he> 
  652.     he> write test
  653.     he> 
  654.     he> ! Let's look at the file 'test'.
  655.     he> close;open test;info -all
  656.      (1)    Version Descriptor            : (Tag 30) Ref 1
  657.      (2)    Scientific Data               : (Tag 702) Ref 2
  658.      (3)    Number type                   : (Tag 106) Ref 2
  659.      (4)    SciData description           : (Tag 701) Ref 2
  660.      (5)    SciData max/min               : (Tag 707) Ref 2
  661.     *(6)    Numeric Data Group            : (Tag 720) Ref 2
  662.     he> 
  663.     he> close;
  664.     he> 
  665. display    he> !We will open a file with some RIS8 images.
  666.     he> 
  667.     he> open denm.HDF
  668.     he> display
  669.     he>
  670.     he> ! display displays the current r8 group image via ICR.
  671.     he> ! I.e. if you are using NCSA Telnet on a MacII, this
  672.     he> ! would display the images from denm.hdf on your screen
  673.     he> ! NOTE: not guaranteed to work otherwise.
  674.     he> 
  675. putr8    he> ! putr8 puts an r8 group into raw files
  676.     he> 
  677.     he> putr8 -image my_image#.@.% -palette my_palette -verbose
  678.     Writing to file: my_image8.10.10
  679.     Writing to file: my_palette
  680.     he> 
  681. select    he> ! To step through a file and, say, putr8 on all r8
  682.     he> ! groups we can use the select command
  683.     he> 
  684.     he> select tag=306
  685.     >> putr8 -image testImages# -palette testPalettes# -verbose
  686.     >> end
  687.     Writing to file: testImages8
  688.     Writing to file: testPalettes8
  689.     Writing to file: testImages14
  690.     Writing to file: testPalettes14
  691.     Writing to file: testImages21
  692.  
  693. Figure 6.1    Tutorial Session (continued)
  694.  
  695.     Writing to file: testPalettes21
  696.     he> 
  697.     he> ! select and if commands take the same predicates as
  698.     he> ! next and pref.  There are also the predicates 
  699.     he> ! "succeed" and "fail" that test the return status
  700.     he> ! of the last command.
  701.     he> 
  702. put    he> ! put puts an element into a binary file
  703.     he> ! This is a dumb routine and does not know about the
  704.     he> ! formats of the element
  705.     he> 
  706.     he> put -file binary#
  707.     he> put -file myBinary -verbose
  708.     Writing to file: myBinary
  709.     he> 
  710.     he> ! that's it for now
  711.     he> revert;close;quit
  712.     zaphod|2% 
  713.  
  714.  
  715.  
  716. hdfed with the -batch Option
  717.  
  718. Sometimes we want to have hdfed execute a series of commands, 
  719. without waiting for a prompt between commands. This process is 
  720. useful when a certain sequence of hdfed commands is commonly 
  721. used, as illustrated in the following shell script:
  722.  
  723. #!/bin/csh -f
  724. set file=$1
  725. shift
  726. hdfed -batch $file -nobackup << EOF
  727. info -all -group $*
  728. close
  729. quit
  730. EOF
  731. echo ""
  732.  
  733. This shell script lists information about the groups in an HDF 
  734. file. The "-batch"  in the line that calls hdfed tells hdfed that the 
  735. edit commands are to be taken from the stream of characters 
  736. beginning on the next line and ending with the EOF symbol.
  737.  
  738.  
  739.  
  740. fptohdf:   Converting Floating-Point Data to SDS and/or RIS8
  741.  
  742. Basics
  743.  
  744. fptohdf is a utility that converts 32-bit floating-point arrays  
  745. (from either text files or HDF float32 scientific datasets) to either 
  746. HDF 8-bit raster image sets (RIS8) or HDF scientific float32 
  747. datasets (SDS), or both, and stores the results in an HDF file (see 
  748. Fig. 6.2).  The image can be scaled about a mean value that is 
  749. provided by the user.
  750.  
  751. Figure 6.2    The fptohdf Utility
  752.                                                                      
  753.  
  754. The syntax of fptohdf is as follows:
  755.  
  756. fptohdf infile [infile ...] -o outfile [out_opts]
  757.  
  758. out_opts: 
  759.     [[-r] [[-e|-i] <horiz> <vert>] [-p palfile] 
  760.     -m <mean>] [-f]
  761.  
  762. *  infile is a file containing a single floating-point array in 
  763. either text or HDF SDS format. If the format is text, see "Notes" 
  764. below on how it must be organized.
  765.  
  766. *  outfile is a file containing the converted dataset in HDF format. 
  767. Depending on out_opts, outfile contains a scientific dataset 
  768. and/or raster  image set for each of the datasets in the input 
  769. files.
  770.  
  771. Options
  772.  
  773. -r    Stores as image in raster image set in output file
  774.  
  775. -e      Expands float data via pixel replication to produce image 
  776.         (default if -I option chosen)
  777.  
  778. -i      Applies bilinear interpolation when expanding float data 
  779.         to produce image
  780.  
  781.         <horiz> <vert>
  782.         when -e or -i options are chosen, these give the resolution 
  783.         in pixels of the desired image
  784.  
  785. -p palfile
  786.     Stores palette with image; get palette from HDF file palfile.
  787.  
  788. -m <mean>
  789.     Causes the data to be scaled around <mean> when
  790.     generating the image, according to the following 
  791.     formulas:
  792.     newmax = mean + 0.5*max(abs(max-mean),abs(mean-min))
  793.     newmin = mean - 0.5*max(abs(max-mean),abs(mean-min))
  794.  
  795. -f    Stores as scientific dataset in output file (default)
  796.  
  797. Notes
  798.  
  799. *  Image expansion is available via either pixel replication (-e) or 
  800. bilinear interpolation (-i), but not both.
  801.  
  802. *  If the "-i" option is chosen, the expanded image must have 
  803. dimensions that are greater than or equal to the dimensions of 
  804. the original dataset
  805.  
  806. *  An optional palette can accompany the image by loading it from 
  807. an HDF file that contains a palette.
  808.  
  809. *  Data from several input files (one set per input file) are stored 
  810. as several datasets and/or images in one output file. 
  811. Alternatively, a shell script can be used to call fptohdf 
  812. repeatedly to convert data from several input files to several 
  813. corresponding HDF files.
  814.  
  815. *  If an HDF file is used for input, it must contain an SDS. The SDS 
  816. need only contain a dimension record and the data, but if it also 
  817. contains max and min values and/or scales for the horizontal and 
  818. vertical axes, these will be used also.
  819.  
  820. ("Scales" are used for determining the gaps between the points 
  821. on the axes.  If the gaps are all the same, a uniform scale is 
  822. given, such as "1.0 2.0 3.0 ... n".  In an HDF file, scales may be 
  823. omitted, but in a text file (see below) they must be included.)
  824.  
  825. *  If a text file is used for input, it must follow the format shown 
  826. in Figure 6.3.
  827.  
  828. ED. NOTE:  Figures are not available in this plain text version
  829. of the specification.
  830.  
  831. Figure 6.3    Format Used in a Text File for Input
  832.                                             
  833.  
  834.  
  835. NOTE:  There are nrows vertical axis scale values and ncols 
  836. horizontal axis scale values. data1, data2, etc., are the floating-
  837. point data and are assumed to be ordered by rows, left to right 
  838. and top to bottom.
  839.  
  840.  
  841. Examples
  842.  
  843. Example 1
  844.  
  845. Convert floating-point data in file f1.txt to a SDS format, and store 
  846. it as an SDS in HDF file o1:
  847.  
  848. fptohdf f1.txt -o o1 
  849.  
  850.  
  851. Example 2
  852.  
  853. Convert floating-point data in file f2 to an 8-bit raster image and 
  854. store it as an RIS8 in file o2:
  855.  
  856. fptohdf f2 -o o2 -r
  857.  
  858.  
  859. Example 3
  860.  
  861. Convert floating-point data in file f3 to RIS8 format and SDS 
  862. format and store both the RIS8 and the SDS in file o3:
  863.  
  864. fptohdf f3 -o o3 -r -f
  865.  
  866.  
  867. Example 4
  868.  
  869. Convert floating-point data in file f4 to a 500 x 600 raster image, 
  870. storing the corresponding RIS8 in file o4. Also store a palette from 
  871. palfile with the image:
  872.  
  873. fptohdf f4 -o o4 -r -e 500 600 -p palfile
  874.  
  875.  
  876. Example 5
  877.  
  878. Convert floating-point data in all files whose names begin with the 
  879. letter 'f ' to 500 x 600 images and store the corresponding RIS8s 
  880. in file o5:
  881.  
  882. fptohdf f* -o o5 -r -i 500 600 
  883.  
  884.  
  885. Utilities for Working with Raster Image Sets
  886.  
  887. There are three utility programs for working with HDF files that 
  888. contain raster image sets. These routines can be executed 
  889. interactively at the command level without being embedded in 
  890. programs.
  891.  
  892.  
  893. ristosds:  Converting several RIS8 Images to one 3D SDS
  894.  
  895. The utility  converts a series of HDF raster image files into  a 
  896. single HDF 3D SDS file. Each input file contains one or more raster 
  897. images. All images should be of the same dimension sizes. If there 
  898. is a palette associated with the images, the palette should be 
  899. included in the first HDF file. Any subsequent palettes will be 
  900. ignored. The syntax for this utility is as follows:
  901.  
  902. ristosds <infile>{ <infile>} -o <outfile>
  903.  
  904.  
  905. where
  906.  
  907. infile    is a file containing one or more 8-bit raster images 
  908. sets (RIS8), and
  909.  
  910. outfile    is the file that will contain the 3D scientific data 
  911. set (SDS).
  912.  
  913. Example.
  914.  
  915. A directory contains 20 files named storm001, storm002, ... 
  916. storm020.  Each file contains a single RIS8 with a 100x200 image.  
  917. We wish to combine these 20 images into a 32-bit float SDS with 
  918. dimensions 100x200x20.  We can do this by executing ristosds as 
  919. follows:
  920.  
  921. ristosds storm*.hdf -o storm.hdf
  922.  
  923.  
  924. r8tohdf:  Converting 8-Bit Raster Images to HDF
  925.  
  926. The utility r8tohdf converts one or more raw images to HDF RIS8 
  927. format and writes them to a file. The syntax for storing one RIS8 in 
  928. a file using r8tohdf is as follows:
  929.  
  930. r8tohdf rows cols outfile [-p palfile] {[-c],[-r],
  931. [-i]} imf1 imf2 ...
  932.  
  933.  
  934. where
  935.  
  936. rows and cols     are the number of rows and columns, 
  937.         respectively, of the raster image
  938.  
  939. outfile     is the file that will contain the raster image 
  940.         set, and
  941.  
  942. imf1, imf2,    and so forth, are files containing 8-bit raw 
  943.         raster images.
  944.  
  945. Options
  946.  
  947. -p palfile    optionally stores a file containing a palette in 
  948.     the RIS8. If -p is not specified, no palette is stored in the RIS8.
  949.  
  950. {[-c],[-r],[-i]}    optionally chooses compression by run 
  951.     length encoding (-c), compression by the IMCOMP method 
  952.     (-i), or no compression (-r). The default is -r.
  953.  
  954.  
  955. Example 1
  956.  
  957. A 256 x 512 byte raw raster image is contained in a file called 
  958. rawras, and the palette with which it is to be used is stored in a 
  959. file called mypal. To convert this information to an RIS8 without 
  960. compression and store the result in a file called ras.hdf, enter:
  961.  
  962. r8tohdf 256 512 ras.hdf -p mypal rawras
  963.  
  964.  
  965. Example 2
  966.  
  967. A 800 x 1000 byte raw raster image is stored in a file called 
  968. bigpic. You want to first convert this information to an RIS8 with 
  969. run length encoding for compression and no palette, and then store 
  970. the result in a file called bigpic.hdf. Enter:
  971.  
  972. r8tohdf 800 1000 bigpic.hdf -c bigpic
  973.  
  974.  
  975. Example 3
  976.  
  977. Three 300 x 400 raw images are contained in files pic1, pic2, and 
  978. pic3. To convert all three files to RIS8s with imcomp compression 
  979. and store them in pic.hdf, enter:
  980.  
  981. r8tohdf 300 400 pic.hdf -i pic1 pic2 pic3
  982.  
  983.  
  984. Example 4
  985.  
  986. A combination of different types of raster image sets is to be 
  987. stored in a file called ras.hdf. The image from file rawras1 is to be 
  988. stored without a palette. The images from rawras2 are to be stored 
  989. with a palette that is copied from a file called mypal. The images 
  990. from rawras1 and rawras2 are to be compressed using run length 
  991. encoding, and rawras3 is not to be compressed. All images are 
  992. 256 x 512.
  993.  
  994. r8tohdf 256 512 ras.hdf -c rawras1 -p mypal rawras2 
  995. -r rawras3
  996.  
  997.  
  998. hdftor8:  Extracting 8-Bit Raster Images and Palettes from an 
  999. HDF File
  1000.  
  1001. The utility hdftor8 extracts the images and or palettes from an 
  1002. HDF file and stores them in two sets of files that contain only 
  1003. images and palettes, respectively. The syntax for hdftor8 is as 
  1004. follows:
  1005.  
  1006. hdftor8 hdf_file [-i] [-v] [-r image_file][-p
  1007.     palette_file]
  1008.  
  1009.  
  1010.  
  1011. Where hdf_file is the file to extract images and palettes from, and 
  1012. image_file and palette_file are basic names of  the files that will 
  1013. contain the images and palettes. These names are extended as 
  1014. follows:  For each image file, the filename is given the extension 
  1015. ".#.@.%", where # stands for the image number from the original 
  1016. file, @ is the x dimension of the image, and % is the y dimension 
  1017. of the image. For each palette file, the filename is given the 
  1018. extension ".#", where # stands for the palette number from the 
  1019. original file.
  1020.  
  1021. If no names are given for the image file, the default name 
  1022. "img.#.@.%" is used, where #, @ and % are defined as in the 
  1023. preceding paragraph. Similarly the default name for a palette file 
  1024. is "pal.#".
  1025.  
  1026.  
  1027. Options
  1028.  
  1029. -i    puts the program in interactive mode, so you can specify 
  1030.     filenames interactively.
  1031.  
  1032. -v    specifies verbose mode, providing descriptive     
  1033.     messages.
  1034.  
  1035. -r    indicates that the file whose name follows is to hold 
  1036.         images.
  1037.  
  1038. -p    indicates that the file whose name follows is to hold 
  1039.         palettes.
  1040.  
  1041.  
  1042. Example 5
  1043.  
  1044. A file called denm.hdf contains three 512 x 256 images and three 
  1045. palettes. To extract these images and palettes and put them in 
  1046. separate files, enter:
  1047.  
  1048. hdftor8 denm.hdf
  1049.  
  1050. Six files are produced with the names img1.512.256, 
  1051. img2.512.256, img3.512.256, pal.1, pal.2, and pal.3.
  1052.  
  1053.  
  1054. hdfcomp:  Compress 8-bit raster images in an HDF file.
  1055.  
  1056. The utility hdfcomp reads in raster-8 images from an  HDF file and 
  1057. create a new HDF containing the  images in a compressed format.  
  1058. Images will be appended to the output file, if it exists.
  1059.  
  1060. The syntax for hdfcomp is:
  1061.  
  1062. hdfcomp outfile {[-c],[-r],[-i]} imagefile...
  1063.                 {[-c],[-r],[-i]} imagefile
  1064.  
  1065.  
  1066. outfile    file to store compressed images in
  1067.  
  1068. imagefile    file containing an HDF image
  1069.  
  1070. Options:
  1071.  
  1072. -r    Store without compression (default)
  1073. -c    Store using RLE compression
  1074. -i    Store using IMCOMP compression (requires a palette in the 
  1075.     HDF file)
  1076.  
  1077. Example.
  1078.  
  1079. A directory contains 20 files named storm001, storm002, ... 
  1080. storm020.  Each file contains a single 8-bit image..  We wish to 
  1081. compress these 20 images using run-length encoding and store 
  1082. them in a single file called allcomp.hdf. We can do this by 
  1083. executing hdfcomp as follows:
  1084.  
  1085. hdfcomp allcomp.hdf -c storm*.hdf
  1086.  
  1087.  
  1088. r24hdf8:  Converting 24-bit Raw Raster Image to HDF 8-Bit Raster Images
  1089.  
  1090. The command line utility r24hdf8 quantizes a raw RGB 24-bit pixel 
  1091. image into an 8-bit image with a 256-color palette and stores both 
  1092. the palette and image in an HDF file.
  1093.  
  1094. The syntax for r24hdf8 is:
  1095.  
  1096. r24hdf8 x_dim y_dim r24_file hdf8_file
  1097.  
  1098.  
  1099.  
  1100. x_dim     is the x dimension of the image (horizontal size).
  1101.  
  1102. y_dim     is the y dimension of the image (vertical size).
  1103.  
  1104. r24_file     is a file containing the raw RGB 24 bit image. The 
  1105. order of pixels is left to right and top to bottom. 
  1106. Each pixel is three contiguous bytes: red byte, 
  1107. green byte,  and blue byte. Use filter ptox to 
  1108. convert  from "planar" to "pixel" where planar 
  1109. means all red bytes for the whole image, followed  
  1110. by all green bytes for the whole image,  followed by 
  1111. all blue bytes for the whole  image.
  1112.  
  1113. hdf8_file    is the output file, is an HDF file with one 8-bit 
  1114. raster image set; i.e. 8-bit image, dimensions, and RGB palette.
  1115.  
  1116. hdf24hdf8:  Converting 24-bit HDF image to HDF 8- Bit HDF Image
  1117.  
  1118. The  utility hdf24hdf8 quantizes a HDF RGB 24 bit "pixel" 
  1119. image into a 8 bit image with 256-color palette and stores 
  1120. both the palette and image in an HDF file.
  1121.  
  1122. The syntax for hdf24hdf8 is:
  1123.  
  1124. hdf24hdf8 r24_file hdf8_file
  1125.  
  1126.  
  1127.  
  1128. r24_file is the input file, an HDF file containing the HDF 
  1129.     RGB 24-bit raster image
  1130.  
  1131. hdf8_file is the output file containing one 8-bit RIS with an 
  1132.     RGB palette.
  1133.  
  1134.  
  1135. paltohdf:  Converting a Raw Palette to HDF
  1136.  
  1137. paltohdf converts a raw palette to HDF format. The incoming 
  1138. palette is assumed to have 768 bytes organized in the following 
  1139. order:  256 red values, 256 green values, and 256 blue values. The 
  1140. palette in the HDF file will have the RGB values interlaced: RGB 
  1141. RGB RGB... This is standard HDF format for 8-bit palettes.
  1142.  
  1143. The syntax for paltohdf is:
  1144.  
  1145. paltohdf rawpalfile hdffile
  1146.  
  1147.  
  1148. rawpalfile is a 768-byte input file with the red, green, and blue 
  1149. components stored as described above.
  1150.  
  1151. hdffile, the output file, is an HDF file. If hdffile does not exist, it 
  1152. is created and the palette is added to it. If it already exists, the 
  1153. palette is appended to it.
  1154.  
  1155.  
  1156. hdftopal:  Extracting a palette from an HDF file
  1157.  
  1158. hdftopal converts a palette from an HDF file to a raw palette in a 
  1159. raw palette file. The outgoing palette will have 768 bytes: first 
  1160. 256 red values, then 256 greens, then 256 blues.
  1161.  
  1162. The syntax for hdftopal is:
  1163.  
  1164. hdftopal hdffile rawpalfile
  1165.  
  1166.  
  1167. hdffile, the input file, is an HDF file containing a palette.
  1168.  
  1169. rawpalfile is a 768-byte output file with the red, green, and blue 
  1170. components stored as described above.
  1171.  
  1172.  
  1173. hdfrseq and hdfseq:  Displaying Images
  1174.  
  1175. The utilities hdfseq and hdfrseq display sequences of images, one 
  1176. after the other, from files containing raster image sets. 
  1177.  
  1178. Although hdfseq and hdfrseq perform essentially the same 
  1179. function, the situations in which they are used are different. 
  1180. hdfseq displays images on a Sun-3 console and on any SGI IRIS that 
  1181. has gllib, when those images are stored at  the Sun 3 or IRIS 
  1182. workstation. When hdfseq executes on a file, it causes the raster 
  1183. image to be displayed immediately on the console.
  1184.  
  1185. hdfrseq performs the same operation, only remotely, via a terminal 
  1186. emulator such as Telnet 2.3 or Teltool 1.2. (The "r" in hdfrseq 
  1187. stands for remote.)  When hdfrseq executes on a file, it converts 
  1188. the image from RIS8 format to NCSA's ICR (interactive color raster) 
  1189. format and sends it to the receiving terminal. ICR is a protocol 
  1190. that is easy to transmit to a remote display station. If the 
  1191. receiving software on the display station can decipher the ICR 
  1192. protocol, it displays the image on the console. 
  1193.  
  1194. In a typical application, the display station would be running a 
  1195. program, such as NCSA Telnet (Version 2.3 or later) or NCSA 
  1196. Teltool (Version 1.2 or later), that understands ICR and 
  1197. immediately converts the incoming stream to a screen display.
  1198.  
  1199. The syntax for hdfseq is:
  1200.  
  1201. hdfseq [-s] [-l] [-p xloc yloc] [-e expansion] file1 file2 
  1202. ...
  1203.  
  1204.  
  1205. file1, file2, and so forth are HDF files that contain raster image 
  1206. sets. Only one image is displayed per file. If more than one file is 
  1207. listed, the corresponding images are displayed in sequence, that 
  1208. is, in the order in which the files are listed. Each new image 
  1209. overwrites the preceding image on the screen.
  1210.  
  1211. Options
  1212.  
  1213. -s    single step through the images. Once an image 
  1214. is displayed, it remains on the screen until you 
  1215. press RETURN to display the next image or 
  1216. enter Q to quit.
  1217.  
  1218. -l    makes the image as large as possible on the screen.
  1219.  
  1220. -p xloc yloc    places the upper left corner of the display at 
  1221.     position (xloc, yloc) on the screen.
  1222.  
  1223. -e expansion    expands the image by the expansion factor 
  1224.     specified by expansion.
  1225.  
  1226. The syntax for hdfrseq is exactly the same. 
  1227.  
  1228.  
  1229. Example 6
  1230.  
  1231. Five images are stored in RIS8 form in the files star1, star2, star3, 
  1232. star4, and star5. You want to use hdfrseq to display all five 
  1233. images, in sequence, but with a pause between them. To make them 
  1234. appear on screen three times their normal size, enter:
  1235.  
  1236. hdfrseq -s -e 3 star1 star2 star3 star4 star5
  1237.  
  1238. hdfpack: Compacting an HDF file
  1239.  
  1240. The utility hdfpack compacts an HDF file by reading in all the data 
  1241. elements in the file and writing them out to a new file.
  1242.  
  1243. hdfpack [-i | -b] [-d#] [-t#] <infile> <outfile>
  1244.  
  1245. -b    Don't coalesce linked-block elements
  1246.  
  1247. -i    Interactive mode; prompt for each linked-block element
  1248.  
  1249. -d#    Force the output file to have # DDs per DD block
  1250.  
  1251. -t#    Force output file to have # linked blocks per table entry
  1252.  
  1253. Only one of options b and i can be specified.
  1254.  
  1255.  
  1256. Examples
  1257.  
  1258. To compact the file aa.hdf and put the result in aa.pck, enter
  1259.  
  1260.     hdfpack aa.cdf aa.pck
  1261.  
  1262. Suppose the file bb.hdf contains elements stored as sequences of 
  1263. linked blocks.  To compact this file but leave the linked-block elements 
  1264. intact, and put the result in bb.blk, enter
  1265.  
  1266.     hdfpack -b bb.hdf bb.blk
  1267.  
  1268.  
  1269.