HDF5 BROWSER (h5b) [TOC]

by Ben-chin Cha

I. INTRODUCTION

H5b provides the IDL user with a mouse driven widget application to browse any HDF / NEXUS file saved in HDF5 format. It is developed with IDL 6.0 and features of new ITOOLS are also included. It provides the user with many simple to use data visualization tools and convenient output graphic and ascii output features. This browser also let the user easily to access the default HDF5 browser, H5_BROWSER, provided directly by IDL library.

It has been fully tested under IDL 6.0 and IDL 6.1beta with the example HDF5 data file 'hdf5_test.h5' comes with IDL package. The ITOOLS features currently are not working with IDLVM 6.0 but it will be supported by IDLVM 6.1.

The HDF5 datasets are grouped like a tree structure. The h5b let the user walk trought the group / subgroup /dataset name and pops up subgroup or dataset window accordingly. A user can easily extract any 1D/2D/3D data array and display the data in packaged graphic visualization tools. It also provided various output features like PS plots, TIFF/PNG/PICT/ASCII files.

The h5b also provides a simple command, h5b_readArray, with the known full dataset name it allows the user easily to extract the data array as an IDL variable. This IDL variable then can be passed to any other applicable IDL program. This provides the feature a user can easily plug-in his/her own preferred IDL visualization program into the h5b. This IDL command and plug-in feature are only available in developper version but not for run-time or IDLVM version.

The default color table used is rainbow with peak value as white. The extracted 1D array is passed to plot1d, 2D array is passed to plot2d, 3D array is passed to view3d_2d, palette image is passed to plot2d_image, multiple 2D arrays are passed to panimage and image2d visualization tools.

II. DOWNLOAD AND SETUP

Normally a user only need to download h5b.sav to view any HDF5/NEXUS file. The test example data from the IDL release, hdf5_test.h5, provides a good example of HDF5 sample file, by default it is automatically used by h5b. 
	h5b.sav Download h5b for IDLVM 6.0

	hdf5_test.h5 Download the test example comes with IDL 

If a user want to get the complete collection of the IDL sources the following link is availble.

	Idl.zip Download the complete set of EPICS/IDL source programs 

	Setup Reguirement For accessing installed IDL source programs
The h5b frontend system consists of 3 files: os.init, h5b, and h5b.pro. All the programs implicitly used by the h5b is also contained in the installation directory and they will be dynamically loaded into IDL at runtime. 
	
os.init          - A system dependent file shared by IDL programs with 
                   specific settings for UNIX/WIN system.
h5b.pro         - A HDF5/NEXUS browser written in IDL widget application 
h5b             - A UNIX script file, it automatically sets up the 
                   IDL and runs the h5b.pro

COMMAND SYNTAX

At APS, all the IDL programs are installed in /usr/local/epics/extensions/bin/solaris directory for EPICS 3.13.X. Starting from EPICS 3.14.X the IDL programs are installed in /usr/local/epics/extensions/idllib directory and the UNIX script and IDL saved files are installed in /usr/local/epics/extensions/bin/solaris-sparc directory.

To access the newest version of h5b, a user has to include the /usr/local/epics/extensions/bin/solaris-sparc directory in his/her command search path. 

	UNIX SYSTEM

	1) To access the IDLVM 6.0 version with h5b.sav on the 
	Unix system just enter the following at the unix prompt:
	
		idlvm h5b

	2) To access the h5b developer version on the Unix system 
	just enter the following at the unix prompt:

		h5b

	WIN SYSTEM

	1) To access the IDLVM 6.0 version with h5b.sav on the 
	WIN system just double click the 'h5b.sav' icon

	2) To access the source version h5b on the WIN system first 
	invoke IDLDE, then just enter the following at the IDL prompt:

		@os.init
		h5b

III. USER INTERFACE

File Types Used

Various types of files used by h5b. They include input file, output file, config file. Additional text or image output files used or saved by subsequent program, e.g. PLOT1D, PLOT2D, EZ_FIT, etc., are also automatically used.

Input Files

The input file supported by h5b can be either HDF5 file or NEXUS file saved as in HDF5 format. It is assumed that HDF5 file is ended with '.h5', the NEXUS file can be ended with '.Nx', or '.nx', or '.nexus'. User can modify the file selection dialog to suit user's own name convention as long as it contains HDF5 data.

Output Files

Few different types of output files can be generated by h5b. It provides the user of option override the default input file names used. The user is responsible for unique existence of the file name used. It is recommanded that the user has to keep the consistant file types used for easy file management.

The extracted dataset can be saved in XDR format which is stored at the subdirectory XDR at the current working directory. The xdr file should be ended with '.xdr' suffix. For more knowledge of easy IDL xdr routines please refer the xdr_open.pro.

The extracted image dataset can be saved as TIFF file. The graphic tiff file is stored at the subdirectory TIFF at the current working directory. The tiff file should be ended with '.tiff' suffix.

Various text file can be saved by the sub-program called by the h5b. All text files should be ended with '.txt' suffix.

H5B Main Window

Open... - popup HDF5 file selection dialog, default file types include: '*.h5*', '*.nx*','*.Nx*' 

Color... - popup IDL load color table program

DATASET... - popup the dataset display sub-program for the picked hdf5 file

SDS... - popup the SDS selection dialog for the picked hdf5 file

Help... - display the on line help about main window

Done - exit h5b program

HDF5 File: - text field for displaying current hdf5 picked

File_Attr - find and display the file attributes in the scroll text area

DATA EXTRACTION COMMANDS - display syntax of data extraction command in the scroll text area

Scroll Text Area - text area display file attribute or command syntax

CMD: - text field for entering data extraction command, default extract the 'Eskimo' image from hdf5_test.h5

Run... - accept the CMD syntax and extract it from the selected filename




HDF5 Browser Window

At the end of HDF5 file selection or press the return key in the 'HDF5 File:' text field, the default IDL HDF5 Browser will pop up. A user can browse the tree group structure and display the raw palette image and 2D/3D data arrays by clicking the data name.





IMG with Palette Window

Press the return key in the 'CMD:' text field, it will accept the command syntax h5b_readImage,'images/Eskimo','images/Eskimo_palette' from the field. It will extract the 'Eskimo' image and palette from the default 'hdf5_test.h5' file and plot the data with plot2d_image program. After press the 'Flip Vertical' button, the result is given below.

The plot2d_iamge program provides the option of flipping the image horizontally/vertically, resizing the image by the window size, generating post script plot, or exporting the image to TIFF/PNG/PICT format.



Group DATASET Window

Press the 'DATASET...' button in the H5B Main Window, the top group DATASET window pops up. The window is titled with the selected file name. For the default test sample is given below: 

Plot Image with Palette...
When an image data comes with a palette data, this button can be used to plot the true image data. Before press this button make sure that an image name is picked from DATASET list, and a palette name is picked from the PALETTE list. In order to make this work properly, the palette data name in HDF5 file must always contain '_palette' in its dataset name as shown in this sample example. 
? Struct Data...
This button allows the user to query and display the group structure of the selected dataset. 
SDS...
This button pops up the SDS selection dialog which provides various features of accessing the HDF5 SDS data found in the opened file. 
Color...
This button calls the IDL xloadct subprogram, it allows the user to load any IDL supplied color tables. 
Help...
This button display the on-line help about this window. 
Close
This button close this window dialog. 
Pick DATASET
This selection list contains the complete set of DATASETs found in the opened HDF5. Each DATASET can contains data or sub-groups. If a data is picked, the corresponding data plot sub-program pops up. If a sub-group is picked, a new child DATASET window pops up. If there is attribute found for the selected DATASET or sub-group it will be displayed in the Attributes Info text area. 
Pick PALETTE
This selection list contains the palette data name found in the opened HDF5. For the default test sample there are two palette data: '/images/Eskimo_palette', and '/images/iceberg_palette'. 
Attributes Info
This scrolled text area displays the attributes found for the selected DATASET.



2D Array Window

The '/arrays/2D float array' item is picked from DATASET list, the following window pops up. Whenever a 2D data array is detected, the PLOT2D sub-program will be called.





Mixed Types Window

The '/arrays/Vdata with mixed types' item is picked from the DATASET list, the Attributes Info area is updated, since there is no simple data array found in this dataset, therefore the data structure info window for the selected item pops up.

This structure info window can also be accessed anytime by pressing the query '? Struct Data...' button.



Palette Image Windows

Following three windows show how to get the result of image with known palette.

First window shows the item '/images/Iceberg' is selected from the DATASET list, because a 2D image data is extracted, therefore PLOT2D is called.

Second, a '/images/iceberg_palette' is selected from the PALETTE list, as shown in the second window.

Last the 'Plot Image with Palette...' button is pressed, then the PLOT2D_IMAGE is called and the last window pops up.





H5B_SDS Windows

The following H5B_SDS selection dialog pops up whenever the 'SDS...' button is pressed. It allows the user flexiblely to access and dislpay any SDS dataset found from the opened HDF5 file. 

DumpSDSHeader - display header of all dataset

First - display the first dataset

Next - display the Next dataset

Prev - display the Previous dataset

Last - display the last dataset

SDS # - display the seq number of selected dataset

Slider - pick the seq number for desired dataset

Multiple SDSs... - dialog for multiple SDSs selection

Dataset Nameist - a complete dataset selection list

Close - close the selection dialog
Press the 'DumpSDSHeader' button pops up the following display window. It displays header about all the dataset found in the opened file. For each dataset set the name, type, dimension, and first 6 items are displayed.



Press the 'Multiple SDSs...' button, the following dialog pops up. It allows the user to enter multiple 1D or 2D sequence numbers. A user has to make sure only the same dimension array can be group togather.

In this example a 2D sequence number '0,2,3' are entered, and the 'IMAGE2D...' button is pressed. The PANIMAGE and IMAGE2D windows pops up they are displayed below.

The '/arrays/2D float array' is picked in the following IMAGE2D window.

IV. H5B COMMANDS

Following h5b commands are only available from the IDL prompt, i.e. only when running with developer version. For detail information please refer the h5b.pro source program. The default input file name used in h5b.pro is 'hdf5_test.h5'. 
h5b,file=file

    This command run the widget program h5b.pro with the specified file name.

h5b_readImage,name,name_p,file=file

    This command extracts the an image data with color palette from the specified file.
	name   - a string to specify the full dataset name 
	name_p - a string to specify the full palette name 
	file   - specify the from HDF5 file name

h5b_readArray,name,file=file,data=data,readonly=readonly

    This command extracts the data array from the specified dataset and file.
	name     - a string to specify the full dataset name
	file     - specify the from HDF5 file name
	data     - return the data array extracted from the dataset 
	readonly - if specified no raw data graph is displayed 

h5b_dialogPick,file=file

    This command pops up the group/dataset selection dialog for the specified file.

h5b_sds,file=file

    This command pops up the H5B_SDS selection dialog for the specified file.

h5b_attrs,file,st

    This command finds and returns file attruibute array from the specified file.
	file   - specify the from HDF5 file name
	st     - return string attribute array

h5b_dattrs,gname,st,file=file

    This command finds and returns dataset attruibute array from the specified name and file.
	gname  - a string to specify the full dataset name
	file   - specify the from HDF5 file name
	st     - return string attribute array

h5b_dNames,dnames,name=name,gnames=gnames,SDS=SDS,file=file,debug=debug

    This command returns dataset names found from the specified name and file.
	file   - specify the from HDF5 file name
	name   - a string to specify the input group dataset name, default '/'
	dnames - return dataset names found for the specified dataset name
	gname  - return subgroup names found for the specified dataset name 
	SDS    - return only SDS dataset names for the specified dataset name
	debug  - echo the gnames,dnames,SDS results obtained

h5b_getStruct,name,file=file,data=data

    This command extracts a data structure from the specified file.
	name   - a string to specify the full dataset name
	file   - specify the from HDF5 file name
	data   - return a structured dataset varible

h5b_plot,varname,pn=pn

    This command plots 1D/2D/3D data array extracted from the imported dataset variable.
    
	varname - imported hdf5 dataset variable name, either by h5_browser 
		  or by h5b_getStruct command.
	pn	- specify the hdf5 varible name imported from the color 
                  palette name, either by h5_browser or by h5b_getStruct command