brain-link/scanhub-ui

Cloud-based user interface for ScanHub, an open-source and multi-modal acquisition platform for medical data

---

About

ScanHub is intended to be a multi modal acquisition software, which allows individualizable, modular and cloud-based processing of functional and anatomical medical images. It seamlessly merges the acquisition with the processing of complex data on a single platform. ScanHub is open-source and freely availably to anyone 🌍.

The greatest novalty of ScanHub is the cross-manufacturer and multi-modality aspect, allowing accessible cloud-based data processing in one framework 🚀

Currently we are focussing on the development of an acquisition solution for the open-source MRI OSI2One.

This project only provides the user interface to interact with ScanHub. Check out the backbone of our acquisition platform ➡️ ScanHub.

We welcome anyone who would like to join our mission, just get in touch 📧.

Demo 🎬

The following video shows a short demonstration of the ScanHub UI (September 2023). You will see how to navigate through the acquisition planner, inspect an MRI sequence and start an MRI simulation on a virtual MRI scanner. In the end we are demonstrating how to view the DICOM image, reconstructed by our workflow engine subsequently to the acquisition.

ui_19-09-2023_720p.mov

Installation

To install the package, you need install Docker first. The installation of ScanHub-UI is as simple as using the following command.

docker-compose up -d --build

Note that you need to install ScanHub, which is the backbone of the user interface. Documentation on the installation of scanhub can be found in the README file.

Structural Overview

The repository structures in two major components: the patient manager and the user interface. The patient-manager is suppose to emulate a simplified clinical patient management system. This part of the software might be replaced during setup in a (clinical) research facility. To provide a clean separation between data and patient, the patient manager is location here and is not part of the ScanHub backbone.

The frontend contains a src/ directory which is structured as follows.

• views: All "main" views filling the whole browser window. This components are only included in the router file.
  • dashboard
  • patient-list/patient-table
  • device-list/device-table
  • patient-index
• components: Sub-components for views, if a view is more complex, sub-components might be gathered in a sub-folder. Components can be accessed from different views or also from other components.
• interfaces: Interface files contain ".interface" in front of the file ending ".tsx"
  • data.interface: Interfaces of all data objects like patient, device, workflow, etc.
  • component.interface: Component property interfaces
• client: (Global) Definition of the query client.
  • abstract-query-client: Template
  • urls: Base urls for data queries
  • queries: Constructions of all data query services
  • healthcheck: Queries to health endpoints
• utils: Contains general helper functions and global variables which can be shared between components/views.

The frontend application is written in react-typescript. The UI/UX is designed with MUI. We aim to build the application solely based on MUI Joy-UI and limit ourselves to using material ui in exceptions where there is not yet a solution with joy ui.

ScanHub-UI implements the following routes using the react-router-dom package (see Routes.tsx):

• patients
  • /patient-id/exam-id/procedure-id
• devices
• workflows
• dashboard/home

Database queries are performed using axios and an abstract-query-client implementation. The query clients can be found in the client directory.

License

ScanHub, including all its source code and associated documentation (collectively, the "Software"), is dual-licensed under the GNU General Public License version 3 (GPLv3) and the ScanHub commercial license.

Open Source License

If you want to use the Software under the terms of the GPLv3, you may do so for free. Under the GPLv3, you are allowed to modify and distribute the Software, but any derivative works that you distribute must also be licensed under the GPLv3. For the precise terms and conditions, please refer to the text of the GPLv3, which is included with the Software and can also be found at: http://www.gnu.org/licenses/gpl-3.0.html

Commercial License

If you wish to use the Software without the restrictions of the GPLv3, such as for the purpose of developing proprietary software that includes the Software without the obligation to disclose your source code, you may purchase a commercial license from BRAIN-LINK UG (haftungsbeschränkt).

The commercial license grants you, the licensee, the rights to use, modify, and distribute the Software without the requirement of providing the source code of your proprietary software to the end users. The commercial license also includes access to premium support and services.

For more information on the commercial license, including pricing, please contact us at [email protected].

Choice of License

You may choose to use the Software under either the GPLv3 or the commercial license. If you choose to use the Software under the GPLv3, you must comply with all of the terms of the GPLv3. If you choose to use the Software under the commercial license, you must comply with all of the terms of the commercial license.

Disclaimer

This is not a legal document. The exact terms of the GPLv3 and the commercial license are specified in their respective legal texts. This document is merely intended to provide a general overview of the dual licensing scheme.

scanhub-ui's Issues

FIX: Disable procedure add without exam

When no exam is selected, the user should not be able to create a procedure

Full screen DICOM viewer

Decouple the DICOM viewer from the exam-tree view. Viewer can be accessed through a job, if data was acquired and data is eligible to view (at least 2D image data).

FIX: Close context menu's

If user opens a context menu, the menu is only closed if an option is chosen.
The context menu should also be closed, when focus changes.

Add workflow to a job item

Assign workflows to a job item. All workflows are then executed in the defined order.
This issue gathers the following sub tasks:

• Get all workflows from database
• Create a workflow item
• Create a dropdown with all workflows from database
• Implementation of assignment mechanism: Make jobs selectable, workflow from dropdown menu is assigned to selected job
• Job interactions: Move job up/down, delete job

Setup pre-commit for monorepo?

Integration of pre-commit for mono repo structure.

• pre-commit config in frontend
• pre-commit config in patient-manager

Problem: By default, pre-commit has no official solution for monorepo structure

• pre-commit/pre-commit#1417
• https://github.com/pre-commit/pre-commit/issues?q=is%3Aissue+is%3Aclosed+monorepo

Pre-commit designed for mono repo
Mookme: https://mookme.org

Workaround for MUI material dependency in PatientIndex

The drawer on the patient index page is the only component from the mui material package.
A workaround is to be found to get rid of this dependency.

Issuer and concern mixed up on different views

Implementation of multiple DICOM view container

User defined grid of views, e.g. to display sagittal, axial and coronal view of a 3D image.
For the beginning we focus on simple image stacks were different viewports might be used for different window functions or study comparisons.

Basic annotation of DICOM images

The user should be able to add basic annotations to the viewed images.
This include tools like:

• Distance measure
• Zoom
• Pan
• Rotate
• RoI
• Contrast/Brightness

Configuration/setup of typescript-react linter

• Decide for typescript/react linter
• Pass all linter checks
• Integrate linter in GitHub CI

Connected to issue #6

Error handling on missing workflow

MRI sequence upload UI

User interface component to upload a pulseq file using the sequence manager in scanhub.

FIX: Add warnings for empty sequence/device list

• Add banner to job-list section
• Only display the warning, don't disable job creation

Exam-tree/study browser to view recorded images

The exam-tree or study browser comes into play, when the user selects a patient to view the record data.
To the left of the DICOM viewer, an exam-tree component comes into play, which displays the hierarchy of exams, procedures and jobs, i.e. records. A single job might contain multiple records. However, each execution of a job leads to one record. By now, only the most recent record is displayed.

Remark:
It is also planned to select a different record in the history of a job. In general records are not deleted, new records are always attached to a job.

Fix acquisition trigger with new acquisition control

Use the endpoint of the new acquisition control to trigger an acquisition

Full screen sequence view

Decouple the sequence viewer from the exam-tree view. Plot can be accessed through a job, if a sequence was uploaded/selected and sequence is valid (can be compiled).

Connected to the following issue: #5

FIX: Procedure creation requires page reload to succeed

Problem:

• Procedure is created by a model
• Model component is loaded inside the patient index page
• At the very beginning (e.g. new patient) a patient does not have any exams, the variable params.examId is NaN
• params.examId is used to assign exam id to procedure
• Update of this value is required, when exam id changes

Solution: useEffect hook

Simple sequence plot function

To preview the pulseq sequence a HTML plot is required. We already implemented some code which returned a dictionary for plotly to generate HTML based plot. We still want to use the plotly library, but extracting the channels of the sequence can be achieved much easier.

• Reimplementation of sequence channel extractrion
• Sequence plot endpoint, to be implemented in sequence-manager (scanhub)
• Steps in endpoint:

1. Get sequence by ID
2. Generate a sequence object
3. Extract channels
4. Generate plotly dictionary

Setup pylint and pass checks

• run pylint, flake8, mypy and pydocstyle in CI
• format code so that all checks pass