diff --git a/Modules/Chart/documentation/mitkChart.dox b/Modules/Chart/documentation/mitkChart.dox
index 2c7b98dfb2..84a6111841 100644
--- a/Modules/Chart/documentation/mitkChart.dox
+++ b/Modules/Chart/documentation/mitkChart.dox
@@ -1,256 +1,256 @@
/**
\page ChartModule The MITK Chart Module
\tableofcontents
\section ChartModule_brief Description
The MITK chart module is able to show different types of charts in a widget with customizable labels.
\imageMacro{complexExample.png,"Example chart",10}
\subsection Chart_Technical Technical background
-The module uses the java script library C3js to display the chart in a QWebEngineView (that renders html/js content).
+The module uses the java script library plotly to display the chart in a QWebEngineView (that renders html/js content).
-For examples, please visit http://c3js.org/examples.html.
+For examples, please visit https://plot.ly/javascript/.
\subsection Chart_GUI GUI
\note Be sure that the dependency to the Chart Module is resolved in the CMakeLists.txt of the plugin: MODULE_DEPENDS MitkChart
.
Open the ui file of the plugin. Then add a widget (we always use the name chartWidget
in the following) at the desired position. Change the class of the widget to a user-defined widget (right click → user defined classes, see http://doc.qt.io/qt-5/designer-using-custom-widgets.html). Set "QWidget" as base class. Set "QmitkChartWidget" as class name and "QmitkChartWidget.h" as include file.
\imageMacro{userDefinedWidget.png,"User defined widget",10}
\subsection Chart_data Data
The most important functionality is to add data to the chartWidget. Either one dimensional or two dimensional data can be used. One-dimensional data has the same interval between values on the x-axis (and no x-axis values) while the two-dimensional data has arbitrary x-axis difference values (and given x-axis values).
An example for one-dimensional data is the temperature for each month of a year: std::vector
. The first entry corresponds (implicitly) to the temperature in january, two second to the temperature in february the last entry to the temperature in december. Thus, the x values have same intervals. The given temperature values are defined as y-axis values.
An example for two-dimensional data is the people living in a city in different years: std::map
Thus, the x-values are given as their intervals are different (10 years, 5 years, 10 years). Each x value is connected to an y-value that represents the amount of people (1975 → 129368, 1985 → 134724, ...).
Data is added by calling chartWidget->AddData1D(temperatureHD, "Heidelberg")
or chartWidget->AddData2D(peopleHeidelberg, "Heidelberg")
, where the second argument is a label for the data entry.
\imageMacro{2DDataExample.png,"2D data example: Heidelberg has fewer entries and their x-range (years) is smaller than Freiburg",8}
As the data labels are used as identifier, they have to be unique. This is checked. If non-unique entries are entered, they are made unique by adding numbers. Example:
\code{.cpp}
chartWidget->AddData1D(temperatureHD, "Heidelberg")
chartWidget->AddData1D(temperatureOslo, "Heidelberg")
\endcode
will result in the labels "Heidelberg" and "Heidelberg0", whereas "Heidelberg0" refers to temperatureOslo
.
If you want to add more data, just call chartWidget->AddData1D(data, label, chartType)
or chartWidget->AddData2D(data, label, chartType)
as often as desired. Then, call chartWidget->Show()
. The ranges of x- and y-axis are adjusted automatically.
To delete single data entries, call chartWidget->RemoveData(label)
and update the chart area with chartWidget->Show()
. All data can be cleared by calling chartWidget->Clear()
.
\subsection Chart_type Chart type
The default chart type is bar
. To use a different type, you have to change it.
Seven chart types are available:
bar
line
spline
pie
are
area_spline
scatter
chartWidget->SetChartType(label, QmitkChartWidget::ChartType::line)
for changing the chart type. Note that it is not directly displayed. To change the chart type for all data entries and display the result, call chartWidget->SetChartTypeForAllDataAndReload(QmitkChartWidget::ChartType::line)
.
All chart types except pie chart can be also used mixed (different chart types in the same chart). Pie charts are handled differently. The input data sum is regarded as 100%. The values of all data entries are summed. Example:
\code{.cpp}
chartWidget->AddData1D({5}, "entry1", QmitkChartWidget::ChartType::pie);
chartWidget->AddData1D({2}, "entry2", QmitkChartWidget::ChartType::pie);
chartWidget->AddData1D({3}, "entry3", QmitkChartWidget::ChartType::pie);
\endcode
The pie chart has then entries of 50%, 20% and 30%. Calling chartWidget->AddData1D({5,2,3}, "entry", QmitkChartWidget::ChartType::pie)
leads to a pie chart with one class having 100%. Calling
\code{.cpp}
chartWidget->AddData1D({2,2,1}, "entry1", QmitkChartWidget::ChartType::pie);
chartWidget->AddData1D({1,1}, "entry2", QmitkChartWidget::ChartType::pie);
chartWidget->AddData1D({3}, "entry3", QmitkChartWidget::ChartType::pie);
\endcode
leads to the first result again (50%, 20% and 30%) as entries are summed.
\warning pie charts differ significantly from the other chart types. Be aware of the differences.
\subsection Chart_labels Labels
Four labels can be set to custom strings. These are
chartWidget->SetXAxisLabel("month")
and chartWidget->SetYAxisLabel("temperature")
ensures the labeling of x- and y-Axis in the chart. No labels are defined as default.
chartWidget->SetTitle("temperature chart")
adds a title to the chart.
\note The legend position (of data labels) can be set by chartWidget->SetLegendPosition(QmitkChartWidget::LegendPosition::bottom)
.
\note To hide the legend, call chartWidget->SetShowLegend(false)
.
\subsection Chart_show Displaying the chart
Finally, the chart is displayed by calling chartWidget->Show(bool)
. If the optional parameter is set to true, a subchart is shown additionally. That's useful for ensuring the overview if the user wants to zoom in.
\subsection Chart_dataAttributes Changing visualization attributes of data
Besides the chart type, the following attributes of a data entry can be changed:
chartWidget->SetColor("Heidelberg", "green")
, chartWidget->SetColor("Heidelberg", "#FF4500")
, chartWidget->SetLineStyle("Heidelberg", LineStyle::dashed)
and chartWidget->SetShowDataPoints(false)
.
\note SetShowDataPoints is a global attribute and valid for all data entries due to technical reasons.
-Colors are chosen automatically be C3js if not given. However, if some data entries have given colors and some have not, same colors may appear for different data entries. Color can be given as strings (natural names like red or hexadecimal numbers like #FF0000. For color selection, the following reference is helpful: https://www.w3schools.com/cssref/css_colors.asp)
+Colors are chosen automatically by plotly if not given. However, if some data entries have given colors and some have not, same colors may appear for different data entries. Color can be given as strings (natural names like red or hexadecimal numbers like #FF0000. For color selection, the following reference is helpful: https://www.w3schools.com/cssref/css_colors.asp)
Line style only can be set if ChartType is QmitkChartWidget::ChartType::line
. It is ignored otherwise. Also, if a non-existing label is given, the command is ignored. The default linestyle is LineStyle::solid
.
\section Chart_example Example
\subsection Chart_exampleBarChart Bar chart
To create and visualize a bar chart with two data sets, x/y-axis labels and data labels, the following code is used:
\code{.cpp}
std::vectorchartWidget->AddData1D()
is superfluous and only for completeness as QmitkChartWidget::ChartType::bar
is the default chart type. After Show()
is called, the chart is visualized.
The chart type for all data entries can be changed to spline and directly showed:
\code{.cpp}
chartWidget->SetChartTypeForAllDataAndReload(QmitkChartWidget::ChartType::spline);
\endcode
the equivalent code is:
\code{.cpp}
chartWidget->SetChartType("Heidelberg", QmitkChartWidget::ChartType::spline);
chartWidget->SetChartType("Oslo", QmitkChartWidget::ChartType::spline);
chartWidget->Show();
\endcode
The temperature of another city can be added:
\code{.cpp}
std::vectorShow(true)
is used, a subchart is shown.
\subsection Chart_examplePieChart Pie chart
A pie chart (the same as in \ref Chart_type) can be generated with the following code:
\code{.cpp}
chartWidget->AddData1D({5}, "Heidelberg", QmitkChartWidget::ChartType::pie);
chartWidget->AddData1D({3}, "Oslo", QmitkChartWidget::ChartType::pie);
chartWidget->AddData1D({2}, "New York", QmitkChartWidget::ChartType::pie);
chartWidget->Show();
\endcode
\note Only one pie chart at a time can be displayed.
\subsection Chart_exampleMixedChart Mixed chart
Chart types and attributes like colors and line styles can be mixed as seen in the code example below (example result is the chart in \ref ChartModule_brief):
\code{.cpp}
std::vectororg.mitk.gui.qt.measurementtoolbox\QmitkImageStatisticsView
). The chartWidget
is named m_Controls->m_JSHistogram
there.
*/