AlexAegis/loreplotter

% !TeX root = ../thesis.tex
\chapter{Felhasználói dokumentáció}
\label{ch:user}

Az alkalmazás sem telepítést sem regisztrációt nem igényel, teljes egészében böngészőből használható. Minden alkalmazáson belüli tevékenység egy projekthez köthető melyeket a felhasználó kedve szerint hozhat létre, törölhet, módosíthat. Egyszerre több projektet is vezethetünk, a váltás közöttük azonnali.

\section{A Projekt}

Minden projekt\cref{fig:basic-project-structure} három fő elemből áll, ezek a név, a világ és később a szereplők. Új projekt létrehozásakor a projekt nevét és a világának adatait szükséges megadni.

\begin{figure}[h!]
    \centering
    \begin{forest}
        forked edges,
        for tree={edge+={-Latex}},
        [Projekt
            [Név]
            [Világ [Név] [Méret]]
            [Szereplők [\dots]]
        ]
    \end{forest}
    \caption{
        Projektstruktúra}
    \label{fig:basic-project-structure}
\end{figure}

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.50\textwidth,scale=1]{create-project-button}
    \caption{
        Új projektet létrehozni a jobb felső sarokban található menü legfelső elemével tehetjük meg}
    \label{fig:create-project-button}
\end{figure}

Új projekt létrehozásakor a projekt készítő dialógust kapjuk melyen lehetőséget kapunk a projektünknek a nevét, a világ nevét és méretét megadni, utóbbi alatt a bolygó sugarát értjük kilométerben megadva. Valamint egy tetszőleges fekete-fehér magasságtérképet is megadhatunk amivel inicializálhatjuk a bolygó felületét. A vízmagasság alapértelmezetten 40\%-os szürkeségnél van. A 'Create' gombra kattintva azonnal megnyílik az elkészített projekt.

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.80\textwidth,scale=1]{create-project-form}
    \caption{
        Új projekt dialógus}
    \label{fig:create-project-form}
\end{figure}


\begin{table}[H]
    \centering
    \begin{tabular}{ | m{0.25\textwidth} | m{0.10\textwidth} | m{0.55\textwidth} | }
        \hline
        \textbf{Mező} & \textbf{Típus} & \textbf{Leírás} \\
        \hline \hline
        \emph{Név} & Szöveg & Kötelező. Egyedi. A projekt azonosítója. \\
        \hline
        \emph{Bolygó név} & Szöveg & Kötelező. Alapértelmezett értéke: "Earth" \\
        \hline
        \emph{Bolygó méret} & Szám & Kötelező. Alapértelmezett értéke: "6371". (A föld sugara kilométerben). Minimum 500.  \\
        \hline
        \emph{Magasságtérkép} & Kép & Opcionális. Egy tetszőleges kezdeti magasságtérkép  \\
        \hline
    \end{tabular}
    \caption{Új projekt sablon}
    \label{tab:create-project-form}
\end{table}

Meglévő projektet szerkeszteni a menü gomb mellett a projekt nevére kattintva lehet. Itt lehetőség van megváltoztatni a készítéskor megadott adatokat, új textúrát felölteni, esetleg betölteni az alapértelmezett föld textúrát. Szerkesztéskor bejön a képbe egy új megszorítás. Mivel a szereplőinknek meg kell tudniuk tenni bármely két esemény között a távot a saját sebességüknek megfelelően így itt limitálva van a bolygó maximális mérete aszerint, hogy ez a feltétel még ne sérüljön.

\begin{figure}[h!]
    \centering
    \includegraphics[width=1\textwidth,scale=1]{edit-project-form}
    \caption{
        Projekt szerkesztése dialógus}
    \label{fig:create-project-form}
\end{figure}

\pagebreak

\section{A Kezelőfelület} \label{section:ui}

\begin{figure}[h!]
    \centering
    \includegraphics[width=1.0\textwidth,scale=1]{full-screenshot-open-sidebar}
    \caption{
        A kezelőfelület}
    \label{fig:full-screenshot-open-sidebar}
\end{figure}

A kezelőfelület az alábbi elemeket tartalmazza:

\begin{itemize}
    \item Bal oldalt a szereplőtár\cref{section:ui-actor-tool} amivel készíteni és válogatni tudunk a szereplőink között.
    \item Alul az idővonal\cref{section:ui-timeline} látható ahol a jelenlegi időt és a szereplők eseményeit tudjuk megváltoztatni.
\end{itemize}

\subsection{A Szereplőtár} \label{section:ui-actor-tool}

A szereplőtár legfelső elemével lehet újabb szereplőket hozzáadni a színtérhez. A gombot fogd-és-vidd módon lehet a bolygó bármely pontjára ráhúzni, ami majd a karakter kiindulási pontja lesz. Ez akármikor megváltoztatható, amíg egyedül van pedig korlátok nélkül.

Ez alatt az elkészített karakterek listája van, mellette az összes karakter számával. Egy karakter itt az alábbi információt tartalmazza:

\begin{itemize}
    \item Név (Akkumulált a jelenlegi időpillanatra)
    \item Szín (Akkumulált a jelenlegi időpillanatra)
    \item Összes esemény száma
\end{itemize}

A szereplőtár legalján van a 'Debug mód' gomb is amivel bekapcsolhatunk a színtéren azon vektorok vizualizációját amik az események távolságainak metszetét számolják és tartják az éppen manipulált szereplőt a metszetben.

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.5\textwidth,scale=1]{debug}
    \caption{A debug toolt bekapcsolva láthatjuk akció közben ezeket a számításhoz használt vektorokat.}
    \label{fig:debug}
\end{figure}
\begin{figure}[h!]
    \centering
    \includegraphics[width=0.5\textwidth,scale=1]{debug2}
    \caption{Egy másik szögből egy metszéspont eset. A fehér vektorok az egér pozíciója felé mutatnak.}
    \label{fig:debug2}
\end{figure}




\pagebreak
\subsection{Az Idővonal} \label{section:ui-timeline}

A idővonalat elsősorban három elemre tudjuk bontani:

\subsubsection{A Kurzor}

A vonalzón helyezkedik el. Mindig a jelenlegi időpontra mutat, melyet a kurzoron, fogd-és-vidd módszerrel megváltoztathatunk. Egy fölötte megjelenő buborék a pontos időt mutatja másodperc pontossággal. Ez egyben szerkeszthető is ha egy konkrét időpontra akarunk ugrani. Ha átszerkesztettük az időpontot a kurzoron akkor az 'Enter' billentyűvel a megadott időpontra ugrik. Ha megváltozik az idő akkor az azonnal bekerül értékként ide így lejátszás közben ez nem szerkeszthető.

\paragraph{A Vonalzó}

Beosztásai napokban értendőek, a kisebb fogai pedig óráknak. A vonalzót fogd és vidd módon tudjuk az időben előre vagy hátra eltolni. Az egérgörgővel pedig az aktív idősávot tudjuk kibővíteni, szűkíteni. A legközelebbi megengedett nagyítás 2 napot foglal magában.

\paragraph{A Karakter Sávok}

Minden karakter saját sávval rendelkezik. Bal oldalt a sávhoz tartozó karakter akkumulált nevét lehet látni. A sávon belül pedig a blokkját ami eseményekre van felosztva.

Egy blokk az alábbi interakciós lehetőségeket nyújtja:
\begin{enumerate}
    \item Egy eseményre kattintva a kurzor arra az időpontra ugrik és az esemény kiválasztásra kerül. Kiválasztás után lehetőség van kitörölni az adott eseményt egy megerősítést követően. Emellett kiválasztásra kerül a hozzá tartozó szereplő is a színtéren. Eseményt törölni csak akkor lehet ha törlést követően az előző esemény helyéről még elérhető a következő.
    \item Egy esemény fogd-és-vidd módon áthelyezhetünk bárhova az idővonalon. A művelet érvénytelen ha az környező események megengedett sebességei és távolsága alapján a szereplő már nem tudná teljesíteni az adott utat. Ha ez sérül akkor a művelet érvénytelen és az esemény visszaugrik eredeti pozíciójára. Figyeljünk oda, hogy ha a jövőben egy esemény függ ettől, és egy annál későbbi időpontra helyezzük, akkor ez a függőség sérül. Ez viszont már nincs ellenőrizve.
    \item A blokk egészét is mozgathatjuk fogd és vidd módon, ezzel az összes esemény párhuzamosan fog elmozdulni. Figyeljünk oda, hogy ha egy másik szereplő egy vagy több eseménye függ a mozgatott szereplő eseményeitől, akkor ezek a függőségek sérülhetnek. Ez nincs ellenőrizve.
    \item Az egeret a karakter sávja felett tartva a színtéren a hozzá tartozó objektum körül egy körvonal jelenik meg a gyors azonosításért. Ez akkor is látszik ha a szereplő a bolygó másik oldalán van.
\end{enumerate}

Az idővonalon egyszerre 4 sáv fér el. A többi sávot görgetéssel, függőleges pásztázással, vagy a görgősávval érjük el.

\subsection{A Színtér} \label{section:ui-scene}

A kezelőfelület közepén helyezkedik el a 3D színtér és az azt közvetlen kezelő eszközök. A színtér fő eleme a bolygó és rajta a szereplők. A bolygó mozgatás módban a felületét pásztázva forgatható, az egérgörgővel pedig közelíthető/távolítható.

A bolygó felületén lévő szereplők helyét, a szereplőt reprezentáló színes gömb fogd-és-vidd módon történő áthelyezésével lehet megtenni. Ennek a viselkedése nagyban függ a jelenlegi időtől és a szereplő azon eseményeitől mely a jelenlegi időponton, vagy a körül helyezkednek el. Minden szereplő rendelkezik egy maximum elérhető sebességgel. Hogy ez be legyen tartva, egy szereplő áthelyezésekor, csak olyan távolságba engedett az áthelyezés, amivel még el lehet érni az előző és a következő esemény helyét. Egy esemény helye áthelyezhető ha áthelyezéskor az az esemény ideje van kiválasztva, egyéb esetekben új esemény jön létre.


\subsubsection{Eszközök} \label{section:ui-utilities}

A színtér 3 sarkában 3 eszköztár látható.

\subsubsection{Az interakciós eszköztár}

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.60\textwidth,scale=1]{tool-interaction}
    \caption{Interakciós eszköztár, a színtér bal felső részén.}
    \label{fig:tool-interaction}
\end{figure}

A ceruza ikonnal ellátott gombbal rajzolás módba válthatunk, a mellette lévő két csúszka pedig az ecset paraméterei: magasság és méret. A bolygó felületét pászázva azt megváltoztathatjuk. Alacsony magassággal tengereket is rajzolhatunk. A bolygón kívül pásztázva ugyanúgy forgathatjuk mintha mozgatás módban lennénk.

A tengely ikonnal ellátott gombbal az alap, színtér mozgatáshoz szükséges módba térhetünk vissza. A mellette lévő csúszka a szereplőket reprezentáló gömbök méretét állítja. A gömbök mérete ettől, és a közelítés mértékétől is függ.

\subsubsection{A fény eszköztár}

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.20\textwidth,scale=1]{tool-light-manual-light}
    \caption{A fény eszköztár manuális módban, világosra állítva. A színtér bal alsó részén.}
    \label{fig:tool-light-manual-light}
\end{figure}

A kör alakú gombbal manuális és automata módok között válthatunk. A jobb oldali gomb csak manuális módban látszik. Ezzel tudunk váltani az állandó világos és a sötét mód között.

\paragraph{Világos mód}

Világos módban a kezelőfelület teljes egésze fehérre vált, ahogy színtér háttere is. A színtérben a nap eltűnik és a bolygó egésze megvilágításra kerül.

\paragraph{Sötét mód}

Sötét módban a kezelőfelület teljes egésze sötétre vált, ahogy a színtér háttere is. A színtérben a nap csak ebben a módban van jelen, és a bolygót érő legerősebb fényforrássá válik. Ebben a módban is változhat a megvilágítás a sebességnek megfelelően. \ref{fig:tool-time}

\paragraph{Automata mód}

Automata módban alapértelmezetten a sötét mód aktív de túl közeli zoomnál, vagy akkor ha az idő túl gyorsan telik automatikusan a világos mód kapcsol be.

\subsubsection{Az idő eszköztár}

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.40\textwidth,scale=1]{tool-time}
    \caption{Az idő eszköztár, a színtér jobb alsó részén}
    \label{fig:tool-time}
\end{figure}

Az idő eszköztár fő eleme a lejátszás gomb. Erre kattintva a csúszkával vagy a gombokkal beállított sebességgel megkezdődik a lejátszás. A sebesség egysége egy percet jelent minden valódi másodpercre. A lejátszás megkezdésével a színtér szereplői az eseményeik pozíciói között fognak mozogni.

Az alábbi billentyűkkel is vezérelhető a lejátszás:

\begin{table}[H]
    \centering
    \begin{tabular}{ | m{0.15\textwidth} | m{0.55\textwidth} | }
        \hline
        \textbf{Billentyű} & \textbf{Hatás}\\
        \hline \hline
        \emph{Szóköz} & A lejátszás megkezdése, szünetelése. \\
        \hline
        \emph{Számok 0-9} & A kettő adott hatványával való lejátszás. \\
        \hline
        \emph{Jobbra nyíl} & A lejátszás irányát pozitívra állítja.  \\
        \hline
        \emph{Balra nyíl} & A lejátszás irányát negatívra állítja.  \\
        \hline
        \emph{Felfele nyíl} & A lejátszást gyorsítja 60 egységgel. \\
        \hline
        \emph{Lefele nyíl} & A lejátszást lassítja 60 egységgel.  \\
        \hline
    \end{tabular}
    \caption{Idő vezérlése gombokkal}
    \label{tab:tool-time-control-keys}
\end{table}

\subsection{A Szereplők} \label{section:ui-actors}

A színtér szereplői kattintással, egy eseményét kiválasztva vagy a bal oldali menüből is kiválaszthatóak. Kiválasztást követően egy kis ablak jelenik meg a szereplő színtérbeli pozíciójánál mutatva az összes akkumulált adatát, és hogy melyik eseménynél lett utoljára módosítva. Utóbbi gombra kattintva a kurzor egyből arra az időre ugrik. A tetején lévő négy vezérlőgombbal a legelső, az előző, a következő és a legutolsó eseményéhez lehet ugrani az adott karakternek. Ugrás közben az időablak követi a kurzort így az sose megy ki a képernyőről. Hasznos ha az időablak nagyon messze van a keresett eseménytől.

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.40\textwidth,scale=1]{actor-popup}
    \caption{A szereplő ablaka a jelenlegi adataival, és azok utolsó változásának idejével.}
    \label{fig:actor-popup}
\end{figure}

A szerkesztés gombra kattintva pedig az adott időpillanat, adott helyzetén szerkeszthetjük a szereplő adatait. Minden változtatás a fent megjelenő időtől lesz érvényes. Egy ilyen változtatás nem befolyásolja a karakter pozícióját, mentéskor a megadott dátum alapján -- ugyanúgy ahogy a lejátszás teszi -- kiszámolja, hogy hol tartózkodna akkor a szereplő és azzal a helyzettel menti el az eseményt.

\begin{table}[H]
    \centering
    \begin{tabular}{ | m{0.25\textwidth} | m{0.10\textwidth} | m{0.55\textwidth} | }
        \hline
        \textbf{Mező} & \textbf{Típus} & \textbf{Leírás} \\
        \hline \hline
        \emph{Dátum} & Szöveg & Megváltoztatható a szerkesztés dátuma. \\
        \hline
        \emph{Idő} & Szöveg & Megváltoztatható a szerkesztés időpontja. \\
        \hline
        \emph{Név} & Szöveg & A szereplő neve.  \\
        \hline
        \emph{Maximális sebesség} & Szám & A szereplő sebessége kilóméter per órában. \\
        \hline
        \emph{Szín} & Szín & A szereplő színe. \ref{fig:actor-edit-dialog-color}  \\
        \hline
    \end{tabular}
    \caption{Szereplő alap adatai}
    \label{tab:create-project-form}
\end{table}

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.70\textwidth,scale=1]{actor-edit-dialog}
    \caption{A szereplő szerkesztés ablaka}
    \label{fig:actor-edit-dialog}
\end{figure}

A szereplőnek lehetnek már meglévő, akkumulált tulajdonságai is mikor az ablakot megnyitjuk. Ezeket értékét megváltoztathatjuk, de kitörölni itt nem tudjuk, ugyanis nem itt születtek. De "elfelejthetjük" őket aminek hatására az adott időpillanat után már nem lesz jelen a tulajdonság.

Lehetőség van új tulajdonságok felvitelére is, itt jelennek meg az adott eseményen született tulajdonságok is. Ezek törölhetőek mert nem akkumulált adatok.

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.30\textwidth,scale=1]{actor-edit-dialog-color}
    \caption{A szereplő színének megváltoztatása}
    \label{fig:actor-edit-dialog-color}
\end{figure}


\subsection{Az import/export eszköz} \label{section:ui-import-export}

Lehetőség van az adatbázist szöveges formában kimenteni, beolvasni. Ezt a menü (\ref{fig:create-project-button}) Export gombjával nyithatjuk meg.

\begin{figure}[h!]
    \centering
    \includegraphics[width=1\textwidth,scale=1]{ui-import-export}
    \caption{Az import/export ablak}
    \label{fig:ui-import-export}
\end{figure}

Az itt megjelenő JSON \cite{JSON} reprezentálja a teljes adatbázist amit az alkalmazás használ éppen. A 'Copy to clipboard' gomb egy kattintással a vágólapra helyezi a kiexportált szöveget. Ugyanide visszamásolva, majd az import gombra nyomva, egy megerősítést követően a jelenlegi adatbázist teljesen felülírja. Figyelem, a szöveg nem tartalmazza a projektek textúráit! Ezeket külön lehet letölteni a 'Download all textures' gombbal.