# Руководство пользователя &rocs;

## Введение

В этой главе содержится общее описание основных функций и стандартный процесс работы в приложении. Наиболее важные разделы — это introduction-nutshell и scripting, прочтение которых позволит каждому новому пользователю сразу начать пользоваться &rocs;.

### Цели, целевая аудитория и рабочие процессы

&rocs; — это инструмент для работы с графами для всех, кто заинтересован в разработке и изучении алгоритмов, основанных на графах. Он подойдёт для

- преподавателей, которые хотят продемонстрировать алгоритмы своим студентам,

- студентов и исследователей, которые хотят увидеть, как работает созданный ими алгоритм,

- всех, кто интересуется структурами данных и алгоритмами.

Для всех этих людей &rocs; предоставляет простой в использовании графический редактор для построения графов, обладающий широкими возможностями обработчик сценариев для выполнения алгоритмов и несколько вспомогательныхинструментов для симуляций, экспериментов и экспорта графов. Чаще всего &rocs; используется для построения графа: либо вручную (путём перетаскивания вершин и рёбер в область редактирования), либо с помощью одного из построителей графов. Затем на построенном графе могут быть созданы и выполнены алгоритмы. Все изменения, которые выполняет алгоритм, сразу отображаются в редакторе графов.

Окно &rocs;. Окно &rocs;.

### Вкратце о &rocs;

Каждый сеанс &rocs; — это проект: при открытии &rocs; создаётся пустой проект, а при загрузке уже существующего проекта он становится текущим проектом. Таким образом, проект состоит из документов с графами, сценариев и алгоритмов и журнала.

#### Документы с графами

Документ с графами представляет собой содержимое области редактирования в редакторе графов. Он содержит информацию об указанных пользователем типах вершин и рёбер, их свойствах, а также об уже созданных вершинах и рёбрах. Это значит, что &rocs; распознаёт набор всех вершин и рёбер документа для формирования (не обязательно связанного) графа. Всё, что относится к документу, доступно обработчику сценариев через глобальный объект ``Document``.

#### Типы рёбер

В некоторых сценариях графы состоят из разных типов рёбер (например, ненаправленный граф плюс рёбра дерева, вычисленные с помощью алгоритма поиска в ширину), которые должны обрабатываться и отображаться по-разному. Для этого, помимо стандартного типа ребра, возможно указать произвольные другие типы рёбер. Каждый тип рёбер имеет своё визуальное представление, динамические свойства и может быть либо направленным, либо ненаправленным. Интерфейс сценариев предоставляет удобные методы для доступа только к рёбрам определённых типов.

#### Типы вершин

Аналогично типам рёбер, возможно указать различные типы вершин графа (например, чтобы присвоить некоторым вершинам особые роли). Каждый тип вершины имеет своё визуальное представление и динамические свойства.

#### Свойства

Каждый (вершина или ребро) элемент может иметь свойства. Эти свойства должны быть указаны в соответствующем типе ребра или вершины. Свойства идентифицируются и доступны по именам и могут содержать любое значение. Чтобы создать новое или изменить существующее свойство, воспользуйтесь боковой панелью Типы элементов и кнопкой Свойства для открытия диалога свойств.

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

    var nodes = Document.nodes()
    for (var i = 0; i < nodes.length; ++i){
        nodes[i].weight = i;
    }
    for (var i = 0; i < nodes.length; ++i){
        Console.log("вес вершины " + i + ": " + nodes[i].weight);
    }

### Пример работы с &rocs;

В этом разделе будет представлен пример проекта для изучения некоторых наиболее важных функций &rocs;. Цель состоит в том, чтобы создать граф и сценарий, иллюстрирующий простой алгоритм для задачи минимального вершинного покрытия. Задача минимального вершинного покрытия — это задача поиска подмножества вершин графа С минимального размера, такого, чтобы каждое ребро графа было соединено по крайней мере с одной вершиной в С. Эта задача является NP-сложной, и пример ниже иллюстрирует, как найти приближение фактора 2, вычисляя соответствие на заданном графе.

Цель — визуализировать взаимосвязь соответствия и минимального покрытия вершин. Для этого следует указать два типа рёбер, один для отображения совпадающих рёбер, а другой — для отображения обычных. Также следует указать два типа вершин, которые будут использоваться для обозначения вершин, содержащихся и не содержащихся в C.

#### Построение графа

Для создания графа используется построитель графов, предоставляемый &rocs;. Он находится в главном меню Граф Инструменты Построитель графов. В открывшемся диалоге выберите вариант Случайный граф и укажите количество вершин: 30, количество рёбер: 90 и семя: 1 (семя является начальным значением для генератора случайных графов; многократное использование одного и того же начального значения приводит к одинаковым и воспроизводимым графам).

#### Создание типов элементов

Далее потребуется создать второй тип вершин и второй тип рёбер с помощью панели Типы элементов. Для обоих типов следует открыть диалог со свойствами с помощью соответствующих кнопок Свойства и установить значение идентификатора `2`. После этого поменяйте цвета элементов этих двух новых типов (чтобы отличать их от типов по умолчанию). Затем установите все типы рёбер двунаправленными, а идентификаторы типов по умолчанию должны иметь значение `1`.

#### Алгоритм

После всех проделанных действий требуется запустить алгоритм. Для этого будет использоваться следующий код:

    for (var i=0; i < Document.nodes.length; i++) {
        Document.nodes[i].type = 1;
    }
    for (var i=0; i < Document.edges.length; i++) {
        Document.edges[i].type = 1;
    }

    var E = Document.edges(); // набор необработанных рёбер
    var C = new Array();      // совпадающие рёбра
    while (E.length
    > 0) {
        var e = E[0];         // первое ребро e={u,v}
        var u = e.from();
        var v = e.to();
        e.type = 2;           // указать ребру свойство «совпадающее»
        E.shift();            // убрать e (то есть, E[0]) из списка рёбер
        C.push(u);            // добавить u к C
        C.push(v);            // добавить v к C

        // отметить u,v как вершины в C
        u.type = 2;
        v.type = 2;

        // убрать из E все рёбра, присоединённые к u или v
        var adjacent = u.edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // найти индекс
            if (index != -1) {
                E.splice(index, 1); // убрать индекс, если найден
            }
        }
        var adjacent = v.edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // найти индекс
            if (index != -1) {
                E.splice(index, 1); // убрать индекс, если найден
            }
        }
    }
    Console.log("Вершинное покрытие содержит вершин: " + C.length + ".");

#### Запуск алгоритма

Чтобы запустить алгоритм, нажмите кнопку Запустить на панели управления сценарием.

## Интерфейс &rocs;

### Основные элементы пользовательского интерфейса

Пользовательский интерфейс разделён на несколько логических частей как показано на снимке окна ниже.

Элементы интерфейса &rocs;. Элементы интерфейса &rocs;.

Редактор графов

- Редактор предоставляет область, на которую возможно поместить вершины и рёбра. Щёлкните дважды левой кнопкой мыши по любому элементу, чтобы открыть соответствующее меню свойств. Чтобы создавать и изменять графы, воспользуйтесь инструментами на вкладках боковой панели.

  Доступные инструменты:

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

    - Выделить и переместить: чтобы выбрать элементы, либо, щёлкнув левой кнопкой мыши по неиспользуемому пространству области редактирования, удерживайте нажатой кнопку мыши и нарисуйте прямоугольник, содержащий некоторые элементы данных и/или рёбра, либо нажмите непосредственно на сам элемент. Чтобы переместить выбранный элемент или набор выбранных элементов, щёлкните левой кнопкой мыши по выбранному элементу или набору выбранных элементов и, удерживая кнопку нажатой, переместите указатель мыши в нужное место. Перемещение выбранных элементов также возможно с помощью клавиш со стрелками.

    - Добавить вершину: чтобы создать новый элемент данных, принадлежащий выбранной структуре данных, щёлкните левой кнопкой мыши по произвольному месту области редактирования в редакторе графов. Если навести указатель на кнопку и удерживать левую кнопку мыши нажатой, появится диалог, в котором возможно выбрать тип вершины для добавления новых вершин (только если существуют разные типы данных).

    - Добавить ребро: чтобы соединить вершины ребром, нажмите на одну вершину и, удерживая левую кнопку мыши нажатой, проведите линию к другой вершине. Это действие произойдёт, только если добавление ребра в текущий граф возможно (например, в неориентированном графе нельзя добавлять несколько рёбер между вершинами). При удерживании левой кнопки мыши нажатой откроется диалог, позволяющий выбрать тип ребра для добавления новых рёбер (только если существуют разные типы рёбер).

    - Удалить элемент: чтобы удалить элемент, щёлкните по нему. При удалении вершины будут также удалены все смежные рёбра.

Боковая панель

- Справа расположена боковая панель, которая предлагает несколько инструментов для рабочего процесса:

  - Типы элементов: вкладка предоставляет доступ ко всем доступным типам рёбер и вершин.

  - Журнал: каждый проект имеет собственный журнал, который возможно использовать для записи задач, результатов или наблюдений.

  - API сценариев: эта вкладка предоставляет доступ к документации сценариев.

Редактор сценариев

- Этот текстовый редактор позволяет составлять алгоритмы, как подробнее описано в разделе scripting. Возможно работать с несколькими сценариями одновременно, используя несколько вкладок.

Вывод сценария:

- В этой текстовой области отображается либо отладочная информация, либо вывод сценария, в зависимости от переключаемого параметра в верхней части этой вкладки. Если сценарий выдаёт ошибку, автоматически выводится отладочная информация.

Управление

- Здесь находятся кнопки для управления сценарием. Чтобы запустить открытый в данный момент в редакторе сценарий, воспользуйтесь кнопкой Запустить. Чтобы остановить сценарий в процессе выполнения, нажмите кнопку Остановить.

## Сценарии

### Выполнение сценариев в &rocs;

&rocs; использует обработчик &javascript; QtScript. Это значит, что все реализуемые алгоритмы должны использовать &javascript;. Далее будет представлена информация о том, как изменить элементы графа с помощью обработчика сценариев. Обратите внимание, что изменения, внесённые обработчиком сценариев, напрямую отражаются в свойствах элементов редактора графов.

#### Управление выполнением сценариев

Существует несколько режимов выполнения алгоритмов:

- Запустить: выполнять сценарий до его завершения.

- Остановить: остановить выполнение сценария (доступно только при выполнении сценария).

#### Вывод сценария

Во время выполнения алгоритма отладочные данные и вывод программы отображаются на панели вывода отладки и сценария. Если обработчик сценариев обнаруживает синтаксическую ошибку, эта ошибка будет отображаться в виде отладочного сообщения. Обратите внимание, что все сообщения программы также отображаются в выводе отладки (выделены жирным шрифтом).

Параметры текста, отображаемого в выводе сценария, возможно менять с помощью следующих функций:

    Console.log(строка сообщения);            // отображает сообщение как вывод сценария
        Console.debug(строка сообщения);          // отображает сообщение как вывод отладчика
        Console.error(строка сообщения);          // отображает сообщение как вывод ошибки

#### API обработчика сценариев

Каждая из различных частей &rocs; предоставляет статический элемент, к которому обработчик сценариев может получить доступ. Это:

- ``Document`` для графа

- ``Console`` для вывода журнала консоли

Для явного использования API и ссылок на методы обратитесь к встроенной справке на боковой панели &rocs;.

## Импорт и экспорт

### Обмен проектами &rocs;

Проекты &rocs; возможно импортировать и экспортировать в качестве архива `.tar.gz`. Эти архивы возможно использовать для обмена проектами. Операции импорта и экспорта доступны в меню Граф Импорт графа... и Граф Экспорт графа как….

#### Импорт и экспорт документов с графами

&rocs; на данный момент поддерживает импорт и экспорт в следующих файловых форматах:

- &DOT;-файлы, также известные как файлы Graphviz

- Файлы GML

- Файлы формата Trivial Graph

- Формат Keyhole Markup Language

##### Формат файлов Trivial Graph

Формат Trivial Graph Format (TGF) — это простой текстовый формат файла для описания графов. Файл TGF состоит из списка определений вершин, которые сопоставляют идентификаторы вершин с метками, после чего следует список рёбер. Этот формат позволяет иметь только одну метку на вершину и одно значение на ребро. &rocs; интерпретирует импортированные графы как ненаправленные. Экспортированные графы будут содержать по два ребра на соединение, если соединения являются двунаправленными.

###### Спецификация формата

- Файл начинается со списка вершин (одна вершина на строку), за которым следует строка с единственным символом #, после чего приводится список рёбер (одно ребро на строку).

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

- Ребро состоит из двух целых чисел (идентификаторов), разделённых пробелом, за которыми следует пробел, а затем произвольная строка. Предполагается, что направленное ребро указывает от первого идентификатора ко второму идентификатору.

###### Пример

    1 стартовый узел
    2 передатчик
    3 сток
    #
    1 2 синий
    2 1 красный
    2 3 зелёный

##### Язык &DOT; / Формат файлов Graphviz

Язык &DOT; — это простой текстовый язык описания графов, который обеспечивает как хорошо читаемое человеком представление графов, так и эффективную обработку программами компоновки графов. &DOT; — это формат файла по умолчанию для пакета визуализации графов Graphviz, который также широко используется другими инструментами для работы с графами. Обычными расширениями файлов для &DOT; являются `.gv` и `.dot`..

###### Неподдерживаемые возможности

&rocs; может распознавать любой файл графов, содержащий граф в соответствии со спецификацией языка &DOT;

https://graphviz.org/doc/info/lang.html

. Поддержка языковых функций является полной, несмотря на следующие исключения:

- Подграф: из-за отсутствия понятия «подграф» в &rocs; подграфы импортируются только как набор элементов и соединений. Не импортируются соединения с подграфами.

- Атрибуты &HTML; и &XML;: атрибуты (например, метки), содержащие синтаксис &HTML; или &XML;, остаются без изменений. Особенно это касается стилей и шрифтов.

###### Пример

    digraph myGraph {
        a -> b -> c;
        b -> d;
    }

## Компоновка графов

### Автоматическая компоновка графов в &rocs;

&rocs; позволяет автоматически компоновать графы. Инструмент компоновки графов &rocs; находится в главном меню Граф Инструменты Компоновка графов. Существует два алгоритма компоновки: компоновка на основе силы и компоновка радиального дерева. Чтобы применить один из них, выберите соответствующую вкладку в диалоге компоновки графа, выберите нужные параметры и запустите алгоритм, нажав кнопку OK. Подробные сведения, относящиеся к каждому из алгоритмов компоновки, приведены в следующих разделах.

#### Компоновка по силе

Компоновку на основе силы возможно применить к любому графу. Этот алгоритм симулирует силы, действующие на каждую вершину. Между парами соседних вершин существуют силы отталкивания и силы притяжения. Чтобы задать величину этих сил, следует переместить соответствующие ползунки в соответствующем диалоге.

Окно с диалогом инструмента компоновки на основе силы. Окно с диалогом инструмента компоновки на основе силы.

«Рабочая область» — это ещё один параметр, который возможно настроить. Он регулирует степень разброса вершин. Компоновки, созданные с высокими значениями рабочей области, имеют большие расстояния между вершинами.

##### Радиальное дерево

Компоновка «Радиальное дерево» может быть применена только к графам-деревьям. Любая попытка применить эту компоновку к графу другого типа приведёт к появлению сообщения об ошибке. Параметры этой компоновки доступны в соответствующем диалоге.

Окно с диалогом инструмента компоновки радиального дерева. Окно с диалогом инструмента компоновки радиального дерева.

Параметр типа дерева предлагает два варианта: свободная компоновка дерева и корневая. В свободной компоновке вершины размещаются свободно, без какой-либо видимой иерархии между ними. При компоновке корневого дерева корневая вершина размещается вверху, а под ней располагаются ответвления, что даёт представление об иерархии между вершинами.

Параметр «Основа» определяет, какая вершина будет использоваться в качестве корня для компоновки корневого дерева или в качестве центра для компоновки свободного дерева. Основа компоновки свободного дерева — это первая вершина, размещаемая алгоритмом. Все остальные вершины расположены на окружностях с центром в центральной вершине. Основа может быть выбрана автоматически с помощью алгоритма компоновки.

Параметр разделения вершин позволяет управлять расстоянием между вершинами. Увеличение значения этого параметра приведёт к увеличению расстояния между вершинами. Аналогичным образом, уменьшение значения этого параметра приведёт к уменьшению расстояния между вершинами.

## Авторские права и лицензия

&rocs;

Авторские права на программу:

- © Ugo Sangiori, 2008 (ugorox@gmail.com)

- © Tomaz Canabrava, 2008-2012 (tcanabrava@kde.org)

- © Wagner Reck, 2008-2012 (wagner.reck@gmail.com)

- © Andreas Cord-Landwehr, 2011-2015 (cordlandwehr@kde.org)

Авторские права на документацию:

- © Anne-Marie.Mahfouf, 2009 (annma@kde.org)

- © Tomaz Canabrava, 2009 (tcanabrava@ kde.org)

- © Andreas Cord-Landwehr, 2011-2015 (cordlandwehr@kde.org)

Перевод на русский язык: Алексей Субачalexey.subach@gmail.com, Мария Шикуноваtranslation-team@basealt.ru, Олеся Герасименкоtranslation-team@basealt.ru

&underFDL; &underGPL;
&documentation.index;