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.
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.
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 .wkt to .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. |
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.
- The validation scripts assume the totality of the stfX environment is running locally, using
docker-compose
. - Therefore, please do not forget to run
sh docker.sh
before proceeding with the validation. - However, to run the experiments that depend on the mock PSR service, you must run the application locally and run the mock server available in folder
/validation/psr-mock
. After, runsh experiments_with_mock.sh
to run the experiments that support mock data.
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. -
validate_all.py
Script to validate all the test-scenario, in the given directory, using the stfX tool.
results/
Contains the results under the denomination
.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
_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.
-
Sometimes it happens to exist more than one file for
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