gllmflndn/gifti

MATLAB/Octave GIfTI Library

GIfTI library for MATLAB/Octave

This GIfTI library allows to handle the GIfTI Geometry file format from the Neuroimaging Informatics Technology Initiative (NIfTI) using a MATLAB/Octave class:

• GIfTI: https://www.nitrc.org/projects/gifti/
• NIfTI: https://nifti.nimh.nih.gov/

It relies on external libraries:

• yxml, by Yoran Heling
• Base64, by polfosol
• miniz, by Rich Geldreich

Note that these tools are already included in the GIfTI library provided here, so you don't need to install them separately.

There are import facilities from FreeSurfer, VTK, Wavefront OBJ, Stanford PLY, STL and MZ3 file formats.

There are export facilities to VTK, Collada, IDTF, Wavefront OBJ and JS/JSON (for Plotly) file formats.

This library is also part of SPM.

INSTALLATION

MATLAB R2007a or above is required to use most of the features of this toolbox. GNU Octave is also supported.

All the code is embedded in a @gifti class. To install it, all you need is to make sure that the directory containing @gifti is in MATLAB path:

addpath /home/login/Documents/MATLAB/gifti

The library relies on a number of C-MEX files (zstream, base64, xml_parser). Compiled versions for 64 bit MATLAB on Windows, Linux and Mac are provided but they can easily be compiled by yourself otherwise, see @gifti/private/Makefile.

TUTORIAL

In the following, we use the files contained in BV_GIFTI.tar.gz (BrainVISA examples), available from the NITRC website:

% Read the GIfTI surface file
g = gifti('sujet01_Lwhite.surf.gii')

% Read the GIfTI shape file
c = gifti('sujet01_Lwhite.shape.gii')

% Display mesh
figure; plot(g);
% Display mesh with curvature
figure; plot(g,c);

In a similar way, a gifti object can be created from an extracted isosurface from volume data and saved to a file:

load mri % an example dataset available in MATLAB
D = squeeze(D);
Ds = smooth3(D);
g = gifti(isosurface(Ds,5))

h = plot(g);
daspect([1,1,.4]); view(45,30); axis tight
lightangle(45,30);
set(h,'SpecularColorReflectance',0,'SpecularExponent',50)

save(g,'mri.surf.gii','Base64Binary');

SEE ALSO

Export to Plotly.

gifti's Issues

Error displaying gifti object

I'm getting the below errors when trying to display a loaded gifti object:

I'm running MATLAB 2020b on Mac OS 10.15.7. The surface data itself is read properly, and I can plot the surface or display g.vertices and g.faces without error; displaying g.mat gives a similar error. Any idea what's going wrong? Thanks,

Ben

Enforcing ArrayIndexingOrder on save causes malformed files

When opening the BrainVISA examples and storing them the stored file will have the wrong ArrayIndexingOrder. Opening the file in freeview will prompt an error
(mrisReadGIFTIfile: malformed data array [2] in file test.surf.gii: num_vertices=3 num_cols=22134 expected nvertices=22134, num_cols=3)

example code:
testA=gifti('\Base64\sujet01_Lwhite.surf.gii');
save(testA,'test.surf.gii','Base64Binary');

gifti/subsasgn "Syntax not implemented."

Hi Guillaume,

Consider this example:

>> gii = gifti('goodfile.func.gii');  % the file loads successfully
>> gii.cdata = zeros(size(gii.cdata));
Error using gifti/subsasgn (line 130)
Syntax not implemented.

I tried editing directly the gii.private.(...) fields, and the file then can even be saved, but then it appears to be invalid and can't be read back with gifti.

Not sure what to do...

Thanks!

Cheers,

Anderson

gifti/subsasgn "Syntax not implemented." Change in timeseries length

I am attempting to load a gifti timeseries, remove non-steady-state volumes, and then save the resulting data array. I'm getting the following error:

>> ndiscard=8
>> f = gifti('file.func.gii');
>> ts = f.cdata;
>> ts = ts(:,(ndiscard+1):end);
>> fout = f;
>> fout.cdata = ts;
Error using gifti/subsasgn (line 136)
Syntax not implemented.

This error appears to stem from line 130 of subsasgn (if numel(n) == size(A,2)) which ensures that any processing that changes the timeseries length will lead to an error. I realize I can create a new gifti (e.g. fout = gifti(ts)). However, I then lose all metadata from the original file which creates issues at later steps of my analysis pipeline.

invalid mex-file

Hi there, I am using gifti toolbox in matlab in my PC-macOS (10.15.7) with Matlab2019b & server-centOS with matlab2017b, I suddenly can't use gifti function with an invalid mex-file error...

`a=gifti('sub-01_ses-1_task-rest_run-1_space-fsaverage5_hemi-L_bold.func.gii');
Invalid MEX-file '/Users/gifti-master/@gifti/private/xml_parser.mexmaci64':
dlopen(/Users/gifti-master/@gifti/private/xml_parser.mexmaci64, 6): no suitable image
found. Did find:
/Users/gifti-master/@gifti/private/xml_parser.mexmaci64: code signature in
(/Users/gifti-master/@gifti/private/xml_parser.mexmaci64) not valid for use in
process using Library Validation: library load disallowed by system policy

Error in gifti_read (line 14)
t = xml_parser(filename);

Error in gifti (line 105)
this = gifti_read(varargin{1},giftistruct);`

I googled a lot but nothing helps, (including delete all .mexmaci64 scripts...) I really looking forward to your reply.

Any helps would be appreciated.

Thanks!

Connectome matrix data

This is not an issue per se, but I am after some advice. I have downloaded data and code from NITRC website, so as to run the example presented on git, that works great.

I would like to have access, however, to some connectomic data matrix: if a mesh has n vertices, I would like to generate a (possibly sparse) n-by-n matrix of connectivity strengths from, say, vertex I to vertex J in the mesh.

Do you know if any such data, complementing the gifti data that you already indicate, is present in the NITRC website?

Different dimension issue in save function

Trouble opening gifti files saved with the gifti toolbox in CAT12 display results

Good afternoon,

My apologies if this doesn't belong here, but I am unsure where else I should ask.

I need to edit some the thickness data stored in the cdata of gifti files resulting from CAT12 cortical thickness estimation and am having trouble opening the gifti files with the edited cdata in CAT12, saved using the save function of the gifti toolbox. CAT12 throws an error related to xmlparser or xmltree functions (error message below), depending on what system I try this on (Ubuntu and Windows errors respectively).

To make sure this error is not due to my manipulation of the cdata in the gifti files, I tried simply opening (using gifti() function) and then immediately saving (save() function) a gifti file that is possible to open in CAT12 'display results' function without any problem. However, after doing this simple load and save, I get the same error. This makes me think that there is some information loss when saving the gifti files in the toolbox that makes it impossible for CAT12 to open them.

Is there a way to rectify this?

Please note that I tried saving with all possible encoding options and the problem still persists.

Error message in CAT12 when trying to load the loaded and immediately saved gifti file on Windows:
Warning: [GIFTI] Parsing of XML file C:\Users\Martin
Gell\Desktop\M&B\Classes\Matlab\Toolboxes\spm12\toolbox\cat12\templates_surfaces.mc.freesurfer.gii failed.

In read_gifti_file (line 17)
In gifti (line 108)
In cat_surf_results>display_results_all (line 1129)
In cat_surf_results (line 511)
In cat_surf_results>select_data (line 1663)
Error using xmltree (line 47)
[XMLTree] Cannot open C:\Users\Martin
Gell\Desktop\M&B\Classes\Matlab\Toolboxes\spm12\toolbox\cat12\templates_surfaces.mc.freesurfer.gii

Error in xmltree (line 47)
error(['[XMLTree] Cannot open ' varargin{1}]);

Error in read_gifti_file (line 15)
t = xmltree(filename);

Error in gifti (line 108)
this = read_gifti_file(varargin{1},giftistruct);

Error in cat_surf_results>display_results_all (line 1129)
g1 = gifti(fullfile(spm('dir'), 'toolbox', 'cat12', ['templates_surfaces' H.str32k], [H.S{i}.info(1).side
'.mc.freesurfer.gii']));

Error in cat_surf_results (line 511)
display_results_all;

Error in cat_surf_results>select_data (line 1663)
cat_surf_results('disp', H.S{1}.name, H.S{2}.name);

Error while evaluating DestroyedObject Callback.

coordinate system

Dear Developer and contributors,

Given little documentation on the library, I have hard time figuring out how to specify two coordinate systems to be used for output of the same surface. I know GIFTI formal allows it. Similarly, when reading a GIFTI file, only one transformation (seems to be always the first) is loaded without attributes (anatomical, unknown, etc). How do I deal with these?

Thank you,

Line breaks in Base64 strings

Sometimes Base64 strings contain line breaks (typically) every 76 characters: they should be ignored as well as any other character that is not in the Base64 character list. This is implemented in base64decode.m:
https://github.com/gllmflndn/gifti/blob/master/%40gifti/private/base64decode.m#L36-L39
but not in base64.c. Fixing this will probably result in cancelling the speed advantage of the current C implementation with respect to other ones.
Base64 encoding should not be modified to include line breaks.

See e.g.:

<Data>AhkAAANGAAACZAAABTcAAAJkAAADRgAAAmQAAAU3AACDEQAAA0YAAEIGAAAFNwAAgxEAAANkAAAC
ZAAABGQAAAJkAAADZAAAAmQAAARkAAACGQAAA2QAAMUNAAAEZAAAYwQAAAJGAACILwAABGQAAIgv
AAACRgAA
</Data>

Deprecated syntax in gifti/subsref.m?

This line creates warnings in newer Matlab versions:
https://github.com/gllmflndn/gifti/blob/master/%40gifti/subsref.m#L45

Warning example, form the Brainstorm user forum:

Do you need these () for anything here?

How to write a 2D matrix into gii file in matlab?

Hi! I used the gii.cdata matrix to perform filtering. And after that, I wondered if there's any way to write this 2D matrix into a new gii file.?I've looked at the example in tutorial and it seemed the isosurface function can only be used on 3D data. Thanks!

test_gifti.m fails

Hi, I just began to try the code out and test_gifti.m gave this error:

Error using read_gifti_file
[GIFTI] Loading of XML file
<file_name> failed.

Error in gifti (line 71)
this = read_gifti_file(varargin{1},giftistruct);

Error in test_gifti (line 14)
g = gifti(file);

Plz help out. Thank you

Error on Matlab 2023b

Matlab 2023b; Ubuntu 22.04 (64)

Running the first README example and fails on loading data using gifti function.

Error - too many input arguments for a struct.

Replicated also using any other nifti file.

Any suggestions on which Matlab versions might work?

Error using struct
Too many input arguments.

Error in gifti>giftistruct (line 132)
struct(...

Error in gifti (line 108)
this = gifti_read(varargin{1},giftistruct);

Error using struct
Invalid default value for property 'N' in class 'mtree':
Too many input arguments.

Error in nodeinfo (line 40)
L = struct( lnk{:} );

Error in mtree_info (line 18)
[LNK,LMAP,LOK] = nodeinfo();

Error in matlab.internal.editor.evaluateCode

Error using struct
Invalid default value for property 'N' in class 'mtree':
Too many input arguments.

Error in nodeinfo (line 40)
L = struct( lnk{:} );

Error in mtree_info (line 18)
[LNK,LMAP,LOK] = nodeinfo();

Error in matlab.internal.editor.evaluateCode

Error using struct
Invalid default value for property 'N' in class 'mtree':
Too many input arguments.

Error in nodeinfo (line 40)
L = struct( lnk{:} );

Error in mtree_info (line 18)
[LNK,LMAP,LOK] = nodeinfo();

Error in matlab.internal.editor.evaluateCode