Structure Viewer

Try out the interactive visualizer below. Default controls are as follows:

  • Rotate: Drag with left mouse button held down

  • Pan: Drag with right mouse button held down

  • Zoom: Mousewheel

  • Reset: Double click

Example

This piece of Javascript code shows an example of loading the viewer into a an HTML element that has been given the id canvas. This example assumes that the global variable installation has been used, but it can be very simply changed to also work with the module installation by adding the proper imports and changing the StructureViewer constructor call.

// Initialize viewer
let targetElem = document.getElementById("canvas")
var viewer = new materia.StructureViewer(targetElem)

// Define structure and load into viewer
let structure = {
    species: [11, 17, 11, 17, 11, 17, 11, 17],
    cell: [
        [5.6402, 0.0, 0.0],
        [0.0, 5.6402, 0.0],
        [0.0, 0.0, 5.6402]
    ],
    positions: [
        [0.0, 0.5, 0.0],
        [0.0, 0.5, 0.5],
        [0.0, 0.0, 0.5],
        [0.0, 0.0, 0.0],
        [0.5, 0.5, 0.5],
        [0.5, 0.5, 0.0],
        [0.5, 0.0, 0.0],
        [0.5, 0.0, 0.5]
    ],
    fractional: true,
    pbc: [true, true, true],
};
viewer.load(structure)

// Setup viewer initial state
viewer.align([
  ["up", "c"],
  ["right", "b"],
])
viewer.rotate([
    [0, 1, 0, 60],
    [1, 0, 0, 30],
])
viewer.atoms()
viewer.bonds()
viewer.cell()
viewer.latticeConstants()
viewer.center('COC')
viewer.fit('full', 0.5)
viewer.controls()

// Render final result
viewer.render()

Overview

The general workflow for producing a visualization is as follows:

  • Create an instance of the viewer, which is at some point attached to an HTML element.

  • Load an atomic structure using the StructureViewer.load()-method.

  • Modify the initial view using the functions documented in the API, this may contain e.g. translations, rotations, centerings, fits, zooming etc.

  • Render the result on the HTML host element at any point using the Viewer.render() method.

  • Do any modifications dynamically according to your applications state, do not forget to render when you want the result to be displayed.

Constructor

In the constructor StructureViewer() you can define the host element (this can also be changed at any point using the Viewer.changeHostElement() method) together with a set of default options that control the rendering.

Loading a structure

You can load a new atomic structure to the viewer by calling the StructureViewer.load() method. Check the API for the supported parameters. Notice that this method will simply create the atomic positions for the given structure, and will not yet display anything. See Configuration and Render for more information on how to display the structure.

Configuration

You can dynamically alter the visualization at any point by chaining the provided functions calls. Check out the API for the supported functions. Notice that all of these functions will change the visualization state internally, but will not yet render the result on screen, see Render on how to produce the final result.

Render

You can control when the structure gets rendered on screen by manually calling the Viewer.render() method. This way you can modify any number of options without any screen flickering by only calling render when you are finished.

Tips

  • If you are not seeing your changes updated on the screen, or they are updated only after interacting with the structure, double check that you have called Viewer.render() after your changes.

  • If the interactive controls are not working, remember that you have to set them up by calling Viewer.controls().

  • When the HTML element containing the canvas change size, you may want to refit the canvas to it using Viewer.fitCanvas().

  • You can change the visualization canvas at any point by calling Viewer.changeHostElement(). Remember to refit the canvas after this with Viewer.fitCanvas().

API

class StructureViewer(hostElement, options)

Class for visualizing an atomic structure.

Arguments

  • hostElement (any()) – is the html element where the visualization canvas will be appended.

  • options (Object()) – An object that can hold custom settings for the viewer.

  • options.renderer.pixelRatioScale (string()) – Scaling factor for the pixel ratio. Defaults to 1.

  • options.renderer.antialias.enabled (string()) – Whether antialiasing is enabled. Defaults to true.

  • options.renderer.background.color (string()) – Color of the background. Defaults to “#fff”.

  • options.renderer.background.opacity (number()) – Opacity of the background. Defaults to 0.

  • options.renderer.shadows.enabled (boolean()) – Whether shows are cast by atoms onto others. Note that enabling this increases the computational cost for doing the visualization. Defaults to false

  • options.controls (Object()) – Default options for the controls-function. See the function for more information.

  • options.atoms (Object()) – Default options for the atoms-function. See the function for more information.

  • options.bonds (Object()) – Default options for the bonds-function. See the function for more information.

  • options.cell (Object()) – Default options for the cell-function. See the function for more information.

  • options.latticeConstants (Object()) – Default options for the latticeConstants-function. See the function for more information.

StructureViewer.load(structure)

Visualizes the given atomic structure.

Arguments

  • structure (object()) – A Javascript object containing the structure. See below for the subparameters.

  • structure.positions (Array.) – Atomic positions. Default interpretation is as cartesian positions, but you can specify whether they are cartesial or fractional with the “fractional” attribute.

  • structure.fractional (boolean()) – Whether the given positions are fractional or not. Defaults to false if not specified.

  • structure.species (Array.) – Atomic numbers or chemical symbols of the atoms.

  • structure.cell (Array.) – The lattice vectors of the unit cell as rows of a 3x3 array.

  • structure.pbc (Array.) – The periodic boundary conditions for the structure as a list of three boolean values for each lattice vector direction. Defaults to [false, false, false].

  • structure.bonds (Array.) – Optional manually set bonds. Provide a list of atomic index pairs, each pair specifying a bond between atoms. If these bonds are not specified, the visualizer will by default use an automated detection of bonds. This can be disabled through options.bonds.enabled.

  • structure.wrap.type (string()) – How atomic positions are wrapped in periodic systems. Available options are: - “none”: Visualized as is. - “boundary”: Positions that are on the cell boundaries are repeated. - [a, b, c]: Positions are repeated along each lattice vector the given amount of times. Defaults to ‘none’

  • structure.wrap.tolerance (number()) – The wrapping tolerance in angstroms. Defaults to 1e-8.

StructureViewer.atoms(options)

Creates/updates representation for the atoms based on the given list of options. Notice that you can select the targeted atoms using the include/exclude options and also provide several configurations at once using a list.

Arguments

  • options (object()) – A Javascript object, or array of objects containing the visualizaiton options. See below for the subparameters.

  • options.include (number()) – List of atomic indices to target with these options.

  • options.exclude (number()) – List of atomic indices to exclude from these options.

  • options.smoothness (number()) – A value between 0-180 that controls the number of polygons. Used as the angle between adjacent cylinder/sphere sectors that indirectly controls the number of polygons.

  • options.opacity (number()) – The opacity of the atom

  • options.material.phong.shininess (number()) – Shininess of the atom material (for phong material)

  • options.material.toon.tones (number()) – Tone-steps for toon material

  • options.radii (string|Array.) – The radius to use for the atom. Defaults to covalent radii. Available options are: - “covalent”: Covalent radius from DOI:10.1039/B801115J. - Radius in angstrom.

  • options.color (string|Array.) – The color to use. Available options are: - “Jmol” (default): Jmol color. - Hexadecimal color, e.g. ‘#ffffff’

  • options.scale (number()) – Scaling factor for the atomic radii. Used to scale the given radius.

  • options.outline.enabled (boolean()) – Used to enable or disable a fixed color outline around the atom. Notice that enabling the outline incurs a performance penalty.

  • options.outline.color (string()) – Outline color.

  • options.outline.size (number()) – Outline size.

StructureViewer.bonds(options)

Creates/updates bond representation based on the given config.

Arguments

  • options (boolean()) – A Javascript object containing the options. See below for the subparameters.

  • options.enabled (boolean()) – Show bonds. Defaults to true.

  • options.include (any()) – The atom indices to take into account when creating bonds. Either provide a array or leave undefined to include all. Defaults to undefined.

  • options.color (string()) – Color of bonds. Defaults to “#ffffff”.

  • options.radius (number()) – Bond radius. Defaults to 0.08.

  • options.smoothness (number()) – A value between 0-180 that controls the number of polygons. Used as the angle between adjacent cylinder/sphere sectors that indirectly controls the number of polygons. Defaults to 145.

  • options.material.phong.shininess (number()) – Shininess of the bond material. Defaults to 30.

  • options.threshold (number()) – Controls the automatic detection of bonds between atoms. If custom bonds have not been specified for the structure, bonds will be detected automatically with the following criteria: distance <= options.threshold * 1.1 * (radius1 + radius2)

  • options.outline.enabled (boolean()) – Used to enable or disable a fixed color outline around the bond. Notice that enabling the outline incurs a performance penalty. Defaults to true.

  • options.outline.color (string()) – Outline color. Defaults to “#000000”.

  • options.outline.size (number()) – Outline size. Defaults to 0.025.

StructureViewer.cell(options)

Returns the color for the given atomic number.

Arguments

  • options.enabled (boolean()) – Show unit cell wireframe. Defaults to true.

  • options.color (boolean()) – Unit cell wireframe color. Defaults to “#000000”.

  • options.linewidth (boolean()) – Unit cell wireframe line width. Defaults to 1.5.

  • options.dashSize (boolean()) – Unit cell wireframe dash size. Defaults to 0. Provide a value > 0 for a dashed line.

  • options.gapSize (boolean()) – Unit cell wireframe dash size. Defaults to 0. Provide a value > 0 for a dashed line.

  • options.periodicity (boolean()) – Periodicity of the cell. The non-periodic directions will be flattened. Defaults to [true, true, true].

StructureViewer.latticeConstants(options)

Visualizes the lattice constants using the given visualization options.

Arguments

  • options.enabled (boolean()) – Show lattice parameters. Defaults to true.

  • options.periodicity (boolean()) – Periodicity of the lattice. Defaults to [true, true, true]:

  • options.font (string()) – Font size for lattice constants. Defaults to 0.7. constants. Applied as default to all labels, can be overridden individually for each lattice constant.

  • options.color (string()) – Font color for lattice constants. Applied as default to all labels, can be overridden individually for each lattice constant. Defaults to

  • options.stroke.color (string()) – Font stroke color for lattice constants. Defaults to “#000”. Applied as default to all labels, can be overridden individually for each lattice constant.

  • options.stroke.width (string()) – Font stroke width for lattice constants. Defaults to “#000”. Applied as default to all labels, can be overridden individually for each lattice constant.

  • options.a.enabled (string()) – Whether to display this lattice contant. Defaults to true.

  • options.a.color (string()) – Font color. Defaults to “#C52929”.

  • options.a.font (string()) – Font family. Defaults to “Arial”.

  • options.a.size (number()) – Font size. Defaults to 0.7.

  • options.a.label (number()) – The label to display. Defaults to “a”.

  • options.a.stroke.width (number()) – Font stroke width. Defaults to 0.06.

  • options.a.stroke.color (string()) – Font stroke color. Defaults to “#000”.

  • options.b.enabled (string()) – Whether to display this lattice contant. Defaults to true.

  • options.b.color (string()) – Font color. Defaults to “#47A823”.

  • options.b.font (string()) – Font family. Defaults to “Arial”.

  • options.b.size (number()) – Font size. Defaults to 0.7.

  • options.b.label (number()) – The label to display. Defaults to “b”.

  • options.b.stroke.width (number()) – Font stroke width. Defaults to 0.06.

  • options.b.stroke.color (string()) – Font stroke color. Defaults to “#000”.

  • options.c.enabled (string()) – Whether to display this lattice contant. Defaults to true.

  • options.c.color (string()) – Font color. Defaults to “#3B5796”.

  • options.c.font (string()) – Font family. Defaults to “Arial”.

  • options.c.size (number()) – Font size. Defaults to 0.7.

  • options.c.label (number()) – The label to display. Defaults to “c”.

  • options.c.stroke.width (number()) – Font stroke width. Defaults to 0.06.

  • options.c.stroke.color (string()) – Font stroke color. Defaults to “#000”.

  • options.alpha.enabled (string()) – Whether to display this lattice contant. Defaults to true.

  • options.alpha.color (string()) – Font color. Defaults to “#ffffff”.

  • options.alpha.font (string()) – Font family. Defaults to “Arial”.

  • options.alpha.size (number()) – Font size. Defaults to 0.7.

  • options.alpha.label (number()) – The label to display. Defaults to “α”.

  • options.alpha.stroke.width (number()) – Font stroke width. Defaults to 0.06.

  • options.alpha.stroke.color (string()) – Font stroke color. Defaults to “#000”.

  • options.beta.enabled (string()) – Whether to display this lattice contant. Defaults to true.

  • options.beta.color (string()) – Font color. Defaults to “#ffffff”.

  • options.beta.font (string()) – Font family. Defaults to “Arial”.

  • options.beta.size (number()) – Font size. Defaults to 0.7.

  • options.beta.label (number()) – The label to display. Defaults to “β”.

  • options.beta.stroke.width (number()) – Font stroke width. Defaults to 0.06.

  • options.beta.stroke.color (string()) – Font stroke color. Defaults to “#000”.

  • options.gamma.enabled (string()) – Whether to display this lattice contant. Defaults to true.

  • options.gamma.color (string()) – Font color. Defaults to “#ffffff”.

  • options.gamma.font (string()) – Font family. Defaults to “Arial”.

  • options.gamma.size (number()) – Font size. Defaults to 0.7.

  • options.gamma.label (number()) – The label to display. Defaults to “γ”.

  • options.gamma.stroke.width (number()) – Font stroke width. Defaults to 0.06.

  • options.gamma.stroke.color (string()) – Font stroke color. Defaults to “#000”.

StructureViewer.center(position)

Centers the visualization around a specific point.

Arguments

  • position – The position to center on. Can be one of: - ‘COP’: Center of all atom positions. - ‘COC’: Center of the cell. - Array<Number>: An array of atomic indices, the COP will be used. - Array<Array<Number>>: An array of positions, the COP will be used.

StructureViewer.fit(position, margin)

Adjust the zoom so that the contents fit on the screen. Notice that is is typically useful to center around a point of interest first.

Arguments

  • position – The positions to take into account when fitting. Can be one of: - ‘full’: Fit the full view - Array<Number>: An array of atomic indices, the COP will be used. - Array<Array<Number>>: An array of positions, the COP will be used.

  • margin (number()) – Margin to apply, given in angstroms.

StructureViewer.wrap(wrap=true)

Controls the wrapping of atoms. Notice that only cell directions with periodic boundaries will be wrapped.

Arguments

  • wrap (boolean()) – Whether to wrap or not.

StructureViewer.align(alignments)

Used to rotate the structure based of the alignment of the basis cell vectors with respect to the cartesian axes.

Arguments

  • alignments – List of up to two alignments for any two axis vectors. E.g. [[“up”, “c”], [“right”, “b”]] will force the third basis vector to point exactly up, and the second basis vector to as close to right as possible. The alignments are applied in the given order.

Viewer.translate(rotations)

Translates the objects.

Arguments

  • rotations (Array.) – The rotations as a list. Each rotation should be an array containing four numbers: [x, y, z, angle]. E.g. [[1, 0, 0, 90]] would apply a 90 degree rotation with respect to the x-coordinate. If multiple rotations are specified, they will be applied in the given order. Notice that these rotations are applied with respect to a global coordinate system, not the coordinate system of the structure. In this global coordinate system [1, 0, 0] points to the right, [0, 1, 0] points upwards and [0, 0, 1] points away from the screen. The rotations are applied in the given order.

Viewer.setTranslation(rotations)

Translates the objects.

Arguments

  • rotations (Array.) – The rotations as a list. Each rotation should be an array containing four numbers: [x, y, z, angle]. E.g. [[1, 0, 0, 90]] would apply a 90 degree rotation with respect to the x-coordinate. If multiple rotations are specified, they will be applied in the given order. Notice that these rotations are applied with respect to a global coordinate system, not the coordinate system of the structure. In this global coordinate system [1, 0, 0] points to the right, [0, 1, 0] points upwards and [0, 0, 1] points away from the screen. The rotations are applied in the given order.

Viewer.rotate(rotations)

Rotates the scenes.

Arguments

  • rotations (Array.) – The rotations as a list. Each rotation should be an array containing four numbers: [x, y, z, angle]. E.g. [[1, 0, 0, 90]] would apply a 90 degree rotation with respect to the x-coordinate. If multiple rotations are specified, they will be applied in the given order. Notice that these rotations are applied with respect to a global coordinate system, not the coordinate system of the structure. In this global coordinate system [1, 0, 0] points to the right, [0, 1, 0] points upwards and [0, 0, 1] points away from the screen. The rotations are applied in the given order.

Viewer.setRotation(rotation)

Sets the rotation of all the scenes.

Arguments

  • rotation (Array.) – The rotation as a list. Rotation should be an array containing four numbers: [x, y, z, angle]. E.g. [1, 0, 0, 90] would set a 90 degree rotation with respect to the x-coordinate.

Viewer.controls(options)

Used to setup the controls that allow interacting with the visualization with mouse.

Arguments

  • options (Object()) – An object containing the control options. See below for the subparameters.

  • options.zoom.enabled (string()) – Is zoom enabled

  • options.zoom.speed (string()) – Zoom speed

  • options.rotation.enabled (string()) – Is rotation enabled

  • options.rotation.speed (string()) – Rotation speed

  • options.pan.enabled (string()) – Is panning enabled

  • options.pan.speed (string()) – Pan speed

  • options.resetOnDoubleClick (string()) – Whether to reset the camera on double click.

Viewer.render()

Used to render all the scenes that are present. The scenes will be rendered on top of each other, so make sure that they are in the right order.

This approach is copied from http://stackoverflow.com/questions/12666570/how-to-change-the-zorder-of-object-with-threejs/12666937#12666937

Viewer.zoom(zoom)

Sets the zoom level for the visualization.

Arguments

  • zoom – The wanted zoom level as a floating point number.

Viewer.fitCanvas()

Resizes the WebGL canvas to the host element.

Viewer.resetCamera()

Used to reset the original view.

Viewer.saveCameraReset()

Used to reset the original view.

Viewer.changeHostElement(hostElement, resize=true)

Used to setup the DOM element where the viewer will be displayed.

Arguments

  • hostElement (any()) – The HTML element into which this viewer is loaded.

  • resize (boolean()) – Whether to resize the canvas to fit the new host.