Jul 17, 2023

Public workspaceTelePi: Assembly, Installation and Customization Guide V.1

DOI
dx.doi.org/10.17504/protocols.io.3byl4jp22lo5/v1
  • 1Institute of Pathology, University of Würzburg, Germany
Almoatazbellah Youssef
Icon indicating open access to content
QR code linking to this content
DOI: dx.doi.org/10.17504/protocols.io.3byl4jp22lo5/v1
Protocol Citation: Almoatazbellah Youssef, Andreas Rosenwald, Mathias T. Rosenfeldt 2023. TelePi: Assembly, Installation and Customization Guide. protocols.io https://dx.doi.org/10.17504/protocols.io.3byl4jp22lo5/v1Version created by Almoatazbellah Youssef
License: This is an open access protocol distributed under the terms of the Creative Commons Attribution License,  which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited
Protocol status: Working
We use this protocol and it's working
Created: July 16, 2023
Last Modified: July 17, 2023
Protocol Integer ID: 85081
Disclaimer
Raspberry Pi OS, Fiji, and QuPath are licensed under the GPL 3.0 license. ImageJ is in the Public Domain. The RPi Cam Web Interface and PuTTY are licensed under the MIT license. Mozilla Firefox is licensed under the MPL 2.0 license.
Abstract
Telepathology facilitates histological diagnoses through sharing expertise between pathologists, with added benefits in terms of teaching and potential research collaborations. However, the associated costs are high and frequently prohibitive, especially in low-resource settings, where telepathology would paradoxically be of paramount importance due to a paucity of pathologists.
We have constructed a telepathology system (TelePi) with a budget of < 120 € using the small, single-board computer Raspberry Pi Zero and its High-Quality Camera Module in conjunction with a standard microscope and open-source software on a Linux operating system. The system requires no additional hardware parts, maintenance costs or service contracts, has a small footprint, can be moved and shared across several microscopes, and is independent from other computer operating systems. TelePi uses a responsive and high-resolution web-based live stream which allows remote consultation between two or more locations. TelePi has several potential usage scenarios. It can serve as a telepathology system for remote diagnostics of frozen sections. Additionally, it can be used as a standard microscope camera for teaching of medical students and for basic research. When paired with the open-source image analysis package Fiji, it allows for stitching of multiple images taken at high resolution into one large image that exceeds the field of view of the chosen objective. The quality of the TelePi system compared favorable to a commercially available telepathology system that exceed its cost by more than 125-fold. Additionally, still images are of publication quality equal to that of a whole slide scanner that costs 800 times more.
In summary, TelePi is an affordable, versatile, and inexpensive camera system that potentially enables telepathology in low-resource settings without sacrificing image quality.
Materials
Hardware:

Note: The following list is for orientation only. Several items (e.g. cables, adapters, etc.) can be reused from older smartphones or PCs and do not need to be bought new. Buying a new microSD card from a reputable manufacturer, is however, recommended. The links provided below are only a suggestion. The authors have no affiliation with any commercial partners.



Software:

Before start
The Raspberry Pi Zero and the HQ Camera are sensitive electronic equipment, please make sure to ground yourself before working, or wear antistatic gloves.
Hardware Assembly
Hardware Assembly
15m
15m
Unpack the Raspberry Pi High Quality Camera (HQ Camera) and the mounting bracket. Use the supplied M2 screws and nuts to attach the HQ Camera to the bracket.
Attach the Raspberry Pi Zero to its enclosure without attaching the nuts to the long M2 screws. Mount the assembly directly on the spacer screws on top of the mounting bracket to fix the RPi Zero enclosure directly on top of the HQ Camera bracket.
Attach the flat ribbon cable to the camera port on the RPi Zero (wider end of the cable). The other side (narrower) goes to the HQ Camera itself. Make sure that the cable is inserted with the correct side (the one with the contacts) interfacing with the contacts in the connector itself.
Connect the micro-USB adapter to the RPi Zero. This is where the Ethernet to USB adapter will be connected (after determining the IP address, see below). The micro-USB power cable is connected to the USB power supply and then to the RPi Zero when you are ready to power on the system.
Installing the Raspberry Pi Operating System
Installing the Raspberry Pi Operating System
15m
15m
Download and install the official Raspberry Pi Imager program. For this guide, we are assuming a Microsoft Windows PC is being used. Run the software after the installation is finished.
Insert a microSD card into the PC and choose it from the "Choose Storage" button.



You will be returned to the main window. Using the "Choose OS" button, choose "Raspberry Pi OS (other)".



Choose "Raspberry Pi OS (Lite)" from the list. Alternatively, in case of future Debian versions abandoning the Legacy Camera support, choose "Raspberry Pi OS Lite (Legacy)".



Again, you will be returned to the main window. To setup advanced options, choose the gear icon on the bottom right.



Critical step: TelePi is supposed to run headless (without a monitor or keyboard/mouse). Failure to setup the following options will result in a non-working system.

Add a hostname for the system to identify the system on the network. Enable Secure Shell (SSH) to be able to access the system remotely via terminal commands.


Add a username and password for the main system user.


Time zone and keyboard language can be also selected here. If using a Raspberry Pi with wireless LAN (e.g. RPi Zero W, RPi Zero 2 W, RPi 3B or RPi 4B) do not setup a wireless network. TelePi should run in a wired network for best results.






You will be returned to the main window. Proceed with installation by clicking "Write".


A warning will appear to remind that all old data on the microSD card will be lost after the installation is completed. Accept and proceed.


The microSD card will be ejected at the end of the process. Remove it from the Windows PC.



Configuration and installing the RPi Cam Web Interface
Configuration and installing the RPi Cam Web Interface
15m
15m
Critical step: We will need to find out which IP address was assigned to the RPi Zero, or actually, to the USB-to-Ethernet adapter which is connected to the RPi Zero. To do so simply plug the adapter in the Windows PC after connecting it to a working Ethernet cable and type in the Windows Command Line (Press Start, then type "cmd" and press Enter) the following command:

ipconfig/all

The output will list the current IP address which was given to the adapter. If the network is configured to use dynamic host configuration protocol (DHCP), the IP address will be carried over when the adapter is removed and plugged in the RPi Zero.

Otherwise, using the same command in Windows, find out what the MAC address of the adapter is and assign a fixed IP address or use it to find out what is the assigned IP address through the internet router interface. Or simply contact your network administrator.
Critical
Plug the microSD card into the RPi Zero. Connect the Ethernet-to-USB adapter and plug a working Ethernet cable to it. Connect the RPi Zero to power by plugging in the micro-USB cable to the USB charger and then to the RPi Zero.
Download and install PuTTY. Run the software after installation is finished. Type the IP address that was assigned to the USB-to-Ethernet adapter that will be used with the RPi Zero and use the default settings (alternatively, give the IP address a name and save it as a Saved Session in PuTTY for quick access).


A message will appear asking if the connection is to be trusted or not. If the previous steps were followed, there is no reason to doubt that.



Use the username and password that were previously specified in the Raspberry Pi Imager program to login. While typing the password, no characters will be shown, this is normal behavior.


After logging in, the user will be greeted with some system information and an active command line. In PuTTY, pasting copied commands is done using the right mouse click. The prefix “sudo” indicates that the command needs to be done in the super user mode or as the root user.



Critical step: Enabling the camera at the OS level.

Type the following command to update the system:

sudo apt update ; sudo apt upgrade -y

Wait till the process is finished and then type:


sudo raspi-config

The following screen will appear.


This is the configuration screen for some options in the Raspberry Pi OS. We need to enable the RPi HQ Camera at the OS level. Use the arrow keys on the keyboard to navigate and choose "Interface Options", then "Legacy Camera". Accept the prompt, then use the arrow keys as well the Tab key to choose and finish. A restart prompt will appear. Accept it.



Critical
When the system restarts, the user will be automatically logged out of the PuTTY session. To reactivate the session, restart it by clicking on the upper left window icon and choose "Restart Session".



Critical step: Installing the RPi Cam Web Interface.

To install the RPi Cam Web Interface, we need to clone the Github repository of the project by running the following commands after logging in.


sudo apt install git -y

git clone https://github.com/silvanmelchior/RPi_Cam_Web_Interface.git

To run the installation script, we need to change from the home folder to the project's folder.

cd RPi_Cam_Web_Interface

./install.sh

A prompt will appear to setup the RPi Cam Interface. Specify a username and password (recommended, especially if a multiuser deployment is planned, see below), if required, otherwise accept the default settings. The username and password should be different from the ones used to log into the system. Press the Tab key on the keyboard to change to choose "OK" and move forward.


When prompted to start the camera now, choose "Yes". Otherwise, to ensure a reliable performance, restart the RPi using:


sudo reboot

At this time, there is no more need to immediately use PuTTY again.
Critical
Configuring RPi Cam Web Interface
Configuring RPi Cam Web Interface
5m
5m
Use an internet broswer (e.g. Mozilla Firefox) and type in http://IP-address/html/ (where IP address is that of the of the RPi Zero as obtained before). If a username and password for the RPi Cam Web Interface were selected, a prompt will appear, otherwise the user will be shown this interface:



For the purpose of this paper, we changed the follownig settings under "Camera Settings":

Video resolution: 1280 x 960;
Image resolution: 4056 x 3040;
Annotation Text (none, delete existing line);
Image Quality: 100;
Preview Quality: 10;
Preview Width: 1024



Under "System", it is possible to restart or shutdown the system. Unless a micro-USB power cable with an on/off switch is used, to start the system again after shutdown, it is necessary to unplug and replug the micro-USB cable into the RPi Zero, or remove the power supply from the power outlet and connect it again. We recommend using a micro-USB power cable with an on/off switch.

System Maintenance
System Maintenance
To shutdown the system using PuTTY type:

sudo poweroff

To restart the system:

sudo reboot

Failure to do a clean system shutdown will result in corruption of the data on the microSD card, which will require a new system install.
It is also advisable to routinely perform system updates by running the following commands in PuTTY:

sudo apt update ; sudo apt upgrade -y

User Management and Access Rights for RPi Cam Web Interface
User Management and Access Rights for RPi Cam Web Interface
There are four different user levels with different privileges which can be assigned, as described in the RPi Cam Web Interface documentation:

  • Level 0: User receives a simple live stream without added options.
  • Level 2: User receives a live stream and read-only access to the Download Images and Videos section.
  • Level 3: User receives a live stream and the ability to record images and videos and view them using the Download section without changing the camera settings.
  • Level 6: User receives full administrative control of the camera system (similar to the user created during the installation of the RPi Cam Web Interface (see above)).

To add a new user, type the following command in PuTTY, where "newusername" should be replaced with the chosen new username. This command needs to be repeated for each and every new user. When prompted, type the chosen password for each user to be created.

sudo htpasswd /usr/local/.htpasswd newusername


To define the access level of the new user, a file needs to be added with a list of users and their access levels in this format:

username:Level, where Level is 0, 2, 3 or 6.

For example:

  • resident:6
  • attending:6
  • student:2
  • record:3
  • demo:0

To create the file with the list, type the following in PuTTY to edit a file in the terminal:


sudo nano /var/www/html/userLevel

Now add the user list as explained.

Press on Ctrl + X to save the file when done and choose "Yes" by typing the letter "Y".

To the system aware of the new added users, run the following commands to restart the RPi Cam Web Interface:


~/RPi_Cam_Web_Interface/stop.sh

~/RPi_Cam_Web_Interface/start.sh



Optional
Create a Windows Shared Folder
Create a Windows Shared Folder
The saved images and videos through the TelePi system can be easily accessed through the web browser in the same way as they are originally captured. However, to streamline the process and add extra functionality, the folder where the data is saved can be shared as a network drive and accessed remotely. To do so, run the following commands in PuTTY. This will install Samba, which provides Windows file and folder sharing services on a Linux system.

sudo apt update ; sudo apt upgrade -y ; sudo apt install samba smbclient cifs-utils -y

The saved images and videos are stored in the following directory by default:

/var/www/html/media

This directory is owned by the user www-data, which now will be added to the list of users able to share folders through Samba. Run the following command and add a password (separate password to access the shared folder from other computers, please do not reuse your root password).

sudo smbpasswd -a www-data

Now the /var/www/html/media folder needs to be shared, to do so, the Samba configuration file needs to be manually edited in the terminal.

sudo nano /etc/samba/smb.conf

Scroll to the bottom of the file using the arrow keys on the keyboard or the Page Down key. Then add the following lines (by right clicking in PuTTY where the cursor is blinking). This will create a shared folder called TelePi.


[TelePi]
comment = Captured images and videos
path = /var/www/html/media
guest ok = no
public = no
writable = yes
browseable = yes

Now, restart the Samba service by running the following command:

sudo systemctl restart smbd

On a Windows PC, open a File Explorer window and choose "Map Network Drive" and enter the IP address of the RPi along with the name of the Samba share TelePi. Then input the username www-data and the corresponding password. The shared folder is now mounted on this PC with read and write access rights.



Optional
microSD Image Backup
microSD Image Backup
For redundancy, it is advised to clone the finished microSD card onto several similar sized microSD cards to have working copies for an immediate replacement, in case of a problem with the current card (e.g. corruption after incorrect shutdown, etc.), or to deploy a new system without going through the setup process again. It is advised that the microSD cards are from the same manufacturer/type, so that they have the exact same bit size.

In Windows download and install Win32 Disk Imager. Insert the old microSD card into the Windows PC. Run Win32 Disk Imager and browse to a save location and give a name to the disk image that will be saved onto the PC. Select the drive where the old microSD card is mounted. Click on "Read" to write a disk image of the card to the PC. This image can be archived as a backup (compression with 7zip will save a lot of storage). To copy the image to a new card, use the same program and choose the drive where the new microSD card is mounted. Browse to where the disk image was saved and the click on "Write". This way a 1:1 copy of the same microSD card is obtained.
Adding Scale Bars in Fiji
Adding Scale Bars in Fiji
After performing Köhler’s illumination images were taken with 2, 4, 10, 20 and 40X objectives (all from Olympus, Tokyo, Japan) of a calibration microscope slide (E. Leitz GmbH, Weltzar, Germany). The micrometer scale was measured using the line measurement tool in Fiji (Schindelin et al. 2012) and a micrometer/pixel (MMP) ratio was calculated for each lens.

Below, an example using the 40X objective lens is shown:
Download and unpack Fiji. Run Fiji, then from the TelePi shared folder (see Create a Windows Shared Folder above) drag and drop the image taken with the 40X objective of the microscope calibration slide. Select the Line tool and draw a straight line between two notches on the caliber. Here, we drew one between the 0.1 mm mark (i.e., 100 µm).


Then in Fiji go to Analyze > Set Scale. Type the known distance and the unit (in this example 100 µm) to receive the pixel/µm ratio and set to global. From now on, any image that will be open in this running session of Fiji will have this scale information.


To apply a scale bar, go to Analyze > Tools > Scale bar. The settings below were used. These settings are only valid when using an image captured using the same objective and with the same resolution settings.


The outcome can be seen in the following image:

Scale bar is 50 µm.
To automate the process, the MMP ratio for each lens should be noted by repeating the above steps for each objective lens. Below is a customizable script which can be saved to a text file and dragged and dropped into Fiji. This requires knowledge of the correct MMP ratio for this set of images and placing the images in a folder beforehand. The bolded parts are to be exchanged according to which objective lens was used (i.e. which MMP ratio is to be used and what is the desired width of the scale bar, as well as its thickness). The script can be copied and pasted in Fiji's script editor, or just saved in a text file and dragged and dropped directly in Fiji.

input=getDirectory("Choose a Directory");
list=getFileList(input);
output=getDirectory("Choose a Directory");

for(i=0;i open(input+list[i]);

imageTitle=getTitle();
setBatchMode(false);

run("Set Scale...", "distance=1305.0383 known=100 unit=µm global");

run("Scale Bar...", "width=50 height=18 thickness=60 font=14 color=Black background=None location=[Lower Right] horizontal bold hide overlay");

saveAs("Jpeg", output+ list[i] + "_" + "Scale_Bar" + ".jpeg");

}

print("Done");


Optional
Image Stitching in Fiji
Image Stitching in Fiji
To capture a larger field of view, overlapping single images were taken (with approximately a 10% overlap). Before each image was taken, any necessary adjustment in the focus was performed, so that the image stayed sharp. Afterwards, the images were stitched together using the bundled Fiji plugin Stitching v1.2 (Preibisch et al. 2009). We have uploaded a dataset (Youssef et al. 2023) of overlapping single images of hematoxylin and eosin-stained, formalin-fixed and paraffin-embedded ureter sample captured with a 20X objective (on an Olypmpus BX41 (Olympus, Tokyo, Japan)) and saved as JPEGs without editing. Additionally, we are including the final stitched image using the described method as an exemplary output. As a comparison (shown below), an image of the same region of interest (ROI) taken from a scanned image using a commercial whole slide scanner was included, without any image editing.

Add the images from the dataset to a folder. In Fiji, go to Plugins > Stitching > Grid/Collection stitching. Then make the following choices:



The generated stitched image can then be flattened by Image > Overlay > Flatten and then cropped by selecting Image > Crop. A scale bar can be added by following the previous section using the saved settings of the used objective lens.

Stitched image without cropping.
Stitched and cropped image. Scale bar is 200 µm.
The same ROI was captured with the WSI scanner, and the saved file opened in QuPath (Bankhead et al. 2017) and cropped in the bundled ImageJ (Schneider et al. 2012) program.

Cropped WSI from the same ROI as above. Scale bar is 200 µm.

Optional
Protocol references
Bankhead, P., M. B. Loughrey, J. A. Fernández, Y. Dombrowski, D. G. McArt, P. D. Dunne, S. McQuaid, R. T. Gray, L. J. Murray, H. G. Coleman, J. A. James, M. Salto-Tellez and P. W. Hamilton (2017). "QuPath: Open source software for digital pathology image analysis." Sci Rep7(1): 16878.

Preibisch, S., S. Saalfeld and P. Tomancak (2009). "Globally optimal stitching of tiled 3D microscopic image acquisitions." Bioinformatics25(11): 1463-1465.

Schindelin, J., I. Arganda-Carreras, E. Frise, V. Kaynig, M. Longair, T. Pietzsch, S. Preibisch, C. Rueden, S. Saalfeld, B. Schmid, J. Y. Tinevez, D. J. White, V. Hartenstein, K. Eliceiri, P. Tomancak and A. Cardona (2012). "Fiji: an open-source platform for biological-image analysis." Nat Methods9(7): 676-682.

Youssef, A., Rosenwald, A., Rosenfeldt, M. (2023). TelePi: An affordable telepathology microscope camera system anyone can build and use (v1.0) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.8151968
Schneider, C. A., W. S. Rasband and K. W. Eliceiri (2012). "NIH Image to ImageJ: 25 years of image analysis." Nat Methods9(7): 671-675.