Home

μVES - Wiki

This page will guide you through:

• Installation
• Usage

Installation

Weather this repo is downloaded as a zipped package and extracted or it is cloned from Git, make sure that it gets located inside of a folder that inside of the MATLAB PATH. The root MATLAB folder C:\Users\<user>\Documents\MATLAB is already added to the PATH.

Add additional folders to the path is done in: HOME > Environment > Set Path > Add with Subfolders

---

Version

The code has been developed and tested from MATLAB_R2020a onwards (latest test was perfomed on version R2022a).

You can report version incompatibilities by opening an Issue.

---

Requirements

Other than the basic MATLAB package, the following Add-Ons are required:

• Image Processing Toolbox
• Curve Fitting Toolbox
• Computer Vision Toolbox
• Deep Learning Toolbox

Upon activation, μVES will automatically check for the presence of these packages and will prompt the user to install them if they are not found.

Installation is possible via: HOME > Environment > Set Path > Add with Subfolders

---

Usage

μVES is an automated tool for the topological and morphological analysis of 3D images of microvascular networks acquired from confocal microscopy. The supported file extensions are .oib and .nd2.

A surrogate 2D version of μVES is also available and it supports any standard image file type. However, uncompressed formats like.bmp and .tiff are preferred. The steps for using μVES 2D are analogous to those of its 3D counterpart.

1. Set up the analysis parameters

μVES is highly flexible in terms of prioritizing accuracy or computational time. To best exploit such feature, the muVES_settings.txt configuration file can be personalized with the required parameters.

• Open the muVES_settings.txt file [1] in the text editor of your choice (opening it in MATLAB works fine)
• Edit the parameters as you wish [2].

Most importantly, set the pixel density in the 3 directions: the value in μm/px will be used in outputting the results in μm

Example: By increasing the Radius Precision parameters, the radius of a vessel will be calculated by accounting more points along the longitudinal coordinate, granting a higher accuracy but requiring more computation.

A verbose description of each parameter is provided in the file itself.

2. Run the analysis

Once the analysis parameters have been set up, μVES is ready to run: launch it by opening the file muVES_3D.m [1] and then click on the Run button in the editor tab (or press F5 as the default keyboard shortcut) [2].

You will be prompted to a File Explorer window that you'll use to navigate through your files: select your file saved in one of the files in the supported formats [3] and click Open [4].

μVES is now running, and its progress can be monitored in the command window.

NOTE: μVES does NOT run as a background MATLAB process, therefore the command window cannot be used for other tasks.

The computational time that μVES requires is dependent on:

• The specs of your machine (CPU and RAM speed above all)
• The parameters specified in the muVES_settings.txt configuration file
• The quality of the raw input image
• The topological and morphological complexity of the input image

3. Gather the output data

Once you see message

> Results saved at: <name-of-the-inpout-file>.mat

ans = 

struct with fields:
    info: ...
     raw: ...
    flat: ...
     ...: ...

in the Command Window, μVES has finished its analysis.

Output files are saved in the same directory of your input files and with its same name, but different extensions. For example, if you performed an analysis on

C:\Users\<user>\myfiles\filename.oib

you will find output files in the folder

C:\Users\<user>\myfiles

namely:

• filename.mat: Contains a MATLAB variable named mvn with numerical results of the analysis, as the average length, radius, eccentricity, etc. It contains also the segmented and the skeletonized images of the network, as well as a list of its branches and their connectivity. The file muVES_legend.txt is a detailed description of all the fields of the struct mvn
• filename.bmp: Contains a 2D projection of the 3D image
• filename_radius.pts and filename_bifurcation.pts: Input files for a 3D Poiseuille-Darcy Finite Elements simulation (only if the parameter in muVES_settings.txt configuration is set to output them)

The contents of the .mat file are also accessible from the MATLAB workspace under the ans variable. A legend on the fields of the struct mvn is provided for easier reading at [this wiki page]("wiki/Results interpretation.md")

DIMENSIONALITY: Results are given in μm

4. Visualizing Results

The repository also includes the script muVES_visualize.m. This script produces appealing graphs and visual representations for the analysis performed by μVES.

In the same way as any other MATLAB script, it must be run with a click on the Run button in the editor tab (or with F5 as the default keyboard shortcut). Upon running, it will prompt the user to select the .mat file produced by the μVES analysis.

Although the plotting and rendering of the graphs and 3D models usually does not require toomuch time, specific plots can be skipped by setting the corresponding parametrs to 0 in the first lines of the script.