Estructura interna del formato de archivo TDMS

Los archivos TDMS organizan los datos en una jerarquía de objetos de tres niveles. El nivel superior se compone de un único objeto que contiene información específica del archivo, como, por ejemplo, el autor o título. Cada archivo puede contener un número ilimitado de grupos y cada grupo puede contener un número ilimitado de canales. En la siguiente ilustración, el archivo de ejemplo events.tdms contiene dos grupos, cada uno de los cuales contiene dos canales.

Cada objeto TDMS se identifica de forma exclusiva por medio de una ruta. Cada ruta es una cadena que incluye el nombre del objeto y el nombre de su propietario en la jerarquía TDMS, separados por una barra diagonal. Cada nombre va entre comillas. Todas las comillas simples que van dentro de un nombre de objeto se reemplaza con comillas dobles. La tabla siguiente ilustra ejemplos de formato de ruta para cada tipo de objeto TDMS:

Para que todas las aplicaciones cliente TDMS funcionen correctamente, cada archivo TDMS debe contener un objeto de archivo. Un objeto de archivo debe contener un objeto de grupo para cada nombre de grupo utilizado en una ruta de canal. Además, un objeto de archivo puede contener un número arbitrario de objetos de grupo sin canales.

Cada objeto TDMS puede tener un número ilimitado de propiedades. Cada propiedad TDMS consta de una combinación de un nombre (siempre una cadena), un identificador de tipo y un valor. Los tipos de datos típicos para las propiedades incluyen tipos numéricos como enteros o números de punto flotante, registros de tiempo o cadenas. Las propiedades TDMS no admiten matrices. Si un archivo TDMS se encuentra dentro de un área de búsqueda del DataFinder de NI, todas las propiedades están automáticamente disponibles para la búsqueda.

Solo los objetos de canal en archivos TDMS pueden contener matrices de datos sin procesar. En las versiones actuales de TDMS, solo se admiten matrices unidimensionales.

Cada archivo TDMS contiene dos tipos de datos: metadatos y datos sin procesar. Los metadatos son datos descriptivos almacenados en objetos o propiedades. Las matrices de datos adjuntas a los objetos del canal se denominan datos sin procesar. Los archivos TDMS contienen datos sin procesar para múltiples canales en un bloque contiguo. Para poder extraer datos sin procesar de ese bloque, los archivos TDMS usan un índice de datos sin procesar, que incluye información sobre la composición del bloque de datos, incluido el canal que corresponde a los datos, la cantidad de valores que contiene el bloque para ese canal y el orden en el que se almacenaron los datos.

Diseño de segmento TDMS

Los datos se escriben en archivos TDMS en segmentos. Cada vez que se agregan datos a un archivo TDMS, se crea un nuevo segmento. Consulte las secciones Metadatos y Datos sin procesar de este artículo para ver las excepciones a esta regla. Un segmento consta de las siguientes tres partes:

• Introducción: contiene información básica, como una etiqueta que identifica los archivos como TDMS, un número de versión y la información sobre la extensión de los metadatos y los datos sin procesar.
• Metadatos: contiene nombres y propiedades de todos los objetos del segmento. Para los objetos que incluyen datos sin procesar (canales), la parte de metadatos también contiene información de índice que se utiliza para ubicar los datos sin procesar para este objeto en el segmento.
• Datos sin procesar: un bloque contiguo de todos los datos sin procesar asociados con cualquiera de los objetos incluidos en el segmento. La parte de datos sin procesar puede contener valores de datos intercalados o una serie de fragmentos de datos contiguos. La parte de datos sin procesar también puede contener datos sin procesar de DAQmx.

Todas las cadenas en archivos TDMS, como rutas de objetos, nombres de propiedad, valores de propiedad y valores de datos sin procesar, están codificadas en UTF-8 Unicode. Todos ellos, excepto los valores de datos sin procesar, van precedidos por un entero sin signo de 32 bits que contiene la extensión de la cadena en bytes, sin incluir el valor de la longitud en sí. Las cadenas en archivos TDMS pueden tener terminación nula, pero como se almacena la información de extensión, el terminador nulo se ignorará cuando se lea el archivo.

Los registros de tiempo en los archivos TDMS se almacenan como una estructura de dos componentes:

• (i64) segundos: desde la fecha 01/01/1904 00:00:00.00 UTC (en calendario gregoriano e ignorando los segundos intercalares).
• (u64) fracciones positivas: (2^-64) de segundo.

Los valores booleanos se almacenan como 1 byte cada uno, donde 1 representa VERDADERO y 0 representa FALSO.

Introducción

La introducción contiene información utilizada para validar un segmento. La introducción también contiene información utilizada para el acceso aleatorio a un archivo TDMS. El siguiente ejemplo muestra la huella binaria de la parte de introducción de un archivo TDMS:

La parte de introducción de la tabla anterior contiene la siguiente información:

• La introducción comienza con una etiqueta de 4 bytes que identifica un segmento TDMS (“TDSm”).
• Los siguientes cuatro bytes se usan como una máscara de bits para indicar qué tipo de datos contiene el segmento. Esta máscara de bits se denomina ToC (Tabla de contenido). Cualquier combinación de los siguientes indicadores se puede codificar en ToC:

  Indicador	Descripción
  #define kTocMetaData         (1L<<1)	El segmento contiene metadatos.
  #define kTocRawData          (1L<<3)	El segmento contiene datos sin procesar.
  #define kTocDAQmxRawData     (1L<<7)	El segmento contiene datos sin procesar DAQmx.
  #define kTocInterleavedData  (1L<<5)	Los datos sin procesar en el segmento están intercalados (si el indicador no está configurado, los datos son contiguos).
  #define kTocBigEndian        (1L<<6)	Todos los valores numéricos en el segmento, incluidos la introducción, los datos sin procesar y los metadatos, tienen formato big endian (si no se establece el indicador, los datos son little endian). La ToC no se ve afectada por orden de bytes; siempre es little endian.
  #define kTocNewObjList       (1L<<2)	El segmento contiene una lista de objetos nueva (por ejemplo, los canales en este segmento no son los mismos canales que contiene el segmento anterior).

• Los cuatro bytes siguientes contienen un número de versión (entero sin signo de 32 bits), que especifica la revisión de TDMS más antigua que cumple un segmento. Al momento de redactar este documento, el número de versión es 4713. La única versión anterior de TDMS tiene el número 4712.
  
  Nota: El número de versión 4713 corresponde al formato de archivo TDMS versión 2.0 en LabVIEW. El número de versión 4712 corresponde al formato de archivo TDMS versión 1.0 en LabVIEW.
  
• Los siguientes ocho bytes (entero sin signo de 64 bits) describen la longitud del segmento restante (longitud total del segmento menos la longitud de la introducción). Si se agregan más segmentos al archivo, este número se puede usar para ubicar el punto de partida del siguiente segmento. Si una aplicación ha encontrado un problema grave al escribir en un archivo TDMS (bloqueo, corte de energía), todos los bytes de este entero pueden ser 0xFF. Esto solo puede sucederle al último segmento de un archivo.
• Los últimos ocho bytes (entero sin signo de 64 bits) describen la longitud total de la metainformación en el segmento. Esta información se utiliza para el acceso aleatorio a los datos sin procesar. Si el segmento no contiene metadatos (propiedades, información de índice, lista de objetos), este valor será 0.

Metadatos

Los metadatos TDMS consisten en una jerarquía de tres niveles de objetos de datos que incluye un archivo, grupos y canales. Cada uno de estos tipos de objeto puede incluir una cantidad ilimitada de propiedades. La sección de metadatos tiene el siguiente diseño binario en el disco:

• Número de nuevos objetos en este segmento (entero sin signo de 32 bits).
• Representación binaria de cada uno de estos objetos.

El diseño binario de un único objeto TDMS en disco consta de los componentes en el siguiente orden. En función de la información almacenada en un segmento particular, el objeto puede contener solo un subconjunto de estos componentes.

• Ruta del objeto (cadena).
• Índice de datos sin procesar.
  • Si este objeto no tiene datos sin procesar asignados en este segmento, se almacenará un entero sin signo de 32 bits (0xFFFFFFFF) en lugar de la información del índice.
  • Si este objeto contiene datos sin procesar DAQmx en este segmento, entonces los primeros cuatro bytes del índice de datos sin procesar es “69 12 00 00” (que significa que los datos sin procesar contienen el escalador de cambio de formato DAQmx) o “69 13 00 00” (que significa que los datos sin procesar contienen el escalador de línea digital DAQmx). Después de estos primeros cuatro bytes hay información sobre el índice de datos sin procesar DAQmx. Consulte el elemento de viñeta siguiente para obtener más información sobre el índice de datos sin procesar DAQmx.
  • Si el índice de datos sin procesar de este objeto en este segmento coincide exactamente con el índice que tenía el mismo objeto en el segmento anterior, se almacenará un entero sin signo de 32 bits (0x0000000) en lugar de la información del índice.
  • Si el objeto contiene datos sin procesar que no coinciden con la información de índice asignada a este objeto en el segmento anterior, se almacenará un nuevo índice para esos datos sin procesar:
    • Longitud del índice de datos sin procesar (entero sin signo de 32 bits).
    • Tipo de datos (enum tdsDataType, almacenado como un entero de 32 bits).
    • Dimensión de matriz (entero sin signo de 32 bits) (en el formato de archivo TDMS versión 2.0, 1 es el único valor válido).
    • Número de valores (entero sin signo de 64 bits).
    • Tamaño total en bytes (entero sin signo de 64 bits) (solo almacenado para tipos de datos de longitud variable, por ejemplo, cadenas).
• Si el índice de datos sin procesar es el índice de datos sin procesar DAQmx, el índice contiene la siguiente información:
  • Tipo de datos (entero sin signo de 32 bits), donde “FF FF FF FF” indica que los datos sin procesar son datos sin procesar DAQmx).
  • Dimensión de matriz (entero sin signo de 32 bits) (en el formato de archivo TDMS versión 2.0, 1 es el único valor válido).
  • Número de valores (entero sin signo de 64 bits), también conocido como “tamaño de fragmento”.
  • El vector de escaladores de cambio de formato.
    • Tamaño del vector (entero sin signo de 32 bits).
      Lo siguiente se aplica a la información del primer escalador de Cambio de formato.
    • Tipo de datos DAQmx (entero sin signo de 32 bits).
    • Índice de búfer sin procesar (entero sin signo de 32 bits).
    • Desfase de bytes sin procesar dentro del intervalo (entero de 32 bits sin signo).
    • Mapa de bits de formato de muestra (entero sin signo de 32 bits).
    • ID de escala (entero sin signo de 32 bits).
      (Si el tamaño del vector es mayor que 1, el objeto contiene varios escaladores de cambio de formato y la información de los elementos anteriores de la viñeta puede repetirse).
  • El vector del ancho de datos sin procesar.
    • Tamaño del vector (entero sin signo de 32 bits).
    • Elementos en el vector (cada uno es un entero sin signo de 32 bits).
• Número de propiedades (entero sin signo de 32 bits).
• Propiedades. En cada propiedad, se almacena la siguiente información:
  • Nombre (cadena).
  • Tipo de datos (tdsDataType).
  • Valor (binarios numéricos almacenados, cadenas almacenadas tal como se explicó anteriormente).

La tabla siguiente muestra un ejemplo de metainformación para un grupo y un canal. El grupo contiene dos propiedades, una cadena y un número entero. El canal contiene un índice de datos sin procesar y no tiene propiedades.

La tabla siguiente es un ejemplo del índice de datos sin procesar DAQmx.

En la tabla anterior, el canal "/'Measured Throughput Data (Volts)'/'PXI1Slot03-ai0" contiene dos escaladores. Un escalador es Cambio de formato [Format Changing], donde la información del escalador de cambio de formato se almacena en el índice de datos sin procesar DAQmx. El otro escalador es un escalador lineal [Linear scaler], donde la información se almacena como propiedades TDMS. El escalador de cambio de formato se puede identificar donde la pendiente del escalador lineal es 1,693433E-9, la intercepción es 0 y el ID de la fuente de entrada es 0.

La metainformación que coincide con la metainformación en los segmentos anteriores se puede omitir en los siguientes segmentos. Esto es opcional, pero la omisión de metainformación redundante acelera significativamente la lectura del archivo. Si elige escribir información redundante, después puede eliminarla usando la función Desfragmentar TDMS [TDMS Defragment function] en LabVIEW, LabWindows/CVI, MeasurementStudio, etc.

• Escribir un nuevo objeto en el siguiente segmento implicará que el segmento contiene todos los objetos del segmento anterior, más los objetos nuevos descritos aquí. Si el segmento nuevo no contiene ningún canal del segmento anterior, o si el orden de los canales en el segmento cambia, el nuevo segmento debe contener una lista nueva de todos los objetos. Consulte la sección Optimización de este artículo para obtener más información.
• Al rscribir una nueva propiedad en un objeto que ya existe en el segmento anterior, esta propiedad se añadirá al objeto.
• Escribir una propiedad que ya existe en un objeto sobrescribirá el valor anterior de esa propiedad.
  
  Nota: En el formato de archivo TDMS versión 2.0, al especificar un valor para la propiedad de nombre de un objeto existente cambiará el nombre de ese objeto.

El ejemplo siguiente muestra la huella binaria para la sección de metadatos de un segmento que sigue directamente al segmento descrito anteriormente. La única metainformación escrita en el nuevo segmento es el nuevo valor de la propiedad.

Datos sin procesar

Por último, el segmento contiene los datos sin procesar asociados con cada canal. Las matrices de datos para todos los canales se concatenan en el orden exacto en el que aparecen los canales en la parte de metainformación del segmento. Los datos numéricos deben formatearse de acuerdo con el indicador little-endian/big-endian de la introducción. Tenga en cuenta que los canales no pueden cambiar su tipo de datos o formato endian una vez que se ha escrito en ellos por primera vez.

Los canales de tipo cadena se preprocesan para un acceso aleatorio rápido. Todas las cadenas se concatenan en una pieza de memoria contigua. El desfase del primer carácter de cada cadena de esta pieza de memoria contigua se almacena en una matriz de enteros sin signo de 32 bits. Esta matriz de valores de desfase se almacena primero, seguida de los valores de cadena concatenados. Este diseño permite que las aplicaciones de cliente accedan a cualquier valor de cadena desde cualquier parte del archivo al reposicionar el puntero del archivo un máximo de tres veces y sin leer ningún dato que el cliente no necesite.

Si la metainformación entre segmentos no cambia, las partes de introducción y metainformación se pueden omitir por completo y los datos sin procesar se pueden agregar al final del archivo. Cada fragmento de datos sin procesar siguiente tiene el mismo diseño binario, y el número de fragmentos se puede calcular a partir de la introducción y de la metainformación mediante los siguientes pasos:

1. Calcular el tamaño de los datos sin procesar de un canal. Cada canal tiene un Tipo de datos, Dimensión de matriz y Número de valores en la metainformación. Consulte la sección Metadatos de este artículo para obtener más información. Cada Tipo de datos está asociado con un tamaño de tipo. Puede obtener el tamaño de datos sin procesar del canal por: tipo de tamaño de Tipo de datos × Dimensión de matriz × Número de valores. Si el Tamaño total en bytes es válido, el tamaño de datos sin procesar del canal es este valor.
2. Calcular el tamaño de datos sin procesar de un fragmento acumulando el tamaño de datos sin procesar de todos los canales.
3. Calcular el tamaño de los datos sin procesar de fragmentos totales por: Desfase del segmento siguiente - Desfase de datos sin procesar. Si el valor de Desfase del segmento siguiente es -1, el tamaño de los datos sin procesar de los fragmentos totales es igual al tamaño del archivo menos la posición de inicio absoluta de los datos sin procesar.
4. Calcular el número de fragmentos por: Tamaño de datos sin procesar de los fragmentos totales ÷ Tamaño de datos sin procesar de un fragmento.

Los datos sin procesar se pueden organizar en dos tipos de diseño: intercalados y no intercalados. La máscara de bits de ToC en la introducción del segmento declara si los datos del segmento están intercalados o no. Por ejemplo: almacenar valores enteros de 32 bits en el canal 1 (1,2,3) y el canal 2 (4,5,6) da como resultado los siguientes diseños:

Valores de tipo de datos

El siguiente tipo de enumeración describe el tipo de datos de una propiedad o canal en un archivo TDMS. Para las propiedades, el valor del tipo de datos se almacenará entre el nombre y el valor binario. Para los canales, el tipo de datos formará parte del índice de datos sin procesar.

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=0xFFFFFFFFhttps://forums.ni.com/t5/Example-Code/VI-Based-API-for-Writing-TDMS-Files/ta-p/4101006
} tdsDataType;

Notas:

• Consulte el artículo de Registro de tiempo de LabVIEW para obtener más información sobre el uso de tdsTypeTimeStamp en LabVIEW.6471
• Los tipos de punto flotante de LabVIEW con unidad se traducen en un canal de punto flotante con una propiedad llamada unit_string que contiene la unidad como una cadena.

Consulte el artículo API basada en VI para escribir archivos TDMS para obtener más información sobre las capacidades de escritura de TDMS.

Las formas de onda de LabVIEW se representan en archivos TDMS como canales numéricos, donde los atributos de forma de onda se agregan al canal como propiedades.

• wf_start_time: propiedad que representa el momento en que se ha adquirido o generado la forma de onda. Esta propiedad puede ser cero si la información de tiempo es relativa o si la forma de onda no es del dominio del tiempo, sino, por ejemplo, del dominio de la frecuencia.
• wf_start_offset: propiedad que se usa para el tipo de datos dinámicos de LabVIEW Express. Los datos del dominio de la frecuencia y los resultados del histograma utilizarán este valor como el primer valor en el eje x.
• wf_increment: propiedad que representa el incremento entre dos muestras consecutivas en el eje x.
• wf_samples: propiedad que representa el número de muestras en la forma de onda.

La aplicación de la definición de formato, como se describe en las secciones anteriores, crea archivos TDMS perfectamente válidos. Sin embargo, TDMS permite una variedad de optimizaciones que suele utilizarlas el software de NI, como LabVIEW, LabWindows/CVI, MeasurementStudio, etc. Las aplicaciones que intentan leer datos escritos por el software de NI deben admitir los mecanismos de optimización descritos en este párrafo.

Ejemplo de metainformación incremental

La metainformación, como las rutas de objetos, las propiedades y los índices sin procesar, se agrega a un segmento solo si este cambia. La metainformación incremental se explica en el siguiente ejemplo.

En la primera iteración de escritura, se escriben el canal 1 y el canal 2. Cada canal tiene tres valores enteros de 32 bits (1,2,3 y 4,5,6) y varias propiedades descriptivas. La parte de metainformación del primer segmento contiene rutas, propiedades e índices de datos sin procesar para el canal 1 y el canal 2. Se establecen los indicadores kTocMetaData, kTocNewObjList y kTocRawData del campo de bits de ToC. La primera iteración de escritura crea un segmento de datos. La tabla siguiente describe la huella binaria del primer segmento.

En la segunda iteración de escritura, ninguna de las propiedades ha cambiado, el canal 1 y el canal 2 todavía tienen tres valores cada uno, y no se escriben canales adicionales. Por lo tanto, esta iteración no escribirá ningún metadato. Los metadatos del segmento anterior aún se consideran válidos. Esta iteración no creará un segmento nuevo; en su lugar, esta iteración solo agrega los datos sin procesar al segmento existente y, a continuación, actualiza el Desfase del segmento siguiente [Next Segment Offset] en la sección Introducción [Lead]. La tabla siguiente describe la huella binaria del segmento actualizado.

En la tabla anterior, las dos últimas filas contienen datos agregados al primer segmento durante la segunda iteración de escritura.

La tercera iteración de escritura agrega otros tres valores a cada canal. En el canal 1, el estado de la propiedad se ha establecido como válido en el primer segmento, pero ahora debe establecerse en error. Esta iteración creará un nuevo segmento, y la sección de metadatos de este segmento ahora contiene la ruta del objeto para el canal, el nombre, el tipo y el valor de esta propiedad. En futuras lecturas de archivos, el valor de error anulará el valor válido previamente escrito. Sin embargo, el valor válido anterior permanece en el archivo, a menos que esté desfragmentado. La tabla siguiente describe la huella binaria del segundo segmento.

La cuarta iteración de escritura agrega un canal adicional, voltaje, que contiene cinco valores (7,8,9,10,11). Esta iteración creará un nuevo segmento, el tercero, en el archivo TDMS. Como todos los demás metadatos del segmento anterior siguen siendo válidos, la sección de metadatos del cuarto segmento incluye la ruta del objeto, las propiedades y la información del índice solo para el voltaje del canal. La sección de datos sin procesar contiene tres valores para el canal 1, tres valores para el canal 2 y cinco valores para el voltaje del canal. La tabla siguiente describe la huella binaria del tercer segmento.

En el cuarto segmento, el canal 2 ahora tiene 27 valores. Todos los demás canales permanecen sin cambios. La sección de metadatos ahora contiene la ruta del objeto para el canal 2, el nuevo índice de datos sin procesar para el canal 2 y ninguna propiedad para el canal 2. La tabla siguiente describe la huella binaria del cuarto segmento.

En el quinto segmento, la aplicación deja de escribir en el canal 2. La aplicación continúa escribiendo en el canal 1 y el voltaje del canal. Esto constituye un cambio en el orden de los canales, que requiere que escriba una nueva lista de las rutas de los canales. Debe establecer el bit de ToC kTocNewObjList. La sección de metadatos del nuevo segmento debe contener una lista completa de todas las rutas de objetos, pero no propiedades ni índices de datos sin procesar, a menos que también cambien. La tabla siguiente describe la huella binaria del quinto segmento.

Archivos de índice

Todos los datos escritos en un archivo TDMS se almacenan en un archivo con la extensión *.tdms. Los archivos TDMS pueden ir acompañados de un archivo de índice opcional *.tdms_index. El archivo de índice se utiliza para acelerar la lectura del archivo *.tdms. Si una aplicación de NI abre un archivo TDMS sin un archivo de índice, la aplicación crea automáticamente el archivo de índice. Si una aplicación de NI, como LabVIEW o LabWindows/CVI, escribe un archivo TDMS, la aplicación crea el archivo de índice y el archivo principal al mismo tiempo.

El archivo de índice es una copia exacta del archivo *.tdms, excepto que no contiene datos sin procesar y cada segmento empieza con una etiqueta TDSh en lugar de una etiqueta TDSm. El archivo de índice contiene toda la información para localizar con precisión cualquier valor de cualquier canal dentro del archivo *.tdms.

En resumen, el formato de archivo TDMS está diseñado para escribir y leer datos medidos a muy alta velocidad, mientras se mantiene un sistema jerárquico de información descriptiva. Si bien el diseño binario en sí mismo es bastante simple, las optimizaciones habilitadas al escribir metadatos de forma incremental pueden conducir a configuraciones de archivo muy sofisticadas.

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