====== Zpracování dat ======

Vedle datových souborů, které obsahují měřičské údaje, používá Therion konfigurační soubor obsahující instrukce jak mají být data prezentována.

===== Konfigurační soubor =====

Název konfiguračního souboru může být therionu předán jako argument. Pokud není specifikováno jinak, hledá Therion soubor pojmenovaný ''thconfig'' v aktuálním pracovním adresáři. Ten je čten jako ostatní therionské soubory (t.z. jeden příkaz na řádek; prázdné řádky nebo řádky začínající ‘''#''’ jsou ignorovány; příkazy ukončené zpětným lomítkem na konci řádku pokračují na dalším řádku). Seznam v současné době podporovaných příkazů:

==== ‘encoding’ ====

Funguje stejně jako stejnojmenný příkaz v datových souborech - specifikuje znakovou sadu.

==== ‘input’ ====

Funguje stejně jako stejnojmenný příkaz v datových souborech - zahrnuje obsah jiných souborů

==== ‘source’ ====

//Popis:// Specifikuje které zdrojové (datové) soubory má Therion číst. Můžete takto specifikovat několik souborů; vždy jeden na řádek. Stejný význam má použití volby ''-s'' na příkazovém řádku (viz. níže)

//Syntaxe://

  source <název-souboru>

//Argumenty://

  * ''<název-souboru>''

==== ‘select’ ====

//Description:// selects objects (surveys and maps) for export. By default, all survey objects are selected. If there is no map selected, all maps belonging to selected surveys are selected by default for map export. If there are no such maps, centreline from the selected surveys is exported in the map.

//Syntax://

  select <object> [OPTIONS]

//Arguments://

  * <object> -> any survey or map, identified by its ID.

//Options://
  * ''recursive <on/off>'' -> valid only when a survey is selected. If set on (by default) all subsurveys of the given survey are recursively selected/unselected.
  * ''map-level <number>'' -> valid only when a map is selected. Determines the level at which map expansion for atlas export is stopped. By default 0 is used; if “basic” is specified, expansion is done up to the basic maps. //Note:// Map previews are displayed only as specified in maps in the current map-level.
  * ''chapter-level <number>'' -> valid only when a map is selected. Determines the level at which chapter expansion for atlas export is stopped. By default 0 is used, if “-” or “.” is specified, no chapter is exported for this map. If ''title-pages'' option in layout is on, each chapter starts with a title page.

==== ‘unselect’ ====

//Popis:// vyloučí objekty z exportu.

//Syntaxe:// 

  unselect <objekt> [VOLBY]

//Argumenty://

Stejné jako u příkazu [[czsk:thbook:3#select|select]].

//Volby://

Stejné jako u příkazu [[czsk:thbook:3#select|select]].

==== ‘layout’ ====

//Popis:// Specifies layout for 2D maps. Nastavení týkající se atlas módu jsou označena ‘A’; map módu ‘M’.

//Syntaxe://

  layout <id> [VOLBY]
    copy <source layout id>
    scale <picture length> <real length>
    base-scale <picture length> <real length>
    rotate <number>
    symbol-set <symbol-set>
    symbol-assign <point/line/area/group/special> <symbol-type> \
                                                  <symbol-set>
    symbol-hide <point/line/area/group/special> <symbol-type>
    symbol-show <point/line/area/group/special> <symbol-type>
    size <width> <height> <units>
    overlap <value> <units>
    page-setup <dimensions> <units>
    page-numbers <on/off>
    exclude-pages <on/off> <list>
    title-pages <on/off>
    nav-factor <factor>
    nav-size <x-size> <y-size>
    transparency <on/off>
    opacity <value>
    surface <top/bottom/off>
    surface-opacity <value>
    layers <on/off>
    grid-origin <x> <y> <x> <units>
    grid-size <width> <height> <units>
    origin <x> <y> <z> <units>
    origin-label <x-label> <y-label>
    own-pages <number>
    page-grid <on/off>
    legend <on/off/all>
    legend-columns <number>
    legend-width <n> <units>
    map-comment <string>
    map-header <x> <y> <off/n/s/e/w/ne/nw/se/sw/center>
    statistics <explo/topo/carto/copyright all/off/number>
               <explo/topo-length on/off>
    scale-bar <length> <units>
    language <xx[_YY]>
    colour/color <item> <colour>
    debug <on/all/first/second/off>
    doc-author <string>
    doc-keywords <string>
    doc-subject <string>
    doc-title <string>
    code <metapost/tex-map/tex-atlas>
  endlayout

//Argumenty://

''<id>'' -> layout identifier (to be used in the ''export'' command)

//Command-like options://

  * ''copy <source layout id>'' -> set properties here that are not modified based on the given source layout.

//- map presentation-related://

  * ''scale <picture length> <real length>'' -> set scale of output map or map atlas (M, A; default: ''1 200'')
  * ''base-scale <picture length> <real length>'' -> if set, Therion will optically scale the map by a (''scale/base-scale'') factor. This has the same effect as if the map printed in ''base-scale'' would be photoreduced to the ''scale''. (M, A)
  * ''rotate <value>'' -> rotates the map (M, A; default: ''0'')
  * ''symbol-set <symbol-set>'' -> use ''symbol-set'' for all map symbols, if available (M, A)\\ Therion uses following predefined symbol sets:\\ ''UIS'' (International Union of Speleology)\\ ''ASF'' (Australian Speleological Federation)\\ ''CCNP'' (Carlsbad Caverns National Park)\\ ''SKBB'' (Speleoklub Banská Bystrica)
  * ''symbol-assign <point/line/area/group/special> <symbol-type> <symbol-set>'' -> display a particular symbol in the given symbol-set. This option overrides symbol-set option.\\ If the symbol has a subtype, ''<symbol-type>'' argument may have one of the following forms: ''type:subtype'' or simply ''type'', which assigns new symbol set to all subtypes of a given symbol.\\ Following symbols may not be used with this option: point //section// (which isn’t rendered at all) and all point and line labels (//label, remark, altitude, height, passage-height, station-name, date//). See the chapter //Changing layout/Customizing text labels// for details how to change labels’ appearance. (M, A)\\ Group may be one of the following: all, centerline, sections.\\ There are two special symbols: north-arrow, scale-bar.
  * ''symbol-hide <point/line/area/group/special> <symbol-type>'' -> don’t display particular symbol or group of symbols. You may use ''group cave-centerline'', ''group surface-centerline'', ''point cave-station'' and ''point surface-station'' in ''symbolhide'' and ''symbol-show'' commands. May be combined with ''symbol-show''.(M, A)
  * ''symbol-show <point/line/area/group/special> <symbol-type>'' -> display particular symbol or group of symbols. May be combined with ''symbol-hide''. (M, A)

//- page layout related://

  * ''size <width> <height> <units>'' -> set map size in the atlas mode. In map mode applies if ''page-grid'' is ''on'' (M, A; default: ''18 22.2 cm'')
  * ''overlap <value> <units>'' -> set overlap size in paper units in the atlas mode or map margin in the map mode (M, A; default: ''1 cm'')
  * ''page-setup <dimensions> <units>'' -> set page dimensions in this order: paper-width, paper-height, page-width, page-height, left-margin and top-margin (A; default: ''21 29.7 20 28.7 0.5 0.5 cm'')
  * ''page-numbers <on/off>'' -> turn on/off page numbering (A; default: ''true'')
  * ''exclude-pages <on/off> <list>'' -> exclude specified pages from cave atlas. The list may contain page numbers separated by a comma or dash (for intervals) e.g. ''2,4-7,9,23'' means, that pages 2, 4, 5, 6, 7, 9 and 23 should be omitted. Only the map pages should be counted. (Set ''own-pages 0'' and ''title-pages off'' to get the correct page numbers to be excluded.) Changes of ''own-pages'' or ''title-pages'' options don’t affect page excluding. (A)
  * ''title-pages <on/off>'' -> turn on/off title pages before each atlas chapter (A; default: ''off'')
  * ''nav-factor <factor>'' -> set atlas navigator zoom factor (A; default: ''30'')
  * ''nav-size <x-size> <y-size>'' -> set number of atlas pages in both directions of navigator (A; default: ''2 2'')
  * ''transparency <on/off>'' -> set transparency for the passages (underlying passages are also visible) (M, A; default: ''on'')
  * ''opacity <value>'' -> set opacity value (used if ''transparency'' is ''on''). Value range is 0–100. (M, A; default: ''70'')
  * ''surface-opacity <value>'' -> set the surface bitmap opacity (used if ''transparency'' is ''on''). Value range is 0–100. (M, A; default: ''70'')
  * ''surface <top/bottom/off>'' -> set the position of the surface bitmap above/below the map. (M, A; default: ''off'')
  * ''layers <on/off>'' -> enable/disable PDF 1.5 layers (M, A; default: ''on'')
  * ''grid-origin <x> <y> <x> <units>'' -> set coordinates of grid origin (M, A) [Grid is currently not supported.]
  * ''grid-size <width> <height> <units>'' -> set grid size in real units (M, A; default ''10 m'')
  * ''origin <x> <y> <z> <units>'' -> set origin of atlas pages (M, A)
  * ''origin-label <x-label> <y-label>'' -> set label for atlas page which has the lower left corner at the given origin coordinates (M, A; default: ''0 0'')
  * ''own-pages <number>'' -> set number of own pages added before the first page of automatically generated pages in atlas mode (currently required for correct page numbering) (A; default: ''0'')
  * ''page-grid <on/off>'' -> show pages key plan (M; default: ''off'')

//- map legend related://

  * ''map-header <x> <y> <off/n/s/e/w/ne/nw/se/sw/center>'' -> print map header at location specified by ''<x> <y>''. Predefined map header contains some basic informations about cave: name, scale, north arrow, list of surveyors etc. It is fully customizable (see the chapter //Changing layout// for details). Ranges for ''<x>'' and ''<y>'' are -100–200. Lowerleft corner of the map is ''0 0'', upper-right corner is ''100 100''. The header is aligned with the specified corner or side to this anchor point. (M; default: ''0 100 nw'')
  * ''legend-width <n> <units>'' -> legend width (M, A; default: ''14 cm'')
  * ''legend <on/off/all>'' -> display list of used map symbols in the map header. If set to all, all symbols from the current symbol set are displayed. (M, A; default: ''off'')
  * ''legend-columns <number>'' -> adjusts the number of legend columns (M, A; default: ''2'')
  * ''map-comment <string>'' -> optional comment displayed at the map header (M)
  * ''statistics <explo/topo/carto/copyright all/off/number>'' or
  * ''statistics <explo/topo-length on/off>'' -> display some basic statistics (M, A; default: ''off'')
  * ''scale-bar <length> <units>'' -> set the length of the scale-bar (M, A)
  * ''language <xx[_YY]>'' -> set output language. Currently supported languages are ''sk'' (Slovak), ''en'' (English), ''cz'' (Czech) and ''fr'' (French). See the //Appendix// if you want to add or customize translations. (M, A)
  * ''colour/color <item> <colour>'' -> customize colour for special map items (map-fg, map-bg, preview-above, preview-below). Colour range is 0–100 for grayscale, [0–100 0–100 0–100] triplet for RGB colours.
  * ''debug <on/all/first/second/off>'' -> draw scrap in different stages of transformation in different colours to see how Therion distorts map data. See the description of ''scrap'' command for details. The points with distance changed most during transformation are displayed orange.

//- PDF related://

  * ''doc-author <string>'' -> set document author (M, A)
  * ''doc-keywords <string>'' -> set document keywords (M, A)
  * ''doc-subject <string>'' -> set document subject (M, A)
  * ''doc-title <string>'' -> set document title (M, A)

//- customization://

  * ''code <metapost/tex-map/tex-atlas>'' -> Add/redefine TEX and METAPOST macros here. This allows user to configure various things (like user defined symbols, map and atlas layout at one place &c.) See the chapter //Changing layout// for details.

{{ therion:3_1.png }}

==== ‘export’ ====

//Description:// Exports selected surveys or maps.

//Syntax://

  export <type> [OPTIONS]

//Arguments://

  * ''<type>'' -> The following export types are supported:\\ ''model'' -> 3D model of the cave\\ ''map'' -> one page 2D map\\ ''atlas'' -> 2D atlas in more pages\\ ''database'' -> SQL database with centreline

//Options://

- //common://

  * ''output/o <file>'' -> set output file name. If no file name is given the prefix “''cave.''” is used with an extension corresponding to output format.

- //model://

  * ''format/fmt <format>'' -> set model output format. Currently the following output formats are supported: ''therion'' (native format; default), ''compass'' (plt file), ''survex'' (3d file), ''vrml'' and ''3dmf''.
  * ''enable <walls/[cave/surface-]centerline/surface/all>'' and
  * ''disable <walls/[cave/surface-]centerline/surface/all>'' -> selects which features to export, if the format supports it. Surface is currently exported in therion format only.

- //map/atlas://

  * ''projection <id>'' -> unique identifier that specifies the map projection type. (See the
''scrap'' command for details.)\\ If there is no map defined, all scraps in the given projection are exported.\\ If there are no scraps with the specified projection then Therion will display centreline from selected surveys.
  * ''layout <id>'' -> use predefined map or atlas layout.
  * ''layout-xxx'' -> where xxx stands for other layout options. Using this you can change some layout properties directly within the export command.
  * ''format/fmt <format>'' -> set map format. Currently only ''pdf'' format is supported.

- //database://

  * format/fmt <format> -> currently only sql
  * encoding/enc <encoding> -> set output encoding

===== Spuštění Therionu =====

Po zvládnutí struktury datových a konfiguračních souborů jsme připraveni spustit Therion. Ten obvykle spustíme z datového adresáře napsáním 

  therion

na příkazové řádce

Plná syntaxe je

  therion [-q] [-L] [-l <log-soubor>]
          [-s <zdrojový-soubor>] [-p <cesta-kde-má-hledat>]
          [-g/-u] [-i] [-d] [-x] [--use-extern-libs] [<konfigurační-soubor>]

nebo

  therion [-h/--help]
          [-v/--version]
          [--print-encodings]
          [--print-tex-encodings]
          [--print-init-file]
          [--print-environment]

//Argumenty://

''<konfigurační-soubor>'' Therion akceptuje pouze jeden volitelný argument: jméno konfiguračního souboru. Pokud není soubor uveden, je použit soubor ''thconfig'' z aktualního adresáře. Pokud soubor neexistuje (např. aktuální adresář není datový adresář) skončí Therion s chybovou hláškou.

//Volby://
  * ''-d'' -> Zapnutí ladícího (debug) módu. Vytvoří dočasný adresář pojmenovaný ''thTMPDIR'' (ve vašem systémovém dočasném adresáři) a nesmaže žádné dočasné soubory.
  * ''-g'' -> Vytvoří nový konfigurační soubor. This will be the given ''<cfg-file>'' if specified, or ''thconfig'' in the current directory if not. Pokud soubor existuje bude přepsán.
  * ''-h'', ''--help'' -> Zobrazí krátkou nápovědu.
  * ''-i'' -> Ignore comments when writing ''-g'' or ''-u'' configuration file.
  * ''-L'' -> Nevytvářej log soubor. Normálně Therion zapíše všechna hlášení do souboru therion.log v aktuálním adresáři.
  * ''-l <log-soubor>'' -> Změní jméno log souboru.
  * ''-p <cesta-kde-má-hledat>'' -> Nastaví cestu (nebo seznam cest oddělených čárkou), kde bude Therion hledat zdrojové soubory (pokud je nenajde v pracovním adresáři).
  * ''-q'' -> Spustí Therion v tichém módu. Vypíše pouze varování a chybová hlášení na STDERR.
  * ''--print-encodings'' -> Vypíše seznam podporovaných znakových sad.
  * ''--print-tex-encodings'' -> Vypíše seznam podporovaných znakových sad pro PDF výstup.
  * ''--print-init-file'' -> Print a default initialization file. Podrobnější popis najdete v části //Initialization// v //[[czsk:thbook:6|Dodatku]]//.
  * ''-s <zdrojový-soubor>'' -> Nastaví jméno zdrojového souboru.
  * ''-u'' -> Upgrade the configuration file.
  * ''--use-extern-libs'' -> Don’t copy TEX and METAPOST macros to working directory. TEX and METAPOST should search for them on their own. Use with caution.
  * ''-v'', ''--version'' -> Zobrazí informaci o verzi programu.
  * ''-x'' -> Vytvoří soubor ‘''.xth-thconfig''’ obsahující dodatečné informace pro XTherion.

==== XTherion — okno Compiler ====

Xtherion usnadňuje spuštění Therionu zvláště na systémech bez příkazové řádky. Okno Compiler je výchozím pro XTherion. Ke spuštění Therionu stačí otevřít konfigurační soubor a stisknout 'F9' nebo tlačítko 'Compile'.

Xtherion zobrazuje hlášení Therionu v dolní části obrazovky. Každé chybové hlášení je zvýrazněno a je zároveň linkem do zdrojového souboru obsahujícího chybu.

Po prvním spuštění se aktivují doplňková menu Survey structure a Map structure. Uživatel může dvojklikem na některou z položek ve stromové struktuře pohodlně vybrat měření nebo mapu pro export (viz. [[czsk:thbook:3#select|select]]). Jednoduché kliknutí ve stromové struktuře měření zobrazí v menu Survey info základní informace o měření.