diff --git a/en/chap04.tex b/en/chap04.tex index acd42ee..e0bcb50 100644 --- a/en/chap04.tex +++ b/en/chap04.tex @@ -1 +1,68 @@ \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\X{glos} 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, but running the +\verb|visu.py| script also works when PySide6 is installed in the system.\X{uuuuuuuuuuu!!} + +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 topolgy 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. + +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