Provided by: totalopenstation_0.5.2-3_all 
NAME
totalopenstation - Total Open Station 0.3.0
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-USB
adapter).
Tkinter is at the moment responsible of the Graphical User Interface. This might change in
future releases of Total Open Station.
Getting Python
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.
Getting libraries
Generally speaking, refer to the pySerial website.
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 import serial 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.
Mac OSX
The simplest way is probably to install setuptools and use:
easy_install -U pyserial
Microsoft Windows
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.
Using pip
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 -E tops 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 .
Manual install with setup.py
If you manually download the source distribution file from PyPI or from the mercurial
repository, first make sure you have installed all the required packages. 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.
Getting sample data
Even when your device is not listed among the supported ones, Total Open Station can still
be useful, particularly for:
1. finding the right serial connection parameters 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 sample data 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).
Glossary
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'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”).
output format
A format readable by GIS, CAD or any sort of common software, like CSV or DXF.
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
/dev/ttyUSB0 or COM5.
Users of Total Open Station
So far, Total Open Station has been successfully used by:
• Università di Siena, Dipartimento di Archeologia e Storia delle Arti, for the
excavations at Gortyna and Vignale
• Oxford Archaeology, 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.
FOR DEVELOPERS
Models
General concepts
General concepts here about models and abstract classes.
leica_tcr_1205 -- Leica TCR 1205
Description
This is a quite recent total station. Data were provided by Joseph Reeves of Oxford
Archaeology.
Connection
Baudrate
higher than 19200
Bytesize
8
/1/no
Data format
The data format is ASCII, quite simple.
The only thing to note is that data dumps contain both relative and absolute measures.
Other notes
nikon_npl_350 -- Nikon NPL-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 -- Zeiss Elta R55
Description
This is a quite old device, in use at the University of Siena. The first steps in TOPS
development were achieved with it.
Connection
Baudrate
9600
Bytesize
7
Parity None
Output formats
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
Other notes
The hardware interface consists of a serial RS232 cable, that works also with a common
serial-USB adapter .
Other models
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.
SEE ALSO:
The contributing page to find out how to join the project and participate actively to
the development.
Input formats
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).
An overview about input data formats
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.
XYZ formats
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
Leica TCR 1205
moduleauthor
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.
Nikon RAW format V2.00
author 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.
Trimble AREA format
moduleauthor
Stefano Costa
moduleauthor
Luca Bianconi
moduleauthor
Alessandro Bezzi
zeiss_rec_500 -- Zeiss REC 500
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-step download procedure
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
• origin point defined by the OS string followed by its X, Y, Z coordinates
• orientation angle Om: 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
Other formats
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.
SEE ALSO:
The contributing page to find out how to join the project and participate actively to
the development.
Adding a new input format
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.
Sample data
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 General Public License v3 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 do it. 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 development mailing list.
Coding standards
We try to follow as much as possible PEP-8,
Roadmap
Present
Total Open Station is at version 0.2, which is an alpha release.
Near Future
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!
INDICES AND TABLES
• genindex
• modindex
• search
COPYRIGHT
2008-2011, Stefano Costa, Luca Bianconi