Skip to content

Commit f68f4ca

Browse files
AntonMrtAntonMrt
committed
readme page
1 parent 12cd211 commit f68f4ca

File tree

1 file changed

+42
-212
lines changed

1 file changed

+42
-212
lines changed

‎README.md‎

Lines changed: 42 additions & 212 deletions
Original file line numberDiff line numberDiff line change
@@ -1,236 +1,66 @@
1+
![C++](https://img.shields.io/badge/c++-%2300599C.svg?style=Plastic&logo=c%2B%2B&logoColor=white)
12
![Workflow](https://github.com/valvals/devtools/actions/workflows/cmake-multi-platform.yml/badge.svg?branch=main)
23
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
3-
![C++](https://img.shields.io/badge/c++-%2300599C.svg?style=Plastic&logo=c%2B%2B&logoColor=white)
4+
5+
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=DevToolsOrganization_matrix-data-visualization-DAVIS&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=DevToolsOrganization_matrix-data-visualization-DAVIS)
46
[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=DevToolsOrganization_matrix-data-visualization-DAVIS&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=DevToolsOrganization_matrix-data-visualization-DAVIS)
7+
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=DevToolsOrganization_matrix-data-visualization-DAVIS&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=DevToolsOrganization_matrix-data-visualization-DAVIS)
58
[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=DevToolsOrganization_matrix-data-visualization-DAVIS&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=DevToolsOrganization_matrix-data-visualization-DAVIS)
6-
[<img src="https://github.com/user-attachments/assets/7425ddb9-8b6e-4303-8e29-f1144cc79acb" width="220">](https://github.com/DevToolsOrganization)
9+
[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=DevToolsOrganization_matrix-data-visualization-DAVIS&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=DevToolsOrganization_matrix-data-visualization-DAVIS)
10+
[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=DevToolsOrganization_matrix-data-visualization-DAVIS&metric=bugs)](https://sonarcloud.io/summary/new_code?id=DevToolsOrganization_matrix-data-visualization-DAVIS)
11+
[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=DevToolsOrganization_matrix-data-visualization-DAVIS&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=DevToolsOrganization_matrix-data-visualization-DAVIS)
12+
13+
714

815
![Logo](https://github.com/valvals/devtools/assets/104432560/27f28dde-27bc-47f6-8696-f80fb7b4661b)
916

17+
</br>
1018

11-
## Table of Contents
19+
# [------------> FULL DOCUMENTATION PAGE <------------](https://devtoolsorganization.github.io/matrix-data-visualization-DAVIS/#/)
1220

13-
* [💡 About](#-about)
14-
* [🔍 Examples](#-examples)
15-
* [💻 Usage](#-usage)
16-
* [⚒️ Setup](#-setup)
17-
* [❓ FAQ](#-faq)
18-
* [🚀 Room for Improvement](#-room-for-improvement)
19-
* [⭐ Used By](#-used-by)
20-
* [🐝 Authors](#-authors)
21-
* [📞 Contacts](#-contacts)
22-
* [📝 Licence](#-license)
21+
</br>
2322

2423

2524
# 💡 About
26-
DAVIS (Data Visualisation tool) is utility for data visualization. The visualization is based on [Plotly javascript](https://plotly.com/) So DAVIS generate html page with injected data from code and after that launch browser to show it.
27-
28-
One of the main tasks we solve is to make it easier to debug your application. With Davis you can easy visualize your one- and two-dimensional data variables.
29-
30-
Davis is easy-to-use tool:
31-
* one .h file, one .cpp file, one .js file
32-
* only native c++11 functions, zero external dependences
33-
* simple short syntaxis for minimize code you need to write
34-
35-
# 🔍 Examples
36-
37-
<details>
38-
<summary>Example 1</summary>
39-
40-
```cpp
41-
#include "davis.h"
42-
43-
// vals - is user's 2d array
44-
int rows = 20;
45-
int cols = 20;
46-
int** vals = new int* [rows];
47-
for (int i = 0; i < rows; ++i) {
48-
vals[i] = new int[cols];
49-
for (int j = 0; j < cols; ++j) {
50-
vals[i][j] = i * cols + j;
51-
}
52-
}
53-
dv::show(vals, rows, cols); // pass varible and dimensions of 2d array
54-
```
55-
![2d](https://github.com/valvals/devtools/assets/104432560/16832af7-d8c4-4af9-b4b1-60b0d6027478)
56-
</details>
57-
58-
<details>
59-
<summary>Example 2</summary>
60-
61-
```cpp
62-
#include "davis.h"
63-
64-
//it possible and std::list<std::vector<double>> values = ...
65-
// std::vector<std::list<double>> values = ...
66-
std::vector<std::vector<double>> values = {{30.3, 40, 98, 76}
67-
, {99, 45, 20, 1}
68-
, {5, 56, 93, 25}
69-
, {45, 23, 90, 2}};
70-
auto config = dv::Config();
71-
config.typeVisual = dv::VISUALTYPE_SURFACE; // select surface visual mode
72-
config.surf.colorSc = dv::COLORSCALE_THERMAL; // change colorscale
73-
bool result = dv::show(values, "testSurfacePage", config); // pass 2d data, html page name, configuration structure
74-
```
75-
![surf](https://github.com/valvals/devtools/assets/104432560/8d1c5488-049f-4471-9e58-1e97b59c03e7)
76-
</details>
77-
78-
<details>
79-
<summary> Example 3 </summary>
80-
81-
```cpp
82-
#include "davis.h"
83-
84-
int vals[] = {2, 6, 4, -34, 56, 33, 2, 15};
85-
auto config = dv::Config();
86-
config.heatmap.title = "Custom title"; // change default settings to custom for heatmap
87-
config.heatmap.xLabel = "Custom xLabel"; // change default settings to custom for heatmap
88-
config.heatmap.yLabel = "Custom yLabel"; // change default settings to custom for heatmap
89-
bool result = dv::show(vals, sizeof(vals) / sizeof(vals[0]), "htmlPageName", config);
90-
```
91-
![chart](https://github.com/valvals/devtools/assets/104432560/43903324-f49c-42f3-9ef1-3cb7e95a786d)
92-
</details>
93-
94-
# 💻 Usage
95-
All user's functions, structs, etc. are placed in `dv::` namespace.
96-
97-
<details>
98-
<summary>Show(...) function</summary>
99-
100-
## Show(...) function
101-
There is one template overload function for visualization different types of data:
102-
103-
```cpp
104-
template <typename T>
105-
dv::show(...)
106-
```
107-
108-
First arguments of `dv::show(...)` could be either pointer to array:
109-
| Arguments | Description |
110-
| ------------ | ------------ |
111-
| ` T** data, uint64_t arrRows, uint64_t arrCols` | 2d array with arrRows × arrCols size. Data placed inside array of arrays |
112-
| ` const T* data, uint64_t arrRows, uint64_t arrCols` | 2d array with arrRows × arrCols size. Data placed inside pseudo 2d array (element access [i*arrCols + j]) |
113-
| ` const T* data, uint64_t count` | 1d array. Data placed inside array |
114-
115-
or container:
116-
| Arguments | Description |
117-
| ------------ | ------------ |
118-
| ` C const& container_of_containers ` | 2d array. Data placed inside container of containers. Containers can be `std::vector`, `std::list`, `std::array`, etc. Content of containers must be convertable to `double` |
119-
| ` C const& container` | 1d array. Data placed inside container. Сontainer requirements are the same |
120-
121-
122-
Two last arguments of `dv::show(...)` are also the same: `const std::string& htmlPageName` and `const dv::Config& configuration`. Theese arguments have default values.
123-
* `htmlPageName` - name of html page will be generated
124-
* `configuration` - configuration structure with custom settings
25+
DAVIS (Data Visualisation tool) is utility for data visualization. The visualization is based on [Plotly javascript](https://plotly.com/).
26+
DAVIS generates html page with injected data from code and after that launch browser to show it.
27+
DAVIS is available like C++ one-header library for quick matrix debugging/visualization, GUI- and CMD- application for text files visualization.
12528

126-
</br>
29+
One of the main tasks we solve is to make it easier to debug your application. With DAVIS you can easy visualize your one- and two-dimensional data variables.
30+
The second one task is quick and easy visualization of files with numerical data with GUI application.
12731

128-
```cpp
129-
using std::vector;
130-
using std::string;
131-
132-
//! 2-dimensional array
133-
template <typename T>
134-
bool show(T** data, uint64_t arrRows, uint64_t arrCols,
135-
const string& htmlPageName = dvs::kAppName, const Config& configuration = Config());
136-
137-
//! 1-dimensional array that simulates a 2-dimensional one (element access [i*cols+j])
138-
template <typename T>
139-
bool show(const T* data, uint64_t arrRows, uint64_t arrCols,
140-
const string& htmlPageName = dvs::kAppName, const Config& configuration = Config());
141-
142-
//! 1-dimensional array
143-
template <typename T>
144-
bool show(const T* data, uint64_t count, const string& htmlPageName = dvs::kAppName, const Config& configuration = Config());
145-
146-
//! 1-dimensional container
147-
template<typename C,
148-
typename T = std::decay_t<decltype(*begin(std::declval<C>()))>,
149-
typename = std::enable_if_t<std::is_convertible_v<T, double>> >
150-
bool show(C const& container, const string& htmlPageName = dvs::kAppName, const Config& configuration = Config());
151-
152-
//! 2-dimensional container
153-
template<typename C,
154-
typename T = std::decay_t<decltype(*begin(std::declval<C>()))>,
155-
typename E = std::decay_t<decltype(*begin(std::declval<T>()))>,
156-
typename = std::enable_if_t<std::is_convertible_v<E, double>> >
157-
bool show(C const& container_of_containers, const string& htmlPageName = dvs::kAppName, const Config& configuration = Config());
158-
```
159-
</details>
160-
161-
<details>
162-
<summary>Configuration structure</summary>
163-
164-
## Configuration structure
165-
Data vizuailisation can be tunned with using custom configuration `dv::Config`.
166-
Configuration storred 3 structures and 1 enumeration.
167-
168-
1. Create `dv::Config` object;
169-
170-
2. Change it's type (or not, so it will be `VISUALTYPE_AUTO`)
171-
```cpp
172-
enum config_visualizationTypes {
173-
VISUALTYPE_AUTO, //if user not forces some specific type it will be recognized by context
174-
VISUALTYPE_CHART,
175-
VISUALTYPE_HEATMAP,
176-
VISUALTYPE_SURFACE
177-
};
178-
```
179-
180-
3. Change fields of neaded visualisation type
181-
182-
| Name of structure | Description |
183-
| ------------ | ------------ |
184-
|chart |for chart settings|
185-
|heatmap |for heatmap settings |
186-
|surf |for surface settings|
187-
188-
Settings fields can be
189-
* `title` - title at top of image
190-
* `xLabel` - title of X axis
191-
* `yLabel` - title of Y axis
192-
* `zLabel` - title of Z axis
193-
* `colorScale` - type of colorscale from enum `config_colorscales`
194-
195-
4. Pass it to `dv::show(...)`;
196-
</details>
32+
<img src="docs//_media//DAVIS-components.png" width="720">
19733

19834

19935

20036

20137
# ⚒️ Setup
202-
1. Download **davis.cpp**, **davis.h** and **plotly-2.27.0.min.js** from our last [release](https://github.com/valvals/devtools/releases)
203-
2. Put them in one folder in your project
204-
3. Include **davis.h** to your project
205-
4. Now you can use Davis functionality
206-
207-
# ❓ FAQ
208-
### Generated html page is empty in browser
209-
Check you building folder, find folder **davis_htmls** and check if **plotly-2.27.0.min.js** exists.
210-
If it not exists copy this file manualy to this place.<br>
211-
And create bug issue :)
212-
213-
### Can I use newer Plotly .js file?
214-
All our test are made for plotly .js file which is placed at our last [release](https://github.com/valvals/devtools/releases) <br>
215-
But probably newer version will also work. So download newer .js file [at plotly page](https://plotly.com/javascript/), rename it to **plotly-2.27.0.min.js** and test by yorself.
216-
217-
### Which containers can I use in show() function?
218-
Containers must support implementation of `begin()` and `end()` methods. Content of containers must be convertable to `double`
219-
220-
221-
# 🚀 Room for Improvement
222-
Our next steps will involve:
223-
* template functions for saving arrays like text files with separators
224-
* compiling Davis to exe-file which provide command line interface for visualisation text files or copypasted data
225-
* adding some evaluated statistic information abou data to generated html page
226-
227-
# ⭐ Used By
228-
This project is used by the following companies:
229-
- A. N. Sevchenko Institute of Applied Physical Problems of Belarusian State University
38+
[Visit setup page](https://devtoolsorganization.github.io/matrix-data-visualization-DAVIS/#/downloads)
39+
23040

23141
# 🐝 Authors
232-
[AntonMrt](https://www.github.com/AntonMrt), [ValeryStk](https://www.github.com/ValeryStk)\
233-
You are welcome to our team!
42+
<a href="https://github.com/DevToolsOrganization"><img width="220"
43+
src="https://github.com/user-attachments/assets/7425ddb9-8b6e-4303-8e29-f1144cc79acb"></a>
44+
45+
<table>
46+
<tbody>
47+
<tr style="border: 1px">
48+
<td align="center" >
49+
<a href="https://www.github.com/AntonMrt"><img width="100 height="100"
50+
src="https://avatars.githubusercontent.com/u/104432560?v=4"></a>
51+
</br>
52+
Anton
53+
</td>
54+
<td align="center">
55+
<a href="https://www.github.com/ValeryStk"><img width="100 height="100"
56+
src="https://avatars.githubusercontent.com/u/73784374?v=4"></a>
57+
</br>
58+
Valery
59+
</td>
60+
61+
</tr>
62+
<tbody>
63+
</table>
23464

23565
# 📞 Contacts
23666
For any questions please contact<br>

0 commit comments

Comments
 (0)