NASA Logo, National Aeronautics and Space Administration
SPDF

CDF (V3.6.3.1 version) Patch for Matlab


Mathworks MATLAB supports CDF reading and writing with two groups of modules, cdflib and cdfread/cdfwrite. The module cdflib enables creating/reading/writing portions of CDF variables, while cdfread/cdfwrite reads/writes whole variables. Each release of Matlab supports a particular version of CDF; for instance MATLAB version 2016b is based on CDF V3.6.1. However, the MATLAB modules still do not support CDF_INT8 and CDF_TIME_TT2000 data types.

The CDF patch is able to provide modified version of cdfread/cdfwrite (and other routines such as cdfinfo, cdfupdate, and a set of time encoding/decoding functions) in the patches below, but not updates to cdflib.

Times in CDF are generally stored in one of three forms: CDF_EPOCH (8-byte floating milliseconds from 0AD), CDF_EPOCH16 (two 8-byte floats of seconds from 0AD and picoseconds of that second), and CDF_TIME_TT2000 (8 byte integer of nanoseconds from 2000 AD). By default, MATLAB's cdfread uses an object cdfepoch for each CDF_EPOCH value, and can also read the epoch and convert it to datenum. Creating cdfepoch object for each CDF_EPOCH is not efficient as it takes time and more space. cdfread can not read CDF_EPOCH16 (and CDF_TIME_TT2000). CDF_EPOCH16 can only be read, as is, from the cdflib package; no conversion to datenum is available. cdflib reads CDF_EPOCH data like any other data types. SPDF's spdfcdfread can handle all time types, and optionally can convert their values to MATLAB's datenum. SPDF's spdfcdfread also provides cdfepoch and cdftt2000 objects (more accurate but not as efficient as MATLAB's datenum).

If you get error messages reading a CDF file while using MATALB distributed CDF package/modules, we strongly encourage you to try the patch from this page. The patch, based on the original MATLAB-provided code and later expanded, includes many user suggested enhancements and features. The patch can be updated quickly if needed. This patch works only for Matlab version R2007a and later. .

NOTE: Current MATLAB's release is still based on CDF V3.3.0. [Use cdflib.getLibraryVersion function to acquire CDF's library version.] While it works fine with the CDF files with the older data types, it will not work with files that have the newer data types: CDF_INT8 and CDF_TIME_TT2000 (TT2000 for short), that were introduced in CDF V3.3.2.3. Some of the data from newer NASA missions, e.g., Van Allen Probes, MMS, would present a problem as TT2000 is used as the time format. MATLAB plans to upgrade the CDF in its 2016a release. Before then, you have to use the patch for CDF files that have newer data types.

Please note: MATLAB's CDFLIB package was developed and is maintained sorely by MATLAB.

What's Included in the Patch

  • All SPDF-distributed modules are now renamed with a prefix of 'SPDF', e.g., SPDFCDFREAD replaces CDFREAD, SPDFCDFWRITE replaces CDFWRITE, etc. Each module still keeps its original functionality and may have a few new enhancements/features.
  • Extra information is being collected by the SPDFCDFINFO. This new information will make it easier to create new CDF files, based on a template as the 'MASTER' CDF to provide the file settings, and variable and attributes specifications. SPDFCDFWRITE is enhanced to use the information for the CDF write.
  • SPDFCDFREAD is modified to have: 'CombineRecords', true as the default, due to its greatly improved performance and smaller returned data size.
  • A complete set of epoch data handling modules were added. These modules can encode, parse, compute, and break down the epoch data, in CDF_EPOCH, CDF_EPOCH16, and TT2000 format. These modules are:
    spdfbreakdownepoch spdfcomputeepoch spdfepochtodatenum
    spdfbreakdownepoch16 spdfcomputeepoch16 spdfepoch16todatenum
    spdfbreakdowntt2000 spdfcomputett2000spdftt2000todatenum
    spdfdatenumtoepoch spdfparseepoch spdfencodeepoch
    spdfdatenumtoepoch16spdfparseepoch16 spdfencodeepoch16
    spdfdatenumtott2000 spdfparsett2000 spdfencodett2000
    spdfcdfleapsecondsinfo

    Use "help" for their information.

Download and Installation Instructions

Latest patch created in May 2016 is based on CDF Version 3.6.3.1 with the module (.m) patched version 3.6.3.1. You can enter "spdfcdfinfo()" within matlab to view the versions.

Windows:

  1. Download one of following self-extracting files: The shared library included has the latest leap second table embedded.
  2. Optionally, download the leap second table. Do this only if you intend to use the previous MATLAB patch.
  3. Double-click the downloaded file to extract the files included in the patch to a directory. The files will be extracted into c:\matlab_cdf363_patch by default.
  4. Add the installed directory to the PATH environment variable:

    set PATH <patch_install_dir>;%PATH%
    where <patch_install_dir> is the installed directory. The default installation directory is c:\matlab_cdf363_patch.
  5. If you have downloaded the leap second table, then set the environment variable CDF_LEAPSECONDSTABLE to the table.
    set CDF_LEAPSECONDSTABLE='<patch_install_dir>\CDFLeapSeconds.txt'

    This table will be used, instead of the hard-coded one embedded in the released library. Not setting the environment variable will result in the use of the table from the library. The step is necessary when the leap second table is different from the one in the library. Need to set the environment variable before running CDF modules under MATLAB.
  6. Invoke Matlab and issue the following command at the Matlab prompt:

    addpath '<patch_install_dir>'

    For example, if the patch is installed under C:\matlab_cdf363_patch, the command should be

    addpath 'C:\matlab_cdf363_patch'

  7. Use Matlab as usual: e.g.,
    spdfcdfinfo();
    data=spdfcdfread('test.cdf'));

  8. Check the leap second table being used (relevant only to TT2000 time):
    spdfcdfleapsecondsinfo('DUMP', false)

Mac OS X:

  1. Download one of the the following compressed tar files:
  2. Optionally, download the leap second table. Do this only if you intend to use the previous MATLAB patch.
  3. Move the Matlab-CDF-Patch directory in the downloaded file to the directory you want the patch to be installed under.
  4. Extract the files in the patch using the following command:

    tar zxvf <downloaded compressed tar file>

    [The files will be extracted into matlab_cdf363_patch-[32|64] directory, depending the tarfile being extracted.]
  5. If you have downloaded the leap second table, then set the environment variable CDF_LEAPSECONDSTABLE to the table:
    setenv CDF_LEAPSECONDSTABLE "<patch_install_dir>/CDFLeapSeconds.txt" (for c/tcsh shell)
    export CDF_LEAPSECONDSTABLE="<patch_install_dir>/CDFLeapSeconds.txt" (for bash shell)

    This table will be used, instead of the hard-coded one embedded in the released library. Not setting the environment variable will result in the use of the table from the library. The step is necessary when the leap second table is different from the one in the library. Need to set the environment variable before running CDF modules under MATLAB.
  6. Invoke Matlab and issue the following command at the Matlab prompt:

    addpath '<patch_install_dir>'

    For example, if the 64-bit patch is installed under /Users/cdf, the command should be

    addpath '/Users/cdf/matlab_CDF363_Patch'

  7. Use Matlab as usual: e.g.,
    spdfcdfinfo();
    data=spdfcdfread('test.cdf'));

  8. Check the leap second table being used (relevant only to TT2000 time):
    spdfcdfleapsecondsinfo('DUMP', false)

Linux:

  1. Download one of the following compressed tar files:

  2. The shared library included has the latest leap second table embedded.
  3. Optionally, download the leap second table. Do this only if you intend to use the previous MATLAB patch
  4. Go to the directory where you want the patch to be installed under.
  5. Extract the files in the patch using the following command:

    tar zxvf <downloaded compressed tar file>

    [The files will be extracted into matlab_cdf363_patch-[32|64] directory, depending the tarfile being extracted.]
  6. If you have downloaded the leap second table, then set the environment variable CDF_LEAPSECONDSTABLE to the table:
    setenv CDF_LEAPSECONDSTABLE "<patch_install_dir>/CDFLeapSeconds.txt" (for c/tcsh shell)
    export CDF_LEAPSECONDSTABLE="<patch_install_dir>/CDFLeapSeconds.txt" (for bash shell)

    This table will be used, instead of the hard-coded one embedded in the released library. Not setting the environment variable will result in the use of the table from the library. The step is necessary when the leap second table is different from the one in the library. Need to set the environment variable before running CDF modules under MATLAB.
  7. Invoke Matlab and issue the following command at the Matlab prompt:

    addpath '<patch_install_dir>'

    For example, if the 64-bit patch is installed under /home/cdf, the command should be

    addpath '/home/cdf/matlab_cdf363_patch-64'

  8. Use Matlab as usual: e.g.,
    spdfcdfinfo();
    data=spdfcdfread('test.cdf'));

  9. Check the leap second table being used (relevant only to TT2000 time):
    spdfcdfleapsecondsinfo('DUMP', false)

Solaris:

  1. Download the following compressed tar file:

  2. The shared library included has the latest leap second table embedded.
  3. Optionally, download the leap second table. Do this only if you intend to use the previous MATLAB patch
  4. Go to the directory where you want the patch to be installed under.
  5. Extract the files in the patch using the following command:

    tar zxvf <downloaded compressed tar file>

    The files will be extracted into matlab_cdf363_patch-64 directory.
  6. If you have downloaded the leap second table, then set the environment variable CDF_LEAPSECONDSTABLE to the table:
    setenv CDF_LEAPSECONDSTABLE "<patch_install_dir>/CDFLeapSeconds.txt" (for c/tcsh shell)
    export CDF_LEAPSECONDSTABLE="<patch_install_dir>/CDFLeapSeconds.txt" (for bash shell)

    This table will be used, instead of the hard-coded one embedded in the released library. Not setting the environment variable will result in the use of the table from the library. The step is necessary when the leap second table is different from the one in the library. Need to set the environment variable before running CDF modules under MATLAB.
  7. Invoke Matlab and issue the following command at the Matlab prompt:

    addpath '<patch_install_dir>'

    For example, if the patch is installed under /export/home/cdf, the command should be

    addpath '/export/home/cdf/matlab_cdf363_patch-64'

  8. Use Matlab as usual: e.g.,
    spdfcdfinfo();
    data=spdfcdfread('test.cdf'));

  9. Check the leap second table being used (relevant only to TT2000 time):
    spdfcdfleapsecondsinfo('DUMP', false)

If you have any questions or encounter problems, please send an email to cdfsupport and we'll respond as soon as possible.