tilde-lab / cifplayer

Minimalistic and fast HTML5 visualization of chemical structures in CIF, POSCAR, and OPTIMADE formats

HTML5 CIF player

In-browser ultra-fast and lightweight renderer of the crystallographic information files (CIF), OPTIMADE JSON, and VASP POSCAR atomic structures, written in a pure JavaScript.

In a compiled form it is only one standalone embeddable file web.js of 300 Kb (gzipped). See it online. Only a web-browser is required. After the code is loaded, no internet connection is needed.

Technical details

This app is written in the $mol framework and employs three.js for 3d-rendering and tween.js for phonon animation. Scientific formats conversion is done with matinfio.js.

Compilation is done as follows. Note that, unlike many other frontend frameworks, $mol provides the same single environment for all its projects, under the standard namespace scheme. That is, all your $mol-based code lives inside the same directory $MOL_HOME. So if you don't have $MOL_HOME yet, please create it and navigate there:

mkdir $MOL_HOME && cd $MOL_HOME

Then build with

npm exec mam optimade/cifplayer/player

This will fetch the MAM server (MAM stands for the $mol abstract modules), clone this project, and compile it inside optimade/cifplayer/player/-/ subfolder. You will need the web.js bundle, that's it.

Development is similar to above: inside the $MOL_HOME, start the MAM dev-server with

npm exec mam

and navigate to http://localhost:9080, there select optimade namespace, then cifplayer, then app. As you go through the folder structure, the selected project is being cloned and compiled on the fly, inside the corresponding subfolder of $MOL_HOME.

Integration with the other software

The compiled bundle web.js defines a web-component optimade-cifplayer-player. It can be controlled in a standard way with e.g.

const player = document.getElementsByTagName('optimade-cifplayer-player')[0].view;
player.data(structure);

Or in another $mol application natively, using a tree markup:

    <= Your_block_name $optimade_cifplayer_player
        data <= your_data_string null

Comparison with the other open-source plugin-free engines

See a detailed comparison as well as the blog post, written in 2015. As of now, it is unfortunately severely outdated.

License

cifplayer's Issues

Multiple atoms should not coincide (fall into each other) given the same positions

Here's one example, so we need some position coordinates tolerance, controlling if the atom should be rendered in the proximity of another. On the other hand, this should not break the partial occupancy concept (different types of atoms at the same place), so the above applies strictly to the same atom types. That is, even if some attribute (like charge) is different, then we allow coinciding (and re-calculate the label).

Using *matinfio* in server environment

According to Dmitriy's message in our internal chat, seems to be easy, however still a concrete example would be very much appreciated.

Window resize doesn't work properly

Clean URLs with $mol

This seems to be very non-trivial w.r.t. https://mol.hyoo.ru/#!section=docs/=4jpjgg_1ofop4 however still very much desirable as a cutting-edge technology.

Related to mpds-io/visavis#18

Embedding flaws and color theme setting

As seen in https://jsfiddle.net/etvp39sL/

zooming and expanding controls are outside of the widget + no way to set the light (white) color theme.

Phonons should be populated for all the translated or symmetry-recreated atoms

a phonon is a collective quantum of movement

The minimum Optimade example does not work

{"attributes":{"immutable_id":"x","species":[{"chemical_symbols":["Au"]}],"cartesian_site_positions":[[0,0,0]],"lattice_vectors":[[0,2,2],[2,0,2],[2,2,0]]}}

Phonon visualization with tween.js temporarily dropped

Idea: sharing the renders via (pseudo?-)persistent URL

The main limitation is the URL length, which might be not enough for some huge protein molecules (> 1000 atoms + custom atomic properties).

WebGL <-> Canvas switcher issue

Doesn't consider drag'n'drop --- this is especially valid, if data loading URL changes.

Atoms are neither translated nor recreated by symmetry

*Choose file* filepicker does not work

comparing an old and new versions

CIF without the cell translation block is not accepted

data_image0
_chemical_formula_structural       Cu13C2H3SiCH3CH3CH3
_chemical_formula_sum              "Cu13 C5 H12 Si1"
loop_
  _atom_site_type_symbol
  _atom_site_label
  _atom_site_symmetry_multiplicity
  _atom_site_Cartn_x
  _atom_site_Cartn_y
  _atom_site_Cartn_z
  _atom_site_occupancy
  Cu  Cu1       1.0  -2.94433  -0.80816  -13.10687  1.0000
  Cu  Cu2       1.0  -1.44585  -0.86013  -11.15329  1.0000
  Cu  Cu3       1.0  -2.82502  1.18948  -11.51586  1.0000
  Cu  Cu4       1.0  -1.29643  1.15248  -9.59309  1.0000
  Cu  Cu5       1.0  -2.70266  3.18792  -9.92604  1.0000
  Cu  Cu6       1.0  -0.41576  -0.67646  -13.46114  1.0000
  Cu  Cu7       1.0  1.11555  -0.65642  -11.55574  1.0000
  Cu  Cu8       1.0  -0.29502  1.31977  -11.87099  1.0000
  Cu  Cu9       1.0  1.24215  1.33229  -9.98270  1.0000
  Cu  Cu10      1.0  -0.17432  3.31683  -10.28173  1.0000
  Cu  Cu11      1.0  2.11309  -0.54894  -13.81632  1.0000
  Cu  Cu12      1.0  2.23512  1.44929  -12.22534  1.0000
  Cu  Cu13      1.0  2.35416  3.44726  -10.63467  1.0000
  C   C1        1.0  -1.13470  -1.91411  -9.15128  1.0000
  C   C2        1.0  -0.39000  -1.09033  -8.38364  1.0000
  H   H1        1.0  -0.92703  -0.35334  -7.79134  1.0000
  H   H2        1.0  -2.21677  -1.87006  -9.15870  1.0000
  H   H3        1.0  -0.69429  -2.72110  -9.72433  1.0000
  Si  Si1       1.0  1.48876  -1.19305  -8.11693  1.0000
  C   C3        1.0  2.36171  -2.20822  -9.45311  1.0000
  H   H4        1.0  2.11571  -1.83431  -10.45254  1.0000
  H   H5        1.0  3.44482  -2.14003  -9.36290  1.0000
  H   H6        1.0  2.08574  -3.26142  -9.42279  1.0000
  C   C4        1.0  2.31094  0.41998  -7.57307  1.0000
  H   H7        1.0  1.98398  0.73113  -6.58209  1.0000
  H   H8        1.0  3.39758  0.36529  -7.57785  1.0000
  H   H9        1.0  2.04820  1.23875  -8.25357  1.0000
  C   C5        1.0  1.70533  -2.20156  -6.53333  1.0000
  H   H10       1.0  1.30571  -3.20785  -6.65254  1.0000
  H   H11       1.0  2.75993  -2.28755  -6.27143  1.0000
  H   H12       1.0  1.19003  -1.73457  -5.69466  1.0000

Symmetry icon should only be displayed if symmetry info is present, otherwise not shown

Suggested code for https://github.com/tilde-lab/cifplayer/blob/master/player/player.view.web.ts#L469 does not work, symmetry icon is never shown, even for those structures which actually do contain symmetry.

if( !this.structure_3d_data().cell_matrix ) return []

return [
  this.Info(), 
  ... this.symlabel() ? [ this.Symlabel() ] : [],
  this.Center(),
]

Introduce a set of unit, functional, and integration tests to make sure everything works as expected

as proposed by @nin-jin

Optional support of WebGL, where possible (?)

Cell translations in x, y, z according to a matrix

Periodic cell translations are normally done according to a matrix e.g. [[1, 0, 0], [0, 1, 0], [0, 0, 2]] expands a cell twice into vertical direction. Here a matrix determinant shows how much the volume is expanded.

(However this may expand the number of atoms drastically for bigger cells, so we have to define a reasonable limit, e.g. no more than 10x expansion, otherwise our rendering will burn out.)

Could we avoid parsing the incoming data without the real need?

cifplayer/src/js/app/main.js

Line 558 in dac4ed2

target_data = JSON.parse(event.data); // do we receive a JSON-object or a JSON-string?

Cannot switch off WebGL if switched on for a not supported device

Only cookie cleaning, which is not a solution...

Multi-touch bug in Three.js r72

Background color switcher

*unvibrate()* causes uncaught promise

calling web_component.unvibrate() results in an error warning in a console:

Uncaught Promise { <state>: "pending" }

However the phonon movement is stopped correctly.

CIF frames not supported

Data textarea should not word-wrap

A suggested solution for https://github.com/tilde-lab/cifplayer/blob/master/app/app.view.css.ts#L35

flex: {direction: 'row' },

as well as

Body: {
  flex: { direction: 'column' },
}

and for https://github.com/tilde-lab/cifplayer/blob/master/app/app.view.tree#L15

body / <= Body $mol_view sub /

indeed prevent word-wraping, but the initial empty textarea becomes too short (cut).

Cell angles issue

As the structure below is rendered, all the cell angles are shown as 90, however it is seen to be wrong 🤔

{"data":[{"id":"data/gnome_data/by_id.zip/data/gnome_data/by_id/f88009011b.CIF","type":"structures","attributes":{"immutable_id":null,"last_modified":null,"elements":["Ag","K","P","Se"],"nelements":4,"elements_ratios":[0.1111111111111111,0.1111111111111111,0.2222222222222222,0.5555555555555556],"chemical_formula_descriptive":"Ag4K4P8Se20","chemical_formula_reduced":"AgKP2Se5","chemical_formula_hill":null,"chemical_formula_anonymous":"A5B2CD","dimension_types":[1,1,1],"nperiodic_dimensions":3,"lattice_vectors":[[8.359451,0.0,0.0],[0.0,10.84409822,0.0],[0.0,7.048636471698659,11.832816778560865]],"cartesian_site_positions":[[5.300351703805,12.202652545688954,9.255510956022524],[3.0590992961950008,5.690082146009705,2.577305822538342],[7.238824796195,8.678334309839624,3.3391025667420906],[1.120626203805,9.214400381859035,8.493714211818773],[2.8355508575529997,11.536835616154002,3.9261167743097167],[7.0152763575530015,2.831580839695326,1.990291614970716],[1.344174642447,15.061153852003335,9.842525163590148],[5.523900142446999,6.355899075544656,7.906700004251149],[5.382976517489,8.624899935989834,10.87440595076455],[7.8521326377120015,12.169026194562672,5.456253810395758],[0.507318362288,5.723708497135987,6.376562968165108],[7.156199982511,5.100581700140505,4.957997561484117],[2.976474482511,9.267834755708822,0.9584108277963158],[1.203251017489,12.792152991558154,6.874819217076748],[4.687043862287999,15.693344430412001,11.37266219967619],[3.672407137712,2.1993902612866574,0.4601545788846749],[5.755774594285,7.009337237489533,0.4433401462423399],[4.585418016481001,8.67154886470268,8.856898857203143],[1.187635563021,8.04890301785488,0.6345347997503263],[3.9634497837280005,15.44456444105876,9.310640049393838],[1.576049094285,7.359079218359796,5.473068243038093],[2.9920899369790006,11.57322125370421,6.550943189030759],[2.603676405715,10.883397454209124,11.389476632318525],[8.143175283728,5.9724884864892305,8.43858511844746],[6.161885083316,17.439125340978038,11.67622128131339],[1.982159583316,3.9779275865699493,6.073003886527906],[7.171815436979,9.843831673843777,11.198281978810538],[6.377291416684,13.914807105128709,5.759812892032958],[0.40569251648099997,12.745504062845308,8.892326310638154],[0.21627571627199998,11.920246205209429,3.3942316601134057],[5.367361063021,6.319513437994448,5.2818735895301065],[3.774032983519,9.221185826995976,2.975917921357722],[7.953758483519,5.147230628853352,2.940490467922711],[4.396001216272,2.448170250639901,2.522176729167027],[2.1975659166840007,0.4536093507206201,0.15659549724747449],[6.783401905715001,10.533655473338863,6.3597485355227725]],"nsites":36,"species":[{"name":"Se","chemical_symbols":["Se"],"concentration":[1.0],"mass":null,"original_name":null,"attached":null,"nattached":null},{"name":"P","chemical_symbols":["P"],"concentration":[1.0],"mass":null,"original_name":null,"attached":null,"nattached":null},{"name":"K","chemical_symbols":["K"],"concentration":[1.0],"mass":null,"original_name":null,"attached":null,"nattached":null},{"name":"Ag","chemical_symbols":["Ag"],"concentration":[1.0],"mass":null,"original_name":null,"attached":null,"nattached":null}],"species_at_sites":["K","K","K","K","Ag","Ag","Ag","Ag","P","P","P","P","P","P","P","P","Se","Se","Se","Se","Se","Se","Se","Se","Se","Se","Se","Se","Se","Se","Se","Se","Se","Se","Se","Se"],"assemblies":null,"structure_features":[],"_gnome_decomposition_energy_per_atom":-0.0132,"_gnome_material_id":"f88009011b","_gnome_formation_energy_per_atom":-0.6173}}],"meta":{"query":{"representation":"/structures?filter=chemical_formula_reduced=%22AgKP2Se5%22"},"api_version":"1.1.0","more_data_available":false,"schema":"https://schemas.optimade.org/openapi/v1.1.0/optimade.json","time_stamp":"2024-06-14T13:54:35Z","data_returned":1,"provider":{"name":"Gnome","description":"An unoffiical OPTIMADE API for the Gnome dataset from Google Deepmind (CC-BY NC). Full terms of use can be found on the project homepage.","prefix":"gnome","homepage":"https://github.com/google-deepmind/materials_discovery"},"data_available":384938,"implementation":{"name":"optimade-python-tools (modified for odbx.science)","version":"0.1","source_url":"https://github.com/ml-evs/odbx.science","maintainer":{"email":"[email protected]"},"issue_tracker":"https://github.com/ml-evs/odbx.science/issues"}},"included":[],"links":{"next":null}}

Orbiting directions are wrong

The rotation of the structure (orbiting) works strangely:

• left-right correctly rotates the axis and atom positions, though the spheres representing atoms turn the other way
• up-down rotation is flipped
• rotation around z axis is flipped

NS_ERROR_FAILURE in Firefox

Occurs while iframe integration

Right-click default browser behaviour must be prevented

Especially gestures

CIF tag _atom_site_occupancy not supported

Absolidix integration

A small green triangle icon in the bottom-right corner uploads the structure to https://absolidix.com