This documentation is partly work in progress

Introduction to OpenMicroanatomy

What is OpenMicroanatomy

OpenMicroanatomy is a project built on top of QuPath which contains three components: OpenMicroanatomy Server, OpenMicroanatomy Web and QuPath Edu Extension.

QuPath Edu Extension is an extension for QuPath, which allows QuPath projects (called Lessons in QuPath Edu) to be synced between multiple users via an OpenMicroanatomy Server. The OpenMicroanatomy Server handles all the heavy lifting required to authenticate users, upload new slides, manage data and so on. QuPath Edu is also compatible with other data sources, such as Omero.

OpenMicroanatomy also includes OpenMicroanatomy Web, which is a web application that communicates with a OpenMicroanatomy Server and can be used for viewing projects.

Components
Figure 1. Visual representation of different OpenMicroanatomy components and how they communicate with each other. Green components are downloaded by the end-user and the blue components are set up by the system administrator. Red are optional third-party features.

Hierarchy

A OpenMicroanatomy Server is “compartmentalized” as shown in Figure 2. Each server can host one or multiple Organizations. Each organization has its own Workspaces, which hold Classes, which contain the Lessons. See Table 1 for how to think about these.

Hierarchy
Figure 2. A demonstration of the OpenMicroanatomy hierarchy, with a server with three different organizations.
Table 1. Translations for different OpenMicroanatomy components
Name Translation

Organization

Represents a university, school, department, or such – depending on your needs

Workspace

A course, such as Histology or Pathology.

Class

A class such as Basic Histology or Advanced Histology.

Lesson

A lesson within that class, such as Epithelium or Connective tissue.

Getting started

Feature comparison

✅ = supported ❌ = not supported (and currently no plans to implement) 👷‍♀ = work in progress

Feature Browser / Mobile Desktop app

View slides

✅

✅

Slide tours

✅️

✅

Creating content

❌

✅

Administrative tasks

❌

✅

Authentication

👷‍♀️

✅

Prerequisites

QuPath & QuPath Edu Extension

  • A 64-bit Windows, macOS or Linux machine, with at least 250 MB of disk space

OpenMicroanatomy Web

  • None

OpenMicroanatomy Server

Installing QuPath Edu Extension

  1. Install QuPath by following the instructions on the QuPath website

  2. Download the QuPath Edu extension

  3. Install the extension by drag and dropping the downloaded .jar file to the QuPath viewer

See here for more detailed instructions on how to install QuPath extensions

QuPath Edu Extension

Connecting & authenticating

First time setup

When starting QuPath Edu for the first time, you’ll see the First-time setup dialog. You must either select a public host or enter your QuPath Edu Servers address to continue. If you are unsure what your institutions address is, try contacting your IT-services. Public hosts are QuPath Edu Servers which can be freely viewed by anyone. Currently the only public host is the demo server provided by the University of Oulu.

First Time Setup
Figure 3. First-time setup dialog

You can change your host later by clicking the Change host …​ link on the Login dialog (see Figure 4) or from the QuPath settings Edit › Preferences › Edu

Logging in

You can continue either Continue as a guest (only read permissions) or authenticate using Credentials (regular email & password combination) or a Microsoft account.

Note
 Logging in using Credentials and/or Microsoft Authentication may not be available on your organization depending on your OpenMicroanatomy Server setup.
Login dialog
Figure 4. Login dialog. Change host by pressing the Change host …​ on the bottom-right hand corner.

Password recovery

If you forgot your password, you can recover your password by pressing Login with credentials and then Forgot password from the bottom right-hand corner.

Creating content

Going further, it’s assumed the reader is already familiar with QuPath. If you have never used QuPath before, it’s advised to read the QuPath documentation first.

Before making changes anywhere, confirm that you have Editing mode enabled by pressing Turn editing on on the QuPath toolbar (see Figure 5 below). If any button is disabled, try checking first that a) edit mode is enabled, b) you’re logged in b), you have the required permissions to make changes (see Users & Roles).

Toolbar
Figure 5. QuPath Toolbar. Notice how the annotation tools are disabled because editing mode is not turned on.

Creating workspaces, courses and lessons

Begin by opening the Select lesson (see Figure 7 below) interface by pressing either Open lesson or Create lesson buttons in the main QuPath interface on the left sidebar (see Figure 6 below).

Open or create lesson
Figure 6. Buttons to open and create lesson, and add images
Select lesson dialog
Figure 7. 1: A workspace named Anatomy. 2: Two courses named Course materials and Additional materials. 3: Five lessons belonging to the Course materials course. 4: Create a workspace, course or a lesson.

Create new workspaces by pressing Create …​ and selecting either Workspace, Course or Lesson. Course and Lesson are disabled until you select a Workspace.

Delete or rename any Workspace, Lesson or Class by right-clicking on it. You can also hide Classes or set a description. Hiding a Class will hide that Class from guests and users without write permissions. Deleting a Workspace will delete all Lessons and Classes belonging to that Workspace and similarly deleting a Lesson will delete all Classes belonging to that Lesson.

Warning
 Deleting a workspace, lesson or class is currently not reversible. See Backups for more details.

Adding slides to a lesson

To add a new slide click on Add images (next to Open lesson, see Figure 6 above) to open the Slide manager interface. From here, select any slide you wish to add and click on Add selected. This will open the QuPath Image Import interface. These settings are important if you’re planning on doing any analysis on the slides later. The default options and setting the Image type to Brightfield (H-DAB) is usually enough for teaching purposes. Clicking on Import will add the slide to the lesson.

Making changes to slides

Adding annotations, modifying slide description or such work identically as in QuPath, just make sure you have enabled editing mode (see Figure 5). Read the QuPath documentation for detailed information on annotating and such.

Any changes will be saved when either a) clicking on File › Save or File › Save as, b) changing slides, c) closing the lesson.

Modify Lesson Information

Edit the Lesson Information by either a) double-click anywhere on the Lesson Information tab b) File › Project…​ › Edit lesson information.

Lesson Information supports rich text, which includes custom fonts, colors, tables, images, videos, hyperlinks and much more.

Rich text editor
Figure 8. Rich text editor.

Creating slide tours

Slide tours are a feature introduced by QuPath Edu, it allows teachers to create short guided tours of slides, going through the key points of a slide.

Create Slide tour
Figure 9. Create slide tour button on viewers top-left corner.

Slide tours consists of "frames", which the user views one-by-one. To create a Slide tour, press on Create tour tour on the Viewers top-left corner. Next click on More ⋮ › Create new frame, and pan & zoom on the point of interest, make any annotations you wish. Set a description for this frame by pressing More ⋮ › Edit text. Save changes by clicking on More ⋮ › Save changes. Create as many frames you wish by clicking More ⋮ › Create new frame and again making any annotations, panning & zooming, setting a description and saving the changes with More ⋮ › Save changes. Preview your slide tour by clicking on Previous and Next.

Slide tour
Figure 10. Slide tour editing interface

Administrative tasks

Most administrative tools are available by selecting QuPath Edu › …​ from the QuPath top bar. Some administrative tasks requires access to the server and are detailed in the OpenMicroanatomy Server chapter.

Users & Roles

Manage users by opening the User management interface using QuPath Edu › Manage users.

User management interface
Figure 11. User management interface

Users with the Administrative tasks role are able to view & modify all users regardless of organization. Users with only the Manage users roles can only view & modify users that belong to the users organization.

Only users with the Administrative tasks role are able to migrate users to a different organization.

Passwords are required to have at least 3 characters, no other requirements.

Table 2. Explanation for different roles
Role Explanation

Manage slides

Upload new slides and delete / modify slides that are owned by the users organization.

Manage users

Create new users and edit existing users on the users organization.

Moderator tasks

Create new workspaces, courses and lessons on the users organization.

Administrative tasks

All permissions, regardless of organization.

Slides

Manage slides by opening the Slide management interface using QuPath Edu › Manage slides.

Slide management interface
Figure 12. Slide management interface. Each slide has an UUID (Universal Unique Identifier) which distinguishes it from others.

Users with the Administrative tasks roles are able to view & modify all slides regardless of organization. Users with only the Manage slides roles can only view & modify slides that belong to the users organization.

Import new slides by clicking the Import slide button. QuPath verifies that the selected slide is compatible with QuPath Edu and starts uploading it. After upload the OpenMicroanatomy Server processes the slide which can take up to 30 minutes depending on the slide size and server performance.

Deleting a slide will make it inaccessible from any Lesson that contains it but will not remove it from the slide listing. Deleted slides must be removed manually from each lesson also. Renaming a slide will only affect slides added in the future.

Warning
 In OpenMicroanatomy Server version 1.0 deleting slides only makes them inaccessible but does not remove the data stored. It is up to the server administrator to delete any associated data.

You can view any slide by clicking on Open selected. If you have a lesson open, you will be prompted to add that slide to the current project.

Backups

Manage lesson backups by opening the Backup management interface using QuPath Edu › Manage backups.

Restore a lesson by selecting the lesson and pressing Restore backup or preview it first by pressing Preview backup. Backups are automatically deleted after 30 days.

Warning
 Currently there’s no way to restore a deleted workspace / class or a lesson without administrative tools. A whole database backup is performed every 24 hours, which can be used to restore any deleted workspace / class or lesson.
Note
 In QuPath Edu Server version 1.0 a bug exists, which allows users with write permissions to preview all backups regardless of organization. Restoring backups is still limited to users with proper write permissions to a specific workspace.
Backup management dialog
Figure 13. Backup management interface.

Organizations

Manage organizations by opening the Organization management interface using QuPath Edu › Manage organizations.

Organization management interface
Figure 14. Organization management interface. Each organization has an UUID (Universal Unique Identifier) which distinguishes it from others.

Making any changes to an organization requires the Administrative tasks role.

Deleting an organization will delete permanently all data associated with that project, including workspaces, lessons, courses, users, and slides.

Clicking Edit allows you to rename and upload a logo for that organization, see Figure 13.

Organization logo requirements

  • PNG filetype

  • Size of 400x80 px or greater

  • Aspect ratio of 5:1

Edit organization dialog
Figure 15. Edit organization dialog.

Permissions

Manage permissions by opening the Permission management interface using QuPath Edu › Manage permissions.

By default, when creating a new workspace, it is automatically assigned the Write access for yourself and Read access to no-one. You can restrict access to either a) only yourself, b) specific organizations, c) specific users, d) combination of users and organizations.

Simply use ›, »‹ and « to add/remove permissions. Double-arrows moves all items and single-arrows move only the selected item. Clicking ? will give you an analysis of who has read/write permissions in plain English.

Remember to press Save changes (bottom right-hand corner) separately on "Read" and "Write" respectively; currently QuPath Edu gives no warning if forgetting to save any changes.

Permission management interface
Figure 16. Permission management interface. 1: List of all workspaces, the organization is specified in parentheses. 2 & 3: Read & write permissions separated in different tabs. 4 & 5: Left pane indicates any users/organizations available and right pane indicates users/organizations with active permissions.

OpenMicroanatomy Web

Documentation in progress.

Source code and more details are available at openmicroanatomy/web.

OpenMicroanatomy Server

Note
 The Docker container is still in beta but is stable for production use.

Installation (Docker)

Prerequisites
Installation
Note
 The following instructions installs OpenMicroanatomy to /opt/openmicroanatomy using sudo — feel free to customize this if you know what you’re doing.

  1. cd /opt/ && sudo mkdir openmicroanatomy && cd openmicroanatomy

  2. Download the OpenMicroanatomy Docker configuration: sudo wget https://raw.githubusercontent.com/openmicroanatomy/hosting/main/docker-compose.yml

  3. Start the server for the first time using sudo docker-compose run server

    • If you get a AccessDeniedException error try running sudo chmod 777 server-data and retry the previous command.

    • This error is due to OpenMicroanatomy running inside the Docker container as the user oma which does not have the permissions to modify that folder. If you require stricter security, create a user called oma on the host machine and assign permissions to that user to server-data folder.

  4. Follow the instructions to create the initial organization and administrator account (these can be edited later; see Chapters: Users & Roles and Organizations)

  5. After creating the initial organization and administrator account stop the server by inputting stop into the terminal or by pressing CTRL + A + CTRL + C to exit.

  6. Edit the application.conf inside server-data using e.g. nano (e.g. nano server-data/application.conf)

    • The most important step is to configure server.host to match your hostname (see Chapter: SSL for further instructions); otherwise slides will not work and fixing them later is can be cumbersome — see Fixing Incorrect Slide Paths.

    • See Configuration chapter below for more details about different configuration options.

  7. Start the server using sudo docker-compose up -d; to stop the server run sudo docker-compose down --remove-orphans.

Updating

OpenMicroanatomy uses semantic versioning MAJOR.MINOR.PATCH, meaning no breaking changes happen unless the major version changes (e.g. from 1.X.X to 2.X.X). If you’re using :latest (default) as the Docker container version you may accidentally update to a newer major version. It is recommended that you pin your version to e.g. :v1 to allow minor and patch upgrades or v1.1 to allow only patches by editing docker-compose.yml.

To update OpenMicroanatomy Server, run the following commands.

  1. docker-compose down

  2. docker pull ylihallila/openmicroanatomy-server

  3. docker-compose up -d

Configuration

Configuration is available at application.conf which will be generated during the initial start-up, it contains comments for instructions. The default configuration has sensible defaults, but you’re free to tweak anything you wish.

The only required configuration step is setting the server.host parameter — this should point to your hostname (see SSL chapter). Your server will not function properly if you do not set the host parameter.

For storing the tiles there are two options. Local (default) storage uses the servers disk to store any tiles. For Cloud storage currently CSC Allas is only supported, with initial support for Amazon S3 existing. If you’re interested in support for Amazon S3 or any other cloud provider, please create a GitHub issue regarding this.

To generate a new configuration simply delete the old one and restart the server. To reload the configuration you must restart the server.

SSL

OpenMicroanatomy includes SSL support using Caddy with Docker. You’re free to manually setup a reverse proxy using software such as Caddy, nginx or Apache to provide a secure connection.

Setting up SSL using Caddy server with Docker

  1. Shutdown any Docker instances: sudo docker-compose down (running inside /opt/openmicroanatomy)

  2. Download the Caddy Docker configuration using sudo wget https://raw.githubusercontent.com/openmicroanatomy/hosting/main/docker-compose.caddy.yml

  3. Edit the Caddy Docker configuration: sudo nano docker-compose.caddy.yml

  4. Change virtual.host to your domain name without https:// e.g.: virtual.host: 'example.com'

  5. Change virtual.tls-address to your administrator email account e.g. virtual.tls-address: 'john.smith@example.com' — this is not revealed to anyone and only used by CertBot to notify about any issues with the SSL certificate.

  6. Save and exit

  7. Edit the OpenMicroanatomy Docker configuration: sudo nano docker-compose.yml

  8. Under ports change - '7777:7777' to - '127.0.0.1:7777:7777 to prohibit access using insecure HTTP

  9. Save and exit

  10. Run sudo docker-compose -f docker-compose.yml -f docker-compose.caddy.yml up -d to restart server with SSL.

  11. Done: OpenMicroanatomy should be accessible via https://example.com

Reverse proxy

If your DNS includes an automatic SSL proxy option, feel free to try that. Alternatively you can setup / configure your existing Apache / nginx server to behave as a reverse proxy for OpenMicroanatomy.

Below is an example nginx reverse proxy configuration using Certbot.

server {
    server_name open.microanatomy.server;

    access_log /var/log/nginx/reverse-access.log;
    error_log /var/log/nginx/reverse-error.log;

    include /etc/nginx/conf/proxy.conf;

    location / {
        proxy_pass http://127.0.0.1:7777;
    }

    listen [::]:443 ssl;
    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/open.microanatomy.server/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/open.microanatomy.server/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}

server {
    if ($host = open.microanatomy.server) {
        return 301 https://$host$request_uri;
    }

    listen 80;
    listen [::]:80;

    server_name open.microanatomy.server;
    return 404;
}

Installation (Manually)

Warning
 Manual OpenMicroanatomy installations are not recommended. Assistance for any issues with manual installations cannot be guaranteed.
Prerequisites

  • Server with Java 19 or later installed

Installation

These instructions assume you’re familiar with Linux already and skips multiple crucial steps such as creating a new user.

It’s advised to create a separate user, such as openmicroanatomy and to use software such as screen to create separate sessions for both instances.

  1. Download the latest open-microanatomy-server.jar from GitHub.

  2. Save it to e.g. /home/openmicroanatomy/server/open-microanatomy-server.jar

  3. Extract OpenSlide Binaries

    • these are currently only available from the QuPath repository — download the .jar file specific to your operating system and extract it to where you saved qupath-edu-server.jar.

Running the server

  1. Start the server with java -jar <jar> [-port <port>]

  2. During your initial start-up, you will create your first administrator account.

Updating

Download the latest open-microanatomy-server.jar from GitHub and restart any running screen.

Systemd service

To start OpenMicroanatomy automatically or restart it in case the process gets killed, you can create a Systemd service for it.

Troubleshooting

Fixing Incorrect Slide Paths

Uploading slides with an incorrect server.path inside application.conf will result in QuPath and OpenMicroanatomy Web not knowing where the slides are actually stored and making them inaccessible. The server.path is encoded within each slides .properties file when uploaded, thus requiring them to be manually updated if the server.path is changed.

To check for any incorrect paths run the following command in the server root directory.

cd slides && cat *.properties || grep "<your previous server.path>"

  1. Backup slides: cp -R slides slides-backup

  2. Switch to slides directory: cd slides

  3. Perform a Search & Replace: sed -i — 's/<previous server.path>/<new server.path>/g' *

  4. Validate that all instances have been replaced: cat *.properties || grep "<your previous server.path>"`

HTTP API

OpenMicroanatomy Server includes a REST API — documentation is available here.