Map Viewer

Core Feature

This feature is available in all Portrai Explorer deployments.

The Map Viewer is the primary visualization component in Portrai Explorer. It displays your spatial transcriptomics data as an interactive map, allowing you to explore tissue images overlaid with data points.

Interface Components

Toolbar

The map viewer has two sets of controls: a top toolbar that runs along the top of the view, and a mode switcher that floats at the bottom-center of the map.

Top toolbar (to the right of the subset input field):

Control	Description
Projection select	Switch the coordinate system (Spatial, UMAP, t-SNE, etc.) — the first item in the toolbar
Facet view (Grid icon)	Split the map into per-category panels — see Facet View
Layer Settings (Layers icon)	Adjust point and image appearance — see Layer Settings
Export (Download icon)	Export the current view as a PNG image or feature data as CSV

Bottom mode switcher:

Control	Shortcut	Description
Pan (Hand icon)	V	Navigate the map by clicking and dragging
Lasso (Lasso icon)	S	Draw one closed outline around a region of interest
Brush (Brush icon)	B	Paint cells into the selection
Eraser (Eraser icon)	E	Paint cells out of the selection
Items dropdown		Shows how many points pass the Subset, the cutoff and the current selection, with additional options

Selecting Brush or Eraser adds the brush options (radius slider, numeric input, size preview, and Undo / Redo / Clear) to the right of the tool buttons. Press Esc to return to Pan; hold Space to pan temporarily without changing tools. The facet view covers the map and this mode switcher, so none of the tools can be used while it is open. A pending lasso or brush selection still applies to its panels.

Whichever tool you use, the points it does not select stay on the map, drawn dimmed behind the ones it does (except on very large datasets). Only a Subset condition or a cutoff removes points outright. See Subset for the rule.

Map Area

The central map area displays:

• Background image - Tissue image (if available), supports multi-image overlay with additive blending for fluorescence channels
• Data points - Individual cells or spots colored by the selected feature
• Selection overlay - The lasso outline, or the painted fill while a brush region is pending

To bring everything back into view, click Reset View, the crosshair button in the bottom-left corner of the map. On a projection with a tissue image it fits the whole image; on one without, such as UMAP, it fits the points. See Navigation & Zoom.

Very Large Datasets

When the dataset holds 2 million points or more (counting those the Subset hides) and the map is colored by a continuous feature or a Signature score, the map draws a blended picture instead of individual points: each pixel shows the average color of the points under it. A lasso or brush selection is applied to that picture, so the points it leaves out disappear instead of dimming. The scatter plots do the same.

Color Reference

The map itself shows no legend. The color reference for the current feature is the Detail Panel in the Sidebar:

• Categorical features - Each category with its color and the number of its points that pass the Subset, the cutoff and the current selection
• Continuous features - A histogram drawn in the color scale, with the minimum and maximum values

Hover over a category or a histogram bar there to show only its points on the map (with a lasso or brush selection active, only its selected points) until you move the pointer away. A legend is added to PNG captures of the map.

Subset Panel

Click the subset input field to open the Subset Panel. See Subset for details.

Interaction Modes

Pan Mode

Pan mode is the default interaction mode for navigating the map.

Controls:

Action	Mouse	Result
Pan	Click + drag	Move the map view
Zoom in	Scroll up / Double-click	Zoom into the map
Zoom out	Scroll down	Zoom out of the map

Selection Modes

Three of the four tools select rather than navigate: the Lasso draws one closed outline, while the Brush and Eraser paint a region stroke by stroke.

How to use:

1. Click the Lasso button in the bottom mode switcher
2. Click and drag on the map to draw a closed shape
3. Release to complete the selection
4. The mode switcher shows the count of selected items

The Brush and Eraser work differently: each release folds one stroke into a region you keep building on. See Brush Selection.

After selecting:

Click the Items dropdown to access options:

• Add selection to subset - Save the lasso or the painted region as a subset condition

Alternatively, opening the Subset Panel after making a selection shows a selection preview banner. It names what is pending, a lasso with its vertex count or a brush region with its stroke count, and carries an Add to subset button beside a Clear ✕ that discards it.

Projection Modes

Switch between different coordinate systems to view your data from multiple perspectives.

Available Projections

The available projections depend on your dataset — only the embeddings present in your data are listed. Common ones include:

Mode	Description
Spatial	Original tissue coordinates (default)
UMAP	UMAP dimensionality reduction coordinates
t-SNE	t-SNE dimensionality reduction coordinates

Switching Projections

1. Locate the projection selector, the first item in the top toolbar
2. With two projections or fewer, it shows one button per projection: click the one you want. With three or more, click it to open the dropdown menu and select the projection
3. The map view updates to show the new coordinates

Each projection keeps its own zoom and position: the first time you open one, the map frames it to fit, and returning to it restores the view you left. An embedding without a tissue image, such as UMAP or t-SNE, keeps its own proportions instead of being stretched to the tissue's shape. See Per-Projection View.

Lasso selections made in embedding space (UMAP/t-SNE) can be saved and reused in subsets.

A pending lasso or painted region belongs to the projection it was made on and is discarded when you switch, with a notification titled Lasso selection cleared or Brush selection cleared. Add it to a subset first to keep it. A lasso drawn on a scatter plot is not affected. See Lasso Selection.

Supported Image Formats

The Map Viewer supports multiple image formats for background tissue images:

Format	Description	Best For
GeoTIFF	Cloud Optimized GeoTIFF	Large images, streaming
Static	PNG, JPEG	Small to medium images
Tiles	Multi-resolution tile pyramid	Very large images

The appropriate format is determined by your data configuration and loaded automatically.

Multi-Image Overlay

When a project contains multiple images (e.g., DAPI + Cell Boundary, or H&E + fluorescence channels), the Map Viewer automatically overlays them:

• Fluorescence channels are composited using additive blending with distinct pseudocolors
• H&E images render as the base layer with fluorescence overlaid on top
• Each channel can be independently controlled via Layer Settings
• The background is black in fluorescence-only mode for standard microscopy appearance

Tooltip

Hover over data points to see detailed information:

The tooltip displays:

• Current feature value for the hovered point
• Point index or identifier
• Additional metadata (if configured)

Performance Tips

Large Datasets

For datasets with millions of points:

• Use tile-based images when available
• Allow time for initial rendering
• Zoom into regions of interest for smoother interaction
• Consider using subsets to reduce visible points

Smooth Navigation

• Avoid rapid zoom changes
• You can draw one selection right after another: the map updates right away, and the item count and most plots catch up once you pause
• Use Pan mode for general navigation, switch to a selection tool only when needed

Related Topics

• Navigation & Zoom - Detailed navigation controls
• Lasso Selection - Complete lasso selection guide
• Brush Selection - Painting a region with the Brush and Eraser
• Color Mapping - Configure data point colors
• Layer Settings - Adjust point size and opacity