tdms 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1cdde94353fa626b85a4fa61044c5562baeca357
+  data.tar.gz: 6cd526130eecd98461297ce47a8a51ec11671801
+SHA512:
+  metadata.gz: 8c3ed68005a5ec8c0c97f074d1096b15035cbe3174ebf6f212a0cc6225ba45bac582b3ee10a365c529bfa4ba9fa354c2b2365e84c6d9d32fa3777515ecb48cdc
+  data.tar.gz: 4443ac28b1267c32ac333c606f7c53bf11439d400076dec64ecf859163629a9c7139b4072fee5ce250643236092c509e80fc560ce1c5ce688a622d80f0a16053

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+sudo: false
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
+

data/LICENSE.txt

@@ -0,0 +1,25 @@
+Copyright (c) 2012, Mike Naberezny.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of Maintainable Software, LLC. nor the names of its
+      contributors may be used to endorse or promote products derived from
+      this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,34 @@
+# TDMS for Ruby
+
+TDMS is a binary file format for measurement data.  It was created
+by National Instruments.
+
+ - [NI TDMS File Format](http://zone.ni.com/devzone/cda/tut/p/id/3727)
+ - [TDMS File Format Internal Structure](http://zone.ni.com/devzone/cda/tut/p/id/5696)
+
+National Instruments software such as LabVIEW, DIAdem, and Measurement
+Studio support reading and writing TDMS files.  NI also provides a DLL
+written in C for using TDMS files on Windows.
+
+TDMS for Ruby was written to provide a convenient way to work with
+TDMS files on Unix-like platforms.
+
+## Current State
+
+This library is very early in development but is complete enough to
+read the example TDMS file that comes with NI DIAdem.
+
+ - Segments with interleaved measurements are not yet supported.
+ - Segments with big endian data are not yet supported.
+ - Writing TDMS files is not yet supported.
+
+## Fork
+
+Aaron Ten Clay has a [fork](https://github.com/aarontc/ruby_tdms) of this
+library that claims to support the segment types above, along with reading
+from streams instead of files, and other features.  
+
+## Contributors
+
+[Mike Naberezny](http://github.com/mnaberez) is the author of TDMS for
+Ruby.  Development is sponsored by [Maintainable](http://maintainable.com).

data/Rakefile

@@ -0,0 +1,15 @@
+here = File.expand_path('..', __FILE__)
+$LOAD_PATH.unshift File.join(here, 'lib')
+$LOAD_PATH.unshift File.join(here, 'test')
+
+desc "Run tests"
+task :test do
+  require 'tdms'
+  require 'test_helper'
+
+  Dir.chdir(File.join(here, 'test')) do
+    Dir['**/*_test.rb'].each { |file| require file }
+  end
+end
+
+task :default => [:test]

data/demo.rb

@@ -0,0 +1,16 @@
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), 'lib')
+
+require 'tdms'
+
+filename = File.dirname(__FILE__) + "/test/fixtures/example.tdms"
+doc = Tdms::File.parse(filename)
+
+ch1 = doc.channels.find {|c| c.name == "StatisticsText"}
+ch2 = doc.channels.find {|c| c.name == "Res_Noise_1"}
+
+last = [ch1.values.size, ch2.values.size].min - 1
+
+puts "#{ch1.name},#{ch2.name}"
+0.upto(last) do |i|
+  puts "#{ch1.values[i]},#{ch2.values[i]}"
+end

data/doc/data_types.txt

@@ -0,0 +1,23 @@
+Data Types
+
+Identifier    Name                            Length (bytes)    Ruby
+
+0x00000000    tdsTypeVoid                     1                 Nil
+0x00000001    tdsTypeI8                       1                 Integer
+0x00000002    tdsTypeI16                      2                 Integer
+0x00000003    tdsTypeI32                      4                 Integer
+0x00000004    tdsTypeI64                      8                 Integer
+0x00000005    tdsTypeU8                       1                 Integer
+0x00000006    tdsTypeU16                      2                 Integer
+0x00000007    tdsTypeU32                      4                 Integer
+0x00000008    tdsTypeU64                      8                 Integer
+0x00000009    tdsTypeSingleFloat              4                 Float
+0x0000000A    tdsTypeDoubleFloat              8                 Float
+0x0000000B    tdsTypeExtendedFloat            10                ?
+0x00000019    tdsTypeSingleFloatWithUnit      4                 Float
+0x0000001A    tdsTypeDoubleFloatWithUnit      8                 Float
+0x0000001B    tdsTypeExtendedFloatWithUnit    10                ?
+0x00000020    tdsTypeString                   4 len + n chars   String
+0x00000021    tdsTypeBoolean                  1                 True, False
+0x00000044    tdsTypeTimeStamp                16                DateTime
+0xFFFFFFFF    tdsTypeDAQmxRawData             ?                 ?

data/doc/example_disasm.txt

@@ -0,0 +1,47 @@
+EXAMPLE.tdms
+  Contains 4 segments
+
+
+000000  54 44 53 6d  "TDSm" id tag
+000004  0E 00 00 00  0e is ToC flag, other 3 bytes unused
+000008  68 12 00 00  6812 is little endian for 0x1268 or 4713 (TDMS standard version).  Other two bytes unused.
+00000C  E3 88 20 00
+000010  00 00 00 00  => 64-bit unsigned little endian 0x00000000002088E3 is the next segment offset
+000014  E3 08 00 00
+000018  00 00 00 00  => 64-bit unsigned little endian 0x00000000000008E3 is the raw data offset
+ ( End of Lead-In )
+ (   00001C is the offset of the next byte after the lead-in )
+ (   Next segment offset = 00001C + 2088E3 = 2088FF )
+ (   Raw data offset     = 00001C + 0008E3 = 0008FF )
+
+ ( Start of Metadata )
+00001C  08 00 00 00  => 32-bit unsigned little endian 0x00000008 is the number of
+                        new/changed objects in this segment (8 objects)
+000020  11 00 00 00  => 32-bit unsigned little endian 0x00000011 is the length of
+                        the object's path string (11 bytes)
+ (Begin Path String)
+000024  2F 27 45 58  /'EX
+000028  41 4D 50 4C  AMPL
+00002C  45 27 2F 27  E'/'
+000030  54 69 6D 65  Time
+000034  27           '
+ (Begin Length of Index)
+000034     14 00 00
+000038  0A 00 00    => 32-bit unsigned little endian 0x00000014 is the
+                       raw data index
+ (Begin Data Type)
+000038           0A
+00003C  00 00 00    => 32-bit unsigned little endian 0x0000000A is the
+                       data type (tdsTypeDoubleFloat)
+
+ (Begin Array Dimension)
+00003C           01
+000040  00 00 00     => 32-bit unsigned little endian 0x00000001 is the
+                        array dimension (always 1)
+ (Begin Number of Values)
+000040           00
+000044  04 00 00 00
+000048  04 00 00     => 64-bit unsigned little endian 0x0000000000000400 is the
+                        number of values (1024 values)
+ (Begin Total Size in Bytes)
+

data/doc/tdms_format.txt

@@ -0,0 +1,101 @@
+http://zone.ni.com/devzone/cda/tut/p/id/5696
+
+Object Hierarchy
+
+  Hierarchy                                 Path
+
+  example_events.tdms (File)                /
+   |
+   +-- Measured Data (Group)                /'Measured Data'
+   |     |
+   |     +-- Amplitude Sweep (Channel)      /'Measured Data'/'Amplitude Sweep'
+   |     +-- Phase Sweep (Channel)          /'Measured Data'/'Phase Sweep'
+   |
+   +-- Dr. T's Events (Group)               /'Dr. T''s Events'
+         |
+         +-- Time (Channel)                 /'Dr. T''s Events'/'Time'
+         +-- Description (Channel)          /'Dr. T''s Events'/'Description'
+
+  There are exactly 3 levels of objects in TDMS:
+   - File (every TDMS file must have one)
+   - Group (has many Channels, may have none)
+   - Channel (belongs to a Group)
+
+  Every object is identified by a string path.  The only thing that
+  identifies an object as being a File, Group, or Channel is the
+  number of Segments in the string path:
+
+    Object Type      Example Path         Number of Path Segments
+    File             /                    0
+    Group            /'Group'             1
+    Channel          /'Group'/'Channel'   2
+
+
+File Structure
+
+  File is divided into Segments.
+  Each segment contains one or more Objects
+  Every Object has a string Path
+
+
+Segment
+
+  +-----------+------------+------------+----------------------------
+  |  Lead-in  |  Metadata  |  Raw Data  |  Lead-in (Next Segment) ...
+  +-----------+------------+------------+----------------------------
+
+  Lead-in
+    +---------+--------+---------+--------------------+--------------------+---
+    | 4: TDSm | 4: ToC | 4: Vers | 8: Next Seg Offset | 8: Raw Data Offset | Metadata ...
+    +---------+--------+---------+--------------------+--------------------+---
+    00        04       08        0C                   14                   1C
+
+
+    00-03  4 bytes: TDMS identifier (always "TDSm")
+    04-07  4 bytes: Table of contents (only first byte used)
+                    Flags to indicate what is in the segment
+    08-0B  4 bytes: TDMS version number (always 4713)
+    0C-13  8 bytes: Offset of the next segment (little endian).  Take the
+                    absolute offset of the next byte after the lead-in and
+                    add it to this number to find the next segment.
+    14-1B  8 bytes: Offset of the raw data in this segment (little endian).
+                    Also calculate it from next byte after the lead-in.
+
+
+  Metadata
+    +----------+-------------+---------+-------------------+--------------+-
+    | 4: Count | 4: Path Len | n: Path | 4: Raw data index | 4: Num Props |
+    +----------+-------------+---------+-------------------+--------------+-
+    00         04            08
+
+    4 bytes: Number of new/changed objects in this segment
+
+    For each object in the segment:
+      4 bytes: Length of object's string path
+      n bytes: Object's string path
+
+      Index block or markers:
+        If no raw data in the segment:
+          4 bytes: FF FF FF FF
+        Else if raw data index block exactly matches last segment:
+          4 bytes: 00 00 00 00
+        Else:
+          4 bytes: Length of raw data index block + 4
+          4 bytes: Data type of the raw data in this object
+          4 bytes: Dimension of raw data array (only first byte used, always 1)
+          8 bytes: Number of values
+          8 bytes: Total size in bytes (?) -- may not be here
+
+      Properties Block:
+
+        4 bytes: Number of properties of this object
+
+        For each property:
+          4 bytes: Length of property name
+          n bytes: Property name
+          4 bytes: Data type of property value (only first byte used)
+          n bytes: Property value
+                     String is 4 bytes for length, then bytes of string
+                     Others are fixed number of bytes for value based on type
+
+  Raw Data

data/doc/usage.txt

@@ -0,0 +1,46 @@
+READING
+=======
+
+# display properties of a channel
+
+  group = segment.groups.find {|grp| grp.path == "/'EXAMPLE'" }
+  speed = group.channels.find {|ch| ch.path == "/'EXAMPLE'/'Time'" }
+  speed.properties.each_pair do |k,v|
+    puts k,v
+  end
+
+# loop through a channel
+
+  group = segment.groups.find {|grp| grp.path == "/'EXAMPLE'" }
+  speed = group.channels.find {|ch| ch.path == "/'EXAMPLE'/'Time'" }
+  speed.values.each do |v|
+    puts v  #=> float
+  end
+
+# spreadsheet of two channels
+
+  group = segment.groups.find {|grp| grp.path == "/'EXAMPLE'" }
+
+  time  = group.channels.find { |ch| ch.path == "/'EXAMPLE'/'Time'" }
+  speed = group.channels.find { |ch| ch.path == "/'EXAMPLE'/'Speed'" }
+
+  max = [time.values.size, speed.values.size].max - 1
+  0.upto(max) do |i|
+    puts "%f,%f" % (time.values[i], speed.values[i])
+  end
+
+
+WRITING
+=======
+
+tdms = Tdms::File.new("some filename")
+seg = tdms.segment.build
+
+group = seg.groups.build("foo")
+
+chan = group.channels.build("bar")
+chan.properties["Flux Capacitor"] = "On"
+channel.values << 1.02
+channel.values << 1.02
+
+seg.save

data/lib/tdms.rb

@@ -0,0 +1,8 @@
+require 'tdms/document'
+require 'tdms/streaming'
+require 'tdms/property'
+require 'tdms/datatypes'
+require 'tdms/segment'
+require 'tdms/channel'
+require 'tdms/path'
+require 'tdms/aggregate'

data/lib/tdms/aggregate.rb

@@ -0,0 +1,71 @@
+module Tdms
+
+  class AggregateChannel
+    def initialize(channels=[])
+      @channels = channels
+    end
+
+    def path
+      @channels[0].path
+    end
+
+    def name
+      @channels[0].name
+    end
+
+    def data_type
+      @channels[0].data_type
+    end
+
+    def values
+      @values ||= AggregateChannelEnumerator.new(@channels)
+    end
+  end
+
+  class AggregateChannelEnumerator
+    include Enumerable
+
+    def initialize(channels)
+      @channels = channels
+      @offsets  = []
+
+      size = 0
+      @channels.inject(0) do |size, channel|
+        @offsets << size
+        size += channel.values.size
+      end
+    end
+
+    def size
+      @size ||= @channels.inject(0) { |sum, chan| sum += chan.values.size }
+    end
+
+    def each
+      @channels.each do |channel|
+        channel.values.each { |value| yield value }
+      end
+    end
+
+    def [](i)
+      if (i < 0) || (i >= size)
+        raise RangeError, "Channel %s has a range of 0 to %d, got invalid index: %d" %
+                          [@channels[0].path, size - 1, i]
+      end
+
+      channel, offset = nil, nil
+      j = @offsets.size - 1
+      @offsets.reverse_each do |o|
+        if i >= o
+          channel = @channels[j]
+          offset  = @offsets[j]
+          break
+        else
+          j -= 1
+        end
+      end
+
+      channel.values[i - offset]
+    end
+  end
+
+end

data/lib/tdms/channel.rb

@@ -0,0 +1,100 @@
+module Tdms
+
+  class Channel < Object
+    attr_accessor :file, :path, :data_type_id, :dimension, :num_values,
+                  :raw_data_pos
+
+    def name
+      path.channel
+    end
+
+    def values
+      @values ||= begin
+        klass = if data_type::LengthInBytes.nil?
+          StringChannelEnumerator
+        else
+          ChannelEnumerator
+        end
+
+        klass.new(self)
+      end
+    end
+
+    def data_type
+      @data_type ||= DataType.find_by_id(data_type_id)
+    end
+  end
+
+  class ChannelEnumerator
+    include Enumerable
+
+    def initialize(channel)
+      @channel = channel
+    end
+
+    def size
+      @size ||= @channel.num_values
+    end
+
+    def each
+      0.upto(size - 1) { |i| yield self[i] }
+    end
+
+    def [](i)
+      if (i < 0) || (i >= size)
+        raise RangeError, "Channel %s has a range of 0 to %d, got invalid index: %d" %
+                          [@channel.path, size - 1, i]
+      end
+
+      @channel.file.seek @channel.raw_data_pos + (i * @channel.data_type::LengthInBytes)
+      @channel.data_type.read_from_stream(@channel.file).value
+    end
+  end
+
+  class StringChannelEnumerator
+    include Enumerable
+
+    def initialize(channel)
+      @channel = channel
+
+      @index_pos = @channel.raw_data_pos
+      @data_pos  = @index_pos + (4 * @channel.num_values)
+    end
+
+    def size
+      @size ||= @channel.num_values
+    end
+
+    def each
+      data_pos = @data_pos
+
+      0.upto(size - 1) do |i|
+        index_pos = @index_pos + (4 * i)
+
+        @channel.file.seek index_pos
+        next_data_pos = @data_pos + @channel.file.read_u32
+
+        length = next_data_pos - data_pos
+
+        @channel.file.seek data_pos
+        yield @channel.file.read(length)
+
+        data_pos = next_data_pos
+      end
+    end
+
+    def [](i)
+      if (i < 0) || (i >= size)
+        raise RangeError, "Channel %s has a range of 0 to %d, got invalid index: %d" %
+                          [@channel.path, size - 1, i]
+      end
+
+      inject(0) do |j, value|
+        return value if j == i
+        j += 1
+      end
+    end
+
+  end
+
+end