From 8ced5841506e4838ea4df3bff5d69d9d65dfeb95 Mon Sep 17 00:00:00 2001 From: dominik <907555+shelm@users.noreply.github.com> Date: Thu, 10 Oct 2024 12:01:28 +0200 Subject: [PATCH] Update Readme --- README.md | 26 ++++-- docs/docsource/tutorials/introduction.md | 101 +++++++++++++++-------- 2 files changed, 85 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index c8260d6..2018125 100644 --- a/README.md +++ b/README.md @@ -25,26 +25,32 @@ DISCOVER provides a set of blueprints for exploratory data analysis, serving as ### Prerequesites -Before starting to install NOVA-Server you need to install Python and FFMPEG. While other Python versions may work as well the module is only tested for the following versions: +Before starting to install DISCOVER you need to install Python and FFMPEG. +While other Python versions may work as well the module is only tested for the following versions: -3.9.x -You can download the current version of python for your system here. +* 3.9.x +* 3.10.x +* 3.11.x -Download the current version off FFMPEG binaries from here for your system and make sure to extract them to a place that is in your system path. It is recommended to setup a separate virtual environment to isolate the NOVA server installation from your system python installation. To do so, open a terminal at the directory where your virtual environment should be installed and paste the following command: +You can download the current version of python for your system [here](https://www.python.org/downloads/). -python -m venv nova-server-venv +Download the current version off FFMPEG binaries from [here](https://github.com/BtbN/FFmpeg-Builds/releases) for your system and make sure to extract them to a place that is in your system path. +It is recommended to setup a separate virtual environment to isolate the NOVA server installation from your system python installation. +To do so, open a terminal at the directory where your virtual environment should be installed and paste the following command: + +```python -m venv discover-venv``` You can then activate the virtual environment like this: -.\nova-server-venv\Scripts\activate +```.\discover-venv\Scripts\activate``` -#### Setup +### Setup Install DISCOVER using pip like this: ```pip install hcai-discover``` -#### Start the server +### Start the server To start DISCOVER you just open a Terminal and type @@ -74,7 +80,9 @@ Internally DISCOVER converts the input to environment variables with the followi ```DISCOVER_SERVER_HOST```, ```DISCOVER_PORT```, ```DISCOVER_CML_DIR```, ```DISCOVER_CML_DIR```, ```DISCOVER_CML_DIR```, ```DISCOVER_CML_DIR```, ```DISCOVER_CML_DIR``` -All variables can be either passed directly as commandline argument, set in a dotenv file or as system wide environment variables. During runtime the arguments will be prioritized in this order commandline arguments -> dotenv file -> environment variable -> default value. + +All variables can be either passed directly as commandline argument, set in a [dotenv](https://hexdocs.pm/dotenvy/dotenv-file-format.html) file or as system wide environment variables. +During runtime the arguments will be prioritized in this order commandline arguments -> dotenv file -> environment variable -> default value. If the server started successfully your console output should look like this: ``` diff --git a/docs/docsource/tutorials/introduction.md b/docs/docsource/tutorials/introduction.md index 4eea1b2..37a3a76 100644 --- a/docs/docsource/tutorials/introduction.md +++ b/docs/docsource/tutorials/introduction.md @@ -1,6 +1,29 @@ -# Installation +# DISCOVER - A Modular Software Framework for Human Behavior Analysis -## Prerequesites + +## Overview + +DISCOVER is an open-source software framework designed to facilitate computational-driven data exploration in human behavior analysis. This user-friendly and modular platform streamlines complex methodologies, enabling researchers across disciplines to engage in detailed behavioral analysis without extensive technical expertise. + +Key Features + +* Modularity: DISCOVER's modular architecture allows for easy integration of new features and customization. +* User-Friendliness: Intuitive interface simplifies the data exploration process, making it accessible to non-technical users. +* Flexibility: Supports a wide range of data types and analysis workflows. +* Scalability: Handles large datasets with ease. + +Use Cases + +* Interactive Semantic Content Exploration +* Visual Inspection +* Aided Annotation +* Multimodal Scene Search + +## Getting Started + +DISCOVER provides a set of blueprints for exploratory data analysis, serving as a starting point for researchers to engage in detailed behavioral analysis. + +### Prerequesites Before starting to install DISCOVER you need to install Python and FFMPEG. While other Python versions may work as well the module is only tested for the following versions: @@ -12,67 +35,79 @@ While other Python versions may work as well the module is only tested for the f You can download the current version of python for your system [here](https://www.python.org/downloads/). Download the current version off FFMPEG binaries from [here](https://github.com/BtbN/FFmpeg-Builds/releases) for your system and make sure to extract them to a place that is in your system path. -It is recommended to setup a separate virtual environment to isolate the NOVA server installation from your system python installation. -To do so, open a terminal at the directory where your virtual environment should be installed and paste the following command: +It is recommended to setup a separate virtual environment to isolate the NOVA server installation from your system python installation. +To do so, open a terminal at the directory where your virtual environment should be installed and paste the following command: -```python -m venv nova-server-venv``` +```python -m venv discover-venv``` -You can then activate the virtual environment like this: +You can then activate the virtual environment like this: ```.\discover-venv\Scripts\activate``` - -## Setup +### Setup Install DISCOVER using pip like this: ```pip install hcai-discover``` -## Start the server +### Start the server -To start DISCOVER you just open a Terminal and type +To start DISCOVER you just open a Terminal and type ```discover``` - DISCOVER takes the following optional arguments as input: -```--env```: ```''``` : Path to a dotenv file containing your server configuration +``` +--env: '' : Path to a dotenv file containing your server configuration -```--host```: ```0.0.0.0``` : The IP for the Server to listen +--host: 0.0.0.0 : The IP for the Server to listen -```--port``` : ```8080``` : The port for the Server to be bound to +--port : 8080 : The port for the Server to be bound to -```--cml_dir``` : ```cml``` : The cooperative machine learning directory for Nova +--cml_dir : cml : The cooperative machine learning directory for Nova -```--data_dir``` : ```data``` : Directory where the Nova data resides +--data_dir : data : Directory where the Nova data resides -```--cache_dir``` : ```cache``` : Cache directory for Models and other downloadable content +--cache_dir : cache : Cache directory for Models and other downloadable content -```--tmp_dir``` : ```tmp``` : Directory to store data for temporary usage +--tmp_dir : tmp : Directory to store data for temporary usage -```--log_dir``` : ```log``` : Directory to store logfiles. +--log_dir : log : Directory to store logfiles. +``` Internally DISCOVER converts the input to environment variables with the following names: -```DISCOVER_HOST```, ```DISCOVER_PORT```, ```DISCOVER_CML_DIR```, ```DISCOVER_CML_DIR```, ```DISCOVER_CML_DIR```, ```DISCOVER_CML_DIR```, ```DISCOVER_CML_DIR``` + +```DISCOVER_SERVER_HOST```, ```DISCOVER_PORT```, ```DISCOVER_CML_DIR```, ```DISCOVER_CML_DIR```, ```DISCOVER_CML_DIR```, ```DISCOVER_CML_DIR```, ```DISCOVER_CML_DIR``` All variables can be either passed directly as commandline argument, set in a [dotenv](https://hexdocs.pm/dotenvy/dotenv-file-format.html) file or as system wide environment variables. During runtime the arguments will be prioritized in this order commandline arguments -> dotenv file -> environment variable -> default value. -If the server started successfully your console output should look like this: - +If the server started successfully your console output should look like this: ``` -Loading environment from /my/path/to/.env - #DISCOVER Config - DISCOVER_HOST: 127.0.0.1 - DISCOVER_PORT: 37317 - DISCOVER_CML_DIR: /cml - DISCOVER_DATA_DIR: /data - DISCOVER_CACHE_DIR: /cache - DISCOVER_TMP_DIR: /tmp - DISCOVER_LOG_DIR: /log - DISCOVER_BACKEND: venv - DISCOVER_VIDEO_BACKEND: IMAGEIO +Starting DISCOVER v1.0.0... +HOST: 0.0.0.0 +PORT: 8080 +DISCOVER_CML_DIR : cml +DISCOVER_DATA_DIR : data +DISCOVER_CACHE_DIR : cache +DISCOVER_TMP_DIR : tmp +DISCOVER_LOG_DIR : log +...done ``` +You can find the full documentation of the project [here](https://hcmlab.github.io/discover). + +## Citation +If you use DISCOVER consider citing the following paper: + +``` +@article{schiller2024discover, +title={DISCOVER: A Data-driven Interactive System for Comprehensive Observation, Visualization, and ExploRation of Human Behaviour}, +author={Schiller, Dominik and Hallmen, Tobias and Withanage Don, Daksitha and Andr{\'e}, Elisabeth and Baur, Tobias}, +journal={arXiv e-prints}, +pages={arXiv--2407}, +year={2024} +} +``` \ No newline at end of file