add guiConfig to specify their GUI preferences (#27)

This PR adds a `guiConfig` to specify their GUI preferences, such as enabling/disabling the GUI entirely or choosing specific components to display.

docs/source/gui.rst

@@ -0,0 +1,125 @@
+==================
+GUI controls
+==================
+
+.. figure:: _static/images/gui-controls.png
+   :width: 80%
+   :align: right
+
+
+The graphical user-interface (GUI) allows users to set up and control the visualization of the atomic structure. It has the following components:
+
+- Fix GUI:
+   - Main controls (top left)
+   - Buttons (top right)
+- Dynamic GUI:
+   - Adjust last operation (bottom left)
+   - Timebar for animations (bottom middle)
+
+Main Controls
+==============
+One can open the control panel by clicking the `open controls` button on the top left. It has the following settings:
+
+Model style
+----------------
+
+Here, four models are supported.
+
+.. list-table::
+   :widths: 25 25 25 25
+
+   * - **Ball**
+     - **Ball-and-stick**
+     - **Polyhedral**
+     - **Stick**
+   * -  .. image:: _static/images/model_style_0.png
+     -  .. image:: _static/images/model_style_1.png
+     -  .. image:: _static/images/model_style_2.png
+     -  .. image:: _static/images/model_style_3.png
+
+
+.. tip::
+
+   The Model Style setting applies exclusively to selected atoms. If no atoms are selected, it will apply to all atoms in the model.
+
+
+Color style
+----------------
+Supported style are:
+
+
+#. **JMOL**: http://jmol.sourceforge.net/jscolors/#color_U
+#. **VESTA**: https://jp-minerals.org/vesta/en/
+#. **CPK**: https://en.wikipedia.org/wiki/CPK_coloring
+
+
+Label
+----------------
+One can add label for each atoms.
+
+You can input string like:
+
+- `symbol`
+- `index`
+
+Here is a example of a molecule with `index` label:
+
+.. image:: _static/images/example_label_index.png
+   :width: 60%
+
+
+Other parameters:
+----------------
+
+- **Atom Scale**: change scale for all atoms.
+- **Unit Cell**: show or hide the unit cell.
+- **Bonded Atoms**: show or hide the bonded atoms outside the unit cell.
+- **Replace Atom**: replace the selected atom with another atom.
+- **Add Atom**: add a new atom to the structure.
+- **Boundary**: show atoms inside the boundary, making a supercell.
+
+
+Buttons
+-------
+There are several buttons on the top right of the GUI. They are:
+
+.. figure:: _static/images/gui-buttons.png
+   :width: 40%
+   :align: center
+
+- **Fullscreen**: enter or exit fullscreen mode.
+- **Undo**: undo the last operation.
+- **Redo**: redo the last operation.
+- **Download**: download the current structure as a .cif file.
+- **Measurement**: measure the distance between two atoms.
+
+
+Configuration
+===================
+One can use a configuration dict to specify their GUI preferences, such as enabling/disabling the GUI entirely or choosing specific components to display.
+
+Disable the GUI entirely
+~~~~~~~~~~~~~~~~~~~~~~~~
+.. code-block:: python
+
+   from weas_widget import WeasWidget
+   viewer = WeasWidget(guiConfig={"enabled": False})
+   viewer
+
+
+Select specific components
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from weas_widget import WeasWidget
+   guiConfig={"enabled": True,
+              "components": {"atomsControl": True,
+                             "buttons": True},
+              "buttons": {"fullscreen": True,
+                          "download": True,
+                          "measurement": True,
+                          }
+            }
+   viewer = WeasWidget(guiConfig=guiConfig)
+   viewer

docs/source/index.rst

@@ -4,6 +4,12 @@ Welcome to WEAS Widget's documentation!
 A widget to visualize and interact with atomistic structures in Jupyter Notebook. It uses WEAS_ (Web Environment For Atomistic Structure) in the backend.
 
 
+.. note::
+
+   If you encounter any problems, please update the widget to the latest version. If the problem persists, please report it on the `GitHub issue <https://github.com/superstar54/weas-widget/issues>`_
+
+
+
 .. figure:: _static/images/example-adsorption.gif
    :alt: Edit the structure
    :align: center
@@ -16,6 +22,7 @@ A widget to visualize and interact with atomistic structures in Jupyter Notebook
    quick_start
    installation
    edit
+   gui
    operation
    boundary
    measurement

docs/source/isosurface.rst

@@ -34,6 +34,6 @@ For the ``isoSetting``:
    - mode=other: Only the given isosurface is drawn.
 
 
-.. tips::
+.. tip::
 
    Support for multiple isosurfaces with individual properties (isovalue and color).

weas_widget/__init__.py

@@ -33,6 +33,7 @@ class WeasWidget(anywidget.AnyWidget):
     _imageFileName = tl.Unicode("atomistic-model.png").tag(sync=True)
     vectorField = tl.List().tag(sync=True)
     showVectorField = tl.Bool(True).tag(sync=True)
+    guiConfig = tl.Dict({}).tag(sync=True)
 
     def drawModels(self):
         """Redraw the widget."""

weas_widget/index.js

@@ -17,7 +17,8 @@ export function render({ model, el }) {
             atoms = new weas.Atoms(atomsData);
         }
         // console.log("atoms: ", atoms);
-        avr = new weas.AtomsViewer(viewerElement, atoms);
+        const guiConfig = model.get("guiConfig");
+        avr = new weas.AtomsViewer(viewerElement, atoms, guiConfig);
         avr.modelStyle = model.get("modelStyle");
         avr.colorType = model.get("colorType");
         avr.materialType = model.get("materialType");