diff --git a/INTERNAL.md b/INTERNAL.md index d692b66e6..2c7a3a1aa 100644 --- a/INTERNAL.md +++ b/INTERNAL.md @@ -52,22 +52,3 @@ See script source for options. Use the below regex to fix image links in WebStor / images / (\w+) / <- contains a space as the final character /images/$1/ ``` - -## Converting images to webp format - -We recommend converting screenshot images to webp format for reduced size with -better compression. - -You can install webp tool in macOS using homebrew: - -```console -brew install webp -``` - -We may batch convert PNG images to webp: - -```console -for file in $( ls *.png); do cwebp "${file}" -o "${file%*.png}.webp"; done -``` - -For more details about webp, please refer to https://developers.google.com/speed/webp diff --git a/README.md b/README.md index 0c3f53315..f4c308bc8 100644 --- a/README.md +++ b/README.md @@ -211,7 +211,7 @@ Use **ONLY RELATIVE** paths starting from the current page, not the absolute one ### Images and Animations -Images (.png, .gif) are stored inside [images](images) directory and are automatically hosted on Git LFS. +Images (.png, .webp, .gif) are stored inside [images](images) directory and are automatically hosted on Git LFS. This is an acceptable way to contribute images, as long as the size is kept small (below 1Mb each) in order to avoid exceeding Github LFS quota. > Note: Do NOT put videos inside this directory! Upload the video into your preferred online storage system such as Google Drive, DropBox, or YouTube, and share its link with us to review and put it up online. @@ -230,6 +230,20 @@ might be "copper-cu-nanoparticle-np-icosahedron-chemistry-nanomaterials-chemical thumb for whether an image title is keyword-stuffed or not is to ask: "Is this a natural way of describing the image that would actually be used in a spoken conversation?" +Preferred Image Format +The .webp format is the preferred one, due to its size-effectiveness on the web. +To convert images to .webp format, make sure you have the `webp` package installed on your system. On MacOS, it can be done using Homebrew: +```bash +brew install webp +``` + +Then convert .png images to .webp using the following command in the target folder: +```bash +for file in $( ls *.png); do cwebp "${file}" -o "${file%*.png}.webp"; done +``` + +For more details about webp, please refer to https://developers.google.com/speed/webp + #### Including Images Including an image/screenshot is done as follows, in MKDocs notation (don't use HTML tags). diff --git a/images/materials-designer/jupyterlite_dialog/jupyterlite-session-dialog.gif b/images/materials-designer/jupyterlite_dialog/jupyterlite-session-dialog.gif new file mode 100644 index 000000000..8d7fa51ee --- /dev/null +++ b/images/materials-designer/jupyterlite_dialog/jupyterlite-session-dialog.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:447cd54a3fff490c018a16b35b1f838939eb3506b3c7dc8afe364bb13a2ead4b +size 1417433 diff --git a/images/materials-designer/jupyterlite_dialog/jupyterlite-transformation-apply-transformation.webp b/images/materials-designer/jupyterlite_dialog/jupyterlite-transformation-apply-transformation.webp new file mode 100644 index 000000000..7eb37b819 Binary files /dev/null and b/images/materials-designer/jupyterlite_dialog/jupyterlite-transformation-apply-transformation.webp differ diff --git a/images/materials-designer/jupyterlite_dialog/jupyterlite-transformation-input-materials.webp b/images/materials-designer/jupyterlite_dialog/jupyterlite-transformation-input-materials.webp new file mode 100644 index 000000000..005db85cf Binary files /dev/null and b/images/materials-designer/jupyterlite_dialog/jupyterlite-transformation-input-materials.webp differ diff --git a/images/materials-designer/jupyterlite_dialog/jupyterlite-transformation-submit-results.webp b/images/materials-designer/jupyterlite_dialog/jupyterlite-transformation-submit-results.webp new file mode 100644 index 000000000..71a309e36 Binary files /dev/null and b/images/materials-designer/jupyterlite_dialog/jupyterlite-transformation-submit-results.webp differ diff --git a/images/materials-designer/jupyterlite_dialog/jupyterlite-transformation.webp b/images/materials-designer/jupyterlite_dialog/jupyterlite-transformation.webp new file mode 100644 index 000000000..7a5aa8a7d Binary files /dev/null and b/images/materials-designer/jupyterlite_dialog/jupyterlite-transformation.webp differ diff --git a/images/materials-designer/jupyterlite_dialog/open-jupyterlite-dialog.webp b/images/materials-designer/jupyterlite_dialog/open-jupyterlite-dialog.webp new file mode 100644 index 000000000..bcc4adb82 Binary files /dev/null and b/images/materials-designer/jupyterlite_dialog/open-jupyterlite-dialog.webp differ diff --git a/lang/en/docs/materials-designer/header-menu/advanced/jupyterlite-dialog.md b/lang/en/docs/materials-designer/header-menu/advanced/jupyterlite-dialog.md new file mode 100644 index 000000000..7e07ec396 --- /dev/null +++ b/lang/en/docs/materials-designer/header-menu/advanced/jupyterlite-dialog.md @@ -0,0 +1,74 @@ +# JupyterLite Transformation Dialog + +The JupyterLite Transformation Dialog enables the modification of materials using Python, Jupyter notebooks with widely used packages (e.g. numpy, pymatgen, ASE, etc.) within the [JupyterLite environment](https://github.com/jupyterlite), a lightweight implementation of JupyterLab that runs entirely in the web browser. + +## Open Dialog + +This dialog is accessible via the ["Advanced" menu](../advanced.md) option. + +![Materials Designer header with Advanced menu opened](../../../images/materials-designer/jupyterlite_dialog/open-jupyterlite-dialog.webp "Open JupyterLite Transformation Dialog") + +## JupyterLite Environment + +The Dialog facilitates access to JupyterLite Environment where materials from the main application are available. + +![JupyterLite Transformation dialog with Introduction.ipynb opened](../../../images/materials-designer/jupyterlite_dialog/jupyterlite-transformation.webp "JupyterLite Transformation Dialog") + +## Select Input Materials + +At the top of the dialog, a drop-down menu allows for the selection of materials to be transferred to the JupyterLite environment. These materials will then be available for further processing within. + +![JupyterLite Transformation dialog with materials_in dropdown opened](../../../images/materials-designer/jupyterlite_dialog/jupyterlite-transformation-input-materials.webp "Select Input Materials") + +## Apply Transformation + +To apply a transformation, open the notebook containing the desired transformation from the list provided in the Introduction.ipynb notebook. Follow the instructions within to apply the transformation to the selected materials. Typically, this process involves specifying settings for the transformation and clicking "Run All Cells." + +![JupyterLite session with Run menu opened](../../../images/materials-designer/jupyterlite_dialog/jupyterlite-transformation-apply-transformation.webp "Apply Transformation") + +### Access Materials in JupyterLite +To access materials inside the JupyterLite environment, use function from `utils.jupyterlite` module. The following code snippet demonstrates how to access the materials inside the JupyterLite environment: + +```python +from utils.jupyterlite import get_data + +get_data("materials_in", globals()) +``` + +Parameters: + +The first parameter specifies the name of the global variable (`"materials_in"`) where the received data will be stored. +The second parameter, `globals()`, ensures that the function operates correctly across both Pyodide and Python environments. It allows `get_data` to dynamically interact with the global namespace of the script. + +Data Handling: + +The materials data is initially stored in a global variable named `data_from_host`, which is updated in response to changes in material selection or the materials themselves. +In the context of the Pyodide environment, `data_from_host` becomes available after the Pyodide kernel has loaded and the extension set the data. + +### Send Materials Back to Materials Designer + +To send the materials back to the Materials Designer, use the following code snippet: + +```python +from utils.jupyterlite import send_data + +materials = [material1, material2, ...] +send_data("materials", materials) +``` + +Parameters: + +The first parameter specifies the data that is being sent, which is "materials" in case for materials, this shouldn't be changed. The second parameter is the list of materials in ESSE format. + + +## Submit Results + +In most cases the result of the transformation is a set of materials that can be passed back to the Materials Designer. They will appear in the "Materials Out" dropdown at the bottom of the dialog. Select the materials you want to pass back to the Materials Designer and click the "Submit" button to complete the transformation. + +![JupyterLite Transformation dialog with materials_out dropdown opened](../../../images/materials-designer/jupyterlite_dialog/jupyterlite-transformation-submit-results.webp "Submit Results") + +## Animation + +The following animation illustrates how to use the JupyterLite Transformation Dialog to create a matching interface between two surfaces using Zur and McGill's algorithm. + +JupyterLite Transformation Dialog Animation diff --git a/mkdocs.yml b/mkdocs.yml index b34f09f40..8da43d6df 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -445,6 +445,7 @@ nav: - "Advanced > Interpolated Set": materials-designer/header-menu/advanced/interpolated-set.md - "Advanced > Surface / Slab": materials-designer/header-menu/advanced/surface-slab.md - "Advanced > Boundary Conditions": materials-designer/header-menu/advanced/boundary-conditions.md + - "Advanced > JupyterLite Transformation": materials-designer/header-menu/advanced/jupyterlite-dialog.md - Help: materials-designer/header-menu/help.md - Sidebar: - Items List: materials-designer/sidebar-items.md