Brillouin Zone 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

  • 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 BrillouinZoneViewer constructor call.

// Initialize viewer
const canvas = document.getElementById("canvas");
const viewer = new materia.BrillouinZoneViewer(canvas);

// Define structure and load into viewer
let reciprocal = {
  basis: [
    [-0.15735, 0.15735, 0.15735],
    [0.15735, -0.15735, 0.15735],
    [0.15735, 0.15735, -0.15735]
  ],
  segments: [
    [
      [0, 0, 0],
      [0.5, 0, 0.5],
      [0.5, 0.25, 0.75],
      [0.375, 0.375, 0.75],
      [0, 0, 0],
      [0.5, 0.5, 0.5],
      [0.625, 0.25, 0.625],
      [0.5, 0.25, 0.75],
      [0.5, 0.5, 0.5],
      [0.375, 0.375, 0.75]
    ],
    [
      [0.625, 0.25, 0.625],
      [0.5, 0, 0.5]
    ]
  ],
  kpoints: [
    ["A", [0.0, 0.0, 0.0]],
    ["B", [0.5, 0.0, 0.5]],
    ["C", [0.5, 0.25, 0.75]],
    ["D", [0.375, 0.375, 0.75]],
    ["E", [0.5, 0.5, 0.5]],
    ["F", [0.625, 0.25, 0.625]],
  ]
}
viewer.load(reciprocal)

// Setup viewer initial state
viewer.align([
  ["up", "a"],
  ["front", "segments"]
])
viewer.rotate([
  [0, 1, 0, 45],
  [1, 0, 0, 25],
])
viewer.fit(0.075)
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 a structure using the BrillouinZoneViewer.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 BrillouinZoneViewer() 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 structure to the viewer by calling the BrillouinZoneViewer.load() method. Check the API for the supported parameters. Notice that this method will only create the internal representation 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 BrillouinZoneViewer(hostElement, options)
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.

BrillouinZoneViewer.load(data, options)

Used to create a visualization for the first Brillouin Zone together with kpath and segment information.

Arguments

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

  • data.basis (Array.) – The basis vectors of the reciprocal cell as rows of a 3x3 array.

  • data.segments (Array.) – List containing lists of k-points, each sublist indicating a continuous segment within the Brillouin zone.

  • data.kpoints (*()) – List of pairs of labels and reciprocal lattice coordinates for specific k-points that should be shown.

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

  • options.segments.color (string()) – Segment color

  • options.segments.linewidth (number()) – Segment linewidth

  • options.faces.color (string()) – Face color

  • options.faces.opacity (number()) – Face opacity

  • options.faces.outline.color (string()) – Face outline color

  • options.faces.outline.width (number()) – Face outline width

  • options.kpoints.label.color (string()) – Label color

  • options.kpoints.label.size (number()) – Label size

  • options.kpoints.label.font (string()) – Label font

  • options.kpoints.label.offset2D (boolean()) – Offset of the labels in the sprite’s 2D coordinate system. The offset is relative to the font size and the default [0, 0] corresponds to centered labels.

  • options.kpoints.point.color (string()) – Point color

  • options.kpoints.point.size (number()) – Point size

  • options.kpoints.stroke.width (string()) – Label outline stroke width

  • options.kpoints.stroke.color (string()) – Label outline stroke color

  • options.basis.color (string()) – Font colour for basis labels. Applied as default to all labels, can be overridden individually for each basis.

  • options.basis.font (number()) – Font size for basis labels. Applied as default to all labels, can be overridden individually for each basis.

  • options.basis.offset (number()) – Offset for basis labels.

  • options.basis.stroke.width (number()) – Label outline stroke width

  • options.basis.stroke.color (string()) – Label outline stroke color

  • options.basis.a.color (string()) – Color applied to the label of the first reciprocal lattice vector.

  • options.basis.a.font (string()) – Font family applied to the label of the first reciprocal lattice vector.

  • options.basis.a.size (number()) – Font size applied to the label of the first reciprocal lattice vector.

  • options.basis.a.stroke.width (number()) – Outline stroke width applied to the label of the first reciprocal lattice vector.

  • options.basis.a.stroke.color (string()) – Outline stroke color applied to the label of the first reciprocal lattice vector.

  • options.basis.b.color (string()) – Color applied to the label of the second reciprocal lattice vector.

  • options.basis.b.font (string()) – Font family applied to the label of the second reciprocal lattice vector.

  • options.basis.b.size (number()) – Font size applied to the label of the second reciprocal lattice vector.

  • options.basis.b.stroke.width (number()) – Outline stroke width applied to the label of the second reciprocal lattice vector.

  • options.basis.b.stroke.color (string()) – Outline stroke color applied to the label of the second reciprocal lattice vector.

  • options.basis.c.color (string()) – Color applied to the label of the third reciprocal lattice vector.

  • options.basis.c.font (string()) – Font family applied to the label of the third reciprocal lattice vector.

  • options.basis.c.size (number()) – Font size applied to the label of the third reciprocal lattice vector.

  • options.basis.c.stroke.width (number()) – Outline stroke width applied to the label of the third reciprocal lattice vector.

  • options.basis.c.stroke.color (string()) – Outline stroke color applied to the label of the third reciprocal lattice vector.

BrillouinZoneViewer.fit(margin=0)

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

  • margin (number()) – Margin to apply.

BrillouinZoneViewer.align(alignments)

Used to rotate the contents based of the alignment of the basis cell vectors or the segments with respect to the cartesian axes.

Arguments

  • alignments – List of up to two alignments for any two axis vectors. E.g. [[“up”, “c”], [“right”, “segments”]] will force the third basis vector to point exactly up, and the segments to as close to right as possible. The alignments 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.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.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.