stfX: SpatioTemporal Features eXtractor

❗ This repository has been archived. Further developments on this repository are done in most-inesctec/stfX. ❗

The SpatioTemporal Features eXtractor (stfX) is the prototype implementation of the conceptual framework detailed in chapter 4 of the corresponding thesis. Thus, the stfX focuses on the quantification of the features of interest occurring over user-inputted spatiotemporal phenomena. The stfX is capable of quantifying a subset of the spatiotemporal change features identified in the literature review, namely: translations, rotations, uniform scaling, changes of direction, moment in time and duration.

The SpatioTemporal Features eXtractor (stfX) is a server-side application utilising the microservices architectural approach, thus emphasising self-management, lightweightness, scalability, and autonomy. In the stfX, each microservice represents a component responsible for the quantification of a given category of spatiotemporal change features. The developed microservices were added to this repository as sub-modules. Below we can visualise the stfX current architecture:

The stfX's API can be consulted in the corresponding Swagger.

Chapter 5 of the corresponding thesis contains a more detailed description of the stfX.

Functionalities

The current stfX version supports the following functionalities:

• Receives as input both the spatiotemporal dataset modelled as a sequence of temporal snapshots and the thresholds that express the end-user interests;
• Extracts both the shapes and associated timestamps from each temporal snapshot;
• For each temporal snapshot, quantifies the rigid transformations that occurred (translation, uniform scaling and rotation);
• From the identified movement derived features, computes change of direction (the motive behind solely considering the change of direction is explained in section 5.2.2.1 in the thesis);
• Filters the identified spatiotemporal change features according to the user-inputted thresholds;
• Computes, from the identified temporal features, duration and moment in time, even though no thresholds are provided for these features of interest;
• Indexes the identified features of interest by temporal range.

Repository Folder Overview

Folder	Description
/configs	Contains necessary configurations for the deployment of the stfX.
/core	Core microservice.
/CPD-service	CPD microservice. The CPD is the used point set registration algorithm in this service. Represents the PSR service of the above figure.
/docs	Contains the associated documents, namely the corresponding thesis.
/PR-GLS-service	Attempt of developing a microservice employing non-rigid registration. Ended up using the CPD microservice.
/swagger	Contains the json file describing the Swagger corresponding to the stfX.
/utils	Contains some utility python scripts, such as the parser of .wktto .json and extracting the .json dataset from an animation modelled as a set of .obj files.
/validation	Contains the resources, the results, and the code necessary to validate the stfX. See chapter 6 of the corresponding thesis for more information.

Validation of stfX

The purpose of the /validation subfolder is none other less than to validate the stfX, by containing all the necessary resources to run the experiments and recreate the results documented.

Some important nuances:

1. The validation scripts assume the totality of the stfX environment is running locally, using docker-compose.
2. Therefore, please do not forget to run docker-compose up, on stfX main folder, before proceeding with the validation.
3. However, to run the experiments that depend on the mock PSR service, you must run the stfXCore microservice in a standalone manner (e.g. using IntelliJ), and run the mock server available in folder /validation/psr-mock (you must not have the original cpd-service running, as both server - the mock and the original - run in the same port on localhost). Afterwards, run sh experiments_with_mock.sh to run the experiments that support mock data.
4. Before running the validations scripts, remember you have to install the requirements, available on the /validationfolder, using pip install -r requirements.txt. It is suggested to first create a virtual environment and activate it.

utils/

Contains Metrics M1 and M2:

• M1
  • metric that consists of comparing the ground truth final representation with the representation obtained by applying the transformations outputted by the stfX. The goal is to identify if the transformations recognised by the stfX result in equivalent representations to the ground truth.
• M2
  • metric that consists of analysing the similarity between the set of transformations outputted by the tool and the ground truth transformations. The goal is to identify how similar are both sets of transformations and, therefore, how effective is the devised solution.

experiment_mock.sh

This script is in charge of running the mock microservice that runs the algorithm point set registration.

validate.py & validate_all.py

• validate.py Script to validate a test-scenario the stfX tool. Usage:

    usage: validate.py [-h] -d DIR [-e ENDPOINT]
  
    Script to validate a test-scenario the stfX tool.
  
    optional arguments:
      -h, --help            show this help message and exit
      -d DIR, --dir DIR     The directory containing the resources necessary for this test. The output is also written to
                            this directory, in file result.txt
      -e ENDPOINT, --endpoint ENDPOINT
                            The endpoint running stfX. Default is http://localhost:0080/stfx
  

• validate_all.py Script to validate all the test-scenario, in the given directory, using the stfX tool. Usage:

    usage: validate_all.py [-h] -d DIR [-o OUT_DIR] [-e ENDPOINT]
  
    Script to validate all the test-scenario, in the given directory, using the stfX tool.
  
    optional arguments:
      -h, --help            show this help message and exit
      -d DIR, --dir DIR     The directory containing the test-scenarios.
      -o OUT_DIR, --out_dir OUT_DIR
                            The directory where the output of the test-scenario will be written to. If the directory does
                            not exist, it is created. Defaults to './results'
      -e ENDPOINT, --endpoint ENDPOINT
                            The endpoint running stfX. Default is http://localhost:0080/stfx
  

results/

Contains the results under the denomination name_of_the_test.json.

The json files have both the obtained results, the metric scores, and the differences between what was accomplish and what was expected for the M2 metric.
As for the files under the denomination name_of_the_test_m1.png, they exhibit the representation of the convex hulls and the phenomena used in the M1 metric.

psr-mock

Contains the imperative code to run the mock microservice.

experiments

Encloses folders for each experiment. As for each experiment, it consists of:

• dataset.json: the dataset that characterizes the spatiotemporal phenomena.
• expected_result.json: the expected result for the M2 metric (changes that effectively affect the phenomenon).
• name.blend: blender file used to create the experience (phenomenon + geometric transformations applied).
• thresholds.json: thresholds adopted for the detection of changes that affect the spatiotemporal phenomenon.
  • Sometimes it happens to exist more than one file for thresholds.json inside an experiment. This occurs because some experiments made with the same dataset adopt different thresholds so that the impact of bad and good thresholds in the quality of the results can be appraised.

Getting started

To download stfX with the latest micro-services versions run:

• As one step:

git clone --recursive https://github.com/EdgarACarneiro/stfX.git

• Two steps - first cloning repository and then updating sub-modules:

git clone https://github.com/EdgarACarneiro/stfX.git
git submodule update --init --recursive

To update the submodules use the command:

git submodule foreach git pull origin master

To add new submodules use the command:

git submodule add <submudole link>

To run the application, using Docker (one must have it installed), run:

docker-compose up

Important notes to run the application:

• if you intend to use the swagger UI, in the browser, you must change the following lines

  stfX/swagger/swagger.json

  Line 13 in a9fe68d

  "url" : "http://fctmost.inesctec.pt:0080/stfx",

  since these are set for the deployment purposes. Hence, if you are running the docker-compose up command locally, change this lines to:

"url" : "http://localhost:0080/stfx",

• By default, the application entrypoint is port 80, hence you must not have anything running on this port or you must change it in lines

  stfX/docker-compose.yml

  Line 9 in a9fe68d

  - 80:80

  , for e.g. (serving application on port 82):

- 82:80