{ "cells": [ { "cell_type": "markdown", "id": "5807fb75-9084-4594-8dfc-bf0e5b1d869d", "metadata": {}, "source": [ "## Using hyperlinks in MODA and CHADA workflow diagrams" ] }, { "cell_type": "markdown", "id": "48957079-c169-4971-9646-8942147eb95d", "metadata": {}, "source": [ "Hyperlinks can be applied to text within an activity element or to the element itself. Hyperlinks can point to an exteral website (URL) or to a local file *e.g.* another diagram or image. This feature can be used to enrich activity diagrams with further information without spoiling their appearance." ] }, { "cell_type": "markdown", "id": "c5bcb543-57ea-4dae-93df-73919e609b1d", "metadata": {}, "source": [ "
\n", "\n", "#### 1. Initial diagram code WITHOUT hyperlinks" ] }, { "cell_type": "markdown", "id": "4dc6f4aa-53cb-4e7c-8e77-b4a4dc62e94f", "metadata": {}, "source": [ "
\n", "\n", "Here's the puml code for a CHADA workflow diagram for SEM with combined EBSD and EDX:\n", "\n", "```\n", "@startuml\n", "!theme MOCHADA-plasma from ../../themes\n", ":Bulk sample or thin film; <>\n", "group SEM-EBSD-EDX <>\n", " :Set up experimental geometry:\\n sample tilt (), working distance (mm),\\ndetector distance (mm); <>\n", " :Acquire electron image (SE, BSE, FSE); <>\n", " :Electron image(s); <>\n", " :Define rectangular ROI, step size,\\ndetector and indexing parameters; <>\n", " split\n", " group EBSD <>\n", " :Acquire EBSD patterns at all points in ROI; <>\n", " :EBSD pattern for each point; <>\n", " :Hough indexing (automatic); <>\n", " end group\n", " split again\n", " group EDX <>\n", " :Acquire EDX spectra at all points in ROI; <>\n", " :EDX spectrum for each point; <>\n", " :Analyse composition (automatic) //e.g.//:\\nno. counts for element 1 > x; <>\n", " end group\n", " end split\n", " :Assign phase and orientation to each point\\n(automatic); <>\n", " :Euler angles and phase ID\\nfor each point in map; <>\n", " :Analysis of orientations (user controlled); <>\n", " :Orientation maps, Pole figures\\nQuantitative measures //e.g.// grain size; <>\n", " detach\n", "end group\n", "@enduml\n", "```\n", "
\n", "\n", "Let's write this to file and run it:" ] }, { "cell_type": "code", "execution_count": 1, "id": "fc1e3a96-f498-434e-ad82-810043b7cc58", "metadata": {}, "outputs": [], "source": [ "import pathlib\n", "\n", "import mochada_kit.running as mr" ] }, { "cell_type": "markdown", "id": "796b4c1a-ead5-4957-819d-58096a1b3c38", "metadata": {}, "source": [ "
\n", "\n", "Note\n", "\n", "**Newline characters within the name of an activity element must be double escaped in a multiline Python string:** `\\\\n`\n", "\n", "(you do not have to do this if you are writing the puml code in a text editor)\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": 3, "id": "4caed0d6-0ea1-4c3c-b4f7-0cb415fe11ed", "metadata": {}, "outputs": [], "source": [ "puml_code = \"\"\"@startuml\n", "!theme MOCHADA-plasma from ../../themes\n", ":Bulk sample or thin film; <>\n", "group SEM-EBSD-EDX <>\n", " :Set up experimental geometry:\\\\n sample tilt (), working distance (mm),\\\\ndetector distance (mm); <>\n", " :Acquire electron image (SE, BSE, FSE); <>\n", " :Electron image(s); <>\n", " :Define rectangular ROI, step size,\\\\ndetector and indexing parameters; <>\n", " split\n", " group EBSD <>\n", " :Acquire EBSD patterns at all points in ROI; <>\n", " :EBSD pattern for each point; <>\n", " :Hough indexing (automatic); <>\n", " end group\n", " split again\n", " group EDX <>\n", " :Acquire EDX spectra at all points in ROI; <>\n", " :EDX spectrum for each point; <>\n", " :Analyse composition (automatic) //e.g.//:\\\\nno. counts for element 1 > x; <>\n", " end group\n", " end split\n", " :Assign phase and orientation to each point\\\\n(automatic); <>\n", " :Euler angles and phase ID\\\\nfor each point in map; <>\n", " :Analysis of orientations (user controlled); <>\n", " :Orientation maps, Pole figures\\\\nQuantitative measures //e.g.// grain size; <>\n", " detach\n", "end group\n", "@enduml\n", "\"\"\"\n", "\n", "out_file = pathlib.Path(\n", " \"../../gallery/puml_code/chada_workflow_SEM_EBSD_EDX_nested_techniques.puml\"\n", ")\n", "\n", "with open(out_file, \"w\") as handle:\n", " handle.write(puml_code)" ] }, { "cell_type": "code", "execution_count": 4, "id": "fbb7ec6e-ea9b-4b0f-8715-3f5f3b401093", "metadata": {}, "outputs": [], "source": [ "mr.run_plantuml_code(\n", " pathlib.Path(\n", " \"../../gallery/puml_code/chada_workflow_SEM_EBSD_EDX_nested_techniques.puml\"\n", " ),\n", " output_dir=pathlib.Path(\"../\"),\n", ")" ] }, { "cell_type": "markdown", "id": "22929cff-3376-4701-938b-aa3b3af3c623", "metadata": {}, "source": [ "Here's the resulting diagram (we have to use ipython display rather than Markdown to display svg files which have line breaks within elements properly):" ] }, { "cell_type": "code", "execution_count": 1, "id": "d1a4421d-663b-4f54-b8b0-ef05b4a36eca", "metadata": {}, "outputs": [], "source": [ "from IPython.display import SVG, display" ] }, { "cell_type": "code", "execution_count": 2, "id": "ccff96df-85ce-418a-b78e-f0a7840296a8", "metadata": {}, "outputs": [ { "data": { "image/svg+xml": [ "Bulk sample or thin filmSEM-EBSD-EDXSet up experimental geometry:sample tilt (°), working distance (mm),detector distance (mm)Acquire electron image (SE, BSE, FSE)Electron image(s)Define rectangular ROI, step size,detector and indexing parametersEBSDAcquire EBSD patterns at all points in ROIEBSD pattern for each pointHough indexing (automatic)EDXAcquire EDX spectra at all points in ROIEDX spectrum for each pointAnalyse composition (automatic)e.g.:no. counts for element 1 > xAssign phase and orientation to each point(automatic)Euler angles and phase IDfor each point in mapAnalysis of orientations (user controlled)Orientation maps, Pole figuresQuantitative measurese.g.grain size" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "display(SVG(filename=\"../../gallery/chada_workflow_SEM_EBSD_EDX_nested_techniques.svg\"))" ] }, { "cell_type": "markdown", "id": "fd73adb2-64a2-4b13-b746-f0579ce2e063", "metadata": {}, "source": [ "
\n", "\n", "#### 2. Adding hyperlinks" ] }, { "cell_type": "markdown", "id": "251338c9-6ed1-42e4-af00-b59031e9b391", "metadata": {}, "source": [ "We can add hyperlinks to any text element or to an element itself.\n", "\n", "Let's demonstrate this functionality by:\n", "\n", "1. linking the title of the single technique group \"EBSD\" to a local file showing the CHADA tables for EBSD (`mochada_kit/gallery/chada_tables_SEM-EBSD.svg`), and\n", "2. linking the element \"Acquire electron image (SE, BSE, FSE)\" to a local file showing the metadata for acquiring images as a json diagram (`mochada_kit/gallery/json_SEM_metadata_with_highlights.svg`)\n", "\n", "
\n", "\n", "To do this, we just need to modify two lines of the original puml source code like this:\n", "\n", "```\n", "@startuml\n", "!theme MOCHADA-plasma from ../../themes\n", ":Bulk sample or thin film; <>\n", "group SEM-EBSD-EDX <>\n", " :Set up experimental geometry:\\n sample tilt (), working distance (mm),\\ndetector distance (mm); <>\n", " [[./json_SEM_metadata_with_highlights.svg{View metadata}]]:Acquire electron image (SE, BSE, FSE); <>\n", " :Electron image(s); <>\n", " :Define rectangular ROI, step size,\\ndetector and indexing parameters; <>\n", " split\n", " group [[./chada_tables_SEM-EBSD.svg{View EBSD CHADA} EBSD]] <>\n", " :Acquire EBSD patterns at all points in ROI; <>\n", " :EBSD pattern for each point; <>\n", " :Hough indexing (automatic); <>\n", " end group\n", " split again\n", " group EDX <>\n", " :Acquire EDX spectra at all points in ROI; <>\n", " :EDX spectrum for each point; <>\n", " :Analyse composition (automatic) //e.g.//:\\nno. counts for element 1 > x; <>\n", " end group\n", " end split\n", " :Assign phase and orientation to each point\\n(automatic); <>\n", " :Euler angles and phase ID\\nfor each point in map; <>\n", " :Analysis of orientations (user controlled); <>\n", " :Orientation maps, Pole figures\\nQuantitative measures //e.g.// grain size; <>\n", " detach\n", "end group\n", "@enduml\n", "```\n" ] }, { "cell_type": "markdown", "id": "b80ab5b7-df72-4d20-a04d-514aff94dffe", "metadata": {}, "source": [ "
\n", "\n", "- In the above code, line 6 now additionally contains `[[./json_SEM_metadata_with_highlights.svg{View metadata}]]`. This is located at the beginning of the line *before* the definition of the activity element and therefore the link applies to the whole element. After the two square brackets, the hyperlink is defined. The hyperlink to a local file can be an absolute path or a relative path with respect to the location of the final diagram file (rather than the puml source code). Anything in curly braces after the link definition will appear as a tooltip when the user hovers the mouse over the element.\n", "\n", "- In line 10, the title of the group `EBSD` has been wrapped in the link definition: `[[./chada_tables_SEM-EBSD.svg{View EBSD CHADA}EBSD]]`. This means that the hyperlink applies to the text `EBSD` *i.e.* to the title of the group, rather than to the whole group element. Again we have specified a relative path to a local file, some text for the tooltip, and this time, additionally the text for the link, which will appear underlined in the diagram.\n", "\n", "- As we have used relative links, as long as the three images are in the same folder, the links will always work.\n", "\n", "- Whatever operating system we use, we specify links using posix paths *i.e.* with forward slashes.\n", "\n", "- For more information on using hyperlinks in plantuml diagrams, see [here](https://plantuml.com/link)." ] }, { "cell_type": "markdown", "id": "5c6bfb26-fc3a-46df-b1be-f1242ffc007b", "metadata": {}, "source": [ "Let's write (remembering to double escape newline characteres in multiline Python strings) and run this code to see what the diagram looks like:" ] }, { "cell_type": "code", "execution_count": 7, "id": "6805b74a-040f-4864-9e58-66fd22446d71", "metadata": {}, "outputs": [], "source": [ "puml_code = \"\"\"@startuml\n", "!theme MOCHADA-plasma from ../../themes\n", ":Bulk sample or thin film; <>\n", "group SEM-EBSD-EDX <>\n", " :Set up experimental geometry:\\\\n sample tilt (), working distance (mm),\\\\ndetector distance (mm); <>\n", " [[./json_SEM_metadata_with_highlights.svg{View metadata}]]:Acquire electron image (SE, BSE, FSE); <>\n", " :Electron image(s); <>\n", " :Define rectangular ROI, step size,\\\\ndetector and indexing parameters; <>\n", " split\n", " group \"[[./chada_tables_SEM-EBSD.svg{View EBSD CHADA} EBSD]]\" <>\n", " :Acquire EBSD patterns at all points in ROI; <>\n", " :EBSD pattern for each point; <>\n", " :Hough indexing (automatic); <>\n", " end group\n", " split again\n", " group EDX <>\n", " :Acquire EDX spectra at all points in ROI; <>\n", " :EDX spectrum for each point; <>\n", " :Analyse composition (automatic) //e.g.//:\\\\nno. counts for element 1 > x; <>\n", " end group\n", " end split\n", " :Assign phase and orientation to each point\\\\n(automatic); <>\n", " :Euler angles and phase ID\\\\nfor each point in map; <>\n", " :Analysis of orientations (user controlled); <>\n", " :Orientation maps, Pole figures\\\\nQuantitative measures //e.g.// grain size; <>\n", " detach\n", "end group\n", "@enduml\n", "\"\"\"\n", "\n", "out_file = pathlib.Path(\n", " \"../../gallery/puml_code/chada_workflow_SEM_EBSD_EDX_nested_techniques_with_hyperlinks.puml\"\n", ")\n", "\n", "with open(out_file, \"w\") as handle:\n", " handle.write(puml_code)" ] }, { "cell_type": "code", "execution_count": 8, "id": "6bbe0034-f385-409a-a4ea-2ebc9d1e695e", "metadata": {}, "outputs": [], "source": [ "mr.run_plantuml_code(\n", " pathlib.Path(\n", " \"../../gallery/puml_code/chada_workflow_SEM_EBSD_EDX_nested_techniques_with_hyperlinks.puml\"\n", " ),\n", " output_dir=pathlib.Path(\"../\"),\n", ")" ] }, { "cell_type": "code", "execution_count": 3, "id": "98587c13-2284-4dfc-b02f-2c17b3ae7c72", "metadata": {}, "outputs": [ { "data": { "image/svg+xml": [ "Bulk sample or thin filmSEM-EBSD-EDXSet up experimental geometry:sample tilt (°), working distance (mm),detector distance (mm)Acquire electron image (SE, BSE, FSE)Electron image(s)Define rectangular ROI, step size,detector and indexing parametersEBSDAcquire EBSD patterns at all points in ROIEBSD pattern for each pointHough indexing (automatic)EDXAcquire EDX spectra at all points in ROIEDX spectrum for each pointAnalyse composition (automatic)e.g.:no. counts for element 1 > xAssign phase and orientation to each point(automatic)Euler angles and phase IDfor each point in mapAnalysis of orientations (user controlled)Orientation maps, Pole figuresQuantitative measurese.g.grain size" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "display(\n", " SVG(\n", " filename=\"../../gallery/chada_workflow_SEM_EBSD_EDX_nested_techniques_with_hyperlinks.svg\"\n", " )\n", ")" ] }, { "cell_type": "markdown", "id": "99d7481b-4ba9-41ba-995e-fdcb1880daab", "metadata": {}, "source": [ "- The only difference in the appearance of the diagram is that the name of the single technique group \"EBSD\" is now underlined, to show that it is a hyperlink." ] }, { "cell_type": "markdown", "id": "3b7e3070-2441-42ea-a182-f6b9c78fed42", "metadata": {}, "source": [ "
\n", "\n", "Note\n", "\n", "**The hyperlinks don't work when the diagram is displayed in a jupyter notebook (or the documentation).**\n", "\n", "Please open the file in your browser to try the links.\n", "\n", "`mochada_kit/gallery/chada_workflow_SEM_EBSD_EDX_nested_techniques_with_hyperlinks.svg` \n", "\n", "
" ] }, { "cell_type": "markdown", "id": "b56b4d22-968a-4803-8975-811092ade5d8", "metadata": {}, "source": [ "- You should see that clicking the element `Acquire electron images` takes you to a json diagram showing the metadata with highlights, and that clicking the name of the single technique group `EBSD` takes you to a json diagram showing the CHADA tables for EBSD.\n", "- The links open in the same tab with these settings, but this behaviour can be changed, see [here](https://plantuml.com/link)." ] }, { "cell_type": "code", "execution_count": null, "id": "2722c799-62dd-42e1-9733-7ef555c29c57", "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.12.7" } }, "nbformat": 4, "nbformat_minor": 5 }