utsw1qbrc/scopeviewer repository overview

⁠ScopeViewer Docker Image

⁠Description

We introduce ScopeViewer, a browser-based software designed to visualize large image data and associated annotations at various zoom levels, allowing for intricate exploration of the data; enable dual interactive viewing of the original images along with their annotations, providing a comprehensive understanding of the context; display spatial molecular features with optimized band-width, ensuring a smooth user experience; and bolster data security by circumventing data transfers.

⁠Usage

To run the ScopeViewer Docker image, execute the following command:

docker run -it --rm -p 3001:3000 -e CHOKIDAR_USEPOLLING=true utsw1qbrc/scopeviewer:latest

Then open your browser at http://localhost:3001⁠

Explanation of options:

• -it: starts the container in interactive mode.
• --rm: Removes the container automatically after it exits.
• -p 3001:3000: Maps port 3001 of the host to port 3000 inside the container. Access ScopeViewer from your local browser using http://localhost:3001/⁠.
• -e CHOKIDAR_USEPOLLING=true: enables a polling mechanism via chokidar (which wraps fs.watch, fs.watchFile, and fsevents) so that hot-reloading will work.

⁠How to Prepare User Data for Visualization on ScopeViewer

⁠1. Prepare Image Data

Our whole slide viewer supports the DZI (Deep Zoom Image) format. Follow these steps to prepare your image data:

1. Convert your large high-resolution images to the DZI format using one of the recommended tools:

   • VIPS⁠
   • deepzoom.py⁠

2. After successful conversion, you should have an imagefile.dzi file and an imagefile_files folder.

3. Provide image information in a JSON file. If you have both the original slide and a slide with a mask, provide links for "tile_folder_url" and "mask_url". The slides must have the same width, height, format, and tile size.

Example JSON:

[
 {
  "image_id": 1,
  "image_name": "Visium_FFPE_Human_Breast_Cancer_image",
  "pathology_histology": "Normal",
  "width": 27452,
  "height": 25233,
  "format": "jpg",
  "tile_size": 256,
  "tile_folder_url": "https://yourhost/user_data/imagename_files/",
  "mask_url": "https://yourhost/user_data/imagename_mask/"
 }
]

⁠2. Prepare Overlay Images using Treelayout

Our viewer supports overlays for displaying additional information on images. Follow these steps:

1. Prepare DZI image files for overlay using transparent background (PNG format).

2. Ensure the overlay images have the same width-to-height aspect ratio as the background slide.

3. Provide image URLs in a JSON file to define the structure of the overlay tree.

Example JSON:

{
  "tree_layout": [
    {
      "value": "root",
      "label": "Tissues",
      "children": [
        {
          "value": "fat",
          "label": "Fat",
          "path": "path_to_fat_overlay.dzi",
          "format": "dzi",
          "overlay": true,
          "tilesize": 256,
          "width": 10000,
          "height": 8000
        },
        // ... other tissue types
      ]
    }
  ]
}

⁠3. Prepare SMP Layer

To overlay spatial molecular profiling (SMP) data:

1. Prepare three essential files: gene name CSV (example⁠), location CSV with x and y coordinates (example⁠), and count CSV with gene expression info (example⁠).

2. Use the provided Python script⁠ to convert the files into an SQLite database (tables: gene_list_sql, smp_loc_sql, smp_count_sql).

3. Provide the database file path using the "smp_layer" key in a JSON file.

Example JSON:

{
  "smp_layer": "http://hostname/sqlite_data.db"
}

⁠Fixing CORS Issues for Your Data Server

To fix CORS issues, set the following HTTP headers in your server's response:

• Access-Control-Allow-Origin: * or your ScopeViewer's domain name
• Access-Control-Allow-Methods: POST, GET, OPTIONS
• Header add Access-Control-Allow-Headers: *

These headers will allow loading resources from specified origins and permit valid methods to query the resource.