1,651
edits
Charts Definition Language (CDL): Difference between revisions
From Cumulus Wiki
Jump to navigationJump to search
m
→Explanation of the definition Keywords
| (29 intermediate revisions by the same user not shown) | |||
| Line 20: | Line 20: | ||
== The Language == | == The Language == | ||
=== The Chart block === | === The Chart block === | ||
CHART <id> TITLE [<word>...<word>] CONNECTSto [1 … 24] | CHART <id> TITLE [<word>...<word>] | ||
CONNECTSto [1 … 24] | |||
HAS WINDBARBS [ ABOVE | BELOW ] | |||
ZOOM <Integer> | |||
[ PLOT [ALL||DAILY|RECENT|EXTRA] <Plotvariable> [ [[CDL - EVAL|EVAL]] '[' <Expression> ']' ] ] | |||
| [ [[CDL - STATS|STATS]] [ALL||DAILY|RECENT|EXTRA] <Plotvariable> <Stats Type> ] | |||
AS <Line Type> | AS <Line Type> | ||
COLOUR <HTML Color> | COLOUR <HTML Color> | ||
| Line 29: | Line 33: | ||
OPACITY <Integer>.<Integer> | OPACITY <Integer>.<Integer> | ||
AXIS <Axis Type> | AXIS <Axis Type> | ||
INVISIBLE | |||
PLOT blocks repeated | PLOT blocks repeated | ||
| Line 36: | Line 39: | ||
[...] | [...] | ||
ENDCHART OUTPUT <filespec> | ENDCHART | ||
OUTPUT <filespec> | |||
INFO " <free text> " | |||
CHART […] ENDCHART blocks repeated | CHART […] ENDCHART blocks repeated | ||
| Line 50: | Line 55: | ||
The output specifier gives the user the possibility to define charts as he likes and to place these in the menu wherever he likes. In the [[Website Generator]] the placements of the charts at the moment will be limited to the [[User Defined Menu]]. In modular use the user can do whatever he likes with the resulting files. In the website the charts require the datafiles to be in the current directory. | The output specifier gives the user the possibility to define charts as he likes and to place these in the menu wherever he likes. In the [[Website Generator]] the placements of the charts at the moment will be limited to the [[User Defined Menu]]. In modular use the user can do whatever he likes with the resulting files. In the website the charts require the datafiles to be in the current directory. | ||
=== Info specifier === | |||
A free helptext can be specified after the chart using this keyword: | |||
INFO " This is a free HTMLformat helptext which can contain an axplanation of the chart " | |||
The double quotes around the helptext are obligatory and must be enclosed by spaces. | |||
=== Keywords === | === Keywords === | ||
| Line 55: | Line 65: | ||
==== Explanation of the definition Keywords ==== | ==== Explanation of the definition Keywords ==== | ||
#EQUATIONS: Starts an equations block. Such block only defines (partial) equations, it does not cause code generation in itself | #EQUATIONS (Optional construct): Starts an equations block. Such block only defines (partial) equations, it does not cause code generation in itself | ||
#CHART: Starts a chart definition | #CHART: Starts a chart definition | ||
#TITLE: Starts the title. All words until the next keyword comprise the title of the chart | #TITLE: Starts the title. All words until the next keyword comprise the title of the chart | ||
#CONNECTSTO: The integer numbers which follow CONNECTSTO represent a pane in the realtime [[Dashboard|dashboard]]. When clicked on that pane this chart appears. This is only valid on charts in the default output. For other outputs there is no semantics for CONNECTSTO and a warning is issued in the logfile if it is specified in any second or higher output. | #CONNECTSTO (Optional construct): The integer numbers which follow CONNECTSTO represent a pane in the realtime [[Dashboard|dashboard]]. When clicked on that pane this chart appears. This is only valid on charts in the default output. For other outputs there is no semantics for CONNECTSTO and a warning is issued in the logfile if it is specified in any second or higher output. | ||
#PLOT: Starts the plot specification using one of the possible variables | #HAS WINDBARBS [ ABOVE | BELOW ] (Optional construct): Defines if the chart displays the WINDBARBS showing direction and speed as indicators (this is not an exact plot of wind). Above | Below specifies the place in the chart. | ||
#[[CDL - STATS|STATS]]: Starts the statistics block using one of the possible variables. Semantics demands the variable to be plotted normally as well. | #ZOOM (Optional construct): Indicates which range selector button is the default when the chart is displayed; Defaults depend on chart range. | ||
#PLOT: Starts the plot specification using one of the possible variables. Each chart requires at least one PLOT. | |||
#[[CDL - STATS|STATS]]: Starts the statistics block using one of the possible variables. Semantics demands the variable to be plotted normally as well. IF a STATS of an equation plot is to be requested, the PLOT statement of the equation must precede the STATS statement. | |||
#RECENT: Defines the variable to be governed by the CMX parameter ''GraphHours'' and are similar to the CMX RECENT graphs (though not equal). | #RECENT: Defines the variable to be governed by the CMX parameter ''GraphHours'' and are similar to the CMX RECENT graphs (though not equal). | ||
#ALL: Defines the variable to be taken from the [[Dayfile.txt|Dayfile]] and all data for that variable will be plotted (Note that the CMX parameter ''ChartMaxDays'' will not be used) | #ALL: Defines the variable to be taken from the [[Dayfile.txt|Dayfile]] and all data for that variable will be plotted (Note that the CMX parameter ''ChartMaxDays'' will not be used) | ||
#DAILY: Identical to the ALL keyword but it sets the datarange for the chart to one month while the ALL keyword sets it to one year. | #DAILY: Identical to the ALL keyword but it sets the datarange for the chart to one month while the ALL keyword sets it to one year. | ||
#EXTRA: Defines the variable to be an extra sensor variable. It has an implicit datarange of RECENT. | #EXTRA: Defines the variable to be an extra sensor variable. It has an implicit datarange of RECENT. | ||
#AS: Defines the type of charting for that variable. | #AS (Optional construct): Defines the type of charting for that variable. All attributes of AS are optional. | ||
#[[CDL - EVAL|EVAL]] [ ]: Defines an expression for the plot variable. The equation must be placed between the square brackets, space has no value here (does not act as separator). | #[[CDL - EVAL|EVAL]] [ ]: Defines an expression for the plot variable. The equation must be placed between the square brackets, space has no value here (does not act as separator). | ||
#COLOUR: Defines the colour of that variable. | #COLOUR: Defines the colour of that variable. | ||
#ZINDEX: Defines the zIndex plane for that variable. | #ZINDEX: Defines the zIndex plane for that variable. | ||
#LINEWIDTH: Defines the linewidth for that variable. | #LINEWIDTH: Defines the linewidth for that variable. When the chart type is ''scatter'', this attribute defines the radius of the points. | ||
#OPACITY: Defines the opacity for that variable (important for area and column graphs) | #OPACITY: Defines the opacity for that variable (important for area and column graphs) | ||
#AXIS: Gives the user the possibility to specify an axis when using the EVAL construct otherwise an error is generated. | #AXIS: Gives the user the possibility to specify an axis when using the EVAL construct otherwise an error is generated. | ||
#INVISIBLE: Gives the user the possibility to switch off the initial display of a series. | |||
#ENDCHART: End the chart definition | #ENDCHART: End the chart definition | ||
#OUTPUT: Gives an optional name of an outputfile which starts at the chart where it is defined. Any chart after this OUTPUT specifier goes to this OUTPUT until another OUTPUT is found. Only the first OUTPUT specifier ( | #OUTPUT (Optional construct): Gives an optional name of an outputfile which starts at the chart where it is defined. Any chart after this OUTPUT specifier goes to this OUTPUT until another OUTPUT is found. Only the first OUTPUT specifier (implicitly: cumuluscharts.txt) accepts click events as defined by CONNECTSTO. | ||
#INFO (Optional construct): Introduces a helptext section for the chart. The free text is enclosed in double quotes and cannot contain double quotes. The double quotes are delimited by a space character. | |||
#PERIOD: Only in the context of the STATS function SMA. Gives the period of that specific running average | |||
The keywords for the actual parameters and the Graph Types speak for themselves. | The keywords for the actual parameters and the Graph Types speak for themselves. | ||
| Line 95: | Line 111: | ||
===== With the ALL/DAILY qualifier ===== | ===== With the ALL/DAILY qualifier ===== | ||
"MinTemp", "MaxTemp", "AverageTemp", " | "MinTemp", "MaxTemp", "AverageTemp", "AvgWindChill", "MaxDewpoint", "MinDewpoint","MaxFeelsLike", "MinFeelsLike", | ||
"MaxGust", "WindRun", " | "MaxGust", "WindRun", "HighAvgWindSpeed", | ||
"UV-Index", "SolarRadiation", "SunHours", | "UV-Index", "SolarRadiation", "SunHours", | ||
"DayRain", "MaxRainRate", | "DayRain", "MaxRainRate", | ||
"MinBarometer", "MaxBarometer", | "MinBarometer", "MaxBarometer", | ||
"MinHumidity", "MaxHumidity", | "MinHumidity", "MaxHumidity", | ||
"HeatingDegreeDays","CoolingDegreeDays"," | "HeatingDegreeDays","CoolingDegreeDays","DayEVT" | ||
Note: The difference between ALL and DAILY is only between the displayed datarange (6 months or 1 month) | Note: The difference between ALL and DAILY is only between the displayed datarange (6 months or 1 month) | ||
| Line 133: | Line 149: | ||
===== Axis Types ===== | ===== Axis Types ===== | ||
The following Axis are possible. | The following Axis are possible. | ||
Temp, Wind, Distance, Hours, Solar, UV, Rain, Rrate, Pressure, Humidity, DegreeDays, EVT, AQ, ppm, Free | Temp, Wind, Distance, Height, Hours, Solar, UV, Rain, Rrate, Pressure, Humidity, DegreeDays, EVT, AQ, ppm, Free | ||
This only has meaning if there is an [[CDL - EVAL|EVAL]] with a valid expression present. As an [[CDL - EVAL|EVAL]] may modify the value of the plot variable to something completely different, the original Axis belonging to that plot variable may be useless or scale wrongly. Therefore you can choose your own Axis. If there is no valid equation, a warning is given and no axis is generated. | This only has meaning if there is an [[CDL - EVAL|EVAL]] with a valid expression present. As an [[CDL - EVAL|EVAL]] may modify the value of the plot variable to something completely different, the original Axis belonging to that plot variable may be useless or scale wrongly. Therefore you can choose your own Axis. If there is no valid equation, a warning is given and no axis is generated. | ||
| Line 147: | Line 163: | ||
== The Chart Axis == | == The Chart Axis == | ||
All PlotVariables have their own defined axis and those axis will be coupled automatically to the chart. Multiple axis will be alternately added left-right where the order in the definition files determines this order. So it is the user who ultimately can define where the axis are | All PlotVariables have their own defined axis and those axis will be coupled automatically to the chart. Multiple axis will be alternately added left-right where the order in the definition files determines this order. So it is the user who ultimately can define where the axis are placed: left or right and from inside to the outside in the order where they are encountered during the parsing process. | ||
The scaling of the axis is flexible i.e. it starts with a reasonable value for the upper and lower bounds and adjusts if the real values are higher or lower. For some axis the lower bound is always 0 (e.g. rain) for another the upper and lower bounds are fixed. Specifics are found below. | |||
The following axis are currently defined and implicit for the plot variables (the user has no options here): | The following axis are currently defined and implicit for the plot variables (the user has no options here): | ||
#None | #'''None''' | ||
#Temp | #'''Temp''' - automatic scaling for min/max | ||
#Pressure | #'''Pressure''' - scaling with a pseudo-fixed scale which means the min/max values of the scale are set to the min/max all time records found in ''alltime.ini''. Highcharts itself sets the scale values such that there is a tick at the end of the scale and the min/max values fall between the ticks at the end of the scale. If the pressure gets a lower/higher value the axis will adjust automatically. The idea is that any barometer you have at home has a fixed scale and with small variations there is little movement of the needle. However when the pressure starts falling/rising significantly it is very obvious. This behaviour is mimicked by CUtils (as far as possible) | ||
#Rain | #'''Rain''' - automatic scaling with minimum value of 0 and an initial maximum of 1 (to accommodate measurement in inches) | ||
#Rrate | #'''Rrate''' - automatic scaling with minimum value of 0 and an initial maximum of 1 (to accommodate measurement in inches) | ||
#Wind | #'''Wind''' - automatic scaling for min/max | ||
#Direction | #'''Direction''' - scaling is fixed for 0 to 360 degree. When only direction is plotted two axis are created: in degrees and in wind directions (N, E, S, W). When combined with another unit only the axis with wind directions is used. | ||
#Humidity | #'''Humidity''' - scaling is fixed between 0 and 100 | ||
#Solar | #'''Solar''' - scaling is fixed between 0 and a rough estimate of the maximum theoretical value for radiation + 50 to give the scale some space. If the actual value goes beyond that, the scale will adjust. | ||
#UV | #'''UV''' - automatic scaling for maximum, minimum is 0 | ||
#Hours | #'''Hours''' - automatic scaling for maximum, minimum is 0 | ||
#Distance | #'''Distance''' - automatic scaling for maximum, minimum is 0 | ||
#DegreeDays | #'''Height''' - automatic scaling for maximum, minimum is 0, basically used for the Cloudbase | ||
#EVT | #'''DegreeDays''' - automatic scaling for maximum, minimum is 0 | ||
#Free | #'''EVT''' - automatic scaling for maximum, minimum is 0 | ||
#AQ | #'''Free''' - has no title, unit or context associated with it. It just displays values. Automatic scaling for min/max. | ||
#ppm | #'''AQ''' - automatic scaling for maximum, minimum is 0 | ||
#'''ppm''' - automatic scaling for maximum which starts at 500, minimum is 0. The default maximum is because the CO<sub>2</sub> value is around 420 (in 2022) outdoors. | |||
Translations for the axis titles come from the [Website] section (until '''''EVT''''') and should require no additional effort. | Translations for the axis titles come from the [Website] section (until '''''EVT''''') and should require no additional effort. | ||
| Line 172: | Line 191: | ||
== Additional details == | == Additional details == | ||
#All parameters can be combined in one graph with the corresponding axis automatically added. Only when scatter is defined as Line Type it is forbidden to combine it with one of the other possibilities. This may change in future. | #All parameters can be combined in one graph with the corresponding axis automatically added. <s>Only when scatter is defined as Line Type it is forbidden to combine it with one of the other possibilities. This may change in future.</s> The scatter combination with other charts types is now available but may be subject to change. | ||
#The Legend texts are implemented as translations of the PlotKeywords (the Plot Variables). You will find these in the translation file section [Compiler]. Legend entries can be multiple words (the keywords can not). | #The Legend texts are implemented as translations of the PlotKeywords (the Plot Variables). You will find these in the translation file section [Compiler]. Legend entries can be multiple words (the keywords can not). | ||
#The width of the graph container is 100% of the viewport. | #The width of the graph container is 100% of the viewport. | ||
#The height of the graph container can be specified in the | #The height of the graph container can be specified in the inifile parameters (not defined in the language to prevent overcharge): | ||
[General] | [General] | ||
ChartContainerHeight=650 (Default) | ChartContainerHeight=650 (Default) | ||
| Line 185: | Line 204: | ||
[General] | [General] | ||
MonthsOfMiracleAndWonder=jan,feb,mrt,apr,mei,jun,jul,aug,sep,okt,nov,dec | MonthsOfMiracleAndWonder=jan,feb,mrt,apr,mei,jun,jul,aug,sep,okt,nov,dec | ||
Default this variable contains the abbreviated month names according to the locale of CumulusUtils. The user may edit those names to the ones used by CMX. | Default this variable contains the abbreviated month names according to the locale of CumulusUtils. The user may edit those names to the ones used by CMX if CMX uses another ''locale'' than CumulusUtils which creates conflicts in the names the monthly log files. | ||
== Example CutilsCharts.def == | == Example CutilsCharts.def == | ||
| Line 229: | Line 248: | ||
Chart Overzicht Title Overzicht van de huidige weerstatus ConnectsTo 2 4 15 20 | Chart Overzicht Title Overzicht van de huidige weerstatus ConnectsTo 2 4 15 20 | ||
Has WindBarbs Above | |||
PLOT Temperature Colour #058DC7 zindex 90 | PLOT Temperature Colour #058DC7 zindex 90 | ||
PLOT DewPoint Colour #50B432 zindex 80 | PLOT DewPoint Colour #50B432 zindex 80 | ||
