Structure Viewer¶

Try out the interactive visualizer below. Controls are as follows:

Rotate: Drag with left mouse button held down

Pan: Drag with right mouse button held down

Zoom: Mousewheel

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.

// Find the element in which the visualizer will be embedded into. It
// determines the visualization canvas size.
let canvas = document.getElementById("canvas");

// Viewer options
let options = {
  layout: {
    viewCenter: "COC",
    periodicity: "none",
    viewRotation: {
      align: {
          top: "c",
          right: "b",
      },
      rotations: [
          [0, 1, 0, 60],
          [1, 0, 0, 30],
      ],
    }
  },
  bonds: {
    enabled: true
  },
  cell: {
    enabled: true
  },
  latticeConstants: {
    enabled: true
  }
};

// Initialize viewer
let viewer = new materia.StructureViewer(canvas, options);

// Define structure and load into viewer
let nacl = {
    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(nacl);

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.

Options¶

The options that are given in the constructor are passed to the StructureViewer.setOptions() method. These options are provided as a nested Javascript object. Check the API for the supported parameters. At any time you can also manually call this method to change the options. Notice that you can also use this method to only update a subset of the options.

API¶

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.<Array.<number>>) – 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.<string>|Array.<number>) – Atomic numbers or chemical symbols of the atoms.
structure.cell (Array.<number>) – The lattice vectors of the unit cell as rows of a 3x3 array.
structure.pbc (Array.<boolean>) – The periodic boundary conditions for the structure as a list of three boolean values for each lattice vector direction.
structure.bonds (Array.<Array.<number>>) – 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.

StructureViewer.setOptions(options, render)¶

Used to setup the visualization options.

Arguments

options (boolean) – A Javascript object containing the options. See below for the subparameters.
options.layout.periodicity (string|Array.<number>) – How periodicity is handled in the visualization. Available options are: - “none”: Visualized as is. - “wrap”: Positions wrapped within unit cell. - “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.
options.layout.translation (Array.<number>) – A fixed cartesian translation to be applied to the atoms.
options.layout.viewCenter (string) – Determines how the view is initially centered. Available options are: - “COC”: Center of cell. - “COP”: Center of atom positions.
options.layout.viewRotation.align.top (string) – Optional alignment indicating which lattice basis vector should point upwards. Possible values are: “a”, “b”, “c”, “-a”, “-b”, “-c”.
options.layout.viewRotation.align.right (string) – Optional alignment indicating which lattice basis vector should point to the right (more precisely: the cross-product of options.layout.viewRotation.align.top and options.layout.viewRotation.align.right will point away from the screen.). Possible values are: “a”, “b”, “c”, “-a”, “-b”, “-c”.
options.layout.viewRotation.align.rotations (Array.<Array.<number>>) – Optional rotations that are applied after the alignment has been done (see options.layout.viewRotation.align). The rotations are given as a list of 4-element arrays containing the rotations axis and rotation angle in degrees. 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.
options.latticeConstants.enabled (boolean) – Show lattice parameters
options.latticeConstants.font (string) – Font size for lattice constants. Applied as default to all labels, can be overridden individually for each lattice constant.
options.latticeConstants.color (string) – Font color for lattice constants. Applied as default to all labels, can be overridden individually for each lattice constant.
options.latticeConstants.stroke.color (string) – Font stroke color for lattice constants. Applied as default to all labels, can be overridden individually for each lattice constant.
options.latticeConstants.stroke.width (string) – Font stroke width for lattice constants. Applied as default to all labels, can be overridden individually for each lattice constant.
options.latticeConstants.a.color (string) – Font color
options.latticeConstants.a.font (string) – Font family
options.latticeConstants.a.size (number) – Font size
options.latticeConstants.a.stroke.width (number) – Font stroke width
options.latticeConstants.a.stroke.color (string) – Font stroke color
options.latticeConstants.b.color (string) – Font color
options.latticeConstants.b.font (string) – Font family
options.latticeConstants.b.size (number) – Font size
options.latticeConstants.b.stroke.width (number) – Font stroke width
options.latticeConstants.b.stroke.color (string) – Font stroke color
options.latticeConstants.c.color (string) – Font color
options.latticeConstants.c.font (string) – Font family
options.latticeConstants.c.size (number) – Font size
options.latticeConstants.c.stroke.width (number) – Font stroke width
options.latticeConstants.c.stroke.color (string) – Font stroke color
options.latticeConstants.alpha.color (string) – Font color
options.latticeConstants.alpha.font (string) – Font family
options.latticeConstants.alpha.size (number) – Font size
options.latticeConstants.alpha.stroke.width (number) – Font stroke width
options.latticeConstants.alpha.stroke.color (string) – Font stroke color
options.latticeConstants.beta.color (string) – Font color
options.latticeConstants.beta.font (string) – Font family
options.latticeConstants.beta.size (number) – Font size
options.latticeConstants.beta.stroke.width (number) – Font stroke width
options.latticeConstants.beta.stroke.color (string) – Font stroke color
options.latticeConstants.gamma.color (string) – Font color
options.latticeConstants.gamma.font (string) – Font family
options.latticeConstants.gamma.size (number) – Font size
options.latticeConstants.gamma.stroke.width (number) – Font stroke width
options.latticeConstants.gamma.stroke.color (string) – Font stroke color
options.outline.enabled (boolean) – Used to enable or disable a fixed color outline around atoms and bonds. Notice that enabling the outline incurs a performance penalty.
options.outline.color (string) – Outline color.
options.outline.size (number) – Outline size.
options.cell.enabled (boolean) – Show unit cell wireframe.
options.cell.color (boolean) – Unit cell wireframe color.
options.cell.linewidth (boolean) – Unit cell wireframe line width.
options.cell.dashSize (boolean) – Unit cell wireframe dash size. Provide a value > 0 for a dashed line.
options.cell.gapSize (boolean) – Unit cell wireframe dash size. Provide a value > 0 for a dashed line.
options.bonds.enabled (boolean) – Show bonds.
options.bonds.color (string) – Color of bonds.
options.bonds.radius (number) – Bond radius.
options.bonds.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.bonds.material.phong.shininess (number) – Shininess of the bond material (for phong material)
options.bonds.material.toon.tones (number) – Tone-steps for toon material.
options.bonds.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 <= this.options.bonds.threshold * 1.1 * (radius1 + radius2)
options.atoms.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.atoms.material.phong.shininess (number) – Shininess of the atom material (for phong material)
options.atoms.material.toon.tones (number) – Tone-steps for toon material
options.atoms.radii (string|Array.<number>) – The radii to use for atoms. Defaults to covalent radii. Available options are: - “covalent”: Covalent radii from DOI:10.1039/B801115J. - Custom list of atomic radii. Provide an array of floating point numbers where the index corresponds to an atomic number.
options.atoms.colors (string|Array.<string>) – The colors to use for atoms. Available options are: - “Jmol” (default): Jmol colors. - Custom list of colors. Provide an array of hexadecimal colors where the index corresponds to an atomic number.
options.atoms.scale (number) – Scaling factor for the atomic radii.
options.renderer.background.color (string) – Color of the background.
options.renderer.background.opacity (number) – Opacity of the background.
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.
render (boolean) – Whether to perform a render after setting the options. Defaults to true. You should only disable this setting if you plan to do a render manually afterwards.