A1S PlantUML Lib

Table of Contents

• 1. Подключение
  • 1.1. Пример подключения для Confluence
• 2. Цвета
  • 2.1. Специальные цвета
  • 2.2. Корпоративные цвета
  • 2.3. Градиенты
• 3. Спрайты
  • 3.1. Вендоры
  • 3.2. Мобильный операторы РФ
  • 3.3. SMS-агрегаторы РФ
  • 3.4. Instant Messengers
• 4. Сборка
• 5. Общий алгоритм к созданию спрайтов
• Appendix A: Частые вопросы
• Appendix B: Известные проблемы и ограничения

Библиотека тем и спрайтов A1S.

Warning

Отказ от ответственности: все права принадлежат их владельцам. Данные получены из открытых источников и сети Интернет. Данная библиотека предоставляется в режиме AS-IS. Автор не несёт ответственности в случае ущерба, понесённого в результате использования данной библиотеки.

Tip	В случае, если у вас есть более качественная версия логотипа или более точная версия цвета, то можете создать MR (fork + pull request/merge request).

В телекоме и в области мобильной связи часто возникает необходимость в диагрммах, например, диаграммах прохождения трафика или каких-то даиграммах последовательностей.

Одним из лучших, если не самым лучшим инстурментом для рисования диаграмм и схем (в парадигде diagram as a code) является PlantUML ( https://plantuml.com/ ).

Кроме того, у данного инструмента есть множество интеграций с другими системами:

• Confluence https://marketplace.atlassian.com/apps/41025/plantuml-for-confluence?tab=overview&hosting=datacenter

• Intellij Idea https://plugins.jetbrains.com/plugin/7017-plantuml-integration

• MS VS Code https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml

Так как достаточно часто приходится рисовать диаграммы, то и появилась необходимость собрать часто используемые части/компоненты в виде библиотеки.

Например, очень не хватало логотипов операторов.

При использовании данной библиотеки можно строить диаграммы такого вида:

Figure 1. Пример диаграммы с использованием библиотеки

В виде такого текстового описания:

Пример текста для генерации диаграммы

@startuml

title Схема прохождения трафика

!include https://raw.githubusercontent.com/wizardjedi/a1s-plantuml-lib/master/a1s-lib.puml

rectangle "<$megafon_s,scale=0.5,color=$CLR_MEGAFON_1>" as megafon
rectangle "<$mts_s,scale=0.5,color=$CLR_MTS_1>" as mts
rectangle "<$beeline_s,scale=0.5>" as beeline $CLR_BEELINE_1
rectangle "<$tele2_s,scale=0.5,color=$CLR_TELE2_1>" as tele2

rectangle "<$smstraffic_s,scale=0.5,color=$CLR_SMSTRAFFIC_1>\nSMS Traffic" as smstraffic
rectangle "<$devino_s,scale=0.5,color=$CLR_DEVINO_1>\nDevino Telecom" as devino

left to right direction

actor client

client --> smstraffic : smpp 50%
client --> devino : smpp 50%

smstraffic --> tele2
smstraffic --> mts $CLR_MTS_1
smstraffic --> megafon $CLR_MEGAFON_1
smstraffic --> beeline $CLR_BEELINE_1

devino --> tele2
devino --> mts $CLR_MTS_1
devino --> megafon $CLR_MEGAFON_1
devino --> beeline $CLR_BEELINE_1

@enduml

1. Подключение

Для подключения библиотеки необходимо либо скачать библиотеку и использовать с локальной файловой системы или импортировать по URL.

Пример подключения библиотеки по URL

!include https://raw.githubusercontent.com/wizardjedi/a1s-plantuml-lib/master/a1s-lib.puml

Warning

PlantUML имеет ограничения безопасности по импорту библиотек по URL. Настройки безопасности описаны на соответствующзей странице https://plantuml.com/security

1.1. Пример подключения для Confluence

Плагин PlantUML для Confluence может загружать файлы из приложений к страницам ( https://avono-support.atlassian.net/wiki/spaces/PUML/pages/9699367/Macro+plantuml ).

Для Confluence алгоритм подключения будет таким:

• Скачиваем файл с описанием библиотеки https://raw.githubusercontent.com/wizardjedi/a1s-plantuml-lib/master/a1s-lib.puml

• Для корневой (или какой-то другой страницы) добавляем файл a1s-lib.puml в приложения (attachment)

• В тексте диаграммы подключаем данный файл с помощью синтаксиса включения

  ^attachment.ext
  pagetitle
  pagetitle^attachment.ext
  spacekey:pagetitle
  spacekey:pagetitle^attachment.ext

Например, для пространства superspace и страницы Space Home.

...
!include superspace:Space home^a1s-lib.puml
...

2. Цвета

Для использования на диаграммах были выделены базовые цвета и дополнительно созданы оттенки данных базовых цветов для использования.

Для всех цветов дейсвтую следующие правила:

• Переменная цвета начинается с префикса CLR_ (например, CLR_BLUE - синий цвет)

• Для оттенков используются суффиксы с насыщенностью от 100(светлый) до 900(тёмный) (базовый цвет имеет насущенность 500) (например, CLR_ORANGE_100 - самый светлый из оранжевых оттенков)

Table 1. Базовые цвета

Переменная	Значение	Описание
$CLR_RED	#d60f0f	Красный
$CLR_BLUE	#1053b0	Синий
$CLR_GREEN	#37750b	Зелёный
$CLR_ORANGE	#fe6300	Оранжевый
$CLR_YELLOW	#fffb16	Жёлтый
$CLR_PURPLE	#7a0f91	Фиолетовый
$CLR_BROWN	#4b1414	Коричневый
$CLR_GRAY	#acacac	Серый
$CLR_BLACK	#000000	Чёрный
$CLR_WHITE	#FFFFFF	Белый
$CLR_LIGHTBLUE	#67a7ff	Голубой
$CLR_PINK	#fe59db	Розовый

Figure 2. Палитра цветов

2.1. Специальные цвета

В диаграммах (особенно даиграммах последовталеьностей) часто используются альтернативные ветки исполнения. Например, успешны сценарий, ошибочный, некоторое количество алтернатив и исключения.

Для данных сценариев добавлены специальные переменные для указания цветов:

Переменная	Описание
$CLR_SUCCESS	Успешно
$CLR_ERROR	Ошибка
$CLR_ALT	Альтернатива
$CLR_EXCEPTION	Исключение

Figure 3. Пример использования специальных цветов для веток исполнения

Пример использования специальных цветов

...
alt $CLR_SUCCESS Успешная отправка
    a1s --> viber : Отправка сообщения
else $CLR_ALT Альтернативный сценарий
    a1s --> whatsapp : Отправка сообщения
else $CLR_ERROR Ошибка отправки
    a1s --x viber : Ошибка отправки

    a1s --> whatsapp : Переотправка сообщения
else $CLR_EXCEPTION Режим аварии
    a1s --> telegram : Уведомление группы мониторинга
end
...

2.2. Корпоративные цвета

Для логотипов компаний и сервисов были выделены корпоративные или цвета бренда. Такие цвета записаны в переменных вида $CLR_<BRAND>_<НОМЕР> (например, $CLR_TELE2_1).

Переменная	Значение	Описание
$CLR_TELE2_1	#1f2229	Теле2 РФ
$CLR_TELE2_2	#ff59a3	Теле2 РФ
$CLR_TELE2_3	#00b4ee	Теле2 РФ
$CLR_TELE2_4	#c882ff	Теле2 РФ
$CLR_MEGAFON_1	#00b956	Мегафон РФ
$CLR_MEGAFON_2	#731982	Мегафон РФ
$CLR_MTS_1	#cc061a	МТС РФ
$CLR_BEELINE_1	#ffcc00	Билайн(Вымпелком) РФ
$CLR_BEELINE_2	#13171b	Билайн(Вымпелком) РФ
$CLR_YOTA_1	#00aeef	Йота РФ
$CLR_MOTIV_1	#fa6600	Мотив РФ/Екатеринбург-2000
$CLR_ROSTELECOM_1	#7700ff	Ростелеком
$CLR_ROSTELECOM_2	#ff4f12	Ростелеком
$CLR_DEVINO_1	#717fff	Девино телеком
$CLR_SMSTRAFFIC_1	#004b93	СМС Траффик
$CLR_EDNA_1	#00ea43	ОСК/Эдна
$CLR_A1S_1	#dc220b	А1 Системс
$CLR_A1S_2	#2c2f30	А1 Системс
$CLR_PROTEY_1	#009cf7	НТЦ Протей
$CLR_BERKUT_1	#2070FD	Беркут
$CLR_VIBER_1	#7360f2	Viber/Вайбер
$CLR_WHATSAPP_1	#075E54	WhatsApp
$CLR_WHATSAPP_2	#25D366	WhatsApp
$CLR_TELEGRAM_1	#24A1DE	Telegram
$CLR_SKYPE_1	#00AFF0	Skype
$CLR_ZOOM_1	#0B5CFF	Zoom

Figure 4. Таблица корпоративных цветов для иллюстрации

Warning

Цвета были получены из открытых источников. В частности с корпоративных сайтов с использованием инструмента CSS Overview из Chrome Developer Tools.

2.3. Градиенты

Библиотека содержит переменные с градиентами, которые начинаются с префикса GRD_CLR_.

Переменная	Описание
$GRD_CLR_RED	Красный градиент
$GRD_CLR_BLUE	Синий градиент
$GRD_CLR_GREEN	Зелёный градиент
$GRD_CLR_ORANGE	Оранжевый градиент
$GRD_CLR_YELLOW	Жёлтый градиент
$GRD_CLR_PURPLE	Фиолетовый градиент
$GRD_CLR_BROWN	Коричневый градиент
$GRD_CLR_GRAY	Серый градиент
$GRD_CLR_LIGHTBLUE	Голубой градиент
$GRD_CLR_PINK	Розовый градиент
$GRD_CLR_DARK_RED	Тёмный красный градиент
$GRD_CLR_DARK_BLUE	Тёмный синий градиент
$GRD_CLR_DARK_GREEN	Тёмный зелёный градиент
$GRD_CLR_DARK_ORANGE	Тёмный оранжевый градиент
$GRD_CLR_DARK_YELLOW	Тёмный жёлтый градиент
$GRD_CLR_DARK_PURPLE	Тёмный фиолетовый градиент
$GRD_CLR_DARK_BROWN	Тёмный коричневый градиент
$GRD_CLR_DARK_GRAY	Тёмный серый градиент
$GRD_CLR_DARK_LIGHTBLUE	Тёмный голубой градиент
$GRD_CLR_DARK_PINK	Тёмный розовый градиент

Переменную $GRD_CLR_BG_PRIMARY пользователь может определить до включения библиотеки для переопределения фона по умолчанию для компонентов диаграмм.

3. Спрайты

Пример использования спрайтов

card "<$beeline>" as beeline

rectangle "<$megafon,scale=0.5,color=$CLR_MEGAFON_1>" as megafon $CLR_MEGAFON_2

• Спрайты разбиты на группы

  • messengers - мессенджеры

  • mobile-operators - логотипы мобильных операторов

  • sms-agregators - логотипы СМС-агрегаторов

  • vendors - вендоры

• Для спрайтов приняты следюущие размеры, которые оформляются в виде суффиксов к имени файла

  • _s - маленький, только логотип, размер 128px x 128px (пример, <$megafon_s>)

  • _l - большой, логотип с названием, максимальный размер по ширине 300px (пример, <$motiv_l>)

• Исходные изображения для спрайтов сохранены в директориях src соответствующей директории с категориями

3.1. Вендоры

Спрайт	Изображение	Размеры
<$a1s_l>		300x105
<$a1s_s>		128x128
<$protey_l>		300x105
<$protey_s>		128x128
<$berkut_l>		300x105
<$berkut_s>		128x128

3.2. Мобильный операторы РФ

Спрайт	Изображение	Размеры
<$beeline_l>		300x63
<$beeline_s>		128x128
<$megafon_l>		300x54
<$megafon_s>		128x128
<$motiv_l>		300x56
<$motiv_s>		128x128
<$mts_l>		300x300
<$mts_s>		128x128
<$rostelecom_l>		300x77
<$rostelecom_s>		128x128
<$sbermobile_l>		300x39
<$sbermobile_s>		128x128
<$tele2_l>		300x118
<$tele2_s>		128x128
<$tinkoff_l>		300x92
<$tinkoff_s>		136x128
<$yota_l>		300x95
<$yota_s>		128x128

3.3. SMS-агрегаторы РФ

Спрайт	Изображение	Размеры
<$devino_l>		300x115
<$devino_s>		128x128
<$edna_l>		300x93
<$edna_s>		128x128
<$rapporto_l>		300x77
<$rapporto_s>		128x128
<$smstraffic_l>		300x50
<$smstraffic_s>		128x128

3.4. Instant Messengers

Спрайт	Изображение	Размеры
<$skype_s>		128x128
<$telegram_s>		128x128
<$viber_s>		128x128
<$whatsapp_s>		128x128
<$zoom_s>		128x128

4. Сборка

5. Общий алгоритм к созданию спрайтов

1. Находим необходимый спрайт, например, на сайте компании

2. Копируем логотип и открываем в графикческом редакторе

   1. Если логотип прозрачный, то добавляем слой с белым фоном и объединяем слои

3. Переводим изображение в оттенки серого

4. Переходим в настройку уровней (Levels)

5. Переводим ползунок в крайнеправое положение для получения чёрного цвета

   1. В случае, если логотип содержим какие-то переходы, то можно переводить ползунок цвета в такое положение, при котором сохраняются переходы

6. Масштабируем изображение до размеров (300 по ширине для длинных логотипов и 128x128 для иконок)

7. Сохраняем изображение в соответствующий файл .png

8. Используем команду для обработки спрайтов

   $ java -jar plantuml.jar -encodesprite 16z supersprite_l.png
   
   sprite $supersprite_l [300x105/16z] {
   ...
   }

9. Полученный вывод (sprite $supersprite …​) добавляем в файл .puml

Appendix A: Частые вопросы

1. Почему картинки чёрные?

   Это связано с ограничениями PlantUML. На текущий момент можно использовать только спрайты в виде монохромных изображений, переведённые в текстовое описание см. https://plantuml.com/sprite

   Такое тектсовое описание позволяет встраивать изображения в текст диаграммы и не требует наличия доступных ресурсов во вне.

2. А если у меня есть доступные внешние ресурсы по ссылке?

   В случае, если есть доутпные по ссылке или в файловой системе ресурсы, то можно воспользоваться форматированием creole

   'Можно использовать <img:ссылка> или <img:путь> для использоания ВНЕШНИХ изображений
   rectangle "<img:https://supersite.tld/super-image.png>" as r3

Appendix B: Известные проблемы и ограничения