Migrated source code from Simantics SVN

[simantics/platform.git] / bundles / org.simantics.history / src-isv / sampleformat.mediawiki

diff --git a/bundles/org.simantics.history/src-isv/sampleformat.mediawiki b/bundles/org.simantics.history/src-isv/sampleformat.mediawiki
new file mode 100644 (file)
index 0000000..6ad2e5e
--- /dev/null
+++ b/bundles/org.simantics.history/src-isv/sampleformat.mediawiki
@@ -0,0 +1,76 @@
+=Sample Format=\r
+The sample format is a record that contains fields that describe what and how data is stored from source. Its fields are defined by the user, their datatype, and possibly unit type too.\r
+At minimum requirement there must be two fields: "time" and "value". \r
+The data type can be anything numerical; but typically is a double or an integer type.\r
+\r
+If there is the optional field "quality", then it is used for expressing discontinuation regions (value -1). Discontinuation can be passed to the collector with a NaN or null value.\r
+ \r
+An example of a simple '''Sample Format'''\r
+{| border="1" cellpadding="3" cellspacing="0" align="center"\r
+|- style="background-color: #f9f9f9;"\r
+|'''Field Name''' ||'''Required'''|| '''Description'''\r
+|- \r
+|time || yes || Time, the time of the 1st sample included into the band. \r
+|- \r
+|value || yes || First value in the band.\r
+|- \r
+|quality || no || 0 = Good, -1 = No value (Byte)\r
+|}\r
+\r
+If collector is given interval or deadband settings, some input samples may need to be dropped. \r
+If the sample format is in ''banded'' mode, then some information about dropped steps are \r
+preserved as count, avg, min, max and median values. \r
+In a banded sample there are (start)time and endTime fields - henge the name value band.\r
+\r
+An example of a '''Banded Sample Format''': \r
+{| border="1" cellpadding="3" cellspacing="0" align="center"\r
+|- style="background-color: #f9f9f9;"\r
+|'''Field Name''' ||'''Required'''|| '''Description'''\r
+|- \r
+|time || yes || Region start time, the time of the 1st sample included into the band. \r
+|- \r
+|endTime || no || Region end time, the time of the last sample included into the band. \r
+|- \r
+| ||\r
+|- \r
+|value || yes || First value in the band.\r
+|- \r
+|lastValue || no || Last value in the band. \r
+|- \r
+|avg || no || Average value from all the steps that were included. \r
+|- \r
+|median || no || Median value from all the steps that were included into the band.\r
+|- \r
+|min || no || Lowest value in the band.\r
+|- \r
+|max || no || Highest value in the band.\r
+|- \r
+| ||\r
+|- \r
+|quality || no || 0 = Good, -1 = No value (Byte)\r
+|- \r
+|count || no || The number of included samples in the band (Integer)\r
+|}\r
+\r
+To create a sample format, instantiate RecordType and add fields.\r
+<pre>\r
+       // Create a sample format ( simple though )\r
+       RecordType sampleFormat = new RecordType();\r
+       sampleFormat.addComponent("time", Datatypes.DOUBLE );\r
+       sampleFormat.addComponent("value", Datatypes.DOUBLE );\r
+       sampleFormat.addComponent("quality", Datatypes.BYTE );\r
+</pre>\r
+\r
+Optionally, get sample format from a user defined class.\r
+<pre>\r
+       class Sample {\r
+               public double time;\r
+               public double value;    \r
+       }\r
+       \r
+       // Get sample binding from a class\r
+       Binding sampleBinding = Bindings.getBinding( Sample.class );\r
+       // Get sample type from the binding\r
+       Datatype sampleFormat = sampleBinding.type();\r
+</pre>\r
+\r