source: trunk/tutorial/model_tutorial.tex @ 22

Revision 21, 8.2 KB checked in by lucsch, 12 years ago (diff)
  • TmDmCreator is now working (supports language selection)
  • Adding swisstopo data model definition
RevLine 
[9]1%
2%  HOW TO BUILD TOOLMAP DATAMODEL
3%
4%  Created by Lucien Schreiber on 2013-02-19.
5%  Copyright (c) 2013. All rights reserved.
6%
7
8\documentclass[a4paper, 12pt]{article}
9\usepackage{crealp-report}
10\usepackage{upquote} %to force Latex not substitute ' by `
11\usepackage{tocbibind}
[10]12\usepackage{mdwlist}
[9]13%\usepackage{natbib}
14
15\begin{document}
16\crealptitle {Tutorial} {How to create a ToolMap datamodel using TmDmCreator} {Lucien Schreiber} {lucien.schreiber@crealp.vs.ch}
17\tableofcontents
18\pagebreak
19
20\section{Introduction}
[12]21This tutorial explains how to create a ToolMap project manually. This approach has the following advantages:
[10]22\begin{enumerate*}
[14]23  \item It ensures that the ID remain consistent
24  \item It could generate a multilingual model
[9]25  \item It allows better monitoring of model changes
[10]26\end{enumerate*}
[12]27The main disadvantage of this approach is the lack of user interface as well as the need for the user to have some knowledge of SQL. Finally, this approach has been developed to meet the need for rigor in the management of the Swiss geological data model.
[9]28
29
30\section{Conceptual Workflow}
31The diagram shown in figure~\ref{fig:conceptual-workflow} illustrates the proposed workflow. User edits the user\_structure.sql and user\_content.txt files. These files as well as base\_structure.sql are used by the software TmDmCreator to produces either:
[10]32\begin{enumerate*}
[9]33  \item a SQL file defining the project (output 1)
34  \item a ToolMap project (output 2)
[10]35\end{enumerate*}
[9]36
37\begin{figure} [htbp]
38        \centering
39    \includegraphics[width=1\textwidth]{img/workflow.pdf}
40    \caption{Conceptual workflow}
41    \label{fig:conceptual-workflow}
42\end{figure}
43
44
45
46\section{Data needed}
[14]47In order work, TmDmCreator needs the following files:
[10]48%\begin{itemize}
49    \begin{description*}
50  \item[base\_structure.sql]\hfill \\ contains the necessary SQL code base for all ToolMap projects. This file should normally not be edited by users
51  \item[user\_structure.sql]\hfill \\ contains the SQL structure describing the layers attributes
52  \item[user\_content.txt]\hfill \\ Is a tabular file (editable in Excel for example) containing the definition of layers, objects, and attribute values.
53\end{description*}
54%\end{itemize}
55The recommended way to work with user\_structure.sql and user\_content.txt is described below
[9]56
[14]57\clearpage
[9]58\section{Preparing user data}
59
60\subsection{Layers}
[12]61Open user\_content.txt using a spreadsheet and edit the thematic\_layers part. Each of the layers that we want to export should appear here. The structure is as follows (see figure~\ref{fig:layers}):
[11]62\begin{description*}
63  \item [LAYER\_INDEX] unique identifier of the layer
64  \item [TYPE\_CD] layer spatial type as follow
65    \begin{description*}
[12]66      \item [0] = Line
67      \item [1] = Point
68      \item [2] = Polygon
[11]69    \end{description*}
70  \item [LAYER\_NAME] the layer name. This name will be given to the SHP file when exporting
71\end{description*}
[9]72
[14]73Make sure you choose an Unicode format (Unicode Text (*.txt) or UTF-16 Unicode Text (*.txt)) when saving from the spreadsheet.
74
[12]75\begin{figure} [hbp]
76        \centering
77    \includegraphics[width=.6\textwidth]{img/layers.png}
78    \caption{List of layers as shown in user\_content.txt}
79    \label{fig:layers}
80\end{figure}
81
[9]82\subsection{Objects}
[13]83\label{sec:objects}
[9]84
[12]85Edit the file user\_content.txt to add objects. They must have the following structure (See figure:~\ref{fig:objects}):
86\begin{description*}
87  \item [OBJECT\_ID] object unique ID.
88  \item [OBJECT\_CD] object code, should not necessarily be unique
89  \item [OBJECT\_TYPE\_CD] object spatial type, uses same values as those described above for TYPE\_CD in thematic\_layers
[14]90  \item [THEMATIC\_LAYERS\_LAYER\_INDEX] the index of the layer that the object refers to. The value 1 shown in the example (Figure~\ref{fig:objects}) therefore relates to the theme Boreholes\_PT.
[12]91  \item [OBJECT\_DESC\_0,1,2,3,4,5] object description in up to 5 languages.
92  \item [OBJECT\_ISFREQ] Set to 1 for frequent objects and 0 otherwise. This parameter is only taken into account for line type objects. Set to 0 for all point or polygon objects.
93  \item [SYMBOL\_CD] leave empty
94  \item [RANK] leave empty
95  \item [REMARK] leave empty
96\end{description*}
97
98\begin{figure} [hbp]
99        \centering
100    \includegraphics[height=.9\textheight]{img/objects.png}
101    \caption{Objects structure as described in user\_content.txt}
102    \label{fig:objects}
103\end{figure}
104
105
[9]106\subsection{Attributes structure}
[14]107Edit the file user\_structure.sql with Notepad (or even better with Notepad + +). For each layer containing attributes, there must be a SQL code of the type:
[9]108
[12]109\crealplisting{SQL}
110\begin{lstlisting}
111-- layer_at1 --
112CREATE TABLE `layer_at1` (
113  `OBJECT_ID` int(10) unsigned NOT NULL,
[13]114  -- add user attributes here --
[12]115  PRIMARY KEY (`OBJECT_ID`),
116  KEY `LAYER_ATX_FKIndex1` (`OBJECT_ID`)
[21]117) ENGINE=MyISAM DEFAULT CHARSET=utf8;
[12]118\end{lstlisting}
[13]119This code is the basic template for creating an attribute table. The number after layer\_at (see line 2) indicates the layer index and refers to the LAYER\_INDEX column in user\_content.txt. In our example layer\_at1 describe the attributes for the layer Boreholes\_PT. User attributes can then be added on line 4 of this template.
120Below are described the five attributes that can be used in a ToolMap data model as well as the corresponding SQL code
[14]121\subsubsection {Enumeration}
122\label{sec:enumeration}
[12]123    \crealplisting{SQL}
124    \begin{lstlisting}
125    `D_C_UNDERG` int(11) DEFAULT NULL COMMENT 'ENUMERATION',
126    \end{lstlisting}
127    If you add such fields, then you must also fill the list of supported values (see section~\ref{sec:attribute-values}).
[13]128    \subsubsection {Text}
[12]129    \begin{lstlisting}
130    `DESCRIPT` varchar(255) DEFAULT NULL,
131    \end{lstlisting}
132    The number next to the keyword varchar indicates the maximum text length.
[13]133    \subsubsection {Integer}
[12]134    \begin{lstlisting}
135    `NUM_REF` int(11) DEFAULT NULL,       
136    \end{lstlisting}
137    There is no special option for integer fields
[13]138  \subsubsection {Float}
[12]139
140    \begin{lstlisting}
141    `TEMP` decimal(5,2) DEFAULT NULL,
142    \end{lstlisting}
143    The two digits next to the keyword decimal indicate the field precision and scale. In this example, 5 is the precision and 2 is the scale. The precision represents the number of significant digits that are stored for values, and the scale represents the number of digits that can be stored following the decimal point. In this case, values that can be stored range from -999.99 to 999.99.
[13]144    \subsubsection {Date}
[12]145
146    \begin{lstlisting}
147    `REF_DATE` date DEFAULT NULL,
148    \end{lstlisting}
149    There is no special option for date fields
150
151
[13]152\subsection{Attributes values}
[12]153\label{sec:attribute-values}
[14]154For each enumeration field  previously added in the user\_structure.sql file, it is necessary to define the allowed values. Therefore it is necessary to edit the attributes section of user\_content.txt. The structure of the attributes section is shown in Figure~\ref{fig:attributs}. This table is divided into two parts, the first three columns describe the attribute fields, the remaining columns describe the values supported by these fields. Below is a description of each column.
[9]155
[13]156\begin{description*}
157  \item [ATTRIBUT\_ID] attribute unique ID.
[14]158  \item [LAYER\_INDEX] the index of the layer that the attribute refers to. The value 1 shown in the example (Figure~\ref{fig:attributs}, row 42 and 43) therefore relates to the theme Boreholes\_PT.
[13]159  \item [ATTRIBUT\_NAME] attribute name. This name will be used as the column name in the exported SHP. Some limitations apply to SHP format for column names, for more information you can refer to \url{http://en.wikipedia.org/wiki/Shapefile#Shapefile\_attribute\_format\_.28.dbf.29} or \url{http://www.gdal.org/ogr/drv\_shapefile.html} 
160  \item [CATALOG\_ID] attribute value unique ID
161  \item [CODE] attribute value code, should not necessarily be unique
162  \item [DESCRIPTION\_0,1,2,3,4,5] attribute value description in up to 5 languages. The order of language is not important, but it must be identical to the one chosen for the objects (see~\ref{sec:objects}).
[9]163
[13]164\end{description*}
[12]165
[13]166\begin{figure} [htbp]
167        \centering
168    \includegraphics[width=.9\textwidth]{img/attributs.png}
169    \caption{Attributes section structure}
170    \label{fig:attributs}
171\end{figure}
172
173
174
[9]175\end{document}
Note: See TracBrowser for help on using the repository browser.