Navigation & Zoom

Core Feature

This feature is available in all Portrai Explorer deployments.

Learn how to navigate the map viewer efficiently using mouse controls and projection modes.

Mouse Controls

Pan Mode (Default)

In Pan mode, use your mouse to move around the map:

Action	Mouse Control	Result
Pan	Click + drag	Move the view in any direction
Zoom in	Scroll wheel up	Zoom into the map
Zoom out	Scroll wheel down	Zoom out of the map
Quick zoom in	Double-click	Zoom in on clicked location
Quick zoom out	Shift + double-click	Zoom out from clicked location
Zoom to a box	Shift + drag	Zoom into the box you draw

Selection Modes

The mode switcher at the bottom of the map holds four tools. Everything other than Pan changes what click and drag do:

Tool	Shortcut	Click + drag	Release
Pan	V	Move the map	-
Lasso	S	Draw one selection boundary	Close and apply the selection
Brush	B	Paint cells into the selection	Fold the stroke into the region
Eraser	E	Paint cells out of the selection	Fold the stroke into the region

Hold Space in any of them to pan without switching tools.

Points the Subset or the cutoff excludes are hidden; points a lasso or a brush simply has not selected stay on screen, dimmed, so a selection keeps its surroundings as context. On very large datasets colored by a continuous feature or a Signature score, a selection hides what it leaves out instead (see Very Large Datasets).

See Lasso Selection and Brush Selection for details.

Zoom Controls

Zoom Levels

The map supports multiple zoom levels:

• Zoomed out - See the entire tissue/sample
• Zoomed in - See individual data points in detail

Zoom to Fit

Reset the view to show all data:

1. Click Reset View, the crosshair button in the bottom-left corner of the map viewer
2. The view adjusts: on a projection with a tissue image it fits the whole image, on one without, such as UMAP, it fits the points

Reset View changes only zoom and position; the projection, selections and subsets stay as they are.

Projection Modes

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

Available Projections

Available projections depend on your project data. Common examples include:

Mode	Description	Use For
Spatial	Original tissue coordinates	Anatomical context
UMAP	UMAP embedding	Transcriptional similarity
t-SNE	t-SNE embedding	Cluster visualization
PCA	PCA embedding	Variance analysis

Your project may include additional or different projections based on the analysis performed during data preparation.

Switching Projections

1. Locate the projection selector — it is the first item in the top toolbar of the map viewer
2. Click to open the dropdown (or use the segmented buttons shown when only two or fewer projections are available)
3. Select the desired projection
4. The view transforms to show the new coordinates

What Changes

When you switch projections:

• Point positions update to the new coordinates
• The background image may hide (embeddings have no tissue image)
• Each projection keeps its own zoom and position (see Per-Projection View)
• An embedding without a tissue image keeps its own proportions, so a UMAP is not stretched to the tissue's shape
• Color mapping and subsets remain active
• A pending lasso or brush selection on the map is cleared, with a notification titled Lasso selection cleared or Brush selection cleared. Add it to a subset first to keep it. See Switch Projection

Selections in Different Projections

Lasso and brush selections are both projection-aware:

• Selections in spatial view select by tissue location
• Selections in UMAP/t-SNE select by transcriptional similarity
• Each selection stores the projection it was made on, and a brush region can only be reopened for editing while that projection is the one on screen (see What Changes for what a switch does to a pending selection)

View State

Preserved State

These settings persist when navigating:

• Current feature/color mapping
• Active subsets
• Point size and opacity settings

Per-Projection View

Each projection remembers its own zoom and position. The first time you open a projection, the map frames it to fit (an embedding once its points have loaded). When you return to a projection, the map restores the view you left it at. Reset View frames the current projection again.

Remembered views last while the Explorer stays open. After a page reload, or after switching to another extension and back, the map starts again on the default projection (the one with the tissue image, if there is one), framed to fit. Coming back from another extension this way also clears a pending lasso or brush selection made on another projection; add it to a subset first to keep it.

Performance Tips

Large Datasets

For datasets with millions of points:

1. Allow loading time - Initial render may take a moment
2. Zoom strategically - Zoomed views render faster
3. Use subsets - Reduce visible points for smoother interaction

Smooth Navigation

1. Select back to back - You can draw one selection right after another; the item count and most plots catch up once you pause
2. Zoom before panning - Zoom into region, then pan within it
3. Use projection wisely - Switch only when needed

Troubleshooting

View is Stuck

• Click Reset View, the crosshair button in the bottom-left corner of the map
• Refresh the page if necessary
• Check if a selection tool is active (switch to Pan)

Zoom Not Working

• Ensure mouse is over the map area
• The map has no zoom buttons: zoom with the scroll wheel, or double-click in Pan mode
• With the Brush or Eraser selected, Shift + scroll wheel resizes the brush instead of zooming; scroll without Shift to zoom
• Zooming out stops at a limit

Projection Won't Change

• Wait for current view to finish loading
• Check if projection data is available
• Some datasets may not have all projections

Related Topics

• Map Viewer - Complete map viewer documentation
• Lasso Selection - Drawing a single outline
• Layer Settings - Point appearance