Structure Visualization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This tutorial will demonstrate the use of the browser-based structure
visualization that we have developed for the Encyclopedia.

We will first setup a the visualization so that it can be accessed on a local
machine through any browser. Then we will go through the basics of how to
interact with the visualization and how to customize it. Finally we will
visualize different structures by modifying the Javascript code.

Through these tasks we hope to show that the visualization tool is suitable for
various atomic structure visualization tasks and can be easily integrated also
into third-party websites.

Setup
-----
    1. Unzip the contents of :download:`enc_viewer_tutorial.zip <files/enc_viewer_tutorial.zip>` to you local computer.
    2. Open the ``index.html`` file on a web browser of your choice.

You should already now see a default structure shown on the browser.

Interaction With the Structure
------------------------------
You can use your mouse to control the structure visualization.
    - Use mouse scroll to zoom in and out on the current center of the screen.
    - Drag with right mouse button to translate the structure on the plane
      defined by the screen.
    - Drag with left mouse button to rotate the structure with respect to the
      current screen center.

Changing the Default Visualization Settings
-------------------------------------------
In the browser you can see an orange settings panel at the top left corner.
Through it you can control the visualization settings. Through these settings
you can:

    - Define if the lattice parameters are shown.
    - Control whether the labels for the elements in the system are shown.
    - Hide and show bonds between atoms. The presence of these bonds are
      approximated from the distance and radii of different atomic pairs.
    - EXPERIMENTAL: You can also toggle the visualization of shadows within the
      structure.

Changing the Structure
----------------------
Open the ``index.html`` in a *text* editor of your choice. Inside it you will see a
``<script>`` element at the bottom. This is where the visualization is set up.

There are predefined examples that you can activate by changing the the
variable name in the "viewer.load()"-function. The examples include:

    - NaCl crystal, example of a bulk material
    - Graphene sheet, example of a 2D material
    - Carbon nanotube, example of a 1D material

After making changes, you will have to refresh the browser in order to see the
new visualization.

Technical Details
-----------------
The viewer is created with a Javascript library called three.js
(https://threejs.org/), that is used to wrap the WebGL-calls into easily
accessible Javascript objects and functions.

The WebGL-acceleration enables smooth real-time 3D rendering on the browser.
Most modern browsers support this feature, but also as a fallback we provide a
canvas-based rendering if WebGL is not available.

Using the visualizer on a third-party website is as easy as importing the
needed dependencies and creating a StructureViewer-object with a DOM-element
and the visualization data, as seen in these examples. For a more easily
accessible and centralized distribution of this viewer, a npm-based
(https://www.npmjs.com/) package can be made.