\chapter{Usage}\label{ch:usage}

% Maybe this is too much of a guide, but I think a section with the user's
% description should be present and there is not much other content to write
% here. Also, the UI is currently horrible, so it is worth having this
% somewhere, and since there is no documentation, here is the place probably.

In this chapter we describe the program from the user's point of view and
present its features.

\section{Running Birdvisu}

First, the user needs to obtain Birdvisu from somewhere. Either, the
attachment~\ref{att:birdvisu} can be extracted, or the project can be
downloaded from its repository at
\url{https://gitea.ledoian.cz/LEdoian/birdvisu}, which will also contain any
future improvements.

The only strict dependency of Birdvisu is Python3.10 or newer. While the project
depends on the PySide6 library for the user interface, it can be downloaded
as a wheel from PyPI. Of course, using a system-wide installation of
PySide6 is also possible.

Birdvisu can read the topology information from files, so it is not necessary
to have a BIRD running and configured if only showing static data is required.

We only support running the project on Linux. However, Birdvisu might be able
to run on other types of operating systems, since we have only used
cross-platform libraries.

There are several ways to start the program. The recommended method is to
install the project into a Python virtual environment and using the \verb|visu|
command. Running the \verb|visu.py| script also works when PySide6 is installed
in the system, without requiring the installation step.

Once the program is started, the user is presented with an empty canvas. Using
the \emph{Topology} menu, it is possible to load both a reference and current
topologies. Both can be loaded from a file, the current one can also be
retrieved directly from a running BIRD via its socket. In the latter case, the
user is provided with a dialog to pick an area and OSPF instance.

Once both topologies are loaded, the graph of the topology appears. Now, the
vertices can be moved around to the user's liking. Alternatively, the
\emph{Positions} menu provides a way to load the positions of vertices from a file.

The program expects the topology files to have the \verb|.ospf| extension,
positioning files may end in \verb|.visu|. Nevertheless, any files may be used,
they just are not offered by default.

Several highlighting ways are available. In the \emph{Highlight} menu, the user
can choose to show differences between the reference and current topology, or
set the widths of edges according to their costs. Alternatively, by
right-clicking any vertex, it is possible to highlight its shortest path DAG.
If the user wants to find a specific route, showing the DAG also serves as
selecting the start vertex. The context menus for vertices then allow finding
the path to those vertices. Note that stub and external networks are sinks in
the OSPF topology, so it is expected that the program draws an empty DAG for them.

Finally, there is an option to reload the shown graph in the Topology menu. We
decided that the graph should not change unexpectedly, because that could be
unpleasant to use.

As a part of Birdvisu we ship the files \verb|gennet.ospf|,
\verb|gennet-changed.ospf| and \verb|gennet.visu| for demonstration purposes.
These files provide a topology of the default Gennet, the same topology with
several manual changes, and a placement of vertices like in figure~\ref{fig:gennet}.

\iffalse
\section{Extending Birdvisu}
\fi