Tramway Collector

Introduction

The project is an application to collect photos of different kinds of tramways.

License

This project is protected by the Apache Licence Version 2.0 (see the LICENSE file).

Architecture of the project

The project is divided into several folders:

• data, containing the file settings.json where the language of the interface is specified as well as the default path to images used for the file explorer.
• releases, containing the apk files for the application. You will find inside a debug version (this apk is unsigned which means Play Protect will raise a warning if you install it directly). If you want to install a signed version, please go to this section
• reports, containing the reports for the coverage and the cleanliness of the code.
  • coverage will contain after execution the files generated by Pytest.
  • linting is dedicated to the files generated by Pylint.
• resources, containing the following subfolders:
  • images_applications, containing the images used in the application.
  • images_readme, containing the images of this README.
  • kivy, containing the styling files of the interface, using the Python graphic librairy Kivy.
  • languages, containing the json files of the different languages supported by the application. The user may add other files, if he wants to translate the interface in another language.
• screens, containing the following modules for the different screens:
  • collection_window, Python module for the collection window of the application.
  • components, Python module for the general classes in Kivy.
  • gallery_window, Python module for window for each gallery.
  • image_edition_window, Python module for the window of image edition.
  • menu_window, Python module for the main window of the application.
  • settings_window, Python module for the settings window of the application.
• test, containing the test modules for the tools package.
• tools, containing the following modules:
  • tools_collection
  • tools_image
  • tools_kivy
  • tools

It also contains the following modules:

• buildoze.spec
• LICENSE
• main.kv, Kivy file containing the graphics of the interface, which is linked to the module main.py.
• main.py, main Python module used to launch the application.

Installation

For users

To install the application, download it on the Play Store using this link.

For developers

Cloning the repository

To clone the github repository, you have to search the clone button on the main page of the project. Then click it and select https or ssh depending on your favorite mode of connexion. Copy the given id and then open a terminal on your computer, go to the folder where you want to install the project and use the command:

git clone <your copied content>

Creation of a virtual environment

You might want to use a virtual environment to execute the code. To do so, use the following command:

python -m virtualenv venv

To start it, use the command on Windows:

venv/Scripts/Activate.ps1

Or for MacOS and Linux:

venv/Scripts/activate

Installation of the necessary librairies

To execute this software, you need several Python librairies, specified in the requirements.txt file. To install them, use the following command:

pip install -r requirements.txt

Installation of buildozer

If you want to compile the application yourself instead of using the provided apk, you will need to install buildozer by following this procedure.

Utilisation

For users

You will find in the settings a short tutorial explaining how to use the application.

For developers

Compilation

Debug version

To launch the compilation of the application into a debug apk file :

• Modify the path inside the spec file to match your own system configuration
• Compile with the command : buildozer -v android debug
• If an android smartphone is connected to your computer and the developer mode is activated on the device you can launch the application in debug mode and access the output using the command : buildozer -v android deploy run logcat | grep python
• If your encounter a java heap space error, try this command to increase the maximum allowed size of files : export GRADLE_OPTS="-Xms1724m -Xmx5048m -Dorg.gradle.jvmargs='-Xms1724m -Xmx5048m'"

Release version

Once the debug version works, to share a clean version of the application, it is necessary to sign the package. To do this, you first need to create a key using these commands :

keytool -genkey -v -keystore ~/keystores/TramwayCollector.keystore -alias TramwayCollector -keyalg RSA -keysize 2048 -validity 10000
keytool -importkeystore -srckeystore ~/keystores/TramwayCollector.keystore -destkeystore ~/keystores/TramwayCollector.keystore -deststoretype pkcs12

You then have to export the variables containing the password and the location of your key in your terminal with these commands :

export P4A_RELEASE_KEYALIAS="TramwayCollector"
export P4A_RELEASE_KEYSTORE=~/keystores/TramwayCollector.keystore
export P4A_RELEASE_KEYSTORE_PASSWD=
export P4A_RELEASE_KEYALIAS_PASSWD=

You can then obtain a release version of the app using the command : buildozer android release