HDF Object Package - How to Use It

  • How to use it
  • Set CLASSPATH
  • Set Library Path
  • How to select a subset
  • Examples


    How to use it

    The HDF Object Package is used by Java applications to access HDF4 and HDF5 files without directly calling the HDF4 and HDF5 library APIs. Library calls are encapsulated into respective classes. The HDF Object Package requires the The Java HDF Interface (JHI) and The Java HDF5 Interface (JHI5). Figure 2 shows the relationship of the packages.

    Figure 2. The Software packages


    Set CLASSPATH

    Befor you use the HDF object package, you must set the Java CLASSPATH.

    At unix

    Suppose you install the HDF object package at /home/usr/hdfobj.
    setenv CLASSPATH $CLASSPATH:/home/usr/hdfobj/jhdf.jar
    setenv CLASSPATH $CLASSPATH:/home/usr/hdfobj/jhdf5.jar
    setenv CLASSPATH $CLASSPATH:/home/usr/hdfobj/jhdfobj.jar
    setenv CLASSPATH $CLASSPATH:/home/usr/hdfobj/jhdf4obj.jar
    setenv CLASSPATH $CLASSPATH:/home/usr/hdfobj/jhdf5obj.jar
    export CLASSPATH

    At Windows

    Suppose you install the HDF object package at c:\apps\hdfobj.
    setenv CLASSPATH=%CLASSPATH%;c:\apps\hdfobj\jhdf.jar
    setenv CLASSPATH=%CLASSPATH%;c:\apps\hdfobj\jhdf5.jar
    setenv CLASSPATH=%CLASSPATH%;c:\apps\hdfobj\jhdfobj.jar
    setenv CLASSPATH=%CLASSPATH%;c:\apps\hdfobj\jhdf4obj.jar
    setenv CLASSPATH=%CLASSPATH%;c:\apps\hdfobj\jhdf5obj.jar

    Set Library Path

    The object package should include the HDF4 and HDF5 library. To use the object pacakge, you must set the path to the library. Otherwise, you will get "java.lang.UnsatisfiedLinkError".

    At unix

    Suppose you install the HDF object package at /home/usr/hdfobj.

    For Solaris
    setenv PATH $PATH:/home/usr/hdfobj/lib/solaris

    For Linux
    setenv PATH $PATH:/home/usr/hdfobj/lib/linux

    At Windows

    Suppose you install the HDF object package at c:\apps\hdfobj.

    setenv PATH=%PATH%;c:\apps\hdfobj\lib\win


    How to select a subset

    Dataset defines APIs for read, write and subet a dataset. No function is defined to select a subset of a data array. The selection is done in an implicit way. Function calls to dimension information such as getSelectedDims() return an array of dimension values, which is a reference to the array in the dataset object. Changes of the array outside the dataset object directly change the values of the array in the dataset object. It is like pointers in C.

    The following is an example of how to make a subset. In the example, the dataset is a 4-dimension with size of [200][100][50][10], i.e. dims[0]=200; dims[1]=100; dims[2]=50; dims[3]=10;
    We want to select every other data points in dims[1] and dims[2]

         int rank = dataset.getRank();   // number of dimension of the dataset
         long[] dims = dataset.getDims(); // the dimension sizes of the dataset
         long[] selected = dataset.getSelectedDims(); // the selected size of the dataet
         long[] start = dataset.getStartDims(); // the off set of the selection
         long[] stride = dataset.getStride(); // the stride of the dataset
         int[]  selectedIndex = dataset.getSelectedIndex(); // the selected dimensions for display
    
         // select dim1 and dim2 as 2D data for display,and slice through dim0
         selectedIndex[0] = 1;
         selectedIndex[1] = 2;
         selectedIndex[2] = 0;
    
         // reset the selection arrays
         for (int i=0; i < rank; i++) {
             start[i] = 0;
             selected[i] = 1;
             stride[i] = 1;
        }
    
        // set stride to 2 on dim1 and dim2 so that every other data points are selected.
        stride[1] = 2;
        stride[2] = 2;
    
        // set the selection size of dim1 and dim2
        selected[1] = dims[1]/stride[1];
        selected[2] = dims[1]/stride[2];
    
        // when dataset.read() is called, the slection above will be used since
        // the dimension arrays is passed by reference. Changes of these arrays
        // outside the dataset object directly change the values of these array
        // in the dataset object.
    

    Examples

    The following examples show you how to use the object pacakage. The examples demonstrate how to access HDF4 and HDF file without any direct function calls to the HDF4 or HDF5 library.

    Create File

    H4FileCreate.java
    H5FileCreate.java

    These two examples show you how to create an empty HDF4/5 file using the "HDF Object Package (Java).

    Create Group

    H4GroupCreate.java
    H5GroupCreate.java

    These two examples show you how to create HDF4/5 groups using the "HDF Object Package (Java). The examples create the group structure:

          "/" (root)
              g1
                  g11
                  g12
              g2
                  g21
                  g22
     

    Create Datatype/Dataset

    H4DatasetCreate.java
    H5DatasetCreate.java

    These two examples show you how to create HDF4/5 datasets using the "HDF Object Package (Java)". The examples create the group structure and datasets:

          "/" (root)
              integer arrays
                  2D 32-bit integer 20x10
                  3D unsigned 8-bit integer 20x10x5
              float arrays
                  2D 64-bit double 20x10
                  3D 32-bit float  20x10x5
      

    Retrieve File Structure

    H4FileStructure.java
    H5FileStructure.java

    These two examples show you how to retrieve HDF file structure using the "HDF Object Package (Java)". The example created the group structure and datasets, and print out the file structure:

          "/" (root)
              integer arrays
                  2D 32-bit integer 20x10
                  3D unsigned 8-bit integer 20x10x5
              float arrays
                  2D 64-bit double 20x10
                  3D 32-bit float  20x10x5
      

    Read/Write Dataset

    H4DatasetRead.java
    H5DatasetRead.java

    These two examples show you how to read/write HDF datasets using the "HDF Object Package (Java)". The example creates an integer dataset, and read and write data values:

        "/" (root)
                2D 32-bit integer 20x10
    

    Create Attribute/Read/Write Attribute

    H4AttributeCreate.java
    H5AttributeCreate.java

    These two examples show you how to create/read/write HDF attribute using the "HDF Object Package (Java)". The example creates an attribute and, read and write the attribute value:

        "/" (root)
                2D 32-bit integer 20x10
                (attribute: name="data range", value=[0, 10000])
    

    Select Subset

    H4SubsetSelect.java
    H5SubsetSelect.java
    These two examples show you how to select a subset using the "HDF Object Package (Java)". The example creates an integer dataset, and read subset of the dataset:
        "/" (root)
            2D 32-bit integer 20x10
    

    The whole 20x10 data set is

    1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009
    1100, 1101, 1102, 1103, 1104, 1105, 1106, 1107, 1108, 1109
    1200, 1201, 1202, 1203, 1204, 1205, 1206, 1207, 1208, 1209
    1300, 1301, 1302, 1303, 1304, 1305, 1306, 1307, 1308, 1309
    1400, 1401, 1402, 1403, 1404, 1405, 1406, 1407, 1408, 1409
    1500, 1501, 1502, 1503, 1504, 1505, 1506, 1507, 1508, 1509
    1600, 1601, 1602, 1603, 1604, 1605, 1606, 1607, 1608, 1609
    1700, 1701, 1702, 1703, 1704, 1705, 1706, 1707, 1708, 1709
    1800, 1801, 1802, 1803, 1804, 1805, 1806, 1807, 1808, 1809
    1900, 1901, 1902, 1903, 1904, 1905, 1906, 1907, 1908, 1909
    2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
    2100, 2101, 2102, 2103, 2104, 2105, 2106, 2107, 2108, 2109
    2200, 2201, 2202, 2203, 2204, 2205, 2206, 2207, 2208, 2209
    2300, 2301, 2302, 2303, 2304, 2305, 2306, 2307, 2308, 2309
    2400, 2401, 2402, 2403, 2404, 2405, 2406, 2407, 2408, 2409
    2500, 2501, 2502, 2503, 2504, 2505, 2506, 2507, 2508, 2509
    2600, 2601, 2602, 2603, 2604, 2605, 2606, 2607, 2608, 2609
    2700, 2701, 2702, 2703, 2704, 2705, 2706, 2707, 2708, 2709
    2800, 2801, 2802, 2803, 2804, 2805, 2806, 2807, 2808, 2809
    2900, 2901, 2902, 2903, 2904, 2905, 2906, 2907, 2908, 2909
    

    Subset: start=(4, 2), size=(5, 3) and stride=(3, 2). The subset values are:

    1402,1404,1406
    1702,1704,1706
    2002,2004,2006
    2302,2304,2306
    2602,2604,2606