Programmer manual

Introduction

This document details the Programming technical documentation, including the installation of the development environment, the structure of the application, its compilation, the configuration of the various integration services used and the group of tests performed.

Directory structure

The project repository has the following structure:

• /: Repository root directory. This is where all the project directories are located, as well as a README.

• /appcode: Application directory. This contains both the application itself and the directories necessary for its correct execution.

• /appcode/: Application source code directory.

• /appcode/code/functions: Directory of the scripts used by the system.

• /appcode/code/livescripts: Directory of the livescripts and their corresponding HTML documentation within the application, both in Spanish and English.

• /appcode/code/livescripts/img: Directory of the images used in the documentation of the livescripts.

• /appcode/code/test: Directory of the unit tests of the ‘/functions’ scripts. They have a README to run them correctly.

• /appcode/code/data: Directory of the images provided and their respective ground truth images, it also contains a README to explain the nomenclature used in the images.

• /appcode/code/data/images: Directory of the images provided by the application.

• /appcode/code/data/images_ground_truth: Directory of the ground truth images corresponding to the images provided by the application.

• /experiment/: This directory contains the (i) input image/dataset, (ii) output image results when applying the combination of invariant and clustering algorithms, and (iii) a spreadsheet with summary statistics to compare the performance of image segmentation when applying combinations of invariant and clustering algorithms.

Programmer manual

The following manual aims to explain how a programmer can download the project and develop his/her own version.

Development environment

In order to work with the project it is necessary to have this series of programs and dependencies installed.

• MATLAB 2023b.

• MATLAB Add-On Toolboxes.

• GitHub Desktop.

The reader will find below the instructions to correctly install and configure each one of them.

MATLAB 2023b

The main and essential program for the execution of this project is MATLAB, more specifically version 2023b. To download it we have to go to the official MATLAB website . Once the application is started, you will be asked to enter a MATLAB account.

MATLAB Add-On Toolboxes

Once MATLAB is installed, it will be necessary to install a series of Add-On Toolboxes for the correct execution of the project. These are the following:

• Statistics and Machine Learning Toolbox.

• Fuzzy Logic Toolbox.

• HMRF-EM-image.

• MATLAB Compiler.

This can be done from the APPS’ top menu and then clicking on Get More Apps’. A new window will then appear where, using a search engine, the necessary Add-On Toolboxes can be accessed. Below is an example of the installation of ‘Statistics and Machine Learning Toolbox’´. Figure shows the window that is obtained after installing Statistics and Machine Learning Toolbox.

GitHub Desktop

Installing GitHub Desktop is not strictly necessary, but it is recommended as it allows version control, which is of great interest when making changes to the application.

To install GitHub Desktop, go to the official page and download the necessary files from there. After installation, you will be asked to enter your GitHub user.

Repository download

There are two main options:

Manual source code access

In case we do not consider version control necessary, we can directly download the project’s .zip file from the GitHub repository. This is done by clicking on the ‘Code’ button and then on the ‘Download ZIP’ button. After this, all that remains is to unzip the project into the desired directory.

Source code using GitHub Desktop

If you want to have version control, you can use the GitHub Desktop application mentioned.

To do this, you must enter the application, click on ‘Clone repository’ and enter the link of the project you want to clone. In this case, the repository link for this project is the following: https://github.com/admirable-ubu/InvIPM.git. Next, you must indicate where you want to store the repository.

Project import

For a correct project execution, you must open MATLAB 2023b and navigate within MATLAB to the directory where the repository is located. Once there, you must type ‘appdesigner’ in the console to open the corresponding window, where you can view, modify and execute, among many other functionalities, the application.

MATLAB App Designer

The first screen that appears when you open MATLAB App Designer will allow you to open a project. Here you have to select the file ‘InvIPM.mlapp’ that is located in the ‘/app’ directory.

Once the project is opened, you will see a design view of the application where you can modify the position and some values ​​within the visual section as shown in figure [fig:MATLAB_App_Designer] and another button that allows you to access the code view.

Figure shows the interface that MATLAB displays after the previously downloaded project has been opened.

It is in the code view where you can modify the visual objects in more depth and program the functionalities of the different interactions of the application.

Although the way of programming in MATLAB App Designer is very similar to programming in MATLAB, there are a series of changes and functionalities that are very relevant. In the following link you will find a guide to the functionalities and how to program in MATLAB App Designer

Project complation, installation and execution

Here’s how to:

• Compiling and running the project within MATLAB.

• Creating a new release using a MATLAB Standalone Application.

• Directories created by the MATLAB compiler.

• Running the Standalone App.

App Designer compilation

MATLAB allows you to compile and run the application directly from the interface. To do this, simply click the ‘run’ icon on the top bar. This icon is shown in figure.

Figure shows the location in the interface of the button used to compile and run the app.

After this, the application will open in a pop-up window where you can easily test the different functionalities that are added. This window will have a similar appearance to that shown in figure.

Figure shows the window that is automatically created after compiling and running the application.

Creation of a new release

After making the necessary changes or adding new features to the application, the next step is to share the application. MATLAB has three options for this:

• MATLAB App: This option allows you to create an installation file to share the application with other MATLAB users. If the goal is for them to be able to modify or see how the application works, this is the best option.

• Web App: This option allows you to create and deploy web applications using MATLAB Compiler, facilitating their distribution and use in different environments. This has been rejected since this functionality is offered but it is paid for.

• Standalone Desktop App: This option allows you to create standalone desktop applications using MATLAB Compiler, which require MATLAB to be installed in order to run. This is the option that has been used and will be explained in more detail below.

MATLAB Standalone Application

In order to create a Standalone Application within MATLAB App Designer, you must click the share icon and then select the ‘Standalone Desktop App’ option. After this, a window will appear to add the relevant information of the application to be created. Here you must enter the following data, as shown in figure

• Name of the application.

• Version of the application.

• Author (name, email, company).

• Description (optional).

• Files and directories required for the correct execution of the program.

• Files visible to the user.

Figure shows the interface that MATLAB offers for creating a Standalone App.

Standalone App execution

Opening the ‘InvIPM.exe’ file will take you to the application, which will run all the scripts and code transparently to the user, displaying only the desired directories. In this case, these would be:

• The ‘/data’ directory, since it contains the test images with their respective groundtruth images.

• The ‘/cache’ directory, since it will be where all the results of old executions will be stored temporarily.

• The ‘/results’ directory, since it will be the default path offered to the user when he wants to save the results of an execution.

• The README with the pertinent explanations.

• The application splash.

System tests

The system tests are as follows.

Test cases

Multiple unit tests have been created to check the correct operation of the scripts used by the application in isolation.

The different tests created are the following:

• alvarez_transformTest.m

  • Basic test.

  • Extreme value test.

  • Test with a uniform image.

  • Test with a black and white image.

• maddern_transformTest.m

  • Basic test.

  • Extreme value test.

  • Test with a uniform image.

• krajnik_transformTest.m

  • Basic test.

  • Extreme value test.

  • Test with a uniform image.

• upcroft_transformTest.m

  • Basic test.

  • Extreme value test.

  • Test with a uniform image.

• calcular_alphaTest.m

  • Basic values test.

  • Test with lambda1 to 0.

  • Test with the same value for the three lambdas.

• calcular_theta_krajnikTest.m

  • Basic test.

  • Test with a uniform image.

  • Test with a black and white image.

• calcular_coincidenciaTest.m

  • Test with the same image.

  • Test con different images.

• check_cacheTest.m

  • cache exists (creates it, adds an image, then deletes the cache) test.

• convertir_a_blanco_negro_con_bordesTest.m

  • Test with a perfect case.

  • Test with a not perfect case.

• imagen_tres_canalesTest.m

  • Test with a four-channels image.

  • Test with a three-channels image.

• metodos_agrupamientoTest.m

  • K-Means without groundtruth image test.

  • K-Means with groundtruth image test.

• metodos_invariantesTest.m

  • Álvarez invariant method test.

  • Maddern invariant method test.

• moda_colorTest.m

  • Basic test, one colour is repeated.

  • Unique colours test.

• segmentar_imagen_fuzzy_CMeansTest.m

  • Basic test.

• segmentar_imagen_GMMTest.m

  • Basic test.

• segmentar_imagen_KMeansTest.m

  • Basic test.

As you can see, neither PCA nor HMRF_EM have their own unit tests since these libraries have already been tested by their developers.

Tests cases execution

In order to run the test cases, as indicated in the README of the test folder, you have to copy the scripts from the ‘/test’ directory to the ‘/functions’ directory.

Once this is done, we have two options:

1. Execute one by one: If you want to run a specific test separately, you should open the command console and use the following command, replacing ‘testName’ with the name of the test you want to run ‘disp(runtests(‘testName’))’.

2. Execute all at once: If you want to run all the tests at once, you should simply run the file ‘run_all_tests.m’. This file will run all the tests automatically.

   The results of running all the tests are those that can be seen in figure .

Figure shows a summary of the results of running tests on the scripts used by the application.