Contributing to Total Open Station¶
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 git. The main development repository is at
GitHub where it’s easy to fork the source code.
Experiments are welcome. Git allows for easy branching: you are encouraged to clone our repository and go crazy with new features, formats.
We try to follow as much as possible PEP-8
A lot of the functionality of Total Open Station is centered around text manipulation, both when parsing input data and exporting to output formats. For this reason the maintainters decided to standardize on usage of string formatting with the aim of making the code more readable and consistent.
use f-strings everywhere in the
the scripts in the
scriptsdirectory are the three user-facing programs that need their messages translated (see translations below): use old-style string formatting (also known as %-formatting or printf-style string formatting) for all string formatting in these scripts
do not use the
F-strings were introduced in Python 3.6, they are faster than other methods and allow writing code that is both more readable and less verbose. However f-strings are not compatible with gettext, the module used for translation.
The main tool we use for translating Total Open Station is Transifex.
We are happy to accept translations for Total Open Station. Translations can be easily submitted and reviewed at our Transifex page. Translators get recognition for their valuable work.
If your native language is missing, why don’t you start translating Total Open Station right now?
When the release is approaching and the source strings are not going
to change, declare string freeze. Source messages should be updated
with one of
pygettext or Babel (with the
extract_messages command), producing
xgettext scripts/*.py -o locale/totalopenstation.pot
The resulting PO template file mut be uploaded to Transifex for translators to work with:
tx push -s
If there is an existing translation,
msgmerge or Babel
update_catalog should be used to update.
Translators should be invited to submit new translations, either via
.po files or Transifex.
When the translation period is over, pull the updated
from Transifex with:
tx pull -r totalopenstation.totalopenstation-app -a
and check that the files are updated. Commit new files separately from updates.
If using Babel, compile the translated messages with:
python setup.py compile_catalog -d locale
Using Total Open Station as a library¶
All the functionality implemented in Total Open Station can be used independently, with the exception of the user interfaces.
In other words, the classes for reading specific formats and those for writing well-known formats are entirely usable on their own.
This is a feature.
Example: a web app for converting total station data¶
If you want to see how to write a web app to convert total station data in 50 lines of Python code, check out TOPS in the Cloud. It is made with Flask and shows how to use Total Open Station as a programming library.
TOPS in the Cloud is not maintained and does not receive security updates. Please don’t use it in production.
Developing with Total Open Station¶
Adding a new 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 as input or output.
Always write documentation for the format. Add a new document in the
docs/input_formats/ directory or amend the
docs/output_formats/of_implemented.rst file of the source tree with a bare
raw (polar) or processed (cartesian) format
fixed-position based or fluid – this changes the way the parser should work (input format)
which devices, manufacturers or software use this format
name of contributors
reference to the format if available
Shortcomings of Total Open Station that the format exposes shouldn’t be hidden, but rather made explicit both in code and documentation.
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
topcon_gts.topsfor a format implemented in a module named
topcon_gts.py– this will allow for simple automated tests
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.
Feature(point, desc='PT', id=pid, point_name=point_name, dist_unit=dist_unit, attrib=attrib)
Feature(point, desc='PO', id=pid, point_name=point_name, angle_unit=angle_unit, z_angle_type=z_angle_type, dist_unit=dist_unit, dist_type=dist_type, azimuth=azimuth, angle=angle, z_angle=z_angle, dist=dist, th=th, ih=ih, ppm=ppl, prism_constant=prism_constant, station_name=station_name, attrib=attrib)
Station point data
Feature(point, desc='ST', id=pid, point_name=station_name, angle_unit=angle_unit, dist_unit=dist_unit, ih=ih, hz0=hz0, attrib=attrib)
Feature(point, desc='BS', id=pid, point_name=point_name, angle_unit=angle_unit, circle=circle)
Types of values passed to the
formats.Feature class are :
Feature(Point class, desc=str, id=int, point_name=str, angle_unit=str, z_angle_type=str, dist_unit=str, dist_type=str, angle=float, z_angle=float, dist=float, th=float, ih=float, hz0=float, circle=float, ppm=float, prism_constant=float, station_name=str, attrib=list)
Those values are properties of the
For more in-depth knowledge of classes, we encourage reading the code @ Github.
Releasing a new Total Open Station version¶
The documentation is included in the source tree, and is published online at http://totalopenstation.readthedocs.org/.
Manual pages for the three scripts provided with TOPS are not available at the moment.
The version number is declared in
is propagated in other places from there, including
the “About” dialog.
A source distribution is made using:
python setup.py sdist
A built distribution is made using (e.g. for Windows installer):
python setup.py bdist --formats wininst
We are currently following the Python Packaging User Guide and distributing sources and wheels.
Windows portable app¶
A portable Windows app is built with PyInstaller. Using Git Bash, from the root directory of the source repository of Total Open Station:
python.exe -m venv pyinst-env source pyinst-env/Scripts/activate pip.exe install -e . pip.exe install PyInstaller pyinstaller.exe totalopenstation-gui.spec
This will create the file
dist/totalopenstation.exe, a portable
single-file executable that will run from any compatible Windows system,
even from USB sticks.
There is a GitHub action setup to automatically build the portable app for each release.
An executable built on 64 bit systems will not run on 32 bit systems