====== Úvod ======

Therion je program na komplexné spracovanie máp jaskýň. Umožňuje

  * uložiť namerané údaje v počítači v podobe veľmi blízkej pôvodným zápisníkom a spätne ich získať;
  * nakresliť vernú, vždy aktuálnu mapu;
  * vytvoriť realistický trojrozmerný model jaskyne.

To znamená, že Therion poskytuje jazyk na všeobecný popis jaskyne alebo iného podzemného priestoru, ktorý je potom možné ľubovoľne interpretovať.

Program pracuje pod systémami Unix, Linux, MacOS X a Win32. Zdrojový kód a inštalačný program pre systém Windows je dostupný na stránke (http://therion.speleo.sk).

Therion je poskytovaný voľne s licenciou GNU GPL.

===== Prečo vznikol Therion? =====

V polovici 90tych rokov bol po niekoľkoročnej prestávke obnovený prieskum Jaskyne mŕtvych netopierov. Bolo treba spracovať množstvo nových ako aj starých meračských zápisníkov. Veľkou pomocou bol program na spracovanie polygónového ťahu TJIKPR. Vyrovnaný polygón slúžil ako základ pre nový 166stranový atlas jaskyne, kreslený klasicky tušom na pauzák. Po dokončení atlasu sme však rýchlo narazili na problém ako dokresliť novoobjavené priestory do existujúceho atlasu, keďže uzavretie nových okruhov zmenilo súradnice všetkých bodov, nielen tých ktoré pribudli. Jedna možnosť bola prekresliť atlas nanovo alebo deformovať len novoobjavené časti.

Problémy sa nedali vyriešiť ani pomocou CAD programov. Nebolo totiž prakticky možné pridať nové merania bez úpravy starších častí mapy podľa novovypočítaných súradníc meračských bodov celej jaskyne. Postupne sme zistili, že vlastne neexistuje žiadny program schopný nakresliť kompletnú, vždy aktuálnu mapu (tj. nielen polygón s priestormi zadanými ako ĽPHD kvádre), v ktorej sú skôr skôr nakreslené priestory upravené podľa novovypočítaných súradníc bodov.

V roku 1999 sme začali rozmýšľat nad vlastným programom na kreslenie máp jaskýň. Poznali sme programy vhodné na riešenie niektorých čiastkových problémov. Bol tu METAPOST, vysokoúrovňový programovací jazyk na popis vektorovej grafiky, Survex na spracovanie polygónu a TeX na sadzbu výslednej mapy. Išlo len o to, ako ich spojiť. Na Vianoce 1999 bola funkčná predbežná verzia Therionu. Stačilo 32 kB skriptov v Perle a METAPOSTe na overenie správnosti a uskutočniteľnosti našej myšlienky.

V rokoch 2000--2001 sme hľadali optimálny formát dát, programovací jazyk, princípy interaktívneho mapového editora ako aj algoritmov s pomocou Martina Sluku z Prahy a Martina Hellera z Zürichu. Prvá skutočne použiteľná verzia Therionu vznikla v roku 2002.

===== Features =====

Therion is a command-line application. It processes input files, which are—including 2D maps—in text format, and creates files with 2D maps or 3D model as the output. The syntax of input files is described in detail in later chapters. You may create these files in an arbitrary plain text editor like //ed// or //vi//. They contain instructions for Therion like

''point 1303 1004 pillar''

where point is a keyword for point symbol followed by its coordinates and a symbol type specification.

Hand-editing of such files is not easy—especially when you draw maps, you need to think in spatial (Cartesian coordinate) terms. Thus there is a special GUI for Therion called XTherion. XTherion works as an advanced text editor, map editor (where maps are drawn fully interactively), compiler (which runs Therion on the data) and 3D model
viewer.

It may look quite complicated, but this approach has a lot of advantages:

  * There is strict separation of data and visualization. The data files specify only what is where, not what it looks like. The visual representation is added by METAPOST in later phases of data processing. (It’s very similar concept to XML data representation.) This makes it possible to change map symbols used without changing the input data, or merge more maps created by different persons in different styles into one map with unified map symbols set.\\ 2D maps are adapted for particular output scale (level of abstraction, non-linear scaling of symbols and texts)
  * All data are relative to survey station positions. If the coordinates of survey stations are changed in the process of loop closure, then all relevant data is moved correspondingly, so the map is always up-to-date.
  * Therion is not dependent on particular operating system, character encoding or input files editor; input files will remain human readable
  * It’s possible to add new output formats
  * 3D model is generated from 2D maps to get a realistic 3D model without entering too much data
  * although the support for WYSIWYG is limited, you get what you want

===== Software requirements =====

“A program should do one thing, and do it well.” (Ken Thompson) Therefore we use some valuable external programs, which are related to the problems of typesetting and data visualization. Therion can then do its task much better than if it was a standalone application in which you could calibrate your printer or scanner and with one click send
e-mail with your data.

Therion needs:

  * TeX distribution. Necessary only if you want to create 2D maps.
  * Tcl/Tk with //BWidget// and optionally //Tom// and //tkImg// extensions. It is only required for XTherion.

Windows installer includes TeX and Tcl/Tk distributions with all required extensions. Read the //Appendix// if you want to compile Therion yourself.

For displaying of maps and models you may use any of the following programs:

  * any PDF viewer like Acrobat Reader, ghostscript or xpdf for displaying 2D maps;
  * appropriate 3D viewer for models exported in other than default format;
  * any SQL database client to process exported database.

===== Instalace =====

**Instalace ze zdrojového kódu (therion-0.3.*.tar.gz):**

Zdrojový kód je hlávní způsob distribuce Therionu. Vyžaduje kompilaci a instalaci dle instrukcí v //[[czsk:thbook:6|Dodatku]]//.

**Instalace ve Windows:**

Spusťte instalační program a následujte instrukce. Bude nainstalováno vše potřebné a budou vytvořeny odkazy na XTherion a Therion Book v menu Start

**Nastavení prostředí**

Therion čte své nastavení z inicializačního souboru. Default settings should work fine for users using only ASCII (non-accented latin) characters, standard TeX and METAPOST. If you want to use accented latin or non-latin characters, edit initialization file. Patřičné instrukce jak to udělat najdete v //[[czsk:thbook:6|Dodatku]]//.

===== How does it work? =====

So, now it’s clear what Therion needs, let’s have a look at the way it interacts with all these programs:

{{ therion:1_1.png }}

DON’T PANIC! When your system is set-up right the majority of this is hidden from the user and all necessary programs are run automatically by Therion.

For working with Therion it is enough to know that you have to create input data (best done with XTherion), run Therion, and display output files (3D model, PDF map, log file) in the appropriate program.

For those who want to understand more about it, here is a brief explanation of the above flowchart. Program names are in roman font, data files in italics. Arrows show data flow between programs. Temporary data files are not shown. Meaning of colors:

  * black—Therion programs and macros (XTherion is written in Tcl/Tk, so it needs this interpreter to run)
  * red—TeX package
  * green—input files created by the user and output files created by Therion

Therion itself does the main task. It reads the input files, interprets them, finds closed loops and distributes errors. Next it transforms all other data (e.g. 2D maps) according to new stations position. Therion exports data for 2D maps in METAPOST format. METAPOST gives the actual shape to abstract map symbols according to map symbol definitions; it creates a lot of PostScript files with small fragments of the cave. These are read back and converted to a PDF-like format, which forms input data for pdfTeX. PdfTeX does all the typesetting and creates a PDF file of the cave map.

Therion also exports 3D model (full or centreline) in various formats. The model in the therion format may be loaded and displayed in the XTherion’s model viewer. Centreline may be exported for further processing in any SQL database.

===== První spuštění =====

Po vysvětlení základních principů Therionu je dobrý nápad vyzkoušet ukázková data.

  * Stáhněte si ukázková data ze stránek projektu Therion a rozbalte je někam na pevný disk vašeho počítače.
  * Spusťte XTherion (pod Unixem a MacOSX napsáním ‘xtherion’ na příkazovém řádku, pod Windows poklepáním na zástupce v menu Start).
  * V okně ‘Compiler’ otevřete soubor ‘thconfig’ z adresáře obsahujícího stažená ukázková data.
  * Stiskněte ‘F9’ nebo ‘compile’ v menu ke zpracování dat Therionem — zobrazí se vám nějaká hlášení o průběhu kompilace od programů Therion, METAPOST a TeX.
  * Vytvořené PDF mapy a 3D model nejdete v adresáři s ukázkovými daty. 

Dále můžete otevřít datové soubory s měřením (*.th) v okně ‘Text editor’ a datové soubory obsahující mapy (*.th2) v okně ‘Map editor’. Přestože datový formát může v prvním okamžiku vypadat složitě, vše bude vysvětleno v následujících kapitolách.