> For the complete documentation index, see [llms.txt](https://guide.cryosparc.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.cryosparc.com/application-guide/volume-viewer.md).
# Volume Viewer
## Inspecting Volumes
The integrated volume viewer allows for inspection of 3D density maps directly in CryoSPARC. Explore a volume or mask, adjust the density threshold, examine internal features, measure distances, and export images or videos without first downloading the map.
### Opening the Viewer
1. Open a job by selecting it and pressing `Spacebar`, or clicking **View Job**.
2. Select the **Volumes** tab. This tab appears when the job has volume outputs.
3. In the **Volumes** panel at the top left, select a map. Maps are listed by output group and result name. Click the selected map again to clear the selection.
The selected map's box dimensions and pixel size appear beside its name. A previously cached map may be selected automatically when you open a job.
The viewer displays one primary map at a time, with an optional associated mask. To inspect maps from another job, open that job's **Volumes** tab.
#### Viewer Layout
| Area | Controls |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Top left | **Volumes**: select the map and toggle its mask. |
| Top right | **Export**: save an image or video. **Autoplay**: animate the view. **Measure**: measure distances on the density surface. |
| Bottom left | Camera toolbar, orientation indicator, and buttons for minimizing panels, entering focus mode, and opening the volume viewer documentation. |
| Bottom centre | Density histogram, threshold value, undo/redo history, and bookmarks. In **Ortho** projection, a scale bar appears when the pixel size is known. |
| Bottom right | **Display**: surface mode, lighting, colours, outlines, clipping, and camera controls. |
Collapse individual panels to make more room for the map. Use **Minimize all panels** beside the orientation indicator to collapse them together. **Focus mode** hides the panels for an unobstructed view; press `Option+F` on macOS or `Alt+F` on Windows/Linux to toggle it. The adjacent documentation button opens the volume viewer guide. Hover over an icon or setting to see its tooltip.
### Moving Around the Map
| Action | Mouse or trackpad |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Rotate | Left-drag within the view. |
| Roll around the viewing direction | Start a left-drag near the edge of the view. |
| Pan | Right-drag or middle-drag. On macOS, `Command`-drag or `Option`-drag also pans; on Windows/Linux, `Alt`-drag pans. |
| Zoom | Scroll, pinch on a trackpad, or use the camera toolbar's zoom buttons. |
| Rotate around one screen axis | `Shift`+left-drag. A horizontal drag rotates around the vertical axis; a vertical drag rotates around the horizontal axis. |
On a touchscreen, drag with one finger to rotate. Use two fingers to pan or pinch to zoom.
#### Camera Controls
The vertical camera toolbar at the lower left provides quick access to common actions:
* **View all** fits the entire map in the viewport while preserving the current viewing direction (`Shift+F`).
* **Initial view** resets the orientation and fits the map (`Shift+S`). It also stops autoplay.
* **Zoom out** and **Zoom in** adjust the camera distance.
* **Snap to axes** rotates to the nearest axis-aligned orientation (`Option+0` on macOS).
* **Rotation indicator** shows or hides the point about which the map rotates. The separate coloured orientation indicator shows the map's X, Y, and Z axes.
The **Camera** section of **Display** contains two additional controls:
* **Projection**: **Perspective** makes nearer features appear larger; **Ortho** removes perspective distortion, making it easier to compare dimensions at different depths. When a map has a known pixel size, **Ortho** also displays a scale bar in angstroms (Å).
* **Turn 90°**: Click a `+X`, `X`, `+Y`, `Y`, `+Z`, or `Z` turn button to rotate the view by 90° about the corresponding screen axis. **Hold `Shift` while clicking to switch from turning about an axis to viewing along that axis.** The buttons and tooltips indicate the selected direction and action.
{% hint style="info" %}
**Tip:** Use **View all** if the map moves out of frame but you want to keep the current orientation. Use **Initial view** to return to the starting orientation.
{% endhint %}
### Adjusting the Density Threshold
In **Surface** mode, the threshold defines the visible boundary of the density map. Lower thresholds generally include more weak density and noise; higher thresholds isolate stronger density and can separate the map into disconnected regions.
The histogram shows the distribution of density values, with a vertical line marking the current threshold. An initial threshold is chosen automatically for each map; treat it as a starting point, not a recommended contour level for every reconstruction.
* Click or drag within the histogram to adjust the threshold interactively.
* Enter a numerical value in the threshold field or use its stepper buttons.
* When the histogram has focus, use the arrow keys to change the threshold. Hold `Shift` to make larger steps.
* Use the history arrows to undo or redo committed changes. Click **History** or **Bookmarks** to switch what the arrows step through: the complete threshold history or only your bookmarked levels.
* Click the bookmark icon to save a useful threshold temporarily. Bookmarks make it easier to compare different contour levels.
When map statistics are available, the sigma readout shows how many standard deviations the threshold lies above or below the mean density.
The rendered density uses a limited set of intensity levels, even at full spatial resolution. As a result, nearby threshold values may produce the same visible surface.
{% hint style="info" %}
**Tip:** Bookmark a few useful levels to compare the overall envelope with stronger internal features. Threshold history and bookmarks are temporary and reset when a different map is loaded.
{% endhint %}
### Changing the Display
Expand **Display** on the right to adjust how the map appears. The controls are grouped into **Mode**, **Lighting**, **Colour**, **Outlines**, **Clip**, and **Camera**.
#### Surface and Hologram
| Mode | What it shows |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Surface** | A solid, lit boundary at the selected density threshold. Use it to examine the map's shape, cavities, and surface features. |
| **Maximum** | A maximum-intensity projection, showing the highest density along each line of sight. Use it for a see-through overview of the map. |
In **Maximum** mode, **Gate by threshold** distinguishes density below the selected threshold by rendering it in greyscale. It does not remove that density. The option is unavailable in **Surface** mode.
#### Lighting, Colour, and Outlines
* **Diffused** uses ambient shadowing to reveal pockets and cavities without strong directional lighting.
* **Studio** combines directional lighting, cast shadows, and ambient shadowing for stronger depth cues.
* **Ambient** provides softer, subtler ambient shadowing.
* **Depth cue** fades more distant regions toward the background colour.
* **Surface** and **Background** open colour pickers with preset palettes, a custom colour value, and a reset option. You can save custom colours for reuse. The surface colour also tints the **Maximum** view.
* **Outlines** can be switched **On** or off. Adjust **width** to change line thickness and **detail** to control how much edge detail is shown.
#### Looking Inside the Map
Under **Clip**, enable **Far** and adjust the **depth** slider to hide density behind the clipping plane. The clipping plane follows the camera, so rotating the map changes which region is cut away.
{% hint style="info" %}
**Tip:** Combine **Far** clipping with **Ortho** and an axis-aligned view to inspect an internal cavity from a consistent direction.
{% endhint %}
### Inspecting Masks
If the selected output group has an associated mask, a **mask** switch appears beneath its maps. Turn it on to display a translucent mask surface over the density. Turning on a mask in another group also selects a map from that group.
If mask-specific controls are available, use them to adjust how the mask is displayed or contoured independently of the primary map. Selecting a different primary map turns off the current mask.
{% hint style="info" %}
**Tip:** Use the mask overlay to assess coverage without changing the map's own density threshold.
{% endhint %}
### Measuring Distances
Measurements require **Surface** mode and a map with a known pixel size.
1. Expand **Measure** in the right-hand panel and click the **ruler** button to start measuring.
2. Click a point on the visible density surface, then click a second point. The viewer connects them with a line and labels their straight-line 3D distance in angstroms (Å).
3. Continue clicking pairs of points to add measurements. Rotate or zoom the view to examine the selected positions.
4. Click the ruler button again to stop measuring. Press `Escape` to cancel a measurement after placing only its first point.
The **Measure** panel lists the distances you have recorded. Hover over a measurement to inspect its endpoint coordinates; use the delete control to remove one measurement, **Clear** to remove them all, or **Copy** to copy distances and endpoint coordinates for use in notes or a spreadsheet.
Measurements stay attached to their selected map coordinates as the camera or display changes, but are cleared when another map is loaded. Changing the threshold does not automatically move existing endpoints to the new surface.
{% hint style="info" %}
**Tip:** Set an appropriate density threshold before measuring. These are distances between selected positions on a density surface, not atomic-model distances or distances measured along the surface.
{% endhint %}
### Animating the View
Expand **Autoplay** to create a rotating or rocking view of the selected map:
1. Choose **Spin** for continuous rotation or **Rock** for back-and-forth motion.
2. Select an **X**, **Y**, or **Z** axis and adjust the speed or motion settings. For a spin, the panel shows the rotation speed and the time required for a full turn.
3. Choose **Once**, **Loop**, or the double-arrow **Ping-pong** option. Enable **rev** to reverse the direction.
4. Click **Play** to preview the animation, and **Stop** to end it.
Autoplay moves the camera around the selected map; it does not cycle through different maps or job iterations.
{% hint style="info" %}
**Tip:** A slow spin is useful for surveying an overall reconstruction, while a gentle rock helps communicate depth without losing sight of a feature.
{% endhint %}
### Saving Images and Videos
#### Images
1. Expand **Export** and select **Image**.
2. If needed, enable **Transparent background**.
3. If the camera is in **Ortho** projection, you can enable **Scale bar** to include the visible distance scale in the exported image. The scale bar option is not available in Perspective.
4. Click **Save image** to download the rendered image. **Hold `Shift` while clicking to copy the image to the clipboard instead**; the button changes to **Copy image** when this action is available.
The image button shows the export dimensions. Export captures the rendered map, not the surrounding CryoSPARC panels or controls. Clipboard support depends on the browser.
{% hint style="info" %}
**Tip:** Switch to **Ortho** before exporting a figure that needs a scale bar. Check the framing and threshold before saving or copying the image.
{% endhint %}
#### Videos
Configure and preview a **Spin** or **Rock** animation in **Autoplay**, then select **Video** in **Export** to record it. Available recording options and formats depend on browser capabilities, including WebCodecs support and compatible encoders. A recorded video contains a finite animation rather than an endless loop.
#### Original Map Files
The viewer's **Export** controls save rendered images and videos, not volume data. To download an original map or mask, use the download menu for the relevant output group in the job's output sidebar or the download link in **Outputs**. Use the original files when you need full-precision map data or analysis and overlays not available in the viewer.
### Saved Settings and Troubleshooting
Common display preferences, including mode, colours, lighting, outlines, camera projection, and rotation-indicator visibility, are remembered locally in the browser. They do not modify the job's output data. Temporary interactions such as threshold history, bookmarks, measurements, clipping depth, and autoplay setup are not saved with the job.
Use the reset icon in the **Display** header to restore the viewer's display preferences to their defaults. Use **Initial view** separately to reset orientation and framing.
| Situation | What to check |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| The viewer cannot start | WebGPU support is required from both the browser and GPU. Try a recent version of Chrome or Edge. |
| The GPU was reset | Reload the page to restart the viewer. |
| No surface is visible | Confirm that a map is selected, check the threshold and clipping depth, then use **View all** or **Initial view** to recover the framing. |
| The map looks incomplete or low-detail | Allow time for the map to load and rendering to settle. Try reopening the view if it remains incomplete. |
| The histogram fails to load | Use the histogram's retry control, if shown. The map and histogram load separately. |
| A mask appears misplaced | Check the original map and mask grids and any alignment warning. The overlay is not automatically registered. |
| Measuring is unavailable | Choose **Surface** mode and confirm that the map has a known pixel size. |
| The scale bar is missing | Switch the camera to **Ortho** and confirm that the map has a known pixel size. For images, also enable **Scale bar** in **Export**. |
| Clipboard or video export is unavailable | Browser support varies. Try a compatible browser or save an image directly instead of copying it. |
### Related Guide
See [Inspecting Job Data](https://guide.cryosparc.com/application-guide/inspecting-job-data) for opening jobs, navigating the job dialog, and downloading outputs.
