.. _scene_objects.voxel_grid:

Voxel grids
-----------

.. image:: /images/visual_elements/voxel_grid_example.png
  :width: 30%
  :align: right

The *voxel grid* data object in OVITO is a structured grid of voxel cells. Voxel grids are typically discretized
representations of spatial fields in two or three dimensions.

Either the **cells** or the **vertices** of a voxel grid are associated with numeric properties (field values).
These properties may represent a variety of physical quantities, such as charge density, temperature, or magnetic field direction.
OVITO supports scalar, vector, and tensor field properties on voxel grids.
You can perform cell- or vertex-wise computations on these field properties with the
:ref:`particles.modifiers.compute_property` modifier of OVITO.

Importing or creating voxel grids in OVITO
""""""""""""""""""""""""""""""""""""""""""

Voxel grids can be loaded into OVITO from simulation data files, for example charge density fields
written by DFT simulation codes. See the list of :ref:`supported input formats <file_formats.input>` of OVITO to find out which
formats can store volumetric data.

Alternatively, voxel grids can be dynamically generated by OVITO from other forms of data.
The :ref:`particles.modifiers.bin_and_reduce` modifier, for example, projects the particles onto a structured grid to produce a
coarse-grained field representation of some particle property.

Two- and three-dimensional grids
""""""""""""""""""""""""""""""""

A voxel grid is associated with a :ref:`simulation cell <scene_objects.simulation_cell>`, i.e., a **domain** defining the spatial
extent of the grid in 3d space. OVITO supports two- and three-dimensional grids, with and without periodic boundary conditions:

.. figure:: /images/scene_objects/voxel_grid_2d.*
  :figwidth: 40%

  A two-dimensional voxel grid made of :math:`n_x \times n_y` cells. Note that the two edge vectors spanning the grid's domain
  are always embedded in three-dimensional space.

.. figure:: /images/scene_objects/voxel_grid_3d.*
  :figwidth: 40%

  A three-dimensional voxel grid made of :math:`n_x \times n_y \times n_z` cells. The three edge vectors
  spanning the grid's domain can be arbitrary, non-colinear directions in 3d space.

Cell-based and vertex-based data
""""""""""""""""""""""""""""""""

In OVITO, voxel grids can be either **cell-based** or **vertex-based**. In a cell-based grid, each voxel cell is
associated with a field value. In a vertex-based grid, each intersection point is associated with a field value:

.. figure:: /images/scene_objects/grid_cell_based.png
  :figwidth: 21%

  Cell-based grid

.. figure:: /images/scene_objects/grid_vertex_based.png
  :figwidth: 20%

  Vertex-based grid

In a vertex-based grid, the number of data points along each dimension is one more than the number of voxel cells -
with the exception of directions with **periodic boundary conditions (PBCs)**, where the number of physical data points
is equal to the number of cells along that dimension. OVITO automatically supplements the grid with "ghost" data points, i.e.,
virtual copies of the field values at the edges of the grid, to enforce periodicity in the PBC direction.

Visualization methods
"""""""""""""""""""""

.. image:: /images/visual_elements/voxel_grid_example_isosurface.png
  :width: 30%
  :align: right

.. image:: /images/visual_elements/voxel_grid_example_crosssection.png
  :width: 30%
  :align: right

OVITO offers different ways of visualizing voxel grids. The :ref:`Voxel grid <visual_elements.voxel_grid>` visual element
is the default representation automatically generated by the data pipeline to render just the outer cells of the grid (see first picture above).
Thus, this visualization style makes only the field values on the surface of the domain visible.

You can apply the :ref:`particles.modifiers.create_isosurface` modifier to compute a isosurface of the volumetric field, which is
way of visualizing the distribution of a scalar field quantity (see first picture on the right). Another way of showing the interior
values of a three-dimensional voxel grid is provided by the :ref:`particles.modifiers.slice` modifier. It lets you extract a planar
cross-section along an arbitrary direction (see last picture below).

Exporting grid data
"""""""""""""""""""

Writing the numeric data of a voxel grid to an output file is possible using OVITO's :ref:`file export <usage.export>` function.
Among the list of :ref:`supported output formats <file_formats.output>` the `VTK Voxel Grid` format can be used to produce a data file
compatible with the visualization software :program:`ParaView`.

.. seealso::

  :py:class:`ovito.data.VoxelGrid` (Python API)