How to open/export .mrxs files from the 3D-Histech Digital Scanner

Owned by Ofra Golani
Last updated: Mar 08, 2022
8 min read

Overview

This page deals with viewing and exporting MIRAX files. If you need help with further analysis and quantification of the data please approach us. 

The 3D Histech digital scanner saves the data in the MIRAX format which include:

  1. .mrxs file

  2. a folder with many .dat files 

The .dat files are like small pieces of the image 

The .mrxs file include the metadata including the information on how the .dat files are organized. 

In software packages you open mrxs file, but you need all the files to be in place. If you open the mrxs file on its own - you'll get just the low resolution image.



This format is NOT supported by Bio-Format, so the images cannot be opened directly in ImageJ/Fiji. 

You need to export the data to another format (eg tiff) in order to open it in Fiji, Imaris, etc...



There are several image analysis software packages that can open directly 3D Histech files which are either

  • Color RGB images  OR

  • Up to 3 fluorescence channels of 8bit.

 

QuPath - open source software for Quantitative digital Pathology - We recommend using QuPath. See our Image Analysis training material page for QuPath training links.

Arivis - commercial, we have one license in the CellObservatory unit, can be booked through internal services. Please contact us if you want to use it.

OpenSlide library

The files can be also opened by other Commercial Digital Pathology software (not available at WIS) such as CaseCenter by 3D Histech, VisiomorphDP and TissuemorphDP by Visiopharm, TissueStudio by Definiens, HALO, ... 

if you are interested to know more about digital slides formats see the OpenSlide publication

 

16 bit mrxs files, or mrxs files with more than 3 channels should be converted to tif file

The way to convert is to run bioformats2raw utility, followed by raw2ometiff , as described in this Glencore blog.

We have implemented this in the facility - contact @Vitaly Golodnitsky or @Ofra Golani for instructions. 



3D Histech provides 2 free software tools for viewing and exporting the files:

  1. CaseViewer - The latest viewer. Make sure you download the version with Converter to be able to export the files to other formats 

  2. Panoramic Viewer - older viewer that also provide export options



We recommend using QuPath (see instructions below), because:

  • It enables you to define, keep and export selected Rois of the slides while working directly from (read only) BioImg storage server. On the contrary 3D Histech Viewers save the Rois with the slides, and require that you have write permission in order to export Selected Rois, Thus if you use 3D Histech viewers you need to copy the original slides locally if you wish to export selected Rois to another format. 

  • QuPath provides also many analysis options ... 

  • 3D Histech Viewers do not set the pixels size correctly while exporting the files to tiled tiff, while QuPath handle this correctly. 

  • QuPath is available for either Windows or Mac, while 3D Histech Viewers are available only for Windows, 

However, if you have more than 3 channels you must use Panoramic Viewer, and export each of them independently.


Recently Glencore implemented the following pipeline to convert MRXS files to tif. It works also on multi-channel images.

Olivier Burri from EPFL-BIOP has a detailed protocol for this.

 

Working with QuPath

  • Create Project: , you need to provide an empty folder on your hard disk, in which QuPath will save all the selected ROIs. It will not copy the data to that folder. 

  • Add Images: select the desired mrxs files 

  • For each file and desired Roi:

    • Select ROI using the Rectangle ROI tool for example, you can give it a name by going to the Annotation Tab, Highlighting the ROI, right click and select "Set Properties"  

    • From the menu select: Extensions=>imageJ=>Send region to ImageJ

  • select desired Down sampling factor and click OK (you may be asked for verification if the expected file size is big)

  • The image will be opened with ImageJ (a version installed with QuPath, not your own installation of ImageJ/Fiji), Use File => Save AS... Tiff  to save it to a desired folder. We suggest to include the Roi Name and any downsample factor used in the saved file name for future reference



Working with 3D Histech Viewers

You can export the data from 3D Histech viewers for further analysis in other by saving it to tiled-tiff format and reading this data using Bio-Formats plugin in the other software (eg ImageJ/Fiji)

The CaseViewer/3DHistech Slide Converter allows you to convert a whole slide or selected region of interest, with the original resolution. It exports each channel into different file. Note that the files are not scaled to original unit, and you need to take care of scaling.

Depending on the data, in some cases exporting the whole slide creates files that are too big to open in Fiji and gives you an error when you try to open them (java.lang.IllegalArgumentException: Array size too large: ....    eg: 53248 x 137216 x 1 x 1 ). 

Even if you can open these files, you may want in some cases to opt for smaller files because of the file size which reflects on opening and processing time. 

You can also export only part of the file using annotation, but this requires 

  1. Annotation - eg a rectangle around your desired region of interest (use only 1 annotation each time !) 

  2. Exporting the regions of interest to MIRAX file

  3. Opening the smaller MIRAX file and exporting it to tiled-tiff file



The Panoramic Viewer exporter provides more flexibility, which allows reducing the file size:

  • Export selected region of interest - eg export independently each of the 4 sections you mounted on the slide

  • Down sample the data (AKA binning), in many cases 1:4 reduction is OK, but inspect your data to make sure you see the details that you are looking for

Both converters allow you to select uncompressed and compressed (losless / lossy)  format

See details below. 

To Export the data using Panoramic Viewer 

See instructions in the following document

Notes: If you have more then 3 channels - you must export each channel indepently



To export the a whole slide using CaseViewer / 3DHistech Slide Converter 

Open the file from the local computer 

Click on the left-most icon (Slide Operations), and then on the "Export Slide" button 

This will open the 3DHistech Slide Converter. You can also Open the Converter directly , in this case you can browse to select the input slide

Set the "To:" field on the top of the window to be "tiled tiff"

Select the output location 

Set Properties: select the compression type to be "Loseless copression", click the save button

Click on "Add Slides to Queue", this will add the files to the list below. 

Check the box on the left side before the file name, and click on "start converting". This will create a tiled-tiff format file that you can open in Fiji and Imaris.

Note however that the files are not scaled to the correct unit.



To export selected area slide using CaseViewer / 3DHistech Slide Converter 

In some cases the exported slide is too big for Fiji, ad you will need to export only selected region of interest.

You can also export only part of the file using annotation, but this requires 

  1. Annotation in CaseViewer - eg a rectangle around your desired region of interest 

  2. Exporting to MIRAX file

  3. Opening the smaller MIRAX file and exporting it to tiled-tiff file

Note that the Anootation icon will be enabled only if you have write permission - so you cannot export with selected region using Annotation directly from BioImg. You need to copy slides from BioImg to your local disk to draw annotations, or export the whole slide directly from BioImg as described above



Stage 1, Set Annotation. eg rectangle around the selected section. Use single annotation each time. Trying to do this having several annotations, did not work for me. 



Stage 2, export to MIRAX: Click on the left-most icon (Slide Operations), and then on the "Export Slide" button. The Slide Converter will be opened. 

Set Properties: convert from MIRAX to MIRAX and check the "Annotation Area Only", save

Click on "Add Slides to Queue", and then select the slide from the list below and and click on "start converting".

Stage 3, export the small MIRAX to tiled-tif: When done, click on the "Open" button on the right side of the exported file (inside the converter) , select the To: format to be tiled-tiff, click on properties 

set properties: select Properties uncompressed conversion and add slides to the queue and start converting. 

This will create a smaller tiled-tiff format file that you can open in Imaris and Fiji using Plugins=>Bioformats=>BioFormats Importer.



For more details see the 3DHistech user guides which are accesible through the Start menu.



To scale the data correctly you need to:

Get the pixel size from CaseViewer

  • Click on the Show Label buttton on the left side

  • Click the  i  button on the label on the right

  • In the new window - look for (Micrometer/Pixel)

Set the Scale

In Fiji :

  • Open the File with Plugins=>Bio-Formats=>Bio-Formats Importer

  • Set the scale using Image=>Properties: Set Pixel Width and  Pixel Height to (Micrometer/Pixel)

In Imaris: 

  • Open the file using Fiji =>  Plugins=> BioFormats =>  Bioformats Importer

  • Set the Scale using Edit=>Image Properties. A new window will be opened. Set Voxel Size for both X and Y to (Micrometer/Pixel) , 



Acknowledgment

We thank the following people for useful discussion and input: Peter Bankhead (Author of QuPath), Szymon Stoma and Simon Noerrelykke from ScopeM ETH Zurich .