Structure interne du format de fichier TDMS

Les fichiers TDMS organisent les données dans une hiérarchie d’objets à trois niveaux. Le niveau supérieur est composé d’un seul objet qui contient des informations spécifiques au fichier comme l’auteur ou le titre. Chaque fichier peut contenir un nombre illimité de groupes et chaque groupe, un nombre illimité de voies. Dans l’illustration suivante, l’exemple de fichier events.tdms contient deux groupes, chacun contenant deux voies.

Chaque objet TDMS est identifié de manière unique par un chemin. Chaque chemin est une chaîne comprenant le nom de l’objet et le nom de son propriétaire dans la hiérarchie TDMS, séparés par une barre oblique. Chaque nom est entouré de guillemets. Tout guillemet simple dans un nom d’objet est remplacé par des guillemets doubles. Le tableau suivant illustre des exemples de formatage de chemin pour chaque type d’objet TDMS :

Pour que toutes les applications clientes TDMS fonctionnent correctement, chaque fichier TDMS doit contenir un objet fichier. Un objet fichier doit contenir un objet groupe pour chaque nom de groupe utilisé dans un chemin de voie. De plus, un objet fichier peut contenir un nombre arbitraire d’objets de groupe sans voies.

Chaque objet TDMS peut avoir un nombre de propriétés illimité. Chaque propriété TDMS est constituée d’une combinaison d’un nom (toujours une chaîne), d’un identificateur de type et d’une valeur. Les types numériques, comme les nombres entiers ou à virgule flottante, les horodatages ou les chaînes font partie des types de données typiques pour les propriétés. Les propriétés TDMS ne supportent pas les tableaux. Si un fichier TDMS se trouve dans une zone de recherche de NI DataFinder, toutes les propriétés sont automatiquement disponibles pour la recherche.

Seuls les objets de voies dans les fichiers TDMS peuvent contenir des tableaux de données brutes. Dans les versions TDMS actuelles, seuls les tableaux unidimensionnels sont pris en charge.

Chaque fichier TDMS contient deux types de données : les métadonnées et les données brutes. Les métadonnées sont des données descriptives stockées dans des objets ou des propriétés. Les tableaux de données attachés aux objets de voies sont appelés données brutes. Les fichiers TDMS contiennent des données brutes pour plusieurs voies dans un bloc contigu. Afin de pouvoir extraire des données brutes de ce bloc, les fichiers TDMS utilisent un index de données brutes, qui comprend des informations sur la composition du bloc de données, y compris la voie qui correspond aux données, la quantité de valeurs que le bloc contient pour cette voie, et l’ordre dans lequel les données ont été stockées.

Structure du segment TDMS

Les données sont écrites dans des fichiers TDMS en segments. Chaque fois que des données sont ajoutées à un fichier TDMS, un nouveau segment est créé. Reportez-vous aux sections Métadonnées et Données brutes de cet article pour connaître les exceptions à cette règle. Un segment comporte les trois éléments suivants :

• Attributs : contiennent les informations de base, par exemple le tag qui identifie les fichiers comme TDMS, le numéro de version et les informations de longueur des métadonnées et des données brutes.
• Métadonnées : contiennent les noms et les propriétés de tous les objets dans le segment. Pour les objets qui incluent des données brutes (voies), la partie métadonnées contient également des informations d’index qui sont utilisées pour localiser les données brutes de cet objet dans le segment.
• Données brutes : un bloc contigu de toutes les données brutes associées à l’un des objets inclus dans le segment. La partie de données brutes peut contenir des valeurs de données entrelacées ou une série de blocs de données contigus. La partie données brutes peut en outre contenir des données brutes de DAQmx.

Toutes les chaînes des fichiers TDMS, telles que les chemins d’objet, les noms de propriété, les valeurs de propriété et les valeurs de données brutes, sont codées en Unicode UTF-8. Toutes, à l’exception des valeurs de données brutes, sont précédées d’un entier non signé 32 bits qui contient la longueur de la chaîne en octets, sans inclure la valeur de longueur elle-même. Les chaînes dans les fichiers TDMS peuvent être à terminaison nulle, mais comme les informations de longueur sont stockées, la terminaison null sera ignoré lorsque vous lirez le fichier.

Les horodatages dans les fichiers TDMS sont stockés sous la forme d’une structure de deux composants :

• (i64) secondes : depuis le 01/01/1904 00:00:00.00 UTC (en utilisant le calendrier grégorien et en ignorant les secondes intercalaires)
• (u64) fractions positives : (2^-64) d’une seconde

Les valeurs booléennes sont stockées dans 1 octet chacune, où 1 représente TRUE (VRAI) et 0 représente FALSE (FAUX).

Attributs

Les attributs contiennent des informations utilisées pour valider un segment. Les attributs contiennent également des informations utilisées pour l’accès aléatoire à un fichier TDMS. L’exemple suivant montre l’encombrement binaire de l’attribut dans une partie d’un fichier TDMS :

La partie des attributs dans le tableau précédent contient les informations suivantes :

• Les attributs commencent par un tag de 4 octets qui identifie un segment TDMS ("TDSm").
• Les quatre octets suivants sont utilisés comme masque de bits afin d’indiquer le type de données que contient le segment. Ce masque de bits est appelé ToC (Table of Contents). Toute combinaison des marqueurs suivants peut être encodée dans ToC :

  Option	Description
  #define kTocMetaData         (1L<<1)	Le segment contient des métadonnées
  #define kTocRawData          (1L<<3)	Le segment contient des données brutes
  #define kTocDAQmxRawData     (1L<<7)	Le segment contient des données brutes DAQmx
  #define kTocInterleavedData  (1L<<5)	Les données brutes du segment sont entrelacées (si le marqueur n’est pas défini, les données sont contiguës)
  #define kTocBigEndian        (1L<<6)	Toutes les valeurs numériques du segment, y compris l’attribut, les données brutes et les métadonnées, sont formatées en Big-endian (si le marqueur n’est pas défini, les données sont au format Little-endian). ToC n’est pas affecté par le format endian. Il est toujours au format Little-endian.
  #define kTocNewObjList       (1L<<2)	Le segment contient une nouvelle liste d’objets (par exemple, les voies de ce segment ne sont pas les mêmes voies que le segment précédent)

• Les quatre octets suivants contiennent un numéro de version (entier non signé 32 bits), qui spécifie la révision TDMS la plus ancienne à laquelle un segment est conforme. Au moment d’écrire ces lignes, le numéro de version est 4713. La seule version précédente de TDMS porte le numéro 4712.
  
  Remarque : Le numéro de version 4713 correspond à la version 2.0 du format de fichier TDMS dans LabVIEW. Le numéro de version 4712 correspond à la version 1.0 du format de fichier TDMS dans LabVIEW.
  
• Les huit octets suivants (entier non signé 64 bits) décrivent la longueur du segment restant (longueur totale du segment moins la longueur de l’attribut). Si d’autres segments sont ajoutés au fichier, ce numéro peut être utilisé pour localiser le point de départ du segment suivant. Si une application a rencontré un problème grave lors de l’écriture dans un fichier TDMS (plantage, panne de courant), tous les octets de cet entier peuvent être 0xFF. Cela ne peut arriver qu’au dernier segment d’un fichier.
• Les huit derniers octets (entier non signé 64 bits) décrivent la longueur totale des métadonnées dans le segment. Ces informations sont utilisées pour un accès aléatoire aux données brutes. Si le segment ne contient aucune métadonnée (propriétés, informations d’index, liste d’objets), cette valeur sera 0.

Métadonnées

Les métadonnées TDMS se composent d’une hiérarchie à trois niveaux d’objets de données, notamment un fichier, des groupes et des voies. Chacun de ces types d’objets peut inclure un nombre quelconque de propriétés. La section des métadonnées a la structure binaire suivante sur le disque :

• Nombre de nouveaux objets dans ce segment (entier 32 bits non signé).
• Représentation binaire de chacun de ces objets.

La disposition binaire d’un seul objet TDMS sur disque se compose de composants dans l’ordre suivant. Selon les informations stockées dans un segment particulier, l’objet peut contenir uniquement un sous-ensemble de ces composants.

• Chemin de l’objet (chaîne)
• Indice des données brutes
  • Si cet objet n’a pas de données brutes qui lui sont affectées dans ce segment, un entier 32 bits non signé (0xFFFFFFFF) sera stocké à la place des informations d’indice.
  • Si cet objet contient des données brutes DAQmx dans ce segment, les quatre premiers octets de l’indice de données brutes sont « 69 12 00 00 » (ce qui signifie que les données brutes contiennent une échelle de changement de format DAQmx) ou « 69 13 00 00 » (ce qui signifie que les données brutes contiennent une échelle DAQmx Digital Line). Après ces quatre premiers octets, vous trouverez des informations sur l’indice de données brutes DAQmx. Reportez-vous à la puce ci-dessous pour plus d’informations sur l’indice des données brutes DAQmx.
  • Si l’indice de données brutes de cet objet dans ce segment correspond exactement à l’indice du même objet dans le segment précédent, un entier 32 bits non signé (0x0000000) sera stocké à la place des informations d’indice.
  • Si l’objet contient des données brutes qui ne correspondent pas aux informations d’indice affectées à cet objet dans le segment précédent, un nouvel indice pour ces données brutes sera stocké :
    • Longueur de l’indice de données brutes (entier 32 bits non signé)
    • Type de données (énum tdsDataType, stockée sous forme d’entier 32 bits)
    • Dimension du tableau (entier 32 bits non signé) (au format de fichier TDMS version 2.0, 1 est la seule valeur valide)
    • Nombre de valeurs (entier 64 bits non signé)
    • Taille totale en octets (entier 64 bits non signé) (uniquement stocké pour les types de données de longueur variable, par exemple des chaînes)
• Si l’indice de données brutes est l’indice de données brutes DAQmx, l’indice contient les informations suivantes :
  • Type de données (entier 32 bits non signé), où « FF FF FF FF » indique que les données brutes sont des données brutes DAQmx)
  • Dimension du tableau (entier 32 bits non signé) (au format de fichier TDMS version 2.0, 1 est la seule valeur valide)
  • Nombre de valeurs (entier 64 bits non signé), également appelé « taille des segments »
  • Le vecteur des échelles à changement de format
    • Taille du vecteur (entier 32 bits non signé)
      Les informations suivantes s’appliquent aux informations de la première échelle à changement de format.
    • Type de données DAQmx (entier 32 bits non signé)
    • Indice de buffer brut (entier 32 bits non signé)
    • Offset d’octets bruts dans la longueur (entier 32 bits non signé)
    • Exemple de format bitmap (entier 32 bits non signé)
    • ID de l’échelle (entier 32 bits non signé)
      (Si la taille du vecteur est supérieure à 1, l’objet contient plusieurs échelles de changement de format et les informations des éléments de puce précédents peuvent être répétées.)
  • Le vecteur de la largeur des données brutes
    • Taille du vecteur (entier 32 bits non signé)
    • Éléments du vecteur (chacun est un entier 32 bits non signé)
• Nombre de propriétés (entier 32 bits non signé)
• Propriétés. Pour chaque propriété, les informations suivantes sont stockées :
  • Nom (chaîne)
  • Type de données (tdsDataType)
  • Valeur (numériques stockés en binaire, chaînes stockées comme expliqué ci-dessus).

Le tableau suivant montre un exemple de méta-informations pour un groupe et une voie. Le groupe contient deux propriétés, une chaîne et un entier. La voie contient un indice de données brutes et aucune propriété.

Le tableau suivant est un exemple de l’indice de données brutes DAQmx.

Dans le tableau précédent, la voie "/'Measured Throughput Data (Volts)'/'PXI1Slot03-ai0" contient deux échelles. L’une est une échelle de changement de format. Ses informations sont stockées dans l’indice des données brutes DAQmx. L’autre échelle est une échelle linéaire, où les informations sont stockées en tant que propriétés TDMS. L’échelle de changement de format est identifiable lorsque la pente de l’échelle linéaire est 1.693433E-9, l’ordonnée à l’origine est 0 et l’identifiant de la source d’entrée est 0.

Les méta-informations qui correspondent aux méta-informations des segments précédents peuvent être omises dans les segments suivants. Ceci est facultatif, mais le fait d’omettre des méta-informations redondantes augmente considérablement la vitesse de lecture du fichier. Si vous choisissez d’écrire des informations redondantes, vous pouvez ensuite les supprimer en utilisant le nœud la fonction de défragmentation TDMS dans LabVIEW, LabWindows/CVI, MeasurementStudio, etc.

• L’écriture d’un nouvel objet dans le segment suivant impliquera que le segment contient tous les objets du segment précédent, plus les nouveaux objets décrits ici. Si le nouveau segment ne contient aucune voie du segment précédent, ou si l’ordre des voies dans le segment change, le nouveau segment doit contenir une nouvelle liste de tous les objets. Reportez-vous à la section Optimisation de cet article pour plus d’informations.
• L’écriture d’une nouvelle propriété dans un objet qui existe déjà dans le segment précédent ajoutera cette propriété à l’objet.
• L’écriture d’une propriété qui existe déjà sur un objet remplacera la valeur précédente de cette propriété.
  
  Remarque : Dans le format de fichier TDMS version 2.0, la spécification d’une valeur pour la propriété du nom d’un objet existant renommera cet objet.

L’exemple suivant montre l’empreinte binaire pour la section de métadonnées d’un segment suivant directement le segment décrit ci-dessus. La seule méta-information écrite dans le nouveau segment est la nouvelle valeur de propriété.

Données brutes

Le segment contient enfin les données brutes associées à chaque voie. Les tableaux de données pour toutes les voies sont concaténés dans l’ordre exact dans lequel les voies apparaissent dans la partie méta-informations du segment. Les données numériques doivent être formatées en fonction du marqueur Little-endian/Big-endian dans l’attribut. Veuillez noter que les voies ne peuvent pas changer leur format endian ou type de données une fois qu’ils ont été écrits pour la première fois.

Les voies de type chaîne sont prétraitées pour un accès aléatoire rapide. Toutes les chaînes sont concaténées à un morceau de mémoire contigu. L’offset du premier caractère de chaque chaîne dans cette pièce de mémoire contiguë est stocké dans un tableau d’entiers 32 bits non signés. Ce tableau de valeurs offset est stocké en premier, suivi des valeurs de chaîne concaténées. Cette structure permet aux applications clientes d’accéder à n’importe quelle valeur de chaîne de n’importe où dans le fichier en repositionnant le pointeur de fichier au maximum trois fois et sans lire les données dont le client n’a pas besoin.

Si les méta-informations entre les segments ne changent pas, les parties d’attributs et de méta-informations peuvent être complètement omises et les données brutes peuvent simplement être ajoutées à la fin du fichier. Chaque tronçon de données brutes suivant a la même structure binaire, et le nombre de tronçons peut être calculé à partir des informations d’attributs et de métadonnées par les étapes suivantes :

1. Calculez la taille des données brutes d’une voie. Chaque voie a un type de données, une dimension de tableau et un nombre de valeurs dans les méta-informations. Reportez-vous à la section Métadonnées de cet article pour plus de détails. Chaque type de données est associé à une taille de type. Vous pouvez obtenir la taille des données brutes de la voie en faisant : taille du type de données × dimension du tableau × nombre de valeurs. Si la taille totale en octets est valide, la taille des données brutes de la voie correspond à cette valeur.
2. Calculez la taille des données brutes d’un tronçon en accumulant la taille des données brutes de toutes les voies.
3. Calculez la taille des données brutes de tous les tronçons, en faisant : Offset du segment suivant - offset des données brutes. Si la valeur Offset du segment suivant est -1, la taille des données brutes du total des tronçons est égale à la taille du fichier moins la position de début absolue des données brutes.
4. Calculez le nombre de tronçons en faisant : Taille des données brutes du total des tronçons ÷ Taille des données brutes d’un tronçon.

Les données brutes peuvent être organisées en deux types de structure : intercalé et non intercalé. Le masque de bits ToC dans l’attribut du segment déclare si les données du segment sont intercalées ou non. Par exemple : le stockage de valeurs entières 32 bits sur les voies 1 (1,2,3) et 2 (4,5,6) entraîne les dispositions suivantes :

Valeurs des types de données

Le type d’énum suivant décrit le type de données d’une propriété ou d’une voie dans un fichier TDMS. Pour les propriétés, la valeur du type de données sera stockée entre le nom et la valeur binaire. Pour les voies, le type de données fera partie de l’indice de données brutes.

typedef enum {
    tdsTypeVoid,
    tdsTypeI8,    
    tdsTypeI16,    
    tdsTypeI32,    
    tdsTypeI64,
    tdsTypeU8,    
    tdsTypeU16,    
    tdsTypeU32,    
    tdsTypeU64,
    tdsTypeSingleFloat,    
    tdsTypeDoubleFloat,    
    tdsTypeExtendedFloat,    
    tdsTypeSingleFloatWithUnit=0x19,    
    tdsTypeDoubleFloatWithUnit,    
    tdsTypeExtendedFloatWithUnit,
    tdsTypeString=0x20,   
    tdsTypeBoolean=0x21,   
    tdsTypeTimeStamp=0x44,
    tdsTypeFixedPoint=0x4F,
    tdsTypeComplexSingleFloat=0x08000c,
    tdsTypeComplexDoubleFloat=0x10000d,
    tdsTypeDAQmxRawData=0xFFFFFFFF
} tdsDataType;

Remarques :

• Reportez-vous à l’article LabVIEW Timestamp pour plus d’informations sur l’utilisation de tdsTypeTimeStamp dans LabVIEW.
• Les types à virgule flottante LabVIEW avec unité se traduisent en une voie à virgule flottante avec une propriété nommée unit_string qui contient l’unité sous forme de chaîne.

Reportez-vous à l’article API basée sur VI pour l’écriture de fichiers TDMS pour plus d’informations sur les capacités d’écriture TDMS.

Les waveforms LabVIEW sont représentées dans les fichiers TDMS sous forme de voies numériques, où les attributs de waveforms sont ajoutés à la voie en tant que propriétés.

• wf_start_time : cette propriété représente le temps auquel la waveform a été acquise ou générée. Cette propriété peut être 0 si les informations sont en temps relatif ou si la waveform n’appartient pas au domaine temporel, mais par exemple au domaine de fréquence.
• wf_start_offset : cette propriété est utilisée pour le type de données dynamique LabVIEW Express. Les données fréquence-domaine et les résultats d’histogrammes utilisent cette valeur comme première valeur sur l’axe des x.
• wf_increment : cette propriété représente l’incrément entre deux échantillons consécutifs sur l’axe des x.
• wf_samples : cette propriété représente le nombre d’échantillons dans la waveform.

L’application de la définition de format décrite dans les sections précédentes crée des fichiers TDMS parfaitement valides. Cependant, TDMS permet une variété d’optimisations couramment utilisées par les logiciels NI tels que LabVIEW, LabWindows/CVI, MeasurementStudio, etc. Les applications qui tentent de lire des données écrites par le logiciel NI doivent prendre en charge les mécanismes d’optimisation décrits dans ce paragraphe.

Exemple de méta-informations incrémentielles

Les méta-informations telles que les chemins d’objet, les propriétés et les indices bruts sont ajoutées à un segment uniquement si elles changent. Les méta-informations incrémentielles sont expliquées dans l’exemple suivant.

Dans la première itération d’écriture, les voies 1 et 2 sont écrites. Chaque voie a trois valeurs entières de 32 bits (1,2,3 et 4,5,6) et plusieurs propriétés descriptives. La partie méta-informations du premier segment contient des chemins, des propriétés et des indices de données brutes pour les voies 1 et 2. Les marqueurs kTocMetaData, kTocNewObjList et kTocRawData du champ de bits ToC sont définis. La première itération d’écriture crée un segment de données. Le tableau suivant décrit l’empreinte binaire du premier segment.

Dans la deuxième itération d’écriture, aucune des propriétés n’a changé, les voies 1 et 2 ont toujours trois valeurs chacune et aucune voie supplémentaire n’est écrite. Par conséquent, cette itération n’écrira aucune métadonnée. Les métadonnées du segment précédent sont toujours supposées valides. Cette itération ne créera pas de nouveau segment; à la place, cette itération ajoute uniquement les données brutes au segment existant, puis met à jour l’offset du segment suivant dans la section Attributs. Le tableau suivant décrit l’empreinte binaire du segment mis à jour.

Dans le tableau précédent, les deux dernières lignes contiennent des données ajoutées au premier segment lors de la deuxième itération d’écriture.

La troisième itération d’écriture ajoute trois autres valeurs à chaque voie. Dans la voie 1, le statut de la propriété a été défini sur valide dans le premier segment, mais doit maintenant être défini sur erreur. Cette itération créera un nouveau segment et la section de métadonnées de ce segment contient désormais le chemin d’objet pour la voie, le nom, le type et la valeur de cette propriété. Lors de futures lectures de fichiers, la valeur erreur remplacera la valeur valide précédemment écrite. Cependant, la valeur valide précédente reste dans le fichier, sauf si elle est défragmentée. Le tableau suivant décrit l’empreinte binaire du deuxième segment.

La quatrième itération d’écriture ajoute une voie supplémentaire, la tension, qui contient cinq valeurs (7,8,9,10,11). Cette itération créera un nouveau segment, le troisième segment, dans le fichier TDMS. Étant donné que toutes les autres métadonnées du segment précédent sont toujours valides, la section des métadonnées du quatrième segment inclut le chemin d’objet, les propriétés et les informations d’indice pour la tension de voie uniquement. La section des données brutes contient trois valeurs pour la voie 1, trois valeurs pour la voie 2 et cinq valeurs pour la tension de la voie. Le tableau suivant décrit l’empreinte binaire du troisième segment.

Dans le quatrième segment, la voie 2 a maintenant 27 valeurs. Toutes les autres voies restent inchangées. La section des métadonnées contient maintenant le chemin d’objet pour la voie 2, le nouvel indice de données brutes pour la voie 2 et aucune propriété pour la voie 2. Le tableau suivant décrit l’empreinte binaire du quatrième segment.

Dans le cinquième segment, l’application arrête d’écrire sur la voie 2. L’application continue uniquement d’écrire sur la voie 1 et la tension de la voie. Cela constitue un changement dans l’ordre des voies, ce qui vous oblige à écrire une nouvelle liste de chemins de voies. Vous devez définir le bit ToC kTocNewObjList. La section des métadonnées du nouveau segment doit contenir une liste complète de tous les chemins d’objet, mais pas de propriétés ni d’indice de données brutes, à moins qu’ils ne changent également. Le tableau suivant décrit l’empreinte binaire du cinquième segment.

Fichiers d’indices

Toutes les données écrites dans un fichier TDMS sont stockées dans un fichier avec l’extension *.tdms. Les fichiers TDMS peuvent être accompagnés d’un fichier d’indice facultatif *.tdms_index. Le fichier d’indice est utilisé pour accélérer la lecture du fichier *.tdms. Si une application NI ouvre un fichier TDMS sans fichier d’indice, l’application crée automatiquement le fichier d’indice. Si une application NI, telle que LabVIEW ou LabWindows/CVI, écrit un fichier TDMS, l’application crée le fichier d’indice et le fichier principal en même temps.

Le fichier d’indice est une copie exacte du fichier *.tdms, sauf qu’il ne contient aucune donnée brute et que chaque segment commence par un tag TDSh au lieu d’un tag TDSm. Le fichier d’indice contient toutes les informations pour localiser avec précision n’importe quelle valeur de n’importe quelle voie dans le fichier *.tdms.

En bref, le format de fichier TDMS est conçu pour écrire et lire des données mesurées à très grande vitesse, tout en conservant un système hiérarchique d’informations descriptives. Alors que la structure binaire en elle-même est plutôt simple, les optimisations activées en écrivant les métadonnées de manière incrémentielle peuvent conduire à des configurations de fichiers très sophistiquées.

• VI-based API for Writing TDMS Files
• Introduction to the LabWindows/CVI TDM Streaming Library