Specification for the Lab VIEW Measurement File

概览

The LabVIEW Measurement (.lvm) format is a text-based file format for one-dimensional data that you want to use with the Read LabVIEW Measurement File and Write LabVIEW Measurement File Express VIs. The .lvm file is designed so it is easy to parse and easy to read when imported into a spreadsheet program, such as Microsoft Excel, or a text editor, such as Notepad. It supports multiple data sets, grouping of data sets, and the addition of data sets to existing files. The file format is not designed for high-performance or for very large data sets, as is the case with all text-based formats. Use the binary file format, such as HDF5, for very large data sets.

Structure of the Format
Format of the File
Conventions
Tags
Header
Segment Header
Special Blocks

Structure of the Format

Each .lvm file consists of a file header section, followed by the data arranged in segments. Each segment represents a call to the Write LabVIEW Measurement File Express VI. The header includes information about how the how the data should be parsed, such as the separator character used, as well as time format used.

Each segment can have each its own header section, which is useful if each segment comes from a different source, such as different channels. The Read LabVIEW Measurement File Express VI can read each segment individually from each .lvm file, or you can specify how much data to read from the file regardless of how the segments are divided. Each segment can contain a single reading, such as a temperature reading, or a large collection of data, such as the data that makes up a sine wave. Each header includes information about the data, such the time the data were acquired and the increment values for the x-axis of each segment.

Note: LVM 2.0 was introduced in LabVIEW 8.6. The only change is an additional field called Decimal_Separator, details of which can be found below

Format of the File

.lvm files are ASCII text files arranged in rows and columns. An end-of-line character, usually CR-LF, separates each row. A separator character, such as a tab, separates each column. The separator character also is defined in the header. Information within the file is in a tagged field format. Each piece of information is contained in a single row. The first column contains a tag that identifies the information. The second column contains the information. Each tag is unique and no tag is dependent upon information found in another tag. This facilitates easy line-by-line parsing of the file.

Note: To facilitate extending the .lvm file format while ensuring backwards compatibility, do not build parsers where information in one tag is dependent upon the information found in another tag.

Special tags divide the header information from the segment information. The ***End_of_Header*** tag indicates the end of either the file header or a segment header. A blank line can appear after the file header tag to make the file easier to read. However, a blank line cannot appear after the segment header because the first line after the segment header is assumed to be the column heading for the data. These column headings are arbitrary text. The fields in the header of the file determine the format of the headings and therefore, the order of the data columns. If, in the file header, X_Columns is No or One, a single label, such as X Value, appears in the first column of each segment. If X_Columns is Multi, x and y data labels alternate, with the x label appearing first. The data are in columns under the corresponding labels. For example, if you acquire a sine wave, a square wave, and a triangle wave, each segment consists of six columns with the following labels:

X_Value Sine X_Value Square X_Value Triangle

However, if No appears in the X_Columns, the first data column is empty. Each data column can have different numbers of data points.

After the last data column, a comment field appears. It contains an arbitrary text string that describes the data in the columns. To avoid conflicts with the separator and new line characters used to parse the file, use escape characters for this field. Refer to the Conventions section of this document for more information about using escape characters for this field.

The ***Start_Special*** tag indicates the start of a special segment of data and the ***End_Special*** tag indicates the end of the segment. Use these tags to indicate where segments of data begin and end that otherwise could not be processed on a line-by-line basis. For example, measurement data associated with a waveform can include special segments at any point, including the data section. Special blocks are the mechanism to add proprietary information to an .lvm file in such a way that a default reader can read the file. Most readers do not parse these tags. Simple readers are not required to parse special segments, but are required to ignore the segments correctly.

Data sections immediately follow segment headers. There can be multiple data sections after a single segment header, depending upon the format defined in the Multi_Headings header tag. The number of data points specified in the Samples section determines the number of data points in each segment.

Conventions

In the following sections, each tag is defined by its identifier and possible values. The first line of a tag definition appears bold. If the tag is optional, the default value of the tag appears in the adjacent cell. A paragraph explaining the tag follows. The possible values of a tag are given as lists below the explanation. If necessary, each value is defined. For tags with numeric values, the values are specified as Integer, Float, or Number, depending on the numeric format required for the tag. For tags with string values, the values are specified as Text. The format of the text appears in the value explanation field. Use escape characters for arbitrary text strings so they do not include the file separator character. National Instruments recommends that you replace all tabs and commas and the new line in the text with a backslash followed by the ASCII character code in hexadecimal. For example, the string yes, no appears yes\2C no after you replace the comma. The following example shows a tag with a number value.

tag0 - required - A general number

Number - Any number

This is an example of a tag that has set multiple values.

tag1 - optional, default Val1 - Only two possible values

Val1 - First possible value
Val2 - Second possible value

Header

***End_of_Header*** - required - Indicates the end of the header.

no data associated with this tag

Date - required - Date when the data collection started.

YYYY/MM/DD - The format is the same, regardless of the system time configuration.

Description - optional : default <empty string> - Description of the data in the file.

Text - Arbitrary text string; should be escaped

LabVIEW Measurement - required - Identifies the file as a LabVIEW measurement file (.lvm). This tag always appears in column 0, row 0 (the first characters in the file).

no data associated with this tag

Multi_Headings - optional : default No - Specifies whether each packet has a header.

No - The file includes a single segment header for the first segment of data. You must format the data in succeeding segments the same way as the first packet.
Yes - Every segment has its own header.

Operator - optional - The default is an empty string.

Text - Arbitrary text string; escape this tag

Project - optional : default empty string - Name of the project associated with the data in the file.

Text - Arbitrary text string; escape this tag

Reader_Version - optional : default is same version as the Writer_Version - Version number of reader needed to parse the file correctly the file type. For example, a 1.0 version of a reader can parse the file until the file format changes so much that it is no longer backwards compatible. The Writer_Versionsupplies the actual file type version.

Float - Format is (Major Version).(Minor Version)

Separator - optional : default Tab - Character(s) used to separate each field in the file. You can use any character as a separator except the new line character. However, base-level readers usually use tabs or commas as delimiters. Escape other text fields in the file to prevent the separator character(s) from appearing as text rather than delimiters. To use the character(s) specified as a delimiter requires that you know what that character(s) is. To find out what the separator character(s) is, read the entire header block and search for the keyword Separator. The character(s) that follows the keyword is the separator. To parse the file faster, place this field in the header after the LabVIEW Measurement ID field. To read in the entire header block, read until you find the ***End_of_Header***tag.

Tab - Tab character, ASCII \0x09
Comma - Comma character, ASCII \0x2C

Decimal_Separator - required for version 2.0. - The default is the decimal separator of the system. Symbol used to separate the integral part of a number from the fractional part. A decimal separator usually is a dot or a comma.

Dot - Dot character, ASCII \0x2E
Comma - Comma character, ASCII \0x2C

Time - required - Time at which the start of a data series occurred.

HH:MM:SS.XXX - The format is the same, regardless of the system time configuration. The SS.XXX is the number of seconds since the last minute as a floating-point number. The number of digits in the fractional seconds is arbitrary and can be zero. If there are no fractional seconds, the decimal point is optional.

Time_Pref - optional : default Relative - Format of the x-axis values. This tag is valid only if the X_Dimension tag value is set to Time.
Absolute - x-value is number of seconds since midnight, January 1, 1904 GMT
Relative - x-value is number of seconds since the date and time stamps

Writer_Version - required - Version number of the file type written by the software.

Float - Format is (Major Version).(Minor Version)

X_Columns - optional : default One - Specifies which x-values are saved.

No - save no x-values. The first data column is blank. The x-values can be generated from the X0 and Delta_X values.
One - saves one column of x-values. This column corresponds to the first column of data that contains the most number of samples.
Multi - saves a column of x data for every column of y data.

Segment Header

Tags that do not depend upon the Channels tag should appear before the Channels tag. Typically, the Notes tag appears first, followed by the Test_* and UUT_* tags and any special blocks. The Channels tag follows, then any other tags used before the ***End_of_Header*** tag and the data.

***End_of_Header*** - required - Indicates the end of the header.

none - No data for this tag

Channels - required - Number of channels in the packet. This field must occur before any fields that depend on it. For example, the Samples field has entries for each channel, so the reader must know the number of channels to properly parse it.

Integer - This number must be positive and non-zero

Date - required - Date the data set in the segment started. There are separate dates for each data set. The dates are placed in the same column as the y data of the data set.

YYYY/MM/DD - The format is the same, regardless of the system time configuration.

Delta_X - required - The increment between points on the x-axis. The .lvm format assumes all data is equally spaced in the x-dimension. There is one value for each data set in the packet. The value appears in the same column as the y-values for the data.

Number

Notes - optional : The default is an empty string - Comments the user adds to the segment header. A segment header does not necessarily exist for every packet. Use the Comment field at the far right of the data for specific notes about each segment.

Text - arbitrary text string - should be escaped

Samples - required - Number of samples in each waveform in the packet.

Integer - There is one entry for every data set. The entry appears in the same column as the y data of the data set.

Test_Name - optional : default <empty string> - Name of the test that acquired the segment of data.

Text - arbitrary text string - should be escaped

Test_Numbers - optional : default empty string - Test numbers in the Test_Series that acquired the data in this segment.

Text - arbitrary text string - Should be escaped. Semicolons separate the test numbers. If the file separator is a semicolon, commas separate the numbers.

Test_Series - optional : default <empty string> - Series of the test performed to get the data in this packet.

Text - arbitrary text string - should be escaped

Time - required - Time of day when you started acquiring the data set in the segment. Each data set includes a different time. The times are placed in the same column as the y data of the data set.

HH:MM:SS.XXX - The format is the same, regardless of the computer locale. The HH is the number of hours since midnight. The MM field is the number of minutes since the last hour. The SS.XXX is the number of seconds since the last minute as a floating-point number. The number of digits in the fractional seconds is arbitrary and can be zero. If there are not fractional seconds, the decimal point is optional.

UUT_M/N - optional : default empty string - Model number of the unit under test.

Text - arbitrary text string - should be escaped

UUT_Name - optional : default empty string - Name or instrument class of the unit under test.

Text - arbitrary text string - should be escaped

UUT_S/N - optional : default <empty string> - Serial number of the unit under test.

Text - arbitrary text string - should be escaped

X0 - required - The initial value for the x-axis. Each data set in the packet has a single X0 value. The value appears in the same column as the y-values for the data.

Number

X_Dimension - optional : default Time - Unit type of the x-axis. The actual data does not need to be in SI units. The X_Unit_Label field indicates the actual units of the data.

X_Unit_Label - optional : default SI units from X_Dimension - Labels for the units used in plotting the x data. The label appears in the same column as the y data to which it corresponds. You do not have to fill in all unit labels.

Text - arbitrary text string - should be escaped

Y_Dimension - optional : default Electric_Potential - Unit type of the y-axis. The actual data does not need to be in SI units. The Y_Unit_Label field indicates the actual units of the data.

Y_Unit_Label - optional : default SI units from Y_Dimension - Labels for the units used in plotting the y data. The label appears in the same column as the y data to which it corresponds. You do not have to fill in all unit labels.

Text - arbitrary text string - should be escaped

Special Blocks

Special blocks start with the ***Start_Special*** tag and end with the ***End_Special*** tag. These tags indicate to the reader that it can ignore the blocks with no error. Use the special blocks to add proprietary data to the .lvm file. All data in a special block is encapsulated and base-level readers ignore the data within the tags.

Special blocks have only one common format specification. The first row after the start tag must have the identifier (ID) of the block in the first column. The identifier then determines the format of the block. The following are special blocks already defined. These are usually specific to an application.

Binary Data

ID: Binary_Data

Normal Location: Replaces data in a packet. Appears immediately after the packet column headers.

Designed For: Scope-SFP, any application that stores binary waveform files.

Intended Use: Use of the .lvm format as a documentation tool for binary files. Note that using this special block breaks most readers because it replaces the data in the packet. The binary file is a flat sequence of binary numbers representing a single channel. This special block describes the format of the data and the linear scaling parameters needed to reconstruct it.

Format: The first row contains only the ID. The remainder of the block follows standard .lvm format, with a tag-value sequence. The tags are as follows.

Filename - required - Name of the file containing the binary data
- Text - Must be a valid file name for the system
Format - required - Binary representation of the data
- 8-bit signed integer
- 8-bit unsigned integer
- 16-bit signed integer
- 16-bit unsigned integer
- 32-bit signed integer
- 32-bit unsigned integer
- 64-bit signed integer - not required for base readers
- 64-bit unsigned integer - not required for base readers
- 32-bit IEEE float - single-precision
- 64-bit IEEE float - double-precision
- 128-bit IEEE float - quad-precision, not required for base readers
Endian - required - Byte ordering of the data
- Big-Endian
- Little-Endian
Vout = a1*DigIn + a0 - optional - Documentation line for the Scale (a1) and Offset (a0) tags
- none
Scale (a1) - optional : default 1 - Scaling factor for the data. This is usually present when the data is a raw integer from a digitizer.
- Number
Offset (a0) - optional : default 0 - Offset for the data. This is usually present when the data is a raw integer from a digitizer.
- Number
an - optional : default 0 - Higher order scaling factors for the data. An integer replaces the n to give the order number of the factor. For example, a6 is the sixth order scaling factor. There can be an arbitrary number of these, as long as they represent different order numbers.
- Number

Segment Notes

ID: Packet_Notes

Normal Location: Segment Header

Designed For: any application

Intended Use: Notes field that is more flexible than the Comment field in individual segments.

Format: The first row contains only the ID. The rest of the data is completely arbitrary. Design the formatting for use in a spreadsheet. For example, to create channel specific notes, put the channel y data header in column 0 and the note in column 1 on each row.

Waveform Scalar Measure

ID: Wfm_Sclr_Meas

Normal Location: Segment Header

Designed For: Scope-SFP, soft front panel for NI-Scope devices

Intended Use: Recording scalar measurements taken on the waveforms in the packet

Format: The first row contains only the ID. The data is subdivided into blocks corresponding to the different data channels, each of which has measurement data. Each block starts with a row containing the y channel header for the data. The next row contains the header for the measurements. The header consists of a blank first column, then the following text strings in the succeeding columns - Value, Units, Hi_Lvl, Mid_Lvl, Lo_Lvl, Lvl_Units, Units_Method, and Other_Channel. The following list defines these strings.

Value - Value of the measurement
Units - Units of the measurement
Hi_Lvl - High level, if any, used to perform the measurement. For example, a rise time measurement requires a high and a low level. If there is no value, the field appears with an en dash (ASCII \0x2D).
Mid_Lvl - Middle level, if any, used to perform the measurement. For example, a period measurement requires a middle level to provide the level crossing information. If there is no value, the field appears with an en dash (ASCII \0x2D).
Lo_Lvl - Low level, if any, used to perform the measurement. For example, a rise time measurement requires a high and a low level. If there is no value, the field appears with an en dash (ASCII \0x2D).
Lvl_Units - This field can have one of two values - Actual and Percent. If Actual, the units of the level fields are the same as the units of the y-axis for the data. If Percent, the units of the level fields are in percent. The method of calculating the percent values is contained in the Units_Method field.
Units_Method - Describes the method used to calculate the high and low limits from which the percentage values for the levels are calculated. There are four values: LowHigh, MinMax, BaseTop, and the en dash (ASCII \0x2D). LowHigh uses a standard histogram method so square wave overshoot is ignored. MinMax uses the minimum and maximum of the waveform for the limits. BaseTop uses the LowHigh method if the histogram has clear peaks at the ends, such as square waves, and MinMax if the histogram does not have clear peaks at the ends, such as sine waves. The en dash indicates that this field is not used due to the Lvl_Units field being set to Actual.
Other_Channel - The zero-based index of the other channel in the list of channels for this packet used to perform the measurement. Only measurements that require two channels, such as phase delay, result in an entry in this field.

Each line following the header in a measurement block corresponds to an individual measurement. The first column contains the measurement. Each succeeding column contains the values for the headers listed above. The following measurements have been defined.

AC_Estimate - RMS voltage of the waveform calculated by subtracting the DC estimate and applying a window function, such as Hanning, then calculating the RMS value. This minimizes the effect of a non-integer number of cycles of a periodic function.
Area - Area under the waveform by summing the y-values, calculated multiplying by the x-increment and dividing by the number of points.
Average_Freq - Average frequency of a periodic waveform in the trace. Determined from the position of the first and last cycles. Uses Mid_Lvl.
Average_Period - Average period of a periodic waveform in the trace. Determined from the position of the first and last cycles. Uses Mid_Lvl.
Cycle_Area - Area of the first cycle of the waveform. Uses Mid_Lvl.
DC_Estimate - Average voltage of the waveform calculated by applying a window function, such as Hanning, to the data, then calculating the average. This minimizes the effect of a non-integer number of cycles of a periodic function.
Fall_Slew_Rate - Falling slew rate of the first pulse in a waveform. Uses Hi_Lvl and Lo_Lvl.
Fall_Time - Fall time of the first pulse in a waveform. Uses Hi_Lvl and Lo_Lvl.
FFT_Amplitude - Height of the largest amplitude peak in the FFT spectrum of the waveform.
FFT_Freq - Frequency of the highest peak in the FFT spectrum of the waveform.
Frequency - Frequency of a periodic waveform in the trace. Determined from the first cycle. Uses Mid_Lvl.
High_Ref_Volts - Value of the Hi_Lvl.
Integral - Integral of the waveform using Simpson's rule.
Levels