How to use the MATLAB CEFLIB interface

By looking at the <install-dir>/MATLAB directory you will find :

startup.m

Matlab script to describe where to find the CEFLIB binaries and Matlab scripts

You can copy this file in your usual Matlab working directory, or insert its commands on your own startup file

lib/libcef.so

Dynamic library used to access to the CEFLIB

lib/libcef_mfile.m

Matlab script file describing the CEFLIB interface

lib/cef_init.m

Matlab script file that loads the library and creates alias to facilitate CEFLIB functions calls

Configuration

You will have to update the startup.m, and modify the following line :

ceflib_install_dir = <directory>

Set this variable to the path of the directory where you extract the delivery file.

e.g. : if you extract CEFLIB delivery in the /home/username/CEFLIB directory, set the variable to :

ceflib_install_dir = /home/username/CEFLIB

This startup.m script file, run during Matlab launch, will add the following path to the list of directories where Matlab searchs for tools and librairies :

/home/username/CEFLIB/MATLAB/lib

MATLAB library reference manual

The MATLAB CEFLIB interface is compounded of the following functions :

cef_init ()

This function must be called first, in order to :

  • load the shared library libcef.so,

  • create function handlers to facilitate the call to the functions of this CEFLIB library.

cef_read (cef-filename)

This function will read the given CEF file, load all data and metadata in memory, allowing further data or metadata queries.

Return an error code (O : OK, > 100 : error)

cef_close ()

Release memory allocated for the CEF variables and metadata.

cef_verbosity (level)

This function should be used to increase the level of verbosity of the CEFLIB, in order to debug why the CEFLIB is not able to read a given CEF file.

Default value for level is 1, and could be increased up to 2, 3, 4, 5.

Caution As Matlab is not using the usual Unix stdout stream when launched with its Java interface, you will have to run it in console mode to see the CEFLIB debug and trace messages.

Use the following command lines to perform such debug :

$ matlab -nojvm
$ cef_init ()
$ cef_read ('cef-filename')

cef_metanames ()

Returns a list of strings (Matlab cell-array), giving the metadata section names.

cef_meta (metadata-section) → array of strings

Returns the list of string entries for this metadata section

cef_gattributes ()

Returns the list of global attributes names

cef_gattr (attribute)

Returns the value of a global attribute:

  • result should be a string if the attribute has an unique value

  • or a list of strings for multi-valued attributes

cef_vattributes (varname)

Returns the list of attributes names for a given variable

cef_vattr (varname, attribute)

Returns the value of a given CEF variable attribute:

  • result should be a string if the attribute has an unique value

  • or a list of strings for multi-valued attributes

cef_varnames () → array of strings

Returns the list of CEF variables found in the file

cef_var (varname) → array of strings | n-dimensions matrix

Reads the content of a given CEF variable, and returns :

  • a Matlab cell-array for string variables (CEF CHAR)

  • a n-D matrix for numerical variables (CEF ISO_TIME, FLOAT, INTEGER)

cef_depends (varname) → array of strings

Returns a list of DEPEND_i variable names for a given CEF variable

The first one correspond to the DEPEND_0, then DEPEND_1, DEPEND_2, …

Values can be empty strings if DEPEND_i attribute is not set.

cef_date ()

Time-tags are internally coded in milli-seconds from 1958 in the CEFLIB, but you can use this function to translate them in fractional days used by Matlab. Input can be a scalar or an array

tt = cef_date (cef_var ('time_tags'))

milli_to_isotime (time-tag-variable, number-of-digits)

This function will convert internal time-tags (Milli-seconds from 1958) in ISOTIME strings.

The first argument could be an ISO_TIME or ISO_TIME_RANGE CEF variable

The second arguments give the number of digits expected for fractional seconds :

  • 0: seconds

  • 3: milli-seconds

  • 6: micro-seconds

Example

How to open a CEF file and print time-tags with micro-seconds resolution :

cef_read ('some-example-file.cef')
disp (milli_to_isotime (cef_var ('time_tags'), 6))