BVS-Vis: A Web-Based Visualizer for BVS

Regine Wendt <[email protected]> and Chris Deter v1.1, 2019-04-24

Introduction

BVS is a ns-3 module that simulates the global movement of objects in the human body. Its main purpose is to model the work environment of medical nanobots. For a detailed introduction to BVS see: RegineWendt/blood-voyager-s

In this repository you find BloodVoyagerS Visualizer (BVS-Vis) and a complete docker-compose setup to run both BVS and BVS-Vis. BVS-Vis is a web-based visualizer for BVS result files. It can process a 'csvNano.csv' file and visualizes every simulation step in a three-dimensional model. It is possible to zoom in that model or to move it while the simulation is running. The simulation runs automatically or step by step. It is also possible to jump to a specific timestep. There is an option to upload different 'csvNano.csv' files. BVS-Vis streams input files and therefore can handle large files and supports compressed files as well. The jump function is limited in large streamed files. A python script to compress a 'csvNano.csv' file is included. If a compressed file is loaded a heatmap with the actual nanobot concentration gets displayed.

Start Web Visualization

BVS-Vis can be used (by opening index.html) in any browser that supports WebGL.

A webserver is recommended to run this visualizer. When using a webserver, it is possible to set a default file by putting a 'csvNano.csv' file in a folder called 'csv' inside the folder where the index.html is located. It will be automatically loaded on opening the visualizer.

It is possible to execute the python script to compress a 'csvNano.csv' file. It has an optional parameter that defines the number of decimal places that are displayed in the visualizer. By default, this is 1 which corresponds to an accuracy of 1mm.

Getting Started with NS-3 and Docker

It can be tricky to get ns-3 running. If any problems are encountered (especially with windows) it is possible to use a docker container.

Install Docker/Docker-Compose

Starting NS-3 & Web Visualization with Docker-Compose

The root directory includes a docker compose file which consists of two components. The first component is the NS-3 Docker container including the BVS module. The second component contains BVS-Vis.

A config file with runtime parameters is required for the simulation. By default, the config file is called config-blood-voyager.env and contains the following configuration:

# IMPORTANT! no spaces between '=' and value
# simulation duration in seconds
SIMDURATION=95
# number of nanobots
NUMOFNANOBOTS=305
# injection vessel [1-94]
INJECTVESSEL=62
# compression on:1 | off:0
COMPRESSION=1
# number of comma places in compressed file (default: 1)
ACCURACY=1

[Optional] If you haven’t build the image yet or the source has changed, it is necessary to (re-)build the docker image: docker-compose build.
The BVS simulation parameters inside config-blood-voyager.env must be configured or a custom file in the docker-compose file has to be defined.
Docker-compose should be running on the local machine.
The simulation can be started with docker-compose up ns3.
The BVS module will run and stop after the simulation is completed.
The visualization can be started with docker-compose up visualizer.
After opening http://localhost:8080 it is possible to see visualized results.
The visualization can be stopped with docker-compose down.

Starting NS-3 & Web Visualization with Docker

Here are commands to start BVS-Vis (without docker-compose):

Building the docker image: docker build -t bloodvoyagers --build-arg NS3VERSION=3.29 .
Execute the docker image. There are two options to specify the necessary enviroment variables with the run command.
- It is necessary to specify a .env file. For Example, config-blood-voyager.env:
  docker run -d --rm --env-file="config-blood-voyager.env" -v /path/to/output/:/var/www bloodvoyagers
- Alternatively, all necessary environment variables need to be specified:
  docker run -d --rm -e SIMDURATION=95 -e NUMOFNANOBOTS=305 -e INJECTVESSEL=62 -e COMPRESSION=1 -e ACCURACY=1 -v /path/to/output/:/var/www bloodvoyagers
Run the visualizer:
docker run -d --rm -p 80:80 -v $(pwd)/visualizer:/usr/share/nginx/html nginx:latest

Using the Web Visualization

BVS-Vis has a control panel in the upper left corner which looks like the following image:

See and download the actual source file (if available).
See the actual number of nanobots in the animation.
Upload custom BVS data file.
See the actual step and the available steps. * Indicates that more data is loaded at the moment.
Step manually or type a specific step.
Change the animation speed. Pull the slider to the left to stop the animation completely
Change visibility of vasculature.
Change heatmap scale. This part is only visible if the input file is compressed. Change the heatmap scale slider to the left, to disable the heatmap.
Access the documentation and get information about the animation control via mouse.

It is possible to control the animation with the following keys:

left click

to rotate body around its own axis

mouse scrolling

zoom into animation

right click

to move body around

Project Name	Stars	Most Recent Commit	Latest Release	Open Issues	License	Language
Gotrace	1,526	4 years ago	August 22, 2023	19	mit	JavaScript
Concurrency tracer and visualizer for Go (Golang) programming language
Jira Dependency Graph	219	2 years ago		7	mit	Python
Graph visualizer for JIRA tickets' dependencies
Docker101	196	3 years ago		9		PHP
Learn Docker in $0 \| Beginners to Advance Level
Gremlin Visualizer	181	9 months ago		31	mit	JavaScript
visualize the graph network corresponding to a gremlin query
S2map	79	5 years ago		5		C
quick and dirty latlng visualizer
Observability Workshop	32	5 months ago		47	apache-2.0	Java

Org Visualizer	22	3 years ago		9	apache-2.0	TypeScript
Organization Visualizer using Atomist project scanning
Solr Relevance Ranking Analysis	9	4 years ago		2	gpl-3.0	Python
Solr Relevance Ranking Analysis and Visualization Tool
Docker Viswarm	8	6 years ago		4	mit	JavaScript
A docker swarm visualizer
Xiaohongshu Spider Visualizer	7	5 years ago				Python
A distributed web crawler for xiaohongshu.com and visualization for the crawled content.

Bvs Vis