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 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, "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: See below examples of all types: \imageMacro{barChartTemperature.png,"Example bar chart",4} \imageMacro{lineChartTemperature.png,"Example line chart",4} \imageMacro{splineChartTemperature.png,"Example spline chart",4} \imageMacro{pieChartExample.png,"Example pie chart",4} \imageMacro{areaChartTemperature.png,"Example area chart",4} \imageMacro{areaSplineChartTemperature.png,"Example spline area chart",4} \imageMacro{scatterChartTemperature.png,"Example scatter chart",4} Call e.g. 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 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. They are also displayed in the legend. An example x-Axis and y-axis label would be month and temperature, respectively. The data label argument is mandatory. All other labels are optional and 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->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: this is done by referencing the data entry by its label (e.g. "Heidelberg" above): 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::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, "Heidelberg", QmitkChartWidget::ChartType::bar); chartWidget->AddData1D(temperatureOslo, "Oslo", QmitkChartWidget::ChartType::bar); 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 third argument of chartWidget->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::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, "Rome"); chartWidget->Show(true); \endcode As Show(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::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, "Heidelberg", QmitkChartWidget::ChartType::line); chartWidget->AddData1D(temperatureOslo, "Oslo", QmitkChartWidget::ChartType::area); chartWidget->SetColor("Heidelberg", "green"); chartWidget->SetColor("Oslo", "blue"); chartWidget->SetLineStyle("Heidelberg", QmitkChartWidget::LineStyle::dashed); chartWidget->SetXAxisLabel("month"); chartWidget->SetYAxisLabel("temperature"); chartWidget->Show(); \endcode \note Pie chart as chart type is an exception. Pie charts can't be displayed with other data entries having other chart types. \subsection Chart_exampleRemoveData Removing data Data also can be removed again (using the previous example \ref Chart_exampleMixedChart as base): \code{.cpp} chartWidget->RemoveData("Heidelberg"); chartWidget->Show(); \endcode Only the date entries labeled "Oslo" remain. Also all data can be removed: \code{.cpp} chartWidget->Clear(); chartWidget->Show(); \endcode The chart is empty now. \subsection Chart_example2DData Chart with 2D data A line chart with two-dimensional data is the following example (the same as in \ref Chart_data): \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, "Heidelberg", QmitkChartWidget::ChartType::line); chartWidget->AddData2D(peopleFreiburg, "Freiburg", QmitkChartWidget::ChartType::line); 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). \warning mixing AddData2D and AddData1D in a chart is strongly discouraged. It will work, however the visualization may be odd due to implicit and explicit given x values. \subsection Chart_imageStatistics image statistics plugin An example of the use of QmitkChartWidget in MITK can be found in the image statistics plugin (org.mitk.gui.qt.measurementtoolbox\QmitkImageStatisticsView). The chartWidget is named m_Controls->m_JSHistogram there. */