diff --git a/README.md b/README.md index 70f9da951bb9f3bb6e71329cac045d2454ea23f2..babba70a6f46f912d18fd5f7ddceb266572676bb 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,105 @@ # PROG2900 -## Server +# Server The server currently only accepts HTTPS requests, not HTTP. It listens on ip address 127.0.0.1 and port 8443. URL: ```https://127.0.0.1:8443``` ## Endpoints -This server consists of 6 endpoints. Each endpoint requires the desired lake name -to be provided as an url parameter. Of the 6 endpoints, the first 5 only accept GET requests, while +This server consists of 7 endpoints. Each endpoint requires the desired lake name +to be provided as an url parameter. Of the 7 endpoints, the first 5 only accept GET requests, while ```new_lidar_data``` only accepts POST requests. The first three endpoints expose the processed data to the application. +Application endpoints: ``` .../update_map?lake=* .../get_relation?lake=* -.../update_measurements?lake=* +.../get_lake_names + +``` +Other endpoints: +``` +.../update_measurements?lake=* .../add_new_lake?lake=*&cell_size=* .../add_test_data?lake=* .../new_lidar_data?lake=* ``` -Example requests: +Request examples: ``` https://127.0.0.1:8443/update_map?lake=Mjøsa https://127.0.0.1:8443/get_relation?lake=Mjøsa -https://127.0.0.1:8443/update_measurements?lake=Mjøsa +https://127.0.0.1:8443/get_lake_names +https://127.0.0.1:8443/update_measurements?lake=Mjøsa https://127.0.0.1:8443/add_new_lake?lake=Skumsjøen&cell_size=0.8 https://127.0.0.1:8443/add_test_data?lake=Mjøsa https://127.0.0.1:8443/new_lidar_data?lake=Mjøsa ``` ### Update map -```update_map``` returns the contents of the measurement file for the selected lake. +``` +Method: GET +Path: update_map?lake=* +Paramters: + - lake (required) +``` + +Returns the contents of the measurement file for the selected lake. The file which is read is called ```*_measurements.json``` and can be found in ```server/map_handler/lake_relations```. This endpoint makes no changes to any files. This endpoint exposes data for the application. ### Get relation -```get_relation``` returns the contents of the relation file for the selected lake. +``` +Method: GET +Path: get_relation?lake=* +Paramters: + - lake (required) +``` + +Returns the contents of the relation file for the selected lake. The file which is read is called ```*_div.json``` and can be found in ```server/map_handler/lake_relations```. This endpoint makes no changes to any files. This endpoint exposes data for the application. +### Get lake names +``` +Method: GET +Path: get_lake_names +Paramters: none +``` + +```get_lake_names``` returns the contents of the file ```all_lake_names.json```. The file +contains the names of all the lakes in the system. This list is utilized by the applications search +functionality. This endpoint makes no changes to any files. + ### Update measurements -```update_measurements``` updates the ```*_measurements.json``` for the selected lake. +``` +Method: GET +Path: update_measurements?lake=* +Paramters: + - lake (required) +``` + +Updates the ```*_measurements.json``` for the selected lake. The endpoint will retrieve the latest LiDar data from ```_lidar_data.json```, which is also located in ```map_handler/lake_relations/```. The endpoint will also update the ice statistics form the NVE model. This endpoint exposes data for the application. ### Add new lake -```add_new_lake``` is used when a new lake is added to the system. This process +``` +Method: GET +Path: add_new_lake?lake=*&cell_size=* +Paramters: + - lake (required) + - cell_size (optional) +``` + +Is used when a new lake is added to the system. This process requires manual intervention. To add a new lake to the system, first navigate to https://overpass-turbo.eu/. Once you have navigated to th OverpassTurbo API, copy the query below, and enter it into the white field at the left-hand side at the website @@ -91,35 +138,52 @@ should be updated to contain the newly added lake name. ### Add test data +``` +Method: GET +Path: add_test_data?lake=* +Paramters: + - lake (required) +``` As the name implies, this endpoint adds test data to the desired lake. The endpoint will overwrite the file ```*_lidar_data.json``` with measurement objects with random thicknesses. This endpoint is only for production, and is not implemented in the application. ### New lidar data +``` +Method: POST +Path: new_lidar_data?lake=* +Paramters: + - lake (required) +``` -### Dependencies - ## Database This project requires SQLite3. Download the precompiled binary for your operating system. Precompiled binaries can be found on https://www.sqlite.org/download.html. Extract the downloaded binary in a folder and note its path. Add the path to your system environment variables. Now you can manage the SQLite database. -## Application +## Server dependencies + +## Known bugs +```add_new_lake.py``` does all the processing of new lake data. The current implementation of the +shape file processing fails to include internal coordinates. This results in fully enclosed shapes, such +as islands, to not be included. Simply including internal coordinates without further accommodations will cause +the server to throw errors. + +# Application In order to run the application in an IDE like Android Studio, the port randomization of Dart must first be bypassed. To do this, run the adb command ```reverse tcp:8443 tcp:8443 ```. This must be repeated every time the IDE in which the application is running is restarted. A simpler alternative is to add the command to the run configuration as an external tool. If the port randomization is not bypassed, the application will not be able to communicate with the server. -### Dependencies +## Application dependencies The application depends on multiple external libraries. A list of these can be found in the pubspec.yaml file, each with a comment explaining the dependencies usage. To install all the dependencies, simply run ```flutter pub get``` inside the app directory. -## Known bugs -## Developers +# Developers This software was developed by Joakim Aleksandersen, Sara Savanovic Djordjevic, and Hoa Ben The Nguyen. \ No newline at end of file