Provided by: totalopenstation_0.3.3-1_all bug

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