This is an automated email from the git hooks/post-receive script. mfv-guest pushed a commit to branch master in repository totalopenstation.
commit ebf636864c33bfc530e39c2d66ff6a874c7cac23 Author: Matteo F. Vescovi <mfvesc...@gmail.com> Date: Thu Jul 31 10:19:07 2014 +0200 debian/: manual pages added Closes: #755381 --- debian/manpages/totalopenstation-cli-connector.1 | 32 + debian/manpages/totalopenstation-cli-parser.1 | 41 ++ debian/manpages/totalopenstation-gui.1 | 790 +++++++++++++++++++++++ debian/totalopenstation.manpages | 1 + 4 files changed, 864 insertions(+) diff --git a/debian/manpages/totalopenstation-cli-connector.1 b/debian/manpages/totalopenstation-cli-connector.1 new file mode 100644 index 0000000..3eb3844 --- /dev/null +++ b/debian/manpages/totalopenstation-cli-connector.1 @@ -0,0 +1,32 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.45.1. +.TH TOTALOPENSTATION-CLI-CONNECTOR "1" "July 2014" "totalopenstation-cli-connector 0.3" "User Commands" +.SH NAME +totalopenstation-cli-connector \- Command-line connector to Total Station +.SH SYNOPSIS +.B totalopenstation-cli-connector +[\fI\,option\/\fR] \fI\,arg1 \/\fR[\fI\,option\/\fR] \fI\,arg2 \/\fR... +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-m\fR MODEL, \fB\-\-model\fR=\fI\,MODEL\/\fR +select input MODEL +.TP +\fB\-p\fR PORT, \fB\-\-port\fR=\fI\,PORT\/\fR +select input SERIAL PORT +.TP +\fB\-o\fR FILE, \fB\-\-outfile\fR=\fI\,FILE\/\fR +select output FILE (do not specify for stdout) +.SH "SEE ALSO" +The full documentation for +.B totalopenstation-cli-connector +is maintained as a Texinfo manual. If the +.B info +and +.B totalopenstation-cli-connector +programs are properly installed at your site, the command +.IP +.B info totalopenstation-cli-connector +.PP +should give you access to the complete manual. diff --git a/debian/manpages/totalopenstation-cli-parser.1 b/debian/manpages/totalopenstation-cli-parser.1 new file mode 100644 index 0000000..256ce22 --- /dev/null +++ b/debian/manpages/totalopenstation-cli-parser.1 @@ -0,0 +1,41 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.45.1. +.TH TOTALOPENSTATION-CLI-PARSER "1" "July 2014" "totalopenstation-cli-parser 0.3" "User Commands" +.SH NAME +totalopenstation-cli-parser \- Command-line parser for Total Station data +.SH SYNOPSIS +.B totalopenstation-cli-parser +[\fI\,option\/\fR] \fI\,arg1 \/\fR[\fI\,option\/\fR] \fI\,arg2 \/\fR... +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-i\fR FILE, \fB\-\-infile\fR=\fI\,FILE\/\fR +select input FILE (do not specify for stdin) +.TP +\fB\-o\fR FILE, \fB\-\-outfile\fR=\fI\,FILE\/\fR +select output FILE (do not specify for stdout) +.TP +\fB\-f\fR FORMAT, \fB\-\-input\-format\fR=\fI\,FORMAT\/\fR +select input FORMAT +.TP +\fB\-t\fR FORMAT, \fB\-\-output\-format\fR=\fI\,FORMAT\/\fR +select input FORMAT +.TP +\fB\-\-overwrite\fR +overwrite existing output file +.TP +\fB\-\-list\fR +list the available input and output formats +.SH "SEE ALSO" +The full documentation for +.B totalopenstation-cli-parser +is maintained as a Texinfo manual. If the +.B info +and +.B totalopenstation-cli-parser +programs are properly installed at your site, the command +.IP +.B info totalopenstation-cli-parser +.PP +should give you access to the complete manual. diff --git a/debian/manpages/totalopenstation-gui.1 b/debian/manpages/totalopenstation-gui.1 new file mode 100644 index 0000000..11154ba --- /dev/null +++ b/debian/manpages/totalopenstation-gui.1 @@ -0,0 +1,790 @@ +.\" Man page generated from reStructuredText. +. +.TH "TOTALOPENSTATION" "1" "July 31, 2014" "0.3" "Total Open Station" +.SH NAME +totalopenstation \- Total Open Station 0.3.0 +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH FOR USERS +.SS Requirements +.sp +TotalOpenStation is written using the \fI\%Python\fP language. Thus you\(aqll need to +have a working installation of the current version of a Python of your choice. +.sp +Across these pages we will refer to the standard \fI\%Python\fP distribution. +.sp +Obviously, we\(aqre not going to reinvent the wheel, so we have chosen to use +some Python libraries for some specific tasks: +.INDENT 0.0 +.IP \(bu 2 +the \fI\%pySerial\fP library +.IP \(bu 2 +the Python \fI\%Tkinter\fP GUI library, which comes with the standard +Python setup +.UNINDENT +.sp +pySerial is needed for downloading data from the serial port (even +through a \fIserial\-USB adapter\fP). +.sp +Tkinter is at the moment responsible of the Graphical User +Interface. This might change in future releases of Total Open +Station. +.SS Getting Python +.sp +If you\(aqre on GNU/Linux or a recent Mac OSX, Python should be already +installed on your system, so you just need to get the mentioned +libraries. +.sp +On Windows, you can get an installer from the main Python website, in +the \fI\%download\fP section. +.SS Getting libraries +.sp +Generally speaking, refer to the \fI\%pySerial website\fP\&. +.SS GNU/Linux +.sp +Use your package manager (\fBapt\-get\fP, \fByum\fP) and look +for a package named \fBpython\-serial\fP or \fBpyserial\fP and install +it. To test whether the installation went fine, open a terminal, start +the python interpreter with \fBpython\fP and at the prompt type \fBimport +serial\fP then return. It should say nothing, like this: +.sp +.nf +.ft C +>>> import serial +.ft P +.fi +.sp +If it complains, something went wrong: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +>>> import serial +Traceback (most recent call last): + File "<stdin>", line 1, in <module> +ImportError: No module named serial +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +and you need to check with your distribution package manager and bug +reporting system. +.SS Mac OSX +.sp +The simplest way is probably to install setuptools and use: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +easy_install \-U pyserial +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Microsoft Windows +.sp +The pySerial website has executable installers for various versions of +this operating system. As pySerial\(aqs documentation says, you will need +also the \fI\%pywin32\fP library by Mark Hammond. +.SS Installing +.sp +There are a few different ways to install Total Open Station, +depending on your operating system. If you are on GNU/Linux or Mac +OSX, you should already have Python installed on your +system. Instructions for Microsoft Windows are below. +.SS Using \fBpip\fP +.sp +Until your operating system\(aqs packaging tools (e.g. \fBapt\fP or +\fByum\fP) allow you to install Total Open Station along with other +programs, the recommended way to install is using \fBpip\fP, like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +pip install totalopenstation +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This will install all the other required Python packages as +well. \fBpip\fP is complementary with \fI\%virtualenv\fP, and it is encouraged +that you use virtualenv to isolate your installation: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +pip \-E tops install totalopenstation +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +where \fB\-E tops\fP creates a virtual environment named \fBtops\fP and +installs totalopenstation into it. +.sp +Read more about \fBpip\fP at \fI\%http://pip.openplans.org/\fP and +\fI\%http://guide.python\-distribute.org/pip.html\fP . +.SS Manual install with \fBsetup.py\fP +.sp +If you manually download the source distribution file from PyPI or +from the mercurial repository, first make sure you have installed all +the \fIrequired packages\fP\&. Then, just \fBcd\fP into +the uncompressed directory and: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +python setup.py install +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Again, it\(aqs strongly recommended to avoid a system\-wide install. Use +\fBvirtualenv\fP\&. +.SS Windows +.sp +There is a binary installer available at \fI\%PyPI\fP\&. This requires you to +install a \fI\%Python\fP distribution (latest available is 2.7.1 ‒ do not +install Python 3 as we don\(aqt support it yet), and the \fI\%pyserial\fP and +\fI\%setuptools\fP modules. +.SS Getting sample data +.sp +Even when your device is not listed among the supported ones, Total +Open Station can still be useful, particularly for: +.INDENT 0.0 +.IP 1. 3 +finding the right \fBserial connection parameters\fP from an unknown +device. You can play with the 8 options and see the results in a +text area. Once the downloaded results look good, you can be almost +sure that you have used the right parameters, and we can add the +tested model parameters to the program database; +.IP 2. 3 +retrieving \fBsample data\fP from unknown models and submit them to +allow support of those models in future releases of the program. +.UNINDENT +.sp +To do this, you can just use the main Total Open Station +executable. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Remember: Total Open Station is no wizard, and you have to tune the +serial port options using your prior knowledge of your total +station (e.g. read the manual that came with it, look at other +programs\(aq options). +.UNINDENT +.UNINDENT +.SS Glossary +.INDENT 0.0 +.TP +.B input format +An input format is the way data downloaded from the total +station are encoded. This might include a default order for X, +Y and Z coordinates, particular ways of prefixing each point +with some distinctive text string and other features. Each +input format is unique, and it requires a dedicated +module. Input formats are not readable by common CAD or GIS +software packages, and it is TOPS\(aqs work to export them. These +formats have a standard name, either given by the manufacturer +or by the TOPS development team. +.TP +.B model +When we refer to a \fImodel\fP we mean all total stations that +have the same brand name and manufacturer (e.g. all those +labeled “Trimble Geodimeter 600”). +.TP +.B output format +A format readable by GIS, CAD or any sort of common software, +like CSV or DXF. +.TP +.B serial\-USB adapter +While most total stations have a serial interface (port and cable), +modern PCs and laptops tend to have just USB ports. In such cases, it +is possible to use a serial\-USB adapter cable, that enables you to +connect the total station to one of your USB ports. Depending on your +platform, the device might be identified as \fB/dev/ttyUSB0\fP or +\fBCOM5\fP\&. +.UNINDENT +.SS Users of Total Open Station +.sp +So far, Total Open Station has been successfully used by: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +Università di Siena, \fI\%Dipartimento di Archeologia e Storia delle +Arti\fP, for the excavations at Gortyna and Vignale +.IP \(bu 2 +\fI\%Oxford Archaeology\fP, for fieldwork, using the \fI\%OpenMoko\fP mobile +platform +.IP \(bu 2 +\fI\%Arke_Geomática\fP has blogged about TOPS +.IP \(bu 2 +\fI\%Arc\-Team\fP: we have added support for the Trimble “area” format +after Arc\-Team sent us some sample data +.IP \(bu 2 +Università di Padova +.UNINDENT +.UNINDENT +.UNINDENT +.sp +If you\(aqre in the number of happy users, let us know. +.SH FOR DEVELOPERS +.SS Models +.SS General concepts +.sp +General concepts here about models and abstract classes. +.SS \fBleica_tcr_1205\fP \-\- Leica TCR 1205 +.SS Description +.sp +This is a quite recent total station. Data were provided by Joseph Reeves of +Oxford Archaeology. +.SS Connection +.INDENT 0.0 +.TP +.B Baudrate +higher than 19200 +.TP +.B Bytesize +8 +.UNINDENT +.sp +/1/no +.SS Data format +.sp +The data format is ASCII, quite simple. +.sp +The only thing to note is that data dumps contain both relative and absolute +measures. +.SS Other notes +.SS \fBnikon_npl_350\fP \-\- Nikon NPL\-350 +.sp +Download is in ASCII format. +.sp +Even the brute method \fBcat /dev/ttyS0 > file\fP creates an ASCII file without +any problem, so probably the default parameters for the serial port are OK. +.SS \fBzeiss_elta_r55\fP \-\- Zeiss Elta R55 +.SS Description +.sp +This is a quite old device, in use at the University of Siena. The +first steps in TOPS development were achieved with it. +.SS Connection +.INDENT 0.0 +.TP +.B Baudrate +9600 +.TP +.B Bytesize +7 +.TP +.B Parity +None +.UNINDENT +.SS Output formats +.sp +The Zeiss Elta R55 total station can output data in four different +formats, only one of which is currently supported: +.INDENT 0.0 +.IP \(bu 2 +\fIif_zeiss_rec_500\fP +.IP \(bu 2 +Zeiss R\-4 +.IP \(bu 2 +Zeiss R\-5 +.IP \(bu 2 +Zeiss R\-E +.UNINDENT +.SS Other notes +.sp +The hardware interface consists of a serial RS232 cable, that works also with +a common \fIserial\-USB adapter\fP . +.SS Other models +.sp +Unimplemented \fImodels\fP can be added to TotalOpenStation. +.sp +The best way to have your model included in the next version of +TotalOpenStation is to file a support request in the bug tracker and attach +some sample data dumps obtained with the Helper application. +.sp +If you can write Python code, you can also write a module by yourself using +the existing ones as a guide. Should you write a module, we will be happy to +receive it and include it in the TotalOpenStation source tree. +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fIcontributing\fP page to find out how to join the project and +participate actively to the development. +.UNINDENT +.UNINDENT +.SS Input formats +.sp +New in version 0.2: Total Open Station supports a number of input data formats, which +are implemented separately from the device handling machinery +(i.e. downloading data from your total station). This is because +one device can output more than one format, and at the same time +the same format can be used by more than one device (particularly +this is the case for different models by the same manufacturer). + +.SS An overview about input data formats +.sp +Generally speaking, data formats can be classified into two large +groups: +.INDENT 0.0 +.IP 1. 3 +“raw” field data with polar coordinates +.IP 2. 3 +processed data, with XY(Z) cartesian coordinates +.UNINDENT +.sp +The latter are far more easy to process, because they don\(aqt require +any computing of measurements. +.SS XYZ formats +.sp +These formats were the first kind of survey data format supported by +Total Open Station. +.sp +Cartesian coordinates just need to be extracted from ASCII data +.SS Leica TCR 1205 +.INDENT 0.0 +.TP +.B moduleauthor +Stefano Costa +.TP +.B moduleauthor +Luca Bianconi +.UNINDENT +.sp +This format is used by the Leica TCR 1205 (and other similar devices), +and contains both polar and cartesian coordinates. At the moment, only +cartesian coordinates are used to obtain exported data. +.SS Acknowledgements +.sp +Support for this format was added thanks to Joseph Reeves, OA Digital. +.SS Nikon RAW format V2.00 +.INDENT 0.0 +.TP +.B author +Stefano Costa +.UNINDENT +.sp +This format contains polar data. It is the first polar format +supported by Total Open Station. +.sp +Data are basically comma\-separated values, but each row can have a +different format and number of fields. Recorded points are in rows +that start with the \fBSS\fP string, while fixed base points start with +the \fBST\fP string. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +CO,Nikon RAW data format V2.00 +CO,FATE2010 +CO,Description: +CO,Client: +CO,Comments: +CO,Downloaded 08\-Feb\-2010 11:17:17 +CO,Software: Pre\-install version: 1.02 +CO,Instrument: Nikon NPL\-352 +CO,Dist Units: Metres +CO,Angle Units: Gons +CO,Zero azimuth: North +CO,Zero VA: Zenith +CO,Coord Order: NEZ +CO,HA Raw data: Azimuth +CO,Tilt Correction: VA:ON HA:ON +CO, FATE2010 <JOB> Created 04\-Feb\-2010 13:41:40 +MP,1,,0.000,0.000,0.000,ST +CO,Temp:20C Press:760mmHg Prism:0 04\-Feb\-2010 13:47:08 +ST,1,,,,1.430,0.0000,0.0000 +F1,,1.500,,0.0000,110.5344,13:47:08 +SS,2,1.500,8.986,107.9916,102.3376,14:00:04,P +SS,3,1.500,7.706,110.4894,103.4372,14:00:51,P +SS,4,1.500,7.620,105.5898,104.3960,14:01:30,P +SS,5,1.700,7.162,105.5474,103.7754,14:02:48,P +SS,6,1.500,8.539,105.0304,107.6552,14:04:43,P +SS,7,0.000,8.318,111.0776,109.4876,14:06:02,P +SS,8,1.500,7.085,108.6492,101.0370,14:38:22,P +SS,9,1.500,7.592,112.1108,100.0146,14:38:58,P +SS,10,1.500,7.616,114.3392,98.3016,14:40:03,P +SS,11,1.500,8.227,118.5482,97.8578,14:40:53,P +SS,12,1.500,8.364,111.9586,96.9256,14:41:44,P +SS,13,1.500,8.233,120.1832,93.9826,14:47:20,P +SS,14,1.500,7.438,116.4324,95.2816,14:48:15,P +SS,15,1.500,7.266,115.0854,99.0626,14:49:59,P +SS,16,1.500,6.622,112.4368,99.6468,14:50:19,P +SS,17,1.500,7.957,121.7916,93.7194,14:52:29,P +SS,18,1.500,7.956,134.1078,93.9716,14:53:09,P +SS,19,1.500,7.515,126.2412,94.4298,14:54:15,P +SS,20,1.500,6.711,130.6606,96.5976,14:55:03,P +SS,21,1.500,6.857,118.6338,96.0578,14:56:00,P +SS,22,1.500,6.433,117.1546,100.2926,14:56:52,P +SS,23,0.000,8.399,127.3100,103.7122,14:58:30,P +SS,24,0.000,8.351,128.5522,100.1180,14:59:08,P +SS,25,0.000,8.270,134.3588,101.1110,14:59:55,P +SS,26,0.000,8.274,133.8002,104.4368,15:00:26,P +SS,27,1.500,6.511,124.0842,99.5534,15:03:09,P +SS,28,1.500,5.974,122.1514,101.6522,15:04:23,P +SS,29,0.000,8.962,137.1236,98.3588,15:07:38,P +SS,30,0.000,8.934,136.3310,102.4348,15:08:05,P +SS,31,0.000,9.184,144.2620,103.4046,15:08:31,P +SS,32,0.000,9.387,149.0120,103.4142,15:08:59,P +SS,33,0.000,9.362,148.7352,99.7136,15:09:30,P +SS,34,0.000,9.219,144.4228,99.5388,15:09:53,P +SS,35,0.000,7.001,138.7436,114.7446,15:11:07,P +SS,36,1.500,5.851,131.9558,102.5750,15:22:52,P +SS,37,1.500,6.328,133.0952,101.2756,15:23:32,P +SS,38,1.500,5.808,135.2582,104.2262,15:24:29,P +SS,39,1.500,6.923,134.4702,99.9614,15:25:18,P +SS,40,1.500,6.879,139.7302,100.1380,15:25:55,P +SS,41,1.500,7.486,140.0246,98.6866,15:26:40,P +SS,42,1.500,7.661,135.3510,97.9216,15:28:03,P +SS,43,1.500,8.199,135.9068,96.7188,15:28:54,P +SS,44,1.500,8.225,143.5888,97.0652,15:29:50,P +SS,45,1.500,7.827,145.0258,97.5600,15:31:08,P +SS,46,1.500,7.860,147.3556,97.3464,15:31:44,P +SS,47,1.500,8.662,147.2374,95.8390,15:32:27,P +SS,48,1.500,8.568,144.4556,95.8270,15:33:11,P +SS,49,1.500,8.729,143.4210,93.5904,15:34:01,P +SS,50,1.500,8.339,136.3862,93.3592,15:34:38,P +SS,51,1.500,7.429,141.7392,102.7698,15:36:02,P +SS,52,1.500,6.913,140.8836,104.3052,15:36:41,P +SS,53,1.500,7.479,149.9490,103.0626,15:37:25,P +SS,54,1.500,6.938,149.6110,104.9004,15:38:12,P +SS,55,1.700,6.718,143.6064,104.5304,15:39:06,P +SS,56,1.700,6.734,138.1288,104.4754,15:39:44,P +CO,HT changed at PT=56 Old HT=1.500m +CO,OLD=56 X\-3.787 Y5.548 Z\-0.543 +CO,HT changed at PT=55 Old HT=1.500m +CO,OLD=55 X\-4.239 Y5.190 Z\-0.548 +SS,57,1.500,6.132,137.6602,109.0124,15:42:43,P +SS,58,1.500,8.966,150.7654,93.9858,15:44:05,P +SS,59,1.500,9.739,151.4094,93.7238,15:44:39,P +SS,60,1.500,9.919,155.4866,95.0466,15:45:26,P +SS,61,1.500,8.980,152.3926,95.1246,15:46:14,P +SS,62,1.500,9.107,155.8314,95.5764,15:47:06,P +SS,63,1.850,9.150,156.6374,93.9602,15:50:12,P +SS,64,0.000,9.292,157.4092,107.9238,15:52:21,P +SS,65,1.500,10.059,160.4978,95.4160,15:54:36,P +SS,66,1.500,9.330,161.8984,97.0678,15:55:51,P +SS,67,1.500,9.997,161.8576,99.2174,15:56:34,P +SS,68,1.500,10.786,167.3566,98.9458,15:57:09,P +SS,69,1.500,10.240,167.1484,99.9180,15:57:48,P +SS,70,1.780,9.705,169.0404,99.2786,15:59:17,P +CO,HT changed at PT=70 Old HT=1.500m +CO,OLD=70 X\-8.579 Y4.536 Z0.040 +SS,71,1.500,9.408,162.8840,100.4778,16:00:34,P +SS,72,1.750,9.183,163.3532,99.4422,16:02:31,P +SS,73,1.775,9.027,160.3550,99.1590,16:04:06,P +SS,74,1.900,8.753,160.1354,99.1978,16:05:45,P +SS,75,1.900,8.437,165.1502,99.4756,16:06:43,P +SS,76,1.900,8.230,159.7622,99.0878,16:07:33,P +SS,77,1.500,8.092,155.4420,102.0228,16:08:38,P +SS,78,1.500,7.861,150.3918,102.1856,16:09:31,P +SS,79,1.500,8.676,149.3206,100.1448,16:10:12,P +SS,80,1.500,8.841,154.4180,100.2618,16:11:07,P +SS,800,1.500,20.726,178.2156,91.7976,16:13:27,P +SS,801,1.500,21.722,179.8802,92.3712,16:14:05,P +SS,802,2.550,20.961,179.9716,92.2336,16:18:03,P + + +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Acknowledgements +.sp +Support for this format was added thanks to Cynthia Mascione, +Università di Siena. +.SS Trimble AREA format +.INDENT 0.0 +.TP +.B moduleauthor +Stefano Costa +.TP +.B moduleauthor +Luca Bianconi +.TP +.B moduleauthor +Alessandro Bezzi +.UNINDENT +.SS \fBzeiss_rec_500\fP \-\- Zeiss REC 500 +.sp +This was the first format supported by Total Open Station. For +historical reasons, its documentation is far more extended than those +of other formats. The step by step procedure is useful for anyone who +wants to hack on TOPS itself. +.SS Step\-by\-step download procedure +.sp +At the time I was doing the first tests, I found it useful to collect +all steps. The program goes through them automatically: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +>>> import serial +>>> ser = serial.Serial(\(aq/dev/ttyUSB0\(aq, \e + baudrate=9600, bytesize=serial.SEVENBITS, timeout=0, \e + parity=serial.PARITY_NONE, rtscts=1) +>>> ser.open() +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +At this point, you have to start the download from the device +menu. When this operation has finished, it\(aqs good practice to control +if you have actually received any data: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +>>> ser.inWaiting() +648L +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +A non\-zero result means that something has been downloaded. Good enough. +.sp +This number can be saved to a variable and passed as parameter to the +\fBread()\fP command: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +>>> n = ser.inWaiting() +>>> result = ser.read(n) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBresult\fP object is a string that contains our data: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +>>> print(result) + 0001 OR.COOR + 0002 0S X 0.000 Y 0.000 Z 0.000 + 0003 Om 397.0370 + 0004 POLAR + 0005 INPUT th 1.500 ih 0.000 + 0006 INPUT th 0.000 ih 0.000 Z 0.000 + 0007 1 X \-0.472 Y 1.576 Z 0.004 +END +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +So far, we can say that the downloaded file contains this information: +.INDENT 0.0 +.IP \(bu 2 +\fBOR.COOR\fP: but I don\(aqt know if this line can take other values too +.IP \(bu 2 +\fBorigin point\fP defined by the \fBOS\fP string followed by its \fBX\fP, \fBY\fP, +\fBZ\fP coordinates +.IP \(bu 2 +\fBorientation angle\fP \fBOm\fP: are these gradiants? +.IP \(bu 2 +\fBPOLAR\fP: but I don\(aqt know if this line can take other values too +.IP \(bu 2 +\fBINPUT\fP: are there always two \fBINPUT\fP lines? +.INDENT 2.0 +.IP \(bu 2 +\fBth\fP +.IP \(bu 2 +\fBih\fP +.IP \(bu 2 +\fBZ\fP +.UNINDENT +.IP \(bu 2 +points, expressed as \fBN\fP (starting from 1), \fBX\fP, \fBY\fP, \fBZ\fP +.IP \(bu 2 +\fBEND\fP: after this line no more data +.UNINDENT +.SS Other formats +.sp +Unimplemented \fIformats\fP can be added to Total Open Station. +.sp +The best way to have your format included in the next version of +TotalOpenStation is to file a support request in the bug tracker and attach +some sample data dumps obtained with the Helper application. +.sp +If you can write Python code, you can also write a module by yourself using +the existing ones as a guide. Should you write a module, we will be happy to +receive it and include it in the TotalOpenStation source tree. +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fIcontributing\fP page to find out how to join the project and +participate actively to the development. +.UNINDENT +.UNINDENT +.SS Adding a new input format +.sp +There are hundreds of survey data formats out there. One by one, we +will get them added into Total Open Station. Here\(aqs a general process +that defines some minimum requirements when implementing new formats. +.SS Documentation +.sp +Always write documentation for the format. Add a new document in the +\fBdocs/input_formats/\fP directory of the source tree with a bare +description, including: +.INDENT 0.0 +.IP \(bu 2 +raw (polar) or processed (cartesian) format +.IP \(bu 2 +fixed\-position based or fluid \-\- this changes the way the parser +should work +.IP \(bu 2 +which devices or manufacturers use this format +.IP \(bu 2 +name of contributors +.UNINDENT +.sp +Shortcomings of Total Open Station that the format exposes shouldn\(aqt +be hidden, but rather made explicit both in code and documentation. +.SS Sample data +.sp +Never commit support for a new format without including the relevant +sample data in the \fBsample_data\fP directory. Generally speaking, +sample data files should follow these simple rules: +.INDENT 0.0 +.IP \(bu 2 +quality is better than quantity, so prefer a smaller file with many +different corner cases rather than a larger file with a bulk of +ordinary data +.IP \(bu 2 +multiple files are OK, if they serve the purpose of showing +different issues with the format +.IP \(bu 2 +files should be named with the same name of the Python module that +implements the format, using a \fB\&.tops\fP extension, like +\fBtopcon_gts.tops\fP for a format implemented in a module named +\fBtopcon_gts.py\fP \-\- this will allow for simple automated tests +.UNINDENT +.SS Code +.sp +When you have fulfilled the two previous tasks, you can start writing +code (or at least you should pretend doing that). New code is always +better than old code, because you have learned better programming +techniques, or because you are more confident with Total Open +Station. Writing tests for your code isn\(aqt (yet) required, but it\(aqs +highly encouraged. Don\(aqt break current practice. +.sp +All code implementing new formats should not break the existing +API. Changing the API should be done at the scale of the entire +library, to take into account the many different needs of each format +and parser. The development of Total Open Station is not in a stable +shape, so expect the API to change in future versions. However, please +understand that a new format parser is not the right place to do that. +.sp +Experiments are welcome. Mercurial allows for easy branching: you are +encouraged to clone our repository and go crazy with new features, +formats. +.SS Contributing +.sp +Total Open Station is free software, released under the GNU \fI\%General +Public License v3\fP or (at your option) any later version. +.sp +Development is tracked with \fI\%Mercurial\fP, a fast decentralized version +control system. Installing \fIMercurial\fP is not needed unless you want +to participate in TOPS development, but please \fBdo it\fP\&. The main +development repository is on \fI\%bitbucket\fP where it\(aqs easy to fork the +source code for your own experiments. +.sp +The suggested way of contributing is by sending patches using the +Mercurial \fIpatchbomb\fP extension to the \fI\%development mailing list\fP\&. +.SS Coding standards +.sp +We try to follow as much as possible \fI\%PEP\-8\fP, +.SS Roadmap +.SS Present +.sp +Total Open Station is at version 0.2, which is an \fBalpha\fP release. +.SS Near Future +.sp +Total Open Station 0.3 will be released by June 2011. Planned +features include: +.INDENT 0.0 +.IP \(bu 2 +more responsive download dialogs +.IP \(bu 2 +more solid internal data format +.UNINDENT +.SS Future +.sp +Our plans for Total Open Station are focused on different areas of +user experience and development practices. We envisage future versions +based on concepts like: +.INDENT 0.0 +.IP \(bu 2 +seamless integration with geospatial data software +.IP \(bu 2 +dedicated layout for intensive survey use +.IP \(bu 2 +enhanced mobile experience +.IP \(bu 2 +supporting always more devices and formats +.UNINDENT +.sp +If you have an incredible idea on how Total Open Station should look +like, let us know! +.SH INDICES AND TABLES +.INDENT 0.0 +.IP \(bu 2 +\fIgenindex\fP +.IP \(bu 2 +\fImodindex\fP +.IP \(bu 2 +\fIsearch\fP +.UNINDENT +.SH COPYRIGHT +2008-2011, Stefano Costa, Luca Bianconi +.\" Generated by docutils manpage writer. +. diff --git a/debian/totalopenstation.manpages b/debian/totalopenstation.manpages new file mode 100644 index 0000000..4cd44fd --- /dev/null +++ b/debian/totalopenstation.manpages @@ -0,0 +1 @@ +debian/manpages/*.1 -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-grass/totalopenstation.git _______________________________________________ Pkg-grass-devel mailing list Pkgfirstname.lastname@example.org http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-grass-devel