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.
Translations¶
Helping¶
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?
Releasing¶
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 xgettext
, pygettext
or Babel (with the
extract_messages
command), producing totalopenstation.pot
, e.g.:
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 .po
files
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.
We think it’s important to be able to use TOPS in this way as in any other way (GUI, command-line), and this is one of the reasons why there is no stable release yet: the TOPS API is still unstable.
Developping with Total Open Station¶
Advices¶
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.
Documentation¶
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
description, including:
- 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.
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, liketopcon_gts.tops
for a format implemented in a module namedtopcon_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.
Processing data¶
Total Open Station use GeoJSON as its internal processing data following the
RFC 7946 standard.
The library used to handle this format is
PyGeoif.
Thus, all data are build around a formats.Feature
class.
To be able to evaluate which type of data a formats.Feature
holds,
a descriptor has been added as a property.
Those descriptors are:
Descriptor | Explanation | Construction |
---|---|---|
PT |
|
Feature(point,
desc='PT',
id=pid,
point_name=point_name,
dist_unit=dist_unit,
attrib=attrib)
|
PO |
|
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)
|
ST | 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)
|
BS | Backsight information | 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 formats.Feature
class.
Releasing a new Total Open Station version¶
Documentation¶
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.
Release¶
The version number is declared in totalopenstation/__init__.py
and
is propagated in other places from there, including setup.py
and
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:
- follow the instructions for installing PyInstaller on Windows (be sure to install pip-Win and create a virtual environment)
- in the virtual environment, cd into the root directory of the
totalopenstation source code and
pip install .
to install the current version of totalopenstation and all the dependencies - run
pyinstaller 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
Warning
An executable built on 64 bit systems will not run on 32 bit systems