.. highlightlang:: us .. index:: Überblick UniPlot-Datendateien, netCDF-Dateien, Datendateien .. _uberblick-netcdf-dateien: .. _overview-netcdf-files: Überblick UniPlot-Datendateien ============================== Wenn Sie mit UniPlot Daten importieren, z. B. aus Excel- oder INCA-Dateien, werden Sie zunächst in das UniPlot-Datenformat (nc2) konvertiert. Bis UniPlot R2011 konnten optional netCDF-Dateien erzeugt werden. netCDF ist ein Dateiformat für wissenschaftliche Messdaten, das an der University Corporation for Atmospheric Research entwickelt wurde (siehe :ref:`copyright-netcdf`). Ab UniPlot R2012 werden netCDF-Dateien nicht mehr verwendet. Inhalt einer UniPlot-Datendatei ------------------------------- Das folgende Listing enthält eine Ausgabe des Programms :ref:`ncdump_exe`. Das Programm gibt des Inhalt einer nc- oder nc2-Datei als Text-Datei aus. (Mit dem Programm :ref:`ncgen_exe` könnte diese Datei wieder in eine (binäre) nc2-Datei umgewandelt werden.) .. code-block:: none :linenos: netcdf Test1.xls { dimensions: n = 5 ; variables: float EngSpd(n) ; EngSpd:title = "EngSpd" ; EngSpd:long_name = "EngSpd [RPM]" ; EngSpd:units = "RPM" ; float PME(n) ; PME:title = "PME" ; PME:long_name = "PME [bar]" ; PME:units = "bar" ; // global attributes: :Origin = "D:\\uniplot_du\\samples\\Test1.xls" ; :Source = "FEV Software and Testing Solutions GmbH (www.uniplot.de)" ; :Creator = "UniPlot Excel Converter v3" ; data: EngSpd = 1006.00, 1249.00, 1512.00, 1708.00, 1804.00; PME = 8.47, 9.33, 10.64, 11.21, 11.27; } .. highlightlang:: us Dimensionen ^^^^^^^^^^^ Jeder Kanal hat eine benannte Dimension. Alle Kanäle mit der selben Dimension werden im :ref:`Dateneditor ` in einer Tabelle gemeinsam angezeigt. Hat der Kanal ``A`` die Dimension ``n1 = 10`` (10 Punkte) und der Kanal ``B`` die Dimension ``n2 = 10`` (ebenfalls 10 Punkte) werden die Kanäle im Dateneditor in zwei verschiedenen Tabellen angezeigt. Ein Kanal kann auch mehrere Dimension enthalten, diese Eigenschaft wird von UniPlot aber nur bei Stringkanälen verwendet. Dabei ist die erste Dimension die Anzahl der Strings und die zweite Dimension die Länge des längsten Strings. Stringkanäle sind also eine Matrix von Zeichen. Attribute ^^^^^^^^^ Ein Attribut ist ein Key/Value-Paar. Der Key ist ein Name und der Value ist ein Wert mit einem Datentyp und einer Länge. UniPlot-Datendateien kennen folgende Datentypen für Attribute und Kanäle: .. list-table:: :header-rows: 1 * - Datentyp - Bedeutung * - NC_CHAR - Ein Byte einer Zeichenkette. * - NC_INT8 - Eine ganze Zahl mit 8 Bits (1 Byte). (Wertebereich -127 und 128 bzw. 0 bis 255.) * - NC_INT16 - Eine ganze Zahl mit 16 Bits (2 Bytes). * - NC_INT32 - Eine ganze Zahl mit 32 Bits (4 Bytes). * - NC_FLOAT - Eine einfach genaue Gleitkommazahl (4 Bytes). * - NC_DOUBLE - Eine doppelt genaue Gleitkommazahl (8 Bytes). Neben dem Datentyp hat der Attribut-Wert eine Länge. Ist der Attribut-Wert eine Zeichenkette, ist die Länge die Anzahl an Bytes. Ist der Attributwert ein Vektor von doppelt genauen Gleitkommazahlen, ist die Länge die Anzahl der Gleitkommazahlen. Auf Attributwerte kann immer nur als Ganzes zugegriffen werden. Um z. B. ein Zeichen eines Attributwertes zu ändern, wird der ganze Attributwert gelesen, geändert und anschließend komplett wieder gespeichert. Bei Kanälen (siehe unten) können einzelne Zahlen geändert werden, ohne den ganzen Kanal lesen bzw. schreiben zu müssen. Attribute werden deshalb für kleine Datenmengen verwendet (kleiner als 1.000 Bytes), sie dürfen aber auch einige MB groß sein. Eine UniPlot-Datendatei kann bis zu 20.000 globale Attribute enthalten. Global heißen die Attribute, weil sie sich auf die ganze Datei beziehen. Die Kanäle enthalten ebenfalls eine Liste von Attributen, den Kanal-Attributen. Unter :ref:`netcdf-attribute` werden die Attribute beschrieben, die UniPlot verwendet. Kanäle ^^^^^^ Kanäle sind ebenfalls Key/Value-Paare. Der Key ist der Kanalname und der Wert ist ein Vektor mit Zahlen. Die Vektorlänge kann bis zu ca. 2,1 Milliarden Elemente betragen. :: time = [0.1, 0.2, 0.3, ..., 2.000.000] Kanal Namen ----------- Ab UniPlot 5.14.5 dürfen die Kanalnamen die folgenden Sonderzeichen enthalten: ``.``, ``-``, ``+``, ``$``, ``#``, ``~``, ``!``, ``^``, ``&``, ``%``. Damit der Formelinterpreter weiterhin wie gewohnt benutzt werden kann und keine Probleme beim Datenaustausch oder in Automatisierungen entstehen, kann der Kanalname alternativ auch mit Unterstrichen anstatt Sonderzeichen an die Funktion übergeben werden. Beispiel: Die NC-Datei enthält einen Kanal ``AI50%+m``. Die folgenden beiden Aufrufe liefern die selbe *varid*:: varid = nc_varid(ncid, "AI50%+m"); varid = nc_varid(ncid, "AI50__m"); Wenn die NC-Datei jedoch Kanalnamen enthält, die sich nur durch Sonderzeichen unterscheiden, liefert der Aufruf mit Unterstrichen unter Umständen verschiedene varids zurück. Der Grund dafür ist, dass die Funktion die Suche beim ersten passenden Kanalnamen beendet. Beispiel: Eine NC-Datei enthält die Kanalnamen ``AI50%+m`` (varid 0), ``AI50%-m`` (varid 1): Der folgende Aufruf liefert die *varid* = 1:: varid = nc_varid(ncid, "AI50%-m"); Beim Aufruf mit zwei Unterstrichen liefert die Funktion die *varid* der Variablen ``AI50%+m``, also die *varid* = 0:: varid = nc_varid(ncid, "AI50__m"); Um Probleme mit dem Formelinterpreter zu vermeiden, sollten sich alle Kanalname unterscheiden, auch wenn die Sonderzeichen durch Unterstriche ersetzt würden. Falls die NC-Datei mit UniPlot erzeugt worden ist, werden die Variablen die sich nur durch die Sonderzeichen unterscheiden durchnummeriert. Dabei bleibt der erste Kanal unverändert. Alle folgenden Kanäle, die sich nur durch die Sonderzeichen unterscheiden werden beginnend bei 0 durchnummeriert. .. _netcdf-up: Eigenschaften von UniPlot-Datendateien (nc2) -------------------------------------------- * Das nachträgliche Zufügen oder Entfernen von Attributen oder Kanälen ist bei vielen Messdaten-Dateiformaten nicht möglich oder führt zum Kopieren der ganzen Datei. nc2-Dateien können problemlos nachträglich geändert werden. * Stabilität: Bei den meisten Messdaten-Dateiformaten werden bei Änderungen die Daten direkt in die Datei geschrieben. Wird eine Reihe von Änderungen an den Daten durchgeführt und eine der Änderungen schlägt fehlt (z. B. wegen Netzwerkstörungen, Stromausfall oder Softwarefehlern), ist die Datei fehlerhaft. Bei nc2-Dateien können die Änderungen wieder rückgängig gemacht werden, weil UniPlot-Datendateien Transaktionen verwenden. * Häufig kompaktere Dateien, weil Teile der Datei komprimiert werden. * Keine Größenbeschränkung der Dateien auf 2 oder 4 GB, es sind 1 TB große Dateien mit 2,1 Milliarden Punkten pro Kanal möglich. .. _nc-functions: Funktionen ---------- .. us.makeindex nc.tools, Tools .. include:: ../ftab/nc-tools.ftab .. us.makeindex NC_open, Öffnen und Schließen .. include:: ../ftab/NC_open.ftab .. us.makeindex NC, Globale Funktionen .. include:: ../ftab/NC.ftab .. us.makeindex NC_Dim, Dimensionen .. include:: ../ftab/NC_Dim.ftab .. us.makeindex NC_Var, Variablen .. include:: ../ftab/NC_Var.ftab .. us.makeindex NC_Att, Attribute .. include:: ../ftab/NC_Att.ftab .. _netcdf-attribute: Standard-Attribute ------------------ In UniPlot-Datendateien, können neben den Kanälen auch Attribute (Stammdaten) in der Form :: AttributName = AttributWert geschrieben werden. Es wird dabei zwischen globalen Attributen (Attribute die sich auf die gesamte Datei beziehen) und Kanal-Attributen (Attribute die sich nur auf einen Kanal beziehen) unterschieden. Bei den Attributnamen wird Groß-/Kleinschreibung unterschieden. .. _globale-attribute: Globale Attribute ^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 * - Attribut-Name - Datentyp - Bedeutung * - Origin - char - Name aus der die Datendatei entstanden ist, z. B. "c:/test.xls". * - Source - char - Ersteller des Import-Filters, z.B. "FEV Software and Testing Solutions GmbH (www.uniplot.com)" * - Creator - char - Name des Import-Filters, dem Namen kann eine Versionsnummer folgen. Z. B. UniPlot Pasy 1.0. * - Date - char - Datum * - Time - char - Zeit * - Range - int[2] - * - _nc_dl_driver, _nc_dl_driverinfo, _nc_dl_source, _nc_dl_loadcount - char und int - siehe :ref:`delay-loading`. * - _nc_hasgroups - Zahl - Siehe Kanalattribut ``_nc_group``. .. _data-channel-attributes: Kanal-Attribute ^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 * - Attribut-Name - Datentyp - Bedeutung * - title - char - * - long_name - char - * - units - char - Physikalische Einheit, z. B. Nm * - scale_factor - double - Der Kanal wird über die Formel x \* scale_factor + add_offset transformiert * - add_offset - double - Siehe Attribut scale_factor. * - missing_value - wie Kanal - Der Datentyp des Attributs ``missing_value`` ist der Datentyp des Kanals. * - Type - char - Wert ist entweder "Time Channel" oder "Data Channel". * - datatype - char - Mögliche Werte: "date", "time", "datetime" * - C_format - char - Formatzeichenkette, siehe :ref:`printf`. * - __Delete__ - int - Bedeutet, dass der Kanal zum Löschen markiert ist: Wert 0 oder 1 * - Description - char - Beschreibung des Kanals * - Comment - char - Kommentar zum Kanal * - _FillValue - wie Kanal - * - _formula_text - char - * - _formula_description - char - * - _formula_comment - char - * - _formula_onlyif - char - * - _channel_type - char - "formula"/"formula_not_registered" * - valid_range - wie Kanal - ``valid_range`` ist ein Kanalattribut, das den gültigen Wertebereich angibt. Das Attribut enthält zwei Werte. Der erste Wert definiert die untere gültige Grenze und der zweite Wert die obere gültige Grenze. Liegt ein Wert außerhalb des Bereichs, wird die Zahl im Datenbrowser in rot ausgegeben. Der Datentyp des Attributs sollte mit dem Datentyp des Kanals übereinstimmen. * - _nc_enum - char - Das Attribut kann beliebig viele Wert/Text-Paare enthalten. Die einzelnen Elemente müssen durch Oder-Zeichen getrennt sein. Beispiel: ``0|Off|1|On|2|Error``. Die Reihenfolge ist ``Wert|Text|Wert|Text|...``. Das Dezimaltrennzeichen ist ein Punkt (.). Siehe :ref:`nc_get_enum_values`. Beim Laden von 2D-Datensätzen über den Datenbrowser werden die Werte des Attributes für die Beschriftung der Y-Achse verwendet. Auch die Funktion :ref:`auto_LoadDataset` lädt die Werte in die y-Achse. * - XStart_XDelta - double[2] - Startwert und Delta, wenn der Kanal als t/y-Kurve geladen wird. * - nc_min, nc_max, nc_monotone, nc_has_missings, nc_change_counter - double - Siehe :ref:`nc_varinq_info`. * - _nc_dl_loaded, _nc_dl_loadinfo - int - siehe :ref:`delay-loading`. * - _nc_group - char - Enthält einen durch Schrägstriche (slash ``/``) getrennten Pfad zur Anzeige der Kanalnamen in einer Baumstruktur, z. B. ``"Angle Data/Heat Release"``. Das globale Attribut ``_nc_hasgroups`` muss auf 1 gesetzt sein, damit die Gruppen verwendet werden. Gruppieren von Kanälen (Baumstruktur) ------------------------------------- Die Kanäle, die in in einer Gruppe enthalten sein sollen, erhalten das Attribut ``_nc_group`` (Datentyp = NC_CHAR), z. B. ``_nc_group = "Angle Data/Heat Release"`` oder ``_nc_group = "G1"``. Damit die Gruppierung angezeigt wird, muss noch das globale Attribut ``_nc_hasgroups = 1`` (NC_LONG) erzeugt werden:: nc_attput(ncid, -1, "_nc_hasgroups", NC_BYTE, 1); nc_attput(ncid, varid, "_nc_group", NC_CHAR, "G1"); Damit die Gruppierung im Brower angezeigt wird muss der Benutzer den entsprechenden Schalter im Browser (Baumstruktur) drücken. Die Funktion Browser_ShowTreeStructure() schaltet die Ansicht im Browser ein bzw. aus. Der Return-Wert 1 bedeutet, dass eingeschaltet wurde. Der Zustand wird in der globalen Variablen ``_g().nc_use_groups`` gespeichert. .. _delay-loading: .. _verzogertes-laden-von-daten-in-netcdf-dateien: Verzögerter Import ------------------ Wenn die Option "Verzögertes Importieren von Datenkanälen" eingeschaltet ist (siehe :ref:`extrasweitere-optionen`, Gruppe: Datenimport und Datenbrowser), werden nicht alle Kanäle sofort aus der Quelldatei in die nc2-Datei kopiert, sondern die Kanäle werden erst bei Bedarf geladen. Enthält eine Messung z. B. 400 Kanäle, der Anwender ist aber nur an 8 Kanälen interessiert, wird der Import fast 50 mal schneller ausgeführt. Globale Attribute :: _nc_dl_driver = "rs_usdata" _nc_dl_driverinfo = "TDM" _nc_dl_source = "d:\\test.tdm" _nc_dl_loadcount = 0 Kanal-Attribute :: _nc_dl_loaded = 0 _nc_dl_loadinfo = "5,2,amp" :: context = _XXX_DL_open(ncid, ssSource) bool = _XXX_DL_load_channel(context, varid, ssInfo) _XXX_DL_close(context) Beispiel:: def _TDM_DL_open(ncid, ssSource) { ctx = [.]; hTDMFile = _DDC_OpenFileEx(ssSource, "", TRUE /* READONLY */); if (type(hTDMFile) != "error") { ctx.hTDMFile = hTDMFile; ctx.ncid = ncid; ctx.ssOurce = ssSource; return ctx; } return 0; } def _TDM_DL_load_channel(ctx, varid, ssInfo) { sv = strtok(ssInfo, ","); iGroup = strtol(sv[1]); iChannel = strtol(sv[2]); oGroups = _DDC_GetChannelGroups(ctx.hTDMFile); oChannels = _DDC_GetChannels(oGroups[iGroup]); nBlocksize = 10000; nStart = 0; nRead = nBlocksize; while (nRead >= nBlocksize) { rvData = _DDC_GetDataValues(oChannels[iChannel], nStart, nBlocksize); if (type(rvData) == "error") { return FALSE; } nRead = len(rvData); r = nc_varput(ctx.ncid, varid, nStart, nRead, rvData); nStart = nStart + nRead; } return TRUE; } def _TDM_DL_close(ctx) { _DDC_CloseFile(ctx.hTDMFile); } .. _example-nc: Beispiel -------- Die folgende Funktion erzeugt eine nc-Datei. Die Daten werden in diesem Beispiel als String-Matrix (smData) übergeben:: def NC_WriteSimpleNCFile(ssFileName, ssNetCDFName, svChanName, svUnits, ... rvDataType, smData, ssCreator) { nCols = nc(smData); nRows = nr(smData); ncid = nc_create(ssNetCDFName); if (ncid == -1) { MessageBox(sprintf(_s("Cannot create file %s - Is file already open?"), .. ssNetCDFName), "ICONSTOP"); return "#IMPORTERROR#"; } dimids = nc_dimdef(ncid, "nRows", nRows); // Globale Attribute: nc_attput(ncid, -1, "Origin", NC_CHAR, _StandardFileName(ssFileName)); nc_attput(ncid, -1, "Source", NC_CHAR, "FEV Software and Testing Solutions GmbH"); nc_attput(ncid, -1, "Creator", NC_CHAR, ssCreator); rvRange = [1, nRows]; nc_attput(ncid, -1, "Range", NC_LONG, rvRange); nc_attput(ncid, -1, "Reference", NC_CHAR, ""); nc_attput(ncid, -1, "Date", NC_CHAR, sum(date())); nc_attput(ncid, -1, "Time", NC_CHAR, sum(time())); nc_attput(ncid, -1, "Title", NC_CHAR, ""); nc_attput(ncid, -1, "Comment1", NC_CHAR, ""); nc_attput(ncid, -1, "Comment2", NC_CHAR, ""); nc_attput(ncid, -1, "Comment3", NC_CHAR, ""); for (i in 1:nCols) { if (_NC_DATETIME == rvDataType[i]) { varid = nc_vardef(ncid, svChanName[i], NC_DOUBLE, dimids); } else { varid = nc_vardef(ncid, svChanName[i], rvDataType[i], dimids); } nc_attput(ncid, varid, "title", NC_CHAR, svChanName[i]); nc_attput(ncid, varid, "units", NC_CHAR, svUnits[i]); nc_attput(ncid, varid, "long_name", NC_CHAR, .. svChanName[i] + " [" + svUnits[i] + "]"); nc_attput(ncid, varid, "scale_factor", NC_DOUBLE, 1.0); nc_attput(ncid, varid, "add_offset", NC_DOUBLE, 0.0); nc_attput(ncid, varid, "Description", NC_CHAR, ""); nc_attput(ncid, varid, "Comment", NC_CHAR, ""); nc_attput(ncid, varid, "ChanType", NC_CHAR, "DateTime"); } nc_setfill(ncid, NC_NOFILL); nc_endef(ncid); for (i in 1:nCols) { if (rvDataType[i] == 100) { rvData = DT_ParseDateTime(smData[;i]); } else { rvData = strtod(smData[;i]); } nc_varput(ncid, i-1, 0, nRows, rvData); } nc_close(ncid); return ssNetCDFName; } .. _copyright-netcdf: Copyright netCDF ---------------- Siehe :ref:`netCDF-copyright` und http://www.unidata.ucar.edu/software/netcdf/ .. seealso:: :ref:`uberblick-netcdf-browser`, :ref:`netcdf-attribute`, :ref:`uberblick-dateien`, :ref:`funktionen-eingeteilt-in-kategorien`, :ref:`programm-grenzen`, :ref:`netCDF-SDK` :sub:`id-1707929`