Segmentation App 2

⚠️ This project is in early stage. It is mostly empty and contains test structures only. Right now, it has no functionality.

Table of Contents

• Segmentation App 2
  • Table of Contents
  • About
  • Architecture
  • Installation
    • How to Install the Release on Windows
    • How to Install the Release on Linux (Debian)
    • How to Install the Release on macOS
  • Project Structure
  • How to Build and Run the Project
    • Node.js and Python
    • Installing Node.js packages
    • Installing Python packages
      • How to Install Python Packages on Windows
      • How to Install Python Packages on Linux (Debian)
      • How to Install Python Packages on macOS
    • How to Build the Electron app
    • How to Test the Electron App
    • How to Distribute the Electron App
    • How to Test the Svelte Frontend
    • How to Build the Svelte Frontend
    • How to Run Unit Tests in TypeScript
    • Import the Electron project to use Electron Forge
  • Manual
  • Licence

About

This side project builds on my previous work in machine learning-based image segmentation. The current focus is on enhancing software quality and user experience. It serves as a practical environment to improve and deepen my software engineering skills.

Changes include codebase improvement, automated unit testing, modernizing the UI and adding some features missing in the previous project.

Architecture

Backend:
Python handles core logic and data processing.

Bridge:
Electron wraps the frontend as a desktop app and connects to the backend using TypeScript and Node.

IPC (Inter-Process-Communation) and Client-Server:
Enables real-time communication between frontend client and backend (local) server using WebSocket technology.

Frontend:
Svelte is for dynamic frontend UI rendering and interaction using web technology.

Installation

Pre-built binaries for Windows, Linux (Debian), and macOS will be provided via GitHub Actions. Please see the OS-specific sections below for instructions on how to install the corresponding release on your system.

In future releases the python packages will be installed directly from the app.

How to Install the Release on Windows

• Download and install Python. During installation please disable the MAX_PATH limit.
• Download the latest release into your Desktop folder. You need the setup executable and the compressed source files.
• Unzip the source files into your Desktop folder.
• Follow the instructions in Installing Python packages
• After pip installed all packages, run the setup executable. The executable can also be run before installing all Python packages, but the app won't work.

How to Install the Release on Linux (Debian)

TODO

How to Install the Release on macOS

TODO

Project Structure

The root project folder ml-segmentation-2 is divided into three main directories:

• \python directory
  contains the backend implementation written in Python.

  This backend runs a server that processes requests sent from the frontend and performs computational tasks such as machine learning, image generation, graphics processing, and data analysis.

  The backend server communicates with the frontend using WebSocket connections, allowing real-time bidirectional communication between the user interface and the processing engine.

• \src directory
  contains TypeScript application logic responsible for starting and coordinating all major components of the desktop application. It acts as the central runtime layer connecting the backend server, the frontend UI, and the desktop container

• \svelte-frontend directory
  contains the graphical user interface of the application. The frontend is implemented using Svelte with application logic written in TypeScript.

  The interface is built using Skeleton UI, which provides prebuilt UI components and styling utilities for Svelte applications.

Other directories and files included in the root folder:

• \.github\workflows contains GitHub Actions workflow YAML files which define automated tasks to build and release the project on different operating systems
• \dist contains generated JavaScript files compiled from TypeScript src directory after building the Electron app
• \node_modules directory contains node packages necessary to build the Electron app
• \out directory contains the build app binaries and executables generated by Electron Forge
• \eslint.config.mts contains the configuration for ESLint
• \forge.config.ts contains the configuration for Electron Forge
• \requirements.txt contains the required packages for Python
• \tsconfig.json contains the configuration for the TypeScript compiler

Other directories and files included in the svelte-frontend directory:

• \svelte-frontend\dist contains the build Svelte frontend web UI
• \svelte-frontend\node_modules contains node packages necessary to build the Svelte frontend web UI
• \svelte-frontend\src contains the Svelte project for the frontend web UI
• \svelte-frontend\svelte.config.js contains the configuration for the Svelte project
• \svelte-frontend\tsconfig.ts contains the TypeScript compiler configuration for the Svelte project
• \svelte-frontend\vite.config.ts contains the configuration for Vite for building the Svelte project

Please note that some directories are only created after applying corresponding npm commands.

How to Build and Run the Project

Node.js and Python

Download and install Node.js.
Download and install Python.

Installing Node.js packages

Inside the project folder run:
npm install

Then inside the /svelte-frontend folder run
npm install
again.

Installing Python packages

How to Install Python Packages on Windows

Before installing update the package manager pip:
python -m pip install --upgrade pip

Open a terminal and run:
pip install websockets
pip install opencv-python
pip install fastai

or run:
pip install websockets opencv-python fastai

Please note that the current project development state requires just the websockets package.

To remove all installed packages from your system run (e.g. in your Desktop folder):
pip freeze > packages.txt
pip uninstall -r packages.txt -y

How to Install Python Packages on Linux (Debian)

TODO

How to Install Python Packages on macOS

TODO

How to Build the Electron app

Inside the project folder run:
npm run build

The project backend TypeScript files are compiled into JavaScript files and saved into \dist.
Then the project frontend Svelte project is build and saved into \svelte-frontend\dist.

How to Test the Electron App

Inside the project folder run:
npm run start

The project frontend and backend is build and the Electron app is started for testing.

How to Distribute the Electron App

Standalone package:

To create a standalone package, where all components of the app are packaged inside a folder run:
npm run make-package

or run:
npm run make-standalone

The standalone package will be created inside \out.

Setup installer:

To create a setup installer, where all components the app are packaged inside an installer run:
npm run make-setup

or run:
npm run make-installer

The setup installer will be created inside \out\make.

How to Test the Svelte Frontend

Inside the project folder run:
npm run fe-start

or
npm run fe-preview

The Svelte frontend project files are build and saved into \svelte-frontend\dist.
A local server will be started where the frontend app can be run on a browser.

To kill the server, type:
q + enter

How to Build the Svelte Frontend

Inside the project folder run:
npm run fe-build

The Svelte frontend project files are build and saved into \svelte-frontend\dist.

How to Run Unit Tests in TypeScript

The project uses Vitest for Unit testing.
TypeScript unit test files are saved as *.test.ts beside the reference file.

To run a unit test type:
npm run test

Import the Electron project to use Electron Forge

Use if there is a need to add the Electron project manually to Electron Forge (e.g. accidentally removing all dependencies from package.json)

Inside the root project folder ml-segmentation-2 run:

npm install --save-dev @electron-forge/cli
npm exec --package=@electron-forge/cli -c "electron-forge import"

Electron Forge's import commmand will import the existing Electron project to Electron Forge automatically. Refer to the Electron Forge Documentation page for more details.

Manual

TODO

Licence

This project is licensed under the MIT License.