HDF_BROWSER

The HDF_BROWSER function presents a graphical user interface (GUI) that allows the user to view the contents of a Hierarchical Data Format (HDF), HDF-EOS, or NetCDF file, and prepare a template for the extraction of HDF data and metadata into IDL. The output template is an IDL structure that may be used when reading HDF files with the HDF_READ routine. If you have several HDF files of identical form, the returned template from HDF_BROWSER may be reused to extract data from these files with HDF_READ. If you do not need a multi-use template, you may call HDF_READ directly.

Syntax

Template = HDF_BROWSER([Filename] [, CANCEL=variable] [, GROUP=widget_id] [, PREFIX=string])

Return Value

Returns a template structure containing heap variable references, or 0 if no file was selected. The user is required to clean up the heap variable references when done with them.

Arguments

Filename

A string containing the name of an HDF file to browse. If Filename is not specified, a dialog allows you to choose a file.

Keywords

CANCEL

Set this keyword to a named variable that will contain the byte value 1 (one) if the user clicked the "Cancel" button or the byte value 0 (zero) otherwise.

GROUP

Set this keyword to the widget ID of a widget that calls HDF_BROWSER. When this ID is specified, a death of the caller results in the death of the HDF_BROWSER. The following example demonstrates how to use the GROUP keyword to properly call HDF_BROWSER from within a widget application. To run this example, save the following code as browser_example.pro:

PRO BROWSER_EXAMPLE_EVENT,ev  
  
   WIDGET_CONTROL,ev.id,GET_VALUE=val  
      CASE val of  
         'Browser':BEGIN  
            a=HDF_BROWSER(GROUP=ev.top)  
            HELP,a,/st  
         END  
         'Exit': WIDGET_CONTROL,ev.top,/DESTROY  
      ENDCASE  
  
END  
  
PRO BROWSER_EXAMPLE  
  
   a=WIDGET_BASE(/ROW)  
   b=WIDGET_BUTTON(a,VALUE='Browser')  
   c=WIDGET_BUTTON(a,VALUE='Exit')  
   WIDGET_CONTROL,a,/REALIZE  
   XMANAGER,'browser_example',a  
  
END

PREFIX

When HDF_BROWSER reviews the contents of an HDF file, it creates default output names for the various data elements. By default these default names begin with a prefix derived from the filename. Set this keyword to a string value to be used in place of the default prefix.

Examples

template = HDF_BROWSER('test.hdf')   
output_structure = HDF_READ(TEMPLATE=template)

or,

output_structure = HDF_READ('test.hdf', TEMPLATE=template)

Using the HDF Browser Interface

When you call the HDF_BROWSER function from the command line or using the Import HDF macro, the HDF Browser window is displayed.

Figure 3-50: HDF Browser Window

Figure 3-50: HDF Browser Window

Use the following steps when working with the HDF Browser dialog:

Select the type of file you are opening. The following table describes the Display field options:


Display	Select one of the following options to indicate the type of file you are reading: HDF/NETCDF HDF-EOS This selection toggles the following droplist between HDF Summary and HDF-EOS Summary.
HDF Summary	Displays the number of items in each of the following categories: DF24 (24-bit Images) — 24-bit images and their attributes DFR8 (8-bit Images) — 8-bit images and their attributes DFP (Palettes) — Image palettes SD (Variables/Attributes) — Scientific Datasets and attributes AN (Annotations) — Annotations GR (Generic Raster) — Images GR Global (File) Attributes — Image attributes VGroups — Generic data groups VData — Generic data and attributes
HDF-EOS Summary	Displays the number of items in each of the following categories: Point — EOS point data and attributes Swath — EOS swath data and attributes Grid — EOS grid data and attributes

Select any element that contains data. Attributes of the selected data appear in the lower textbox. Use other dialog options as follows:


Preview	Select an image, 2D data set, or 3xnxm data set from the pulldown menu. Make a selection from the following and click Preview to create a display: Preview Image — displays an image or a plot of a 2-D data set (the default) Preview Surface — displays a surface plot Preview Contour — displays a contour plot Preview Show3 — displays an image, surface, and contour plot Fit to Window — fits the display to the visible area of window
Read	Import the selected data into IDL. Select this checkbox to extract the current data or metadata item from the HDF file.
Extract As	Enter name for the extracted data or metadata item. Default names are generated for all data items, but may be changed at any time. Note - The Read checkbox must be selected for the item to be extracted.
Color Table	Select this option to apply a selected, pre-defined color table to the data.
OK	Complete any selected import actions.
Cancel	Dismiss the dialog without making changes.

Select additional data or complete the operation. Continue selecting to read and name the data or metadata items you want to import into IDL and then select one of the following options:


OK	Generate the template used to import HDF data.
Cancel	Dismiss the dialog without making changes.

The result of these actions depends on the location from which you launched the HDF Browser dialog. The HDF_READ function, which reads data from a file according to the template specification, is automatically called when you access the HDF Browser dialog from the Import HDF macro. From the command line, you must explicitly read the HDF data with the template specification. After defining what data to access using the HDF Browser dialog, refer to the appropriate section:

Import HDF macro data access — the HDF data is placed in a structure. You can access fields of the data using a variable_name.element_name syntax. See Using Macros to Import HDF Files.

Command line binary data access — the template is a structure defining the HDF data elements to be read. Access the data using HDF_READ, and specify the template as parameters of the data access operation.

Version History


5.1	Introduced