diff --git a/Modules/Chart/documentation/mitkChart.dox b/Modules/Chart/documentation/mitkChart.dox index 64bd9eb9e2..625eb17181 100644 --- a/Modules/Chart/documentation/mitkChart.dox +++ b/Modules/Chart/documentation/mitkChart.dox @@ -1,169 +1,188 @@ /** \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. Four types of charts are supported: line, bar, spline and pie. \imageMacro{images\barChartTemperature.png,"Example bar chart",6} \imageMacro{images\lineChartTemperature.png,"Example line chart",6} \imageMacro{images\splineChartTemperature.png,"Example spline chart",6} \imageMacro{images\pieChartExample.png,"Example pie chart",6} \subsection Chart_Technical Technical background -The module uses the java script library C3js (http://www.c3js.org) to display the chart in a QWebEngineView (that renders html/js content). For examples, please visit http://c3js.org/examples.html. +The module uses the java script library C3js to display the chart in a QWebEngineView (that renders html/js content). + +For examples, please visit http://c3js.org/examples.html. \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{images\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 temperatureHD = {1.8, 3.1, 6.3, 10.2, 14.5, 17.4, 19.4, 18.9, 15.5, 11.2, 5.8, 2.6}. 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 peopleHeidelberg={{1975, 129368 }, { 1985, 134724 },{ 1990, 136796 },{ 2010, 147312 }}. 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) or chartWidget->AddData2D(peopleHeidelberg). +Data is added by calling chartWidget->AddData1D(temperatureHD, "Heidelberg") or chartWidget->AddData2D(peopleHeidelberg, "Heidelberg"), where the second argument is just a label for the data entry. + +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. \note All data can be cleared by calling chartWidget->Clear(). \imageMacro{images\2DDataExample.png,"2D data example: Heidelberg has fewer entries and their x-range (years) is smaller than Freiburg",8} \subsection Chart_type Chart type The default chart type is bar. To use a different type, you have to change it. See \ref ChartModule_brief for the available chart types. Call e.g. chartWidget->SetChartType(QmitkChartWidget::ChartType::line) for changing the chart type. Note that it is not directly displayed. A convenience function if you want to change the chart type and display the result directly is to use chartWidget->SetChartTypeAndReload(QmitkChartWidget::ChartType::line). bar chart, line chart and spline chart are somewhat similar. 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}) -chartWidget->AddData1D({2}) -chartWidget->AddData1D({3}) +chartWidget->AddData1D({5}, "entry1"); +chartWidget->AddData1D({2}, "entry2"); +chartWidget->AddData1D({3}, "entry3"); \endcode The pie chart has then entries of 50%, 20% and 30%. Calling chartWidget->AddData1D({5,2,3}) leads to a pie chart with one class having 100%. Calling \code{.cpp} -chartWidget->AddData1D({2,2,1}) -chartWidget->AddData1D({1,1}) -chartWidget->AddData1D({3}) +chartWidget->AddData1D({2,2,1}, "entry1"); +chartWidget->AddData1D({1,1}, "entry1"); +chartWidget->AddData1D({3}, "entry1"); \endcode leads to the first result again (50%, 20% and 30%) as entries are summed. \note pie charts differ significantly from the other chart types. Be aware of the differences. \subsection Chart_labels Labels Three labels can be set to custom strings. These are -Data labels provide the name for data legend entries ("Heidelberg" for our 1D data \ref{Chart_data} as it is the average temperature in Heidelberg). An example x-Axis and y-axis label would be month and temperature, respectively. - -If not set, the data labels are set to data1, data2 and so on. The x and y-axis labels are empty strings by default. +Data labels provide the name for data legend entries ("Heidelberg" for our 1D data \ref{Chart_data} as it is the average temperature in Heidelberg) and are given by the second argument of AddData1D and AddData2D. An example x-Axis and y-axis label would be month and temperature, respectively. -Call chartWidget->setDataLabels({"Heidelberg"}) to set the labels for the different data entries. Order is defined by order of calling AddData1D() and AddData2D(). +The data label argument is mandatory. The x and y-axis labels are empty strings by default. -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->SetXAxisLabel("month") and chartWidget->SetYAxisLabel("temperature") ensures the labeling of x- and y-Axis in the chart. No labels are defined as default. \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_changingData changing the data -If you want to add more data, just call chartWidget->AddData1D() or chartWidget->AddData2D() as often as desired. Then, call chartWidget->Show(). The range of x- and y-axis is adjusted automatically. +If you want to add more data, just call chartWidget->AddData1D(data, label) or chartWidget->AddData2D(data, label) as often as desired. Then, call chartWidget->Show(). The range of x- and y-axis is adjusted automatically. + +\subsection Chart_dataAttributes Changing visualization attributes of data + +The following attributes of an data entry can be changed: + + + +this is done by referencing the data entry by its label (e.g. "Heidelberg" above): chartWidget->SetColor("data1", "green"), chartWidget->SetColor("data1", "#FF4500"), chartWidget->SetLineStyle("data1", LineStyle::dashed). + +Colors are chosen automatically be C3js if not given. However, if some data entries have chosen colors and some have not, same colors may appear for different data entries. 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 defined as 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::vector temperatureHD = {1.8, 3.1, 6.3, 10.2, 14.5, 17.4, 19.4, 18.9, 15.5, 11.2, 5.8, 2.6}; std::vector temperatureOslo = {-4.3, -4, -0.2, 4.6, 10.8, 15.2, 16.4, 15.2, 10.8, 6.4, 0.7, -2.8}; -chartWidget->AddData1D(temperatureHD); -chartWidget->AddData1D(temperatureOslo); +chartWidget->AddData1D(temperatureHD, "Heidelberg"); +chartWidget->AddData1D(temperatureOslo, "Oslo"); chartWidget->SetChartType(QmitkChartWidget::ChartType::bar); -chartWidget->SetDataLabels({ "Heidelberg", "Oslo" }); chartWidget->SetXAxisLabel("month"); chartWidget->SetYAxisLabel("temperature"); chartWidget->Show(); \endcode The order when AddData1D() is called influences the colors of the bars and the order of the shown data. The line chartWidget->SetChartType(QmitkChartWidget::ChartType::bar) is superfluos (bar is the default type) and only for completeness. After Show() is called, the chart is visualized. The chart type can be changed to spline and directly showed: \code{.cpp} chartWidget->SetChartTypeAndReload(QmitkChartWidget::ChartType::spline); \endcode the equivalent code is: \code{.cpp} chartWidget->SetChartType(QmitkChartWidget::ChartType::spline); chartWidget->Show(); \endcode The temperature of another city can be added: \code{.cpp} std::vector temperatureRome = {8.1, 8.7, 8.7, 11.6, 18.8, 22.8, 25.4, 25.7, 21.4, 17.6, 12.6, 8.9}; -chartWidget->AddData1D(temperatureRome); -chartWidget->SetDataLabels({ "Heidelberg", "Oslo", "Rome" }); +chartWidget->AddData1D(temperatureRome, "Rome"); chartWidget->Show(true); \endcode If SetDataLabels() is not called, the label data2 is automatically created. As Show(true) is used, a subchart is shown. \subsection Chart_examplePieChart Pie chart A pie chart (the same as \ref ChartModule_brief) can be generated with the following code: \code{.cpp} -chartWidget->AddData1D({5}); -chartWidget->AddData1D({3}); -chartWidget->AddData1D({2}); +chartWidget->AddData1D({5}, "Heidelberg"); +chartWidget->AddData1D({3}, "Oslo"); +chartWidget->AddData1D({2}, "New York"); chartWidget->SetChartType(QmitkChartWidget::ChartType::pie); -chartWidget->SetDataLabels({ "Heidelberg", "Oslo", "New York" }); chartWidget->Show(); \endcode \subsection Chart_example2DData Chart with 2D data A line chart with two-dimensional data is the following example: \code{.cpp} std::map peopleHD= { {1975, 129368 }, { 1985, 134724 },{ 1990, 136796 },{ 2010, 147312 } }; std::map peopleFreiburg = { { 1969, 165960 },{ 1973, 174997 },{ 1982, 178545 },{ 2001, 208294 },{ 2015, 222203 } }; - chartWidget->AddData2D(peopleHD); - chartWidget->AddData2D(peopleFreiburg); + chartWidget->AddData2D(peopleHD, "Heidelberg"); + chartWidget->AddData2D(peopleFreiburg, "Freiburg"); chartWidget->SetChartType(QmitkChartWidget::ChartType::line); - chartWidget->SetDataLabels({ "Heidelberg", "Freiburg" }); chartWidget->SetXAxisLabel("year"); chartWidget->SetYAxisLabel("people"); chartWidget->Show(); \endcode Hence, 2D data is having the following assignment: year → people. In the vector peopleHD, four values are defined, in the vector peopleFreiburg, five values are defined. The defined years are different for Heidelberg (1975-2010) than for Freiburg (1969-2015). \subsection Chart_imageStatistics image statistics plugin Another example of the use of QmitkChartWidget can be found in the image statistics plugin (org.mitk.gui.qt.measurementtoolbox\QmitkImageStatisticsView). The chartWidget is named m_Controls->m_JSHistogram there. */