MATLAB Release Notes

MATLAB 6.5.1 Release Notes

New Features

This section introduces the following new features and enhancements added in MATLAB 6.5.1 since Version 6.5 (Release 13):

If you are upgrading from a release earlier than Release 13, then you should also see New Features in the MATLAB 6.5 Release Notes.

MATLAB Interface to Generic DLLs

A shared library is a collection of functions that are available for use by one or more applications running on a system. On Windows systems, the library is precompiled into a dynamic link library (.dll) file. At run-time, the library is loaded into memory and made accessible to all applications. The MATLAB Interface to Generic DLLs enables you to interact with functions in dynamic link libraries directly from MATLAB.

Documentation

For help on this new feature, see MATLAB Interface to Generic DLLs in the External Interfaces documentation.

The examples used in the documentation use library (.dll) and header (.h) files located in the MATLABROOT\extern\examples\shrlib directory. To use these example files, first add this directory to your MATLAB path with the following command:

addpath([matlabroot '\extern\examples\shrlib'])

Or you can make this your current working directory with this command:

cd([matlabroot '\extern\examples\shrlib'])

Restrictions for This Release

At this time, the MATLAB Interface to Generic DLLs is supported on Windows systems only.
Passing a void ** argument to a function in a dynamic link library is not supported in this release.
Passing a complex structure argument to a function in a dynamic link library is not supported in this release. (The term complex structure argument refers to a structure constructed from other structures.)
Passing an array of pointers, is not supported in this release. An example of an array of pointers is an array of strings.
MATLAB does not support manipulation of pointers returned by functions in a dynamic link library at this time. An example of this type of operation is the addition or subtraction of pointers.

Function and Data Type Names in Generic DLL Interface

Minor changes have been made to the naming of some functions and data types in the Generic DLL interface. If you are upgrading from the post-release 13 download of MATLAB, see Function and Data Type Names in Generic DLL Interface of these release notes.

Relational Operators Work with int64, uint64

All relational operators such as, <, >, <=, >=, ~=, and == now support int64 and uint64 data types.

Reading HDF5 Files

This release includes support for reading files that use the Hierarchical Data Format, Version 5 (HDF5). HDF5 is a product of the National Center for Supercomputing Applications (NCSA). The NCSA develops software and file formats for scientific data management.

This section includes this information:

An overview of the structure of an HDF5 file
Determining the contents of an HDF5 file
Reading data from an HDF5 file
Mapping HDF5 data types to MATLAB data types

Note MATLAB has supported reading and writing HDF files for several releases. The HDF and HDF5 specifications are not compatible.

Overview of HDF5 File Structure

HDF 5 files can contain multiple datasets. A dataset is a multidimensional array of data elements. Datasets can have associated metadata. HDF5 files store the datasets and attributes in a hierarchical structure, similar to a directory structure. The directories in the hierarchy are called groups. A group can contain other groups, datasets, attributes, links, and data types.

To illustrate this structure, the following figure shows the contents of the sample HDF5 file included with MATLAB, example.h5.

Figure 14-1: Hierarchical Structure of example.h5 HDF5 File

Determining the Contents of an HDF5 File

To extract an attribute or dataset from an HDF5 file, you must know the name of the attribute or dataset. You specify the name as an argument to the hdf5read function, described in Reading Data from an HDF5 File.

To find the names of all the datasets and attributes contained in an HDF5 file, you can use the hdf5info function. For example, to find out what the sample HDF5 file, example.h5, contains, use this syntax.

```
fileinfo = hdf5info('example.h5');
```

The fileinfo structure returned by hdf5finfo contains various information about the HDF5 file, including the name of the file and the version of the HDF5 library that MATLAB is using.

fileinfo = 
          Filename: 'example.h5'
        LibVersion: '1.4.2'
            Offset: 0
          FileSize: 8172
    GroupHierarchy: [1x1 struct]

To explore the contents of the file, examine the GroupHierarchy field.

level1 = fileinfo.GroupHierarchy

level1 = 

      Filename: 'C:\matlab\toolbox\matlab\demos\example.h5'
          Name: '/'
        Groups: [1x2 struct]
      Datasets: []
     Datatypes: []
         Links: []
    Attributes: [1x2 struct]

The GroupHierarchy structure describes the top-level group in the file, called the root group. HDF5 uses the UNIX convention and names this top-level group / (forward slash), as seen in the Name field. The other fields in the structure describe the contents of the group. In the example, the root group contains two groups and two attributes. All the other fields, such as the Datasets field, are empty. To traverse further down the file hierarchy, look at one of the structures in the Groups field.

level2 = level1.Groups(2)

level2 = 

      Filename: 'C:\matlab\toolbox\matlab\demos\example.h5'
          Name: '/g2'
        Groups: []
      Datasets: [1x2 struct]
     Datatypes: []
         Links: []
    Attributes: []

In this group, the Groups field is empty and the Datasets field contains two structures. To get the names of the datasets, examine the Name field of either of these Dataset structures. This structure provides other information about the dataset including how many dimensions it contains (Dims) and the data type of the data in the dataset (Datatype).

dataset1 = level2.Datasets(1)

dataset1 = 

      Filename: 'L:\matlab\toolbox\matlab\demos\example.h5'
          Name: '/g2/dset2.1'
          Rank: 1
      Datatype: [1x1 struct]
          Dims: 10
       MaxDims: 10
        Layout: 'contiguous'
    Attributes: []
         Links: []
     Chunksize: []
     Fillvalue: []

Reading Data from an HDF5 File

To read an HDF5 file, use the hdf5read function, specifying the name of the file and the name of the dataset as arguments. For information about finding the name of a dataset, see Determining the Contents of an HDF5 File.

For example, to read the dataset, /g2/dset2.1 from the HDF5 file example.h5, use this syntax:

data = hdf5read('example.h5','/g2/dset2.1');

The return value data, contains the values in the dataset, in this case a 1-by-10 vector of single precision values.

data =

  Columns 1 through 8 

    1.0000    1.1000    1.2000    1.3000    1.4000    1.5000    
1.6000    1.7000

  Columns 9 through 10 

    1.8000    1.9000

Mapping HDF5 Data Types to MATLAB Data Types

The hdf5read function maps HDF5 data types to MATLAB data types, depending on whether the data in the dataset is in an atomic data type or a non-atomic data type.

HDF5 Atomic Data Types. If the data in the dataset is stored in one of the HDF5 atomic data types, hdf5read uses the equivalent MATLAB data type to represent the data. Each dataset contains a Datatype field that names the data type. For example, the dataset /g2/dset2.2 in the sample HDF5 file includes this data type information.

dtype = dataset1.Datatype 
dtype = 

        Name: []
       Class: 'H5T_IEEE_F32BE'
    Elements: []

The H5T_IEEE_F32BE class name indicates the data is a four-byte, big-endian, IEEE floating point data type. (See the HDF5 specification for more information about atomic data types.)

HDF5 Non-Atomic Data Types. If the data in the dataset is stored in one of the HDF5 non-atomic data types, hdf5read represents the dataset in MATLAB as an object. To access the data in the dataset, you must access the Data field in the object.

To illustrate, this example uses hdf5read to read a dataset called /dataset2 from the HDF5 file, my_hdf5_file.h5. The dataset contains four elements; each element is an HDF5 array.

data = hdf5read('my_hdf5_file.h5','/dataset2');

In MATLAB, the hdf5read function creates a a 1x4 array of hdf5.h5array objects to represent this data.

whos 

Name    Size        Bytes     Class

data     1x4                hdf5.h5array

Grand total is 4 elements using 0 bytes

Index into the MATLAB array to view the first element in the dataset.

data(1)

hdf5.h5array: 

Name: '' 
Data: [4x5x3 int32]

To look at the raw data in the HDF5 array element, access the Data field in the object.

data(1).Data

ans(:,:,1) =
0 1 2 3 4 
10 11 12 13 14 
20 21 22 23 24 
30 31 32 33 34

ans(:,:,2) =
100 101 102 103 104 
110 111 112 113 114 
120 121 122 123 124 
130 131 132 133 134

ans(:,:,3) =
200 201 202 203 204 
210 211 212 213 214 
220 221 222 223 224 230 231 232 233 234

The hdf5read function uses any of the following objects to represent HDF5 non-atomic data types.

hdf5.h5array
hdf5.h5enum
hdf5.h5vlen
hdf5.h5compound
hdf5.h5string

Reading and Writing Data with JPEG Lossless Compression

MATLAB now supports reading and writing data that has been compressed using JPEG lossless compression. With lossless compression, you can recover the original image from its compressed form. Lossless compression, however, achieves lower compression ratios than its counterpart, lossy compression.

Using the imread function, you can read data that has been compressed using JPEG lossless compression.

Using the imwrite function, you can write data to a JPEG file using lossless compression. For the imwrite function, you specify the Mode parameter with the 'lossless' value.

Major Bug Fixes Reading and Writing L*a*b* Color Data