Pythostitcher is a tool inspired by AutoStitcher to stitch histopathology images into an artifical whole mount image. These artificial whole-mounts are indispensable for multimodal imaging research, since they greatly improve the ability to relate histopathology information to pre-operative imaging. PythoStitcher works fully automatically and is able to generate very high resolution (0.25 µm/pixel) whole-mounts. For a detailed description check out the official PythoStitcher publication in Nature Scientific Reports.
If your data consists of either halves or quadrants of a certain type of tissue (i.e. a prostate), PythoStitcher should be able to reconstruct the artificial whole-mount for you. PythoStitcher expects that your data has multiple resolution layers, also known as a pyramidal file, and preferably uses .mrxs or .tiff files. In addition, PythoStitcher requires a tissue mask of said tissue. This tissue mask can be generated by your tissue segmentation algorithm of choice; in the provided sample data we make use of the algorithm from Bándi et al.
It is highly recommended to run PythoStitcher as a Docker container, since PythoStitcher uses some libraries that need to be built from source. The Docker container comes prepackaged with these libraries, as well as with model weights of the involved CNNs, and should run out-of-the-box. You can pull the container with the following command or alternatively build it yourself locally with the provided Dockerfile in /build.
docker pull ghcr.io/computationalpathologygroup/pythostitcher:latest
Your input data should consist of a dataframe (.csv) specifying all the paths for the high resolution image and tissue mask files per case. Each case is defined by multiple rows (2 or 4) sharing the same save_path, which dictates where the results will be saved. Required and optional columns:
- image_path - path to the full resolution WSI (.mrxs or .tif)
- mask_path - path to the corresponding tissue foreground mask of the WSI (.tif)
- save_path - dir to save all the results for a given case
- force_config_path [OPTIONAL] - optional path to the force_config file that can be used to force a specific fragment configuration
- landmark_paths [OPTIONAL] - optional path to a npy file holding landmarks (at level 0) which can be warped together with the WSIs
Ensure each mask_path corresponds to its image_path. Files can live anywhere accessible to the container (e.g., under /data).
Example CSV (two fragments for one case). See also the example_df.csv file as example.
imagepath,maskpath,savepath
/home/user/data/case01/images/image1.mrxs,/home/user/data/case01/masks/image1_mask.tif,/home/user/results/case01
/home/user/data/case01/images/image2.mrxs,/home/user/data/case01/masks/image2_mask.tif,/home/user/results/case01
All global settings can be modified through the parameter_config.json file. A template is included at config/parameter_config.json.
After preparing the dataframe and configuration JSON, run PythoStitcher via:
docker run -v /home/user:/home/user ghcr.io/computationalpathologygroup/pythostitcher:latest --df "/home/user/data/cases.csv" --config "/home/user/config/parameter_config.json"
--df points to your csv with the required columns, and --config points to the parameter JSON. The -v /home/user:/home/user flag mounts your local directories so the container can access both input data and output locations.
If you don't have any data available, but are still curious to try PythoStitcher, you can make use of our sample data available from 
The development of PythoStitcher would not have been possible without the open-sourcing of JigsawNet, ASAP and PyVips.
The source code of Pythostitcher is licensed under the GNU Lesser General Public License (LGPL). The provided sample data is licensed under the CC Attribution 4.0 International license. Please take these licenses into account when using PythoStitcher.