.. _scene_objects.voxel_grid:

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

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

A voxel grid is a data object storing a structured grid of uniform cells, each associated with one or more numeric values.
A voxel grid is typically used for the discretized representation of a field quantity. 

Voxel grids can be imported into OVITO from simulation data files, for example charge density fields
output by DFT simulation codes. See the list of :ref:`supported input formats <file_formats.input>` of OVITO. 
Additionally, voxel grids can be dynamically generated within OVITO, for example using the :ref:`particles.modifiers.bin_and_reduce` modifier,
which maps per-particle quantities onto the voxel cells of a structured grid.

Similar to particles, the cells of a voxel grid may be associated with an arbitrary number of properties. 
A property can be a scalar field value, e.g. the local charge density, or a more complex vectorial quantity such as the magnetic moment
vector. The special property ``Color`` determines the rendering color of each individual grid cell.
You can set it with the :ref:`particles.modifiers.color_coding` modifier, for example.
Additional properties may be assigned to the cells of a voxel grid using the :ref:`particles.modifiers.compute_property` modifier 
of OVITO. 

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

There are different ways to visualize a voxel grid in OVITO. The :ref:`Voxel grid <visual_elements.voxel_grid>` visual element
is the default representation automatically generated by the data pipeline, which renders only the outer surfaces of the grid (see first picture).
Thus, it will only visualize the field values on the boundaries of the domain.
Another possibility is to apply the :ref:`particles.modifiers.create_isosurface`
modifier and let it compute a isosurface of the field, which is another way of visualizing the distribution 
of a scalar field quantity (see second picture).

Exporting a voxel grid to an output file is is possible using OVITO's :ref:`file export <usage.export>` function.
Pick the output format `VTK Voxel Grid`, for example.

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