====================================================== Plantuml Sprites ====================================================== PlantUML supports `sprites: `_ small graphic elements that can be used in diagrams. Given we want to make diagrams communicate quickly and clearly, using sprites (rather than just boxes) is very effective. You can #. use the builtin `sprites `_ #. create your own sprites Builtin Sprites - Deployment Diagram Sprites ---------------------------------------------- :ref:`Deployment` diagrams define several sprites. Below is an example using some of these - in a sequence diagram. .. uml:: ./plantuml/examples/keysequence.puml :align: center .. literalinclude:: ./plantuml/examples/keysequence.puml :linenos: Builtin Sprites - Standard Library Sprites ---------------------------------------------- Some standard libaries are available for PlantUML: #. See http://plantuml.com/stdlib for what is supported in official release of PlantUML #. "-stdlib" option lists the builtin icon libaries .. code :: docker run -u `id -u $USER`:`id -g $USER` -i --rm -v $(pwd):/home/documentation -t docdac:ubuntu-1.0 java -jar /usr/share/plantuml/plantuml.jar -stdlib .. code :: aws Version 18.02.22 Delivered by https://github.com/milo-minderbinder/AWS-PlantUML awslib Version 3.0.0 Delivered by https://github.com/awslabs/aws-icons-for-plantuml azure Version 2.1.0 Delivered by https://github.com/RicardoNiepel/Azure-PlantUML c4 Version 1.0.0 Delivered by https://github.com/RicardoNiepel/C4-PlantUML cloudinsight Version 0.0.1 Delivered by https://github.com/rabelenda/cicon-plantuml-sprites/ cloudogu Version 0.0.1 Delivered by https://github.com/cloudogu/plantuml-cloudogu-sprites material Version 0.0.1 Delivered by https://github.com/Templarian/MaterialDesign office Version 0.0.1 Delivered by https://github.com/Roemer/plantuml-office osa Version 0.0.1 Delivered by https://github.com/Crashedmind/PlantUML-opensecurityarchitecture-icons tupadr3 Version 2.0.0 Delivered by https://github.com/tupadr3/plantuml-icon-font-sprites Example Builtin Sprites AWS ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `Plantuml for AWS `__ uses the `icon set from AWS `__ and converts these to sprites for use with PlantUML. :: git clone git@github.com:milo-minderbinder/AWS-PlantUML.git Simple Example ~~~~~~~~~~~~~~ .. uml:: ./plantuml/examples/aws_nested-components.puml :align: center .. literalinclude:: ./plantuml/examples/aws_nested-components.puml :linenos: More Complex Example ~~~~~~~~~~~~~~~~~~~~ .. uml:: ./plantuml/examples/aws_comments-architecture.puml :align: center .. literalinclude:: ./plantuml/examples/aws_comments-architecture.puml :linenos: Create a Sprite ------------------------ It's easy to create your own sprites from existing icons. Start with a 100x100 person icon png ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. figure:: ./images/C4person100.png Convert to sprite of different resolutions as follows ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: java -jar plantuml.jar -encodesprite 4 images/C4person100.png > C4person4.sprite java -jar plantuml.jar -encodesprite 16 images/C4person100.png > C4person16.sprite java -jar plantuml.jar -encodesprite 8 images/C4person100.png > C4person8.sprite C4person4.sprite file: .. literalinclude:: ./plantuml/examples/C4person4.sprite :linenos: Create Diagram with our Sprites ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. uml:: ./plantuml/examples/bigsmall.puml :align: center .. literalinclude:: ./plantuml/examples/bigsmall.puml :linenos: Create Sprites by converting Elastic icon libaries ---------------------------------------------------- See demo and details at https://github.com/Crashedmind/PlantUML-Elastic-icons Create Sprites by converting OSA icon libaries ---------------------------------------------------- `Open Security Architecture `__ (OSA) is a useful resource for security architects providing a catalog of controls, patterns, and requirements from numerous standards, governance frameworks, legislation and regulations. See "`why have OSA? `__\ ". Resources include a `security architecture icon library `__ available under a "`Creative Commons share-alike license `__\ ". These icons are available as png or svg images. Here we'll convert them to sprites so we can use them with PlantUML. Converting the icon set to PlantUML Sprites ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Download the `security architecture icons `__ and extract them into a directory e.g. "osaicons". 2. Configure and/or add styles to the ``puml.ini`` configuration file, or create your own 3. Run the ``puml.py`` script against your downloaded ```` using your custom config Commands ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: # Get OSA icons mkdir ./OpenSecIcons/ mkdir ./OpenSecIcons/icons/ cd ./OpenSecIcons/icons/ wget http://www.opensecurityarchitecture.org/downloads/13_05_osa_icons_png.zip unzip ./13_05_osa_icons_png.zip # Get png to PlantUML conversion script git clone git@github.com:milo-minderbinder/AWS-PlantUML.git cd AWS-PlantUML # Create PlantUML sprites from OSA png icons python3 puml.py -c ./puml.ini ../OpenSecIcons/icons/ #icons output to ./dist/osa/ Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. uml:: ./plantuml/examples/osa.puml :align: center .. literalinclude:: ./plantuml/examples/osa.puml :linenos: All Icons ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Below is what the icons look like - and the associated code. .. uml:: ./plantuml/examples/osa_sprites1.puml :align: center .. literalinclude:: ./plantuml/examples/osa_sprites1.puml :linenos: .. uml:: ./plantuml/examples/osa_sprites2.puml :align: center .. literalinclude:: ./plantuml/examples/osa_sprites2.puml :linenos: .. uml:: ./plantuml/examples/osa_sprites3.puml :align: center .. literalinclude:: ./plantuml/examples/osa_sprites3.puml :linenos: .. uml:: ./plantuml/examples/osa_sprites4.puml :align: center .. literalinclude:: ./plantuml/examples/osa_sprites4.puml :linenos: .. uml:: ./plantuml/examples/osa_sprites5.puml :align: center .. literalinclude:: ./plantuml/examples/osa_sprites5.puml :linenos: .. uml:: ./plantuml/examples/osa_sprites6.puml :align: center .. literalinclude:: ./plantuml/examples/osa_sprites6.puml :linenos: .. uml:: ./plantuml/examples/osa_sprites7.puml :align: center .. literalinclude:: ./plantuml/examples/osa_sprites7.puml :linenos: .. uml:: ./plantuml/examples/osa_sprites8.puml :align: center .. literalinclude:: ./plantuml/examples/osa_sprites8.puml :linenos: .. uml:: ./plantuml/examples/osa_sprites9.puml :align: center .. literalinclude:: ./plantuml/examples/osa_sprites9.puml :linenos: .. uml:: ./plantuml/examples/osa_sprites10.puml :align: center .. literalinclude:: ./plantuml/examples/osa_sprites10.puml :linenos: PlantUML HyperLinks ---------------------- PlantUML supports hyperlinks in output SVG images. This allows diagrams to be linked together, and for a user to easily navigate by clicking around per `Shneiderman's mantra `__: *Overview first, zoom and filter, then details-on-demand* Clicking the image opens up the target ``svg`` image. This target image contains hyperlinks. .. image:: ./plantuml/examples/links.svg :target: ../plantuml/examples/links.svg .. literalinclude:: ./plantuml/examples/links.puml :linenos: .. todo:: Terminal payment icon lib