Add-ons & XMapTools API

NEW in XMapTools 3.3.1 (Dec. 2019)

You can add new functionality to XMapTools by installing one of the official extensions.

• Add-ons stand as separate programs
• They can be called from the XMapTools interface at any step to perform extra computations
• Add-ons have access via the API to the data generated by XMapTools
• Developers can create their own add-on

List of compatible add-ons

Download add-ons

Add-ons listed above are provided in the official XMapTools package. They also can be downloaded directly via the XMapTools interface using the Extension manager.

Warning: You must use the Extension manager to get the add-ons if you updated to XMapTools 3.3.1 or more recent versions via MATLAB© (i.e. without downloading the full package).

1. Open MATLAB©, set the working directory and open XMapTools
2. In menu, select File > Add-Ons > Manage Extensions
3. In the Extension manager, select one add-on in the menu located on the top left
4. If you do not have this add-on, press the button Download
5. If you already have a version of this add-on and you want to update, press the button Delete & Download.
6. This operation will download the last version of the add-on available on the server

Note: Some add-ons require an additional setup. Simply open the add-on from the XMapTools interface and follow the instructions.

Note: Some add-ons have an auto-update functionality directly implemented in the extension. The add-on checks for update every time it is opened. Add-ons without update system should be updated manually following the procedure given above.

Disable or Remove Add-Ons

Follow these steps if you want to remove an add-on:

1. Navigate to the folder /MyDocuments/MATLAB/XMapTools/Addons/
2. Simply delete the folder containing the add-on

XMapTools API for developers

The application programming interface (API) is intended to simplify the implementation and maintenance of XMapTools’ add-ons.

XMapTools performs the following checks before calling an add-on:

1. Call the add-on installer (e.g. the program AOTest_Install.m for an add-on AOTest) and sends as input variable the absolute path of the add-on. XMapTools proceeds further only if the generic answer 1 is received
2. Call the add-on update program (e.g. AOTest_Update.m) and sends as input variable the absolute path of the add-on. Depending on the update state XMapTools stops or continues further (see below). The developers can decide to make the update mandatory or not (can be skipped)
3. Call the add-on gateway (e.g. AOTest.m)

Step 1: Create the add-on folder and files

1. Create a new folder having the add-on name (case-sensitive) in /MyDocuments/MATLAB/XMapTools/Addons/. For an add-on called AOTest, the add-on directory would be …/XMapTools/Addons/AOTest/
2. In this directory, create three MATLAB© m-files based on the add-on name (here AOTest): AOTest.m; AOTest_Install.m; AOTest_Update.m. Those files are required for allowing XMapTools to properly interact with the add-on.

Step 2: Add-on installer

A template for the setup function (in this example AOTest_Install.m) is provided below.

function [OKrun] = AOTest_Install(Path)
%

% Add any installation code here...

OKrun = 1;
return

If the variable OKrun is not set to 1, XMapTools will prevent the add-on to be used and displays the following warning message: The add-on is not correctly installed and cannot be called by XMapTools

Step 3: Add-on updater

A template for the update function (in this example AOTest_Update.m) is provided below.

function [UpdateState] = AOTest_Update(varargin)
%
% This is the update for the program 
%
% Output varibale "UpdateState" (from XMapTools ...):
%   [-1]        No update system                        Continue
%   [0]         Server cannot be reached                Continue
%   [1]         This add-on is up-to-date               Continue
%   [2]         An update has been installed            Continue
%   [3]         An update is available but skiped       Stop
%   [4]         An update is available but skipped      Continue
%   [5]         Abord the call                          Stop

UpdateState = -1;

return

The value of UpdateState controls the behaviour of XMapTools. If there is no update system, the value should be -1. Other options are given in the comment of the code above.

Step 4: Add-on gateway

It is strongly recommended to use the program with the add-on name (in this example AOTest.m) as a gateway to the add-on interface (e.g. VER_AOTest.m and VER_AOTest.fig). A simple example is provided below.

function varargout = AOTest(varargin)
% AOTest runs the program VER_AOTest
%      AOTest is a MATLAB-based graphic user interface used
%      to illustrate the XMapTools add-on system
%

% Step 1: Get data from XMapTools
Infos = varargin{1};       % State of XMapTools
RawData = varargin{2};     % Data from the X-ray workspace
MaskFile = varargin{3};    % Data from the mask files in X-ray
Quanti = varargin{4};      % Data from the Quanti workspace
Results = varargin{5};     % Data from the Result workspace
ColorBar = varargin{6};    % Data of the active colour palette

% Step 2: Check if the add-on can be called (EXAMPLES...)
if ~isequal(Infos.Mode,1)
    warndlg('AOTest is only available from the workspace "Xray" ...','Warning');
    return         % i.e. the add-on does not open
end

if ~iscell(Infos.Xray.ListMaps) || length(Infos.Xray.ListMaps) < 2 
    
    Text{1} = 'AOTest can not be called because there is no map';
    warndlg(Text,'Warning');
    return         % i.e. the add-on does not open
        
end

% If we passed all the tests made above...
VER_AOTest(RawData);     % i.e. call the add-on
                         % in this example only the data in X-ray are used by the add-on
                         % Other variables (e.g. MaskFile) can be sent to VER_AOTest

return

Step 4: Add-on

The add-on interface can be generated using the GUIDE environment of MATLAB

Note: At the moment it is not possible to send back data; Files should be created instead and then imported via the XMapTools interface.