File Exchange

image thumbnail

Volumetric 3

version 1.0.05 (12.3 MB) by James Ryland
3D Volumetric fMRI visualization


Updated 06 Mar 2020

View Version History

View License

View Demo on Youtube Here:
Brief Painting Tutorial:

Volumetric is a full application in Matlab designed to let you create and edit 3D visualizations of brain imaging data. Volumetric easily allows layering and displaying multiple channels of data. It features Volumetric rendering which allows for transparent solids that change color and consistency. You can make very simple and clean visualizations for publication or radically detailed and beautiful brain illustrations or anything in-between. It features a real time layer editor and a ray trace method for producing even higher quality images.
Volumetric only works with data files that have been properly co-registered to a shared space. This can be accomplished using common tools like AFNI and SPM. Typical co-regestration project fMRI coordinates to fMRI coordinates or anatomical coordinates to fMRI coordinates. For visualization purposes you want to project into the highest resolution space possible so you need to project from fMRI to Anatomical coordinates. A tutorial is provided using SPM to help people get accustomed to this work flow.

Volumetric can technically visualize and layer any volumetric data (3D voxel density data). This includes scalar fields, potentially 3D vector fields (if clever), simulation data, geo survey data, and many other domains. Anything that can be converted to a matlab 3D array can be loaded by Volumetric. However size and memory issues can occur depending on scale.
Here are some demo files uploaded to mathworks: <- this is the icon at the top

If you use volumetric for publication purposes please make mention of the Author and cite if possible. I did spend an inordinate amount of time building volumetric 1 2 and 3 so a little recognition would be lovely. I might put some youtube tutorials up at some point.
A lot of people have been asking about this, so I should probably just put it here:
-(Load) at the top of the layer editor loads in a pre-built vl3 visualization file
-(Load Color Source) in the layer editor load in a raw 3D matrix as either .mat or .img, and will allow you to apply a color and transparency mapping to your values.
-(Load Alpha Source) if enabled will allow you to load a 3D matrix for transparency values independently from color
- (The Colored and Grey bars) at the bottom of the layer editor are the color and transparency mappings from low to high. You can paint them by clicking on them, which will update the 3D visualization.
- I will make a YouTube video of the painting process. and link it here soon!

Works on:
Bug Notes:
* Not intended as a toolbox: Recommend downloading as a zip instead and navigating to the Volumetric 3 directory to start
Volumetric. A toolbox version has been uploaded, but not tested....
* Realtime editor has a graphical glitch for Matlab 2016
* Raytrace works but is under development,
* Ray trace lighting is hard to use and unsupported

Author: James Ryland
Institution: The University of Texas at Dallas

Publications that can be cited if you use my software:
1. O’Toole, A. J., Natu, V., An, X., Rice, A., Ryland, J. & Phillips, P. J. (2014). The neural representation of faces and bodies in motion and at rest. NeuroImage. 91, 1-11.
2. Ryland, J. (2013). Volumetric Visualization Technique for Brain Imaging, 2013 International Joint Conference on
Neural Networks.

Cite As

James Ryland (2021). Volumetric 3 (, MATLAB Central File Exchange. Retrieved .

Comments and Ratings (25)

James Ryland

TO: Elisa Alyaqoub:

Thanks for the complement! As I said in the bug-notes I do not think this will run as a toolbox. You should download the program as a zip file/ as loose files then set the volumetric 3 folder as your working directory or navigate to it in matlab then type volumetric in the interpreter to run it. I know that is kind of inconvenient, sorry.

I hope this get you up and running, parting notes if it does not work on your version of matlab see if you can get a hold of matlab 2013b or a version close to that.

Eisa Alyaqoub

This an amazing work.
I download the toolbox file, and when I try to run it, I got installation error which says:
"Toolbox cannot be installed because it is not a valid toolbox file"

Any suggestion on how to be able to run it ?

Thank you.

James Ryland

To Kuchanovics:
You can save a .vl3 file with the layers/alphamaps/colormaps already constructed, and just swap out the input sources for each new visualization. Basically you can treat a saved .vl3 file as a template to be reused. This may not be a great idea with things like fMRI data as machine settings and noise levels may necessitate changing which values are treated as transparent.

To Sara Hanifa:
I've never worked with matlab 7, but given that it was released in 2004 I would guess that it will probably never run on that version of matlab. I would highly recommend trying it on Matlab 2013b if possible, but versions near that release are much more likely to work in general with fewer bugs.

sara hanifa

please , im asking for help, i can't make it working i have matlab 7 and im new in matlab
,must i work with recent version ?? and how can i run it?? plz

Luan Kuchanovicz

Hello James how are you? I have tried in matlab 2013 and it really works and help me a lot. I only want one more help. I am using your program to clear the visualization on my images. I have done 3D arrays with images that are 8bit and contains only points with value 0 and with value 255. i know that i can transparent the points 0 with the scale bar. But have some way that i can change the program to always start with the points 0 to be transparent? In all my array the points with value 0 start in the right side of the edit window. this will help me really a lot!.
If you can help me, email me please.
Really thank you

James Ryland

To Binxu:
Check out the resize tool under the tools menu, it will let you interpolate an input volume to any dimensions you specify. You can use this to create an interpolated version of your volume that has regular voxels.

Sorry if this message doesn't show up or has repeats, mathworks is being weird about me posting messages...

James Ryland

To Binxu:
Clarification, the resize tool will create an interpolated version of your data such that it will have regular voxels if you give it the right settings.

James Ryland

To Laun Kuchanovicz:
Sorry I didn't see this sooner. What version of Matlab are you using? Volumetric was written quite a while back with Matlab 2013b and a lot of small things concerning low-level figure handling and axes rendering have changed syntax slightly. It seems like solving your bug may require a fine grained update of the source code, which I sadly do not have time to do as this was an undergraduate research project that is completely unrelated to my current Ph.D studies.

My recommendation is that you try to get access to an older version of Matlab. If possible Matlab 2013b on a windows or mac machine.

Also a note for any Matlab savvy researchers who have the time and interest, if you want to take a crack at updating my code for new versions of Matlab let me know and you will get my blessing, please remember to accurately cite my code and retain a copy of the license if you choose to update it or adapt it! Alternatively, there is a lot of fun stuff in there that may be useful in your own projects if you want to harvest it, but again please remember to say where you got the code from.


Great work! So how could we specify the voxel size? as we usually has rectangular voxel size with different length in x, y, z direction? Where can we specify that after loading the source data ?

Luan Kuchanovicz

What should I do. When i run the volumetric and chose the 3d array in "Load Color Source" I have this erro.
>> Volumetric
Source Not Set: Base Layer
Error using matlab.ui.Figure/set
Error setting property 'Alphamap' of class 'Figure':
Value must be either:
a vector of type single or double in the range [0 1]
a vector of an integer or logical type

Error in ViewWindow/UpdateMapAlpha (line 161)
set(fig,'alphamap', mapAlpha);

Error in LayerWindow/UpdateScaledVols (line 328)

Error in LayerWindow/UpdateLayer (line 406)

Error in EditWindow/colorVolButton_Callback (line 286)
UpdateLayerHandle(layerStruct, 'vols');

Error while evaluating UIControl Callback.

help me to solve please

James Ryland

Hmm, are you talking about the load button for the Layer Window, or the Load Color Source for the Layer Editor? The load button the the layer window will only load .vl3 files which are produced by loading in volumetric data via the layer editor and saving them?

If you want to load in a 3D matrix stored in a .mat file use the Load Color Source button in the layer editor, then it should pop up after a second.

Symphony Huang

Hi James, good application! But I just found that when I click "Load" it doesn't recognize .mat file...I am using Matlab 2017a on a Macbook Pro. Thanks in advance!

Joel Man

Oh right, I think I solved it with the "Load Color Source" button. Is that correct?

Joel Man

Hi James, the load option does not allow files that are not in the .vl3 format to be loaded.
How can we load .mat files containing a 3D matrix?

James Ryland

When you load a source file it will have an option to directly load it from a .MAT file. You need to save the matrix in as the only object in the .MAT file for it to read correctly. I usually just do >>save 'matrixfile.mat' matrix

Manu Francis

Hi James,

I have a 3D matrix of size 128x128x128. How can I visualize by using volumetric's editor or how can I convert them into .vl3 file?? Thanks in advance

James Ryland

.vl3 is actually just a visualization file format, you create them by loading .mat files that contain 3d arrays and .img files into volumetric's editor.

What you really need is a way to convert from DICOM to IMG files which are another standard MRI format. Alternatively if you have a matlab function that reads DICOM files into 3D density arrays you can just save those arrays and load them into volumetric to build a visualization.

Keep in mind that volumetric is specifically designed for layering multiple sources of voxel data, and you will need to co-register any sources before loading them into volumetric. There is a tutorial doc included which loosely outlines how to do that using SPM.

mohd akmal masud

Hi James, how can i change my image from dicom format to vl3 format?

Tilak Mallikarjun

James Ryland

I have added a section in the description linking to two volumetric Demo files. Additionally I have added a toolbox-version, but I have not had any time to test it. I still recommend downloading as a zip file and navigating to the volumetric 3 folder to start the program.

Jiyang Ye

Hi James

Is it possible you can share some .vl3 test files for test?


James Ryland

Download the entire folder, navigate to that directory in matlab and type volumetric into the command line. That will open application. It is not designed to be run as an add-on. Keep in mind it may not work with matlab 2016 or greater as recent versions of matlab have made changes to key graphics functions and depending on your platform that could cause problems.

Or if you mean how do you download it, you need to choose the download as a .zip file and then unzip it to wherever you want to keep it.

Xinyu Lee

Thank you! But it can't be downloaded in add-on. How to deal with that.

James Ryland

Hey, if people are having trouble using volumetric let me know, and I will speed up my schedule for putting up tutorials!

James Ryland

Recommend that you do not download this as a toolbox. This option has not been tested! Please download the folder, navigate to the Volumetric 3 directory and type Volutmetric to run the program.

MATLAB Release Compatibility
Created with R2013b
Compatible with R2012b to R2014b
Platform Compatibility
Windows macOS Linux

Inspired by: vol3d v2, DTI and Fiber Tracking

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!