totalopenstation - Total Open Station 0.3.0

Copyright

       2008-2011, Stefano Costa, Luca Bianconi

0.3                                               July 31, 2014                              TOTALOPENSTATION(1)

For Developers

ModelsGeneralconcepts
       General concepts here about models and abstract classes.

   leica_tcr_1205--LeicaTCR1205Description
       This is a quite recent total station. Data were provided by Joseph Reeves of Oxford Archaeology.

   ConnectionBaudrate
              higher than 19200

       Bytesize
              8

       /1/no

   Dataformat
       The data format is ASCII, quite simple.

       The only thing to note is that data dumps contain both relative and absolute measures.

   Othernotesnikon_npl_350--NikonNPL-350
       Download is in ASCII format.

       Even the brute method cat/dev/ttyS0>file creates an ASCII file without any problem,  so  probably  the
       default parameters for the serial port are OK.

   zeiss_elta_r55--ZeissEltaR55Description
       This  is  a quite old device, in use at the University of Siena. The first steps in TOPS development were
       achieved with it.

   ConnectionBaudrate
              9600

       Bytesize
              7

       Parity None

   Outputformats
       The Zeiss Elta R55 total station can output data  in  four  different  formats,  only  one  of  which  is
       currently supported:

       • if_zeiss_rec_500

       • Zeiss R-4

       • Zeiss R-5

       • Zeiss R-E

   Othernotes
       The hardware interface consists of a serial RS232 cable, that works also with a common serial-USBadapter
       .

   Othermodels
       Unimplemented models can be added to TotalOpenStation.

       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.

       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.

       SEEALSO:
          The contributing page to find out how to join the project and participate actively to the development.

   Inputformats
       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).

   Anoverviewaboutinputdataformats
       Generally speaking, data formats can be classified into two large groups:

       1. “raw” field data with polar coordinates

       2. processed data, with XY(Z) cartesian coordinates

       The latter are far more easy to process, because they don't require any computing of measurements.

   XYZformats
       These formats were the first kind of survey data format supported by Total Open Station.

       Cartesian coordinates just need to be extracted from ASCII data

   LeicaTCR1205moduleauthor
              Stefano Costa

       moduleauthor
              Luca Bianconi

       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.

   Acknowledgements
       Support for this format was added thanks to Joseph Reeves, OA Digital.

   NikonRAWformatV2.00author Stefano Costa

       This format contains polar data. It is the first polar format supported by Total Open Station.

       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 SS string, while fixed base points start with the ST
       string.

          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

   Acknowledgements
       Support for this format was added thanks to Cynthia Mascione, Università di Siena.

   TrimbleAREAformatmoduleauthor
              Stefano Costa

       moduleauthor
              Luca Bianconi

       moduleauthor
              Alessandro Bezzi

   zeiss_rec_500--ZeissREC500
       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.

   Step-by-stepdownloadprocedure
       At the time I was doing the first tests, I found it useful to collect all steps. The program goes through
       them automatically:

          >>> import serial
          >>> ser = serial.Serial('/dev/ttyUSB0', \
              baudrate=9600, bytesize=serial.SEVENBITS, timeout=0, \
              parity=serial.PARITY_NONE, rtscts=1)
          >>> ser.open()

       At this point, you have to start the download from the device menu. When  this  operation  has  finished,
       it's good practice to control if you have actually received any data:

          >>> ser.inWaiting()
          648L

       A non-zero result means that something has been downloaded. Good enough.

       This number can be saved to a variable and passed as parameter to the read() command:

          >>> n = ser.inWaiting()
          >>> result = ser.read(n)

       The result object is a string that contains our data:

          >>> 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

       So far, we can say that the downloaded file contains this information:

       • OR.COOR: but I don't know if this line can take other values too

       • originpoint defined by the OS string followed by its X, Y, Z coordinates

       • orientationangleOm: are these gradiants?

       • POLAR: but I don't know if this line can take other values too

       • INPUT: are there always two INPUT lines?

         • th

         • ih

         • Z

       • points, expressed as N (starting from 1), X, Y, Z

       • END: after this line no more data

   Otherformats
       Unimplemented formats can be added to Total Open Station.

       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.

       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.

       SEEALSO:
          The contributing page to find out how to join the project and participate actively to the development.

   Addinganewinputformat
       There  are  hundreds of survey data formats out there. One by one, we will get them added into Total Open
       Station. Here's a general process that defines some minimum requirements when implementing new formats.

   Documentation
       Always write documentation for the format. Add a new document in the docs/input_formats/ directory of the
       source tree with a bare description, including:

       • raw (polar) or processed (cartesian) format

       • fixed-position based or fluid -- this changes the way the parser should work

       • which devices or manufacturers use this format

       • name of contributors

       Shortcomings of Total Open Station that the format exposes shouldn't be hidden, but rather made  explicit
       both in code and documentation.

   Sampledata
       Never  commit  support  for  a  new  format without including the relevant sample data in the sample_data
       directory. Generally speaking, sample data files should follow these simple rules:

       • 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

       • multiple files are OK, if they serve the purpose of showing different issues with the format

       • files should be named with the same name of the Python module that implements the format, using a .tops
         extension,  like  topcon_gts.tops for a format implemented in a module named topcon_gts.py -- this will
         allow for simple automated tests

   Code
       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't
       (yet) required, but it's highly encouraged. Don't break current practice.

       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.

       Experiments are welcome. Mercurial allows for easy branching: you are encouraged to clone our  repository
       and go crazy with new features, formats.

   Contributing
       Total Open Station is free software, released under the GNU GeneralPublicLicensev3 or (at your option)
       any later version.

       Development  is tracked with Mercurial, a fast decentralized version control system. Installing Mercurial
       is not needed unless you want to participate in TOPS development, but please doit. The main  development
       repository is on bitbucket where it's easy to fork the source code for your own experiments.

       The  suggested  way  of contributing is by sending patches using the Mercurial patchbomb extension to the
       developmentmailinglist.

   Codingstandards
       We try to follow as much as possible PEP-8,

   RoadmapPresent
       Total Open Station is at version 0.2, which is an alpha release.

   NearFuture
       Total Open Station 0.3 will be released by June 2011. Planned features include:

       • more responsive download dialogs

       • more solid internal data format

   Future
       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:

       • seamless integration with geospatial data software

       • dedicated layout for intensive survey use

       • enhanced mobile experience

       • supporting always more devices and formats

       If you have an incredible idea on how Total Open Station should look like, let us know!

For Users

Requirements
TotalOpenStation is written using the Python language. Thus you'll need to have a working installation of
the current version of a Python of your choice.

Across these pages we will refer to the standard Python distribution.

Obviously, we're not going to reinvent the wheel, so we have chosen to use some Python libraries for some
specific tasks:

• the pySerial library

• the Python Tkinter GUI library, which comes with the standard Python setup

pySerial is needed for downloading data from the serial port (even through a serial-USBadapter).

Tkinter is at the moment responsible of the Graphical User Interface. This might change in future
releases of Total Open Station.

GettingPython
If you're 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.

On Windows, you can get an installer from the main Python website, in the download section.

Gettinglibraries
Generally speaking, refer to the pySerialwebsite.

GNU/Linux
Use your package manager (apt-get, yum) and look for a package named python-serial or pyserial and
install it. To test whether the installation went fine, open a terminal, start the python interpreter
with python and at the prompt type importserial then return. It should say nothing, like this:

>>> import serial

If it complains, something went wrong:

>>> import serial
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ImportError: No module named serial

and you need to check with your distribution package manager and bug reporting system.

MacOSX
The simplest way is probably to install setuptools and use:

easy_install -U pyserial

MicrosoftWindows
The pySerial website has executable installers for various versions of this operating system. As
pySerial's documentation says, you will need also the pywin32 library by Mark Hammond.

Installing
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.

Usingpip
Until your operating system's packaging tools (e.g. apt or yum) allow you to install Total Open Station
along with other programs, the recommended way to install is using pip, like:

pip install totalopenstation

This will install all the other required Python packages as well. pip is complementary with virtualenv,
and it is encouraged that you use virtualenv to isolate your installation:

pip -E tops install totalopenstation

where -Etops creates a virtual environment named tops and installs totalopenstation into it.

Read more about pip at http://pip.openplans.org/ and http://guide.python-distribute.org/pip.html .

Manualinstallwithsetup.py
If you manually download the source distribution file from PyPI or from the mercurial repository, first
make sure you have installed all the requiredpackages. Then, just cd into the uncompressed directory
and:

python setup.py install

Again, it's strongly recommended to avoid a system-wide install. Use virtualenv.

Windows
There is a binary installer available at PyPI. This requires you to install a Python distribution (latest
available is 2.7.1 ‒ do not install Python 3 as we don't support it yet), and the pyserial and setuptools
modules.

Gettingsampledata
Even when your device is not listed among the supported ones, Total Open Station can still be useful,
particularly for:

1. finding the right serialconnectionparameters 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;

2. retrieving sampledata from unknown models and submit them to allow support of those models in future
releases of the program.

To do this, you can just use the main Total Open Station executable.

WARNING:
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'
options).

Glossaryinputformat
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's work to export them. These formats have a standard name, either given by the manufacturer
or by the TOPS development team.

model When we refer to a model we mean all total stations that have the same brand name and manufacturer
(e.g. all those labeled “Trimble Geodimeter 600”).

outputformat
A format readable by GIS, CAD or any sort of common software, like CSV or DXF.

serial-USBadapter
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 /dev/ttyUSB0 or COM5.

UsersofTotalOpenStation
So far, Total Open Station has been successfully used by:

• Università di Siena, DipartimentodiArcheologiaeStoriadelleArti, for the excavations at Gortyna
and Vignale

• OxfordArchaeology, for fieldwork, using the OpenMoko mobile platform

• Arke_Geomática has blogged about TOPS

• Arc-Team: we have added support for the Trimble “area” format after Arc-Team sent us some sample
data

• Università di Padova

If you're in the number of happy users, let us know.

Indices And Tables

       • genindex

       • modindex

       • search

Name

       totalopenstation - Total Open Station 0.3.0