---
title: "Volumetric data"
description: "How Ouro renders Gaussian .cube files as isosurfaces and slices"
date: "2026-09-28"
last_updated: "2026-09-28"
---

Ouro renders any file ending in `.cube` as interactive volumetric data: a
scalar field on a grid, such as a charge density, spin density, or
electrostatic potential. Gaussian cube is the common format for these, and
Gaussian, Quantum ESPRESSO, CP2K, ABACUS, and ASE all write it.

## What the viewer shows

On the file page, the viewer has two views:

- **Surface** draws an isosurface inside the cell, with the atoms and the cell
  edges. A slider sets the isovalue by the share of the cell the surface
  encloses, and reports the share of electrons inside it.
- **Slice** draws one plane of the grid as a color map with contour lines.
  Readers pick the axis and the layer, and can jump to the planes that pass
  through atoms. Hovering reads the value at any point.

A side panel shows the formula, cell, and grid size, the electrons in the
cell, and the electrons in each atom's Voronoi cell. Readers can hide
elements from the key, and hovering an atom shows its site label, position,
and charge.

Signed fields, such as spin densities or density differences, are detected
from the values. The viewer then draws positive and negative lobes in two
colors and reports net and absolute totals in place of an electron count.

Embedded in a post, the file shows the isosurface alone, without the panel.

## Encoding

The viewer reads the standard layout: two comment lines, the atom count and
origin, one line per grid axis, one line per atom, then the values.

- Values are read as densities in e/bohr³, which is what integrating over the
  cell assumes. A field in other units is drawn correctly, but its electron
  counts are scaled.
- Lengths are in bohr. A negative voxel count on an axis line marks the file
  as using ångströms, per the format.
- A file holding several datasets per grid point, such as multiple orbitals,
  shows the first one.
- The grid is treated as one periodic cell. A molecular cube file renders,
  inside the box its grid spans.

Large grids are downsampled for the isosurface; slices and totals use every
grid point.

## Uploading a file

```python
from ouro import Ouro

ouro = Ouro()
ouro.files.create(
    name="Fe3O4 charge density",
    description="Total charge density from Quantum ESPRESSO pp.x",
    visibility="public",
    file_path="Fe3O4.cube",
)
```