Add-ons


NEW in XMapTools 3.3.1 (Dec. 2019)

Installation

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

Extension Developper(s) Current version Auto-Update Setup Req. Requirements
Img2Txt P. Lanari beta 1.0.0 yes no
XThermoTools P. Lanari and E. Duesterhoeft beta 1.5.1 yes yes Gfortran (Mac)
StackMaps J. Reynes beta 1.0 yes no MATLAB© image processing toolbox

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 installation

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 update

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

function [UpdateState] = Img2Txt_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.