ruby-gdsii 1.0.0

data/lib/gdsii/record/datatypes/real8.rb

@@ -0,0 +1,120 @@
+require 'gdsii/record/datatypes/data.rb'
+
+module Gdsii
+
+  module RecData
+
+    #
+    # Class for REAL8 data type
+    #
+    class Real8 < Data
+      
+      # Value is an array of floating point numbers
+      attr_reader :value
+
+      # Construct an Gdsii::RecData::Real8 data object.  The value is an array
+      # of floating point numbers (Float).
+      def initialize(value)
+        super(GDT_REAL8, value)
+      end
+
+      # Set the value for this object; verify that the value items are of
+      # type Float (or at least can be coerced using "to_f").
+      def value=(value)
+        @value = Data.coerce_value(value, Float, :to_f)
+      end
+
+      # Returns the size of the record *data* in bytes.  Each array element
+      # consumes 8 bytes (hence REAL8).
+      def byte_size()
+        @value.length * 8
+      end
+
+      # Reads a REAL8 record from the given file and for the length of bytes
+      # given and returns a new Gdsii::RecData::Real8 object.
+      def Real8.read(file, byte_count)
+        data = []
+        while (byte_count > 0)
+
+          # read the first byte and get sign and exponent values from it
+          raw = file.read(1)
+          sign_val = raw.unpack('B')[0].to_i
+          exponent = raw.unpack('C')[0]
+          exponent -= (sign_val == 0) ? 64 : 192 # exponent is in Excess 64 fmt
+
+          # read the rest of the real number - save as binary
+          raw = file.read(7)
+          mant_binary = raw.unpack('b*')[0]
+
+          # convert mantissa from binary to decimal
+          mantissa = 0.0
+          (1...8).each do |i|
+            str = mant_binary[(i-1)*8,8]
+            ub = [("0"*32+str.reverse.to_s)[-32..-1]].pack("B32").unpack("N")[0]
+            mantissa += ub / (256.0 ** i)
+          end
+          real = mantissa * (16**exponent)
+          real = -real if (sign_val != 0)
+          data.push real
+
+          byte_count -= 8
+
+        end
+
+        Real8.new(data)
+      end
+
+      # Writes the integer values in this Gdsii::RecData::Real8 object to the
+      # given file as a GDSII REAL8 record.
+      def write(file)
+
+        self.value.each do |item|
+
+          if item == 0 then
+            file.write "\x00" * 8
+          else
+            # Note: process differently for big endian?
+            bit_str  = [item].pack('G').unpack('B*')[0]
+
+            # get the sign and expt (IEEE)
+            sign = bit_str[0,1]
+            expt = ['00000'+bit_str[1,11]].pack('B16').unpack('n')[0] - 1023
+
+            # Divide by 4 because 16**x == (2**4)**x == 2**(4*x)
+            b16_expt = (expt / 4).floor
+            b16_rem  = expt % 4
+
+            # Shift the mantissa 4 bits to the right and increment the expt
+            b16_expt += 1
+            mant = ['0', '0', '0', '1', bit_str[12..63].split('')].flatten
+
+            # Shift the mantissa to left to take care of the expt remainder
+            (0...b16_rem).each do |i|
+              mant.shift
+              mant.push '0'
+            end
+            
+            # Bias the base-16 expoent
+            b16_expt += 64
+
+            # Convert the expt to a 7-bit binary string
+            b16_expt_str = [b16_expt].pack('C').unpack('B*')[0][1..7]
+
+            # Now assemble the sign, expt and mantissa    
+            real8_fmt = sign + b16_expt_str + mant.join('')
+            file.write [real8_fmt].pack('B*')
+          end
+
+        end
+      end
+      
+      # Converts the array of floating point values to a string (values are
+      # joined by spaces).
+      def to_s()
+        value.map {|v| v.to_s}.join(' ')
+      end
+      
+    end
+  end
+end
+

data/lib/gdsii/sref.rb

@@ -0,0 +1,61 @@
+require 'gdsii/group'
+require 'gdsii/element'
+require 'gdsii/strans'
+
+module Gdsii
+  
+  #
+  # Represents a GDSII structure reference (SRef) element.  Most
+  # methods are from Element or from the various included Access module
+  # methods.
+  #
+  class SRef < Element
+    
+    # Include various record accessors
+    include Access::XY
+    include Access::ELFlags
+    include Access::Plex
+    include Access::StransGroup
+    include Access::Sname
+
+    #
+    # SRef BNF description:
+    #
+    #  <sref> ::= SREF [ELFLAGS] [PLEX] SNAME [<strans>] XY
+    #
+    self.bnf_spec = BnfSpec.new(
+      BnfItem.new(GRT_SREF),
+      BnfItem.new(GRT_ELFLAGS, true),
+      BnfItem.new(GRT_PLEX, true),
+      BnfItem.new(GRT_SNAME),
+      BnfItem.new(Strans, true),
+      BnfItem.new(GRT_XY),
+      BnfItem.new(Properties, true),
+      BnfItem.new(GRT_ENDEL)
+    )
+                                
+    #
+    # Create a structure reference (SREF) within a Structure object (also
+    # known as a structure "instantiation").
+    #
+    #  struct1 = Gdsii::Structure.new('top')
+    #  struct2 = Gdsii::Structure.new('sub')
+    #  struct1.add SRef.new('sub')
+    #
+    # Alternatively, any object with a #to_s method can be passed and the
+    # #to_s method will be used to coerce the object into a string.  For
+    # example, a structure object itself can be used (instead of the structure
+    # name) through Structure#to_s:
+    #
+    #  struct1.add SRef.new(struct2)
+    #
+    def initialize(sname=nil, xy=nil)
+      super()
+      @records[GRT_SREF] = Record.new(GRT_SREF)
+      self.sname = sname.to_s unless sname.nil?
+      self.xy = xy unless xy.nil?
+      yield self if block_given?
+    end
+    
+  end
+end

data/lib/gdsii/strans.rb

@@ -0,0 +1,133 @@
+require 'gdsii/group'
+
+module Gdsii
+
+  #
+  # Represents a GDSII structure translation object (Strans). 
+  #
+  class Strans < Group
+
+    #
+    # Strans BNF description:
+    #
+    # <strans> ::= STRANS [MAG] [ANGLE]
+    #
+    self.bnf_spec = BnfSpec.new(
+      BnfItem.new(GRT_STRANS),
+      BnfItem.new(GRT_MAG, true),
+      BnfItem.new(GRT_ANGLE, true)
+    )
+
+    # Constructor
+    def initialize(mag=nil, angle=nil, reflect_x=false, abs_mag=false, abs_angle=false)
+      super()
+      @records[GRT_STRANS] = Record.new(GRT_STRANS, 0)
+      self.reflect_x = true if reflect_x
+      self.abs_mag = true if abs_mag
+      self.abs_angle = true if abs_angle
+      self.mag = mag unless mag.nil?
+      self.angle = angle unless angle.nil?
+      yield self if block_given?
+    end
+
+    #
+    # Get the strans bitarray (returns Record)
+    #
+    def record() @records.get(GRT_STRANS); end
+
+    #
+    # Get the strans bitarray data (returns Fixnum).  The recommendation is to
+    # not access this directly but rather use the various bitwise query
+    # methods instead: #reflect_x?, #abs_angle?, #abs_mag?.
+    #
+    def value() @records.get_data(GRT_STRANS); end
+
+    #
+    # Set the strans bitarray record.  The recommendation is to not access
+    # this directly but rather use the various bitwise manipulation methods
+    # instead: #reflect_x=, #abs_angle=, #abs_mag=.
+    #
+    # * 15 = reflect_x
+    # * 2 = abs_mag
+    # * 1 = abs_angle
+    # * All others reserved for future use.
+    #
+    def value=(val)
+      @records.set(GRT_STRANS,val);
+    end
+
+    #
+    # Get the strans angle (returns Record)
+    #
+    def angle_record() @records.get_data(GRT_ANGLE); end
+
+    #
+    # Get the strans angle value (returns Fixnum)
+    #
+    def angle() @records.get_data(GRT_ANGLE); end
+
+    #
+    # Set the strans angle record
+    #
+    def angle=(val) @records.set(GRT_ANGLE,val); end
+  
+    #
+    # Get the strans magnification (returns Record)
+    #
+    def mag_record() @records.get_data(GRT_MAG); end
+
+    #
+    # Get the strans magnification value (returns Fixnum)
+    #
+    def mag() @records.get_data(GRT_MAG); end
+
+    #
+    # Set the strans magnification record
+    #
+    def mag=(val) @records.set(GRT_MAG,val); end
+
+    #
+    # Return true if the translation bitarray indicates that a reflection
+    # about the x-axis is set.
+    #
+    def reflect_x?()
+      (value & 0x8000) == 0x8000
+    end
+
+    #
+    # Set or clear the strans x-reflect bit (true = set; false = clear)
+    #
+    def reflect_x=(flag)
+      self.value = flag ? value | 0x8000 : value & 0x7fff
+    end
+
+    #
+    # Return true if an absolute magnification is set; false if not
+    #
+    def abs_mag?()
+      (value & 0x0004) == 0x0004
+    end
+
+    #
+    # Set or clear the absolute magnification bit (true = set; false = clear)
+    #
+    def abs_mag=(flag)
+      self.value = flag ? value | 0x0004 : value & 0xfffb
+    end
+
+    #
+    # Return true if the absolute angle bit is set; false if not
+    #
+    def abs_angle?()
+      (value & 0x0002) == 0x0002
+    end
+
+    #
+    # Set the strans absAngle bit
+    #
+    def abs_angle=(flag)
+      self.value = flag ? value | 0x0002 : value & 0xfffd
+    end
+
+  end
+end

data/lib/gdsii/structure.rb

@@ -0,0 +1,352 @@
+require 'time'
+require 'gdsii/mixins'
+require 'gdsii/element'
+require 'gdsii/boundary'
+require 'gdsii/path'
+require 'gdsii/text'
+require 'gdsii/node'
+require 'gdsii/box'
+require 'gdsii/sref'
+require 'gdsii/aref'
+
+module Gdsii
+
+  #
+  # Represents a GDSII Structure.
+  #
+  class Structure < Group
+
+    include Access::GdsiiTime
+    
+    #
+    # Structure BNF description:
+    #   
+    #  <structure> ::= BGNSTR STRNAME [STRCLASS] {<element>}* ENDSTR
+    #  <element>   ::= {<boundary> | <path> | <sref> | <aref> |
+    #                  <text> | <node> | <box>}  {<property>}*  ENDEL
+    #
+    self.bnf_spec = BnfSpec.new(
+      BnfItem.new(GRT_BGNSTR),
+      BnfItem.new(GRT_STRNAME),
+      BnfItem.new(GRT_STRCLASS, true),
+      BnfItem.new(Elements, true),
+      BnfItem.new(GRT_ENDSTR)
+    )
+    
+    #
+    # Creates a Structure object.  Various GDSII Elements are added to a
+    # structure such as a Boundary, Path, SRef, ARef, Text, Node, and Box.
+    #
+    #  str_sub = Structure.new('sub')
+    #  str_top = Structure.new('top')
+    #  str_top.add SRef.new(str_sub)
+    #  str_top.add Boundary.new(1, 0, [0,0, 0,10, 10,10, 10,0, 0,0])
+    #
+    def initialize(name=nil)
+      # Create the record grouping
+      super()
+      @records[Elements] = Elements.new
+      @records[GRT_ENDSTR] = Record.new(GRT_ENDSTR)
+
+      # set the name
+      self.name = name unless name.nil?
+
+      # Set create/modify time to the current time
+      now = Time.now
+      self.create_time = now
+      self.modify_time = now
+
+      yield self if block_given?
+    end
+
+    #
+    # Access to the Elements object.  See Elements for a listing of methods.
+    #
+    def elements(); @records.get(Elements); end
+
+    #
+    # Shortcut for Elements#add.  For example, instead of:
+    #
+    #  struct = Structure.new('test')
+    #  struct.elements.add Text(1, 0, [0,0], 'hello')
+    #
+    # It could be simply:
+    #
+    #  struct.add Text(1, 0, [0,0], 'hello')
+    #
+    def add(*args); elements.add(*args); end
+
+    #
+    # Shortcut for Elements#remove.  For example, instead of:
+    #
+    #  struct.elements.remove {|e| e.class == Gdsii::Text}
+    #
+    # It could be simply:
+    #
+    #  struct.remove {|e| e.class == Gdsii::Text}
+    #
+    def remove(*args); elements.remove(*args); end
+
+    #
+    # Get the Structure STRNAME record (returns Record).
+    #
+    def name_record() @records.get(GRT_STRNAME); end
+
+    #
+    # Get the Structure name (returns String).
+    #
+    def name() @records.get_data(GRT_STRNAME); end
+  
+    #
+    # Set the Structure name.
+    #
+    def name=(val) @records.set(GRT_STRNAME, val); end
+
+    #
+    # Get the strclass record (returns Record).
+    #
+    def strclass_record() @records.get(GRT_STRCLASS); end
+
+    #
+    # Get the strclass bitarray number (returns Fixnum).
+    #
+    def strclass() @records.get_data(GRT_STRCLASS); end
+  
+    #
+    # Set the strclass bitarray number.  According to the GDSII specification,
+    # this is only to be used by Calma - otherwise it should be omitted or
+    # set to 0.  It is probably a good idea to not touch this property.
+    #
+    def strclass=(val) @records.set(GRT_STRCLASS, val); end
+    
+    #
+    # Get the bgnstr record (returns Record).
+    #
+    def bgnstr_record() @records.get(GRT_BGNSTR); end
+
+    #
+    # Get the bgnstr number (returns Fixnum).  This holds the create/modify
+    # time stamp for the structure.  It is probably easier to not access this
+    # directly but to use #create_time and #modify_time instead.
+    #
+    def bgnstr() @records.get_data(GRT_BGNSTR); end
+  
+    #
+    # Set the bgnstr number.  The value is a Fixnum representation of the
+    # create/modify time stamp for the structure.  It is probably easier to
+    # not access this directly but to use #create_time= and #modify_time=
+    # instead.
+    #
+    def bgnstr=(val) @records.set(GRT_BGNSTR, val); end
+    
+    #
+    # Accepts a Time object and sets the create time for the structure.
+    #
+    #  struct.create_time = Time.now
+    #
+    def create_time=(time)
+      @create_time = time
+      update_times
+    end
+
+    #
+    # Returns the create time for this structure (returns Time)
+    #
+    def create_time(); @create_time; end
+    
+    #
+    # Accepts a Time object and sets the modify time for the structure.
+    #
+    #  struct.modify_time = Time.now
+    #
+    def modify_time=(time)
+      @modify_time = time
+      update_times
+    end
+
+    #
+    # Returns the modify time for this structure (returns Time)
+    #
+    def modify_time(); @modify_time; end
+
+    #
+    # Reads records related to a Structure header from the given file handle.
+    # It is assumed that the file position is already at BGNSTR (likely after
+    # Library#read_header).  The structure is yielded (if desired) and
+    # returned.  The iterative version of this method is likely preferable
+    # in most cases (Structure#read_each_header).
+    #
+    def Structure.read_header(file)
+      Structure.read(file, nil, nil, :before_group) {|struct|
+        yield struct if block_given?
+        break struct
+      }
+    end
+
+    #
+    # Reads each Structure and its Elements from the given file handle.  Each
+    # Structure is yielded after the entire Structure is read from the file.
+    # Compare this with Structure#read_each_header which might be more
+    # efficient, more streamlined, and consume less memory.
+    #
+    # The Library#read_header method must be called as a prerequisite (the file
+    # handle must be at a BGNSTR record).
+    #
+    #  File.open(file_name, 'rb') do |file|
+    #    Library.read_header(file) do |lib|
+    #      Structure.read_each(file) do |struct|
+    #        puts "#{struct.name} has #{struct.elements.length} elements"
+    #      end
+    #    end
+    #  end
+    #
+    def Structure.read_each(file)
+      while (Record.peek(file).type == GRT_BGNSTR) do
+        yield Structure.read(file)
+      end
+    end
+
+    #
+    # Reads the Structure header records from a file handle but without reading
+    # any Element records.  The resulting Structure element is yielded.  This
+    # is useful for using the high-level GDSII access methods as a stream file
+    # is being read in.
+    #
+    # Prior to using this method, the file position must be at the first
+    # structure definition (i.e. after the Library header).  The best method
+    # to do this is to call Library#read_header first.
+    #
+    # Also, you _MUST_ advance the file position to the next structure record
+    # header (BGNSTR) either with Structure#seek_next or
+    # Structure#read_each_element within the code block.  Otherwise the file
+    # pointer will not be advanced properly and only the first Structure will
+    # be yielded.
+    #
+    #  File.open(file_name, 'rb') do |file|
+    #    Library.read_header(file) do |lib|
+    #      Structure.read_each_header(file) do |struct|
+    #        if struct.name == 'TOP'
+    #          # Show all elements in structure "TOP"
+    #          puts "Processing structure #{struct.name}"
+    #          Element.read_each(file) do |element|
+    #            puts "--> Element: #{element.class}"
+    #          end
+    #        else
+    #          # Skip past elements in other blocks
+    #          puts "Ignoring structure #{struct.name}"
+    #          Structure.seek_next(file)
+    #        end
+    #      end
+    #    end
+    #  end
+    #
+    def Structure.read_each_header(file)
+      while (Record.peek(file).type == GRT_BGNSTR) do
+        yield Structure.read_header(file)
+      end
+    end
+
+    #
+    # Reads from the given file handle until a ENDSTR record is met (presumably
+    # to a BGNSTR or ENDLIB record.  This effectively "skips" past all elements
+    # within a structure and prepares the file handle to read the next
+    # structure in the file (or ENDLIB if at the end of the GDSII library).
+    # See Structure#read_each_header for an example.  The new file position is
+    # returned.
+    #
+    # Compare this with Element#read_each which accomplishes the same thing
+    # but instead yields each element as it is read from the file.
+    #
+    def Structure.seek_next(file)
+      Record.read_each(file) do |record|
+        break file.pos if record.is_endstr?
+      end
+      nil
+    end
+    
+    #
+    # Writes only the header portion of the Structure to a file (no elements).
+    # This is useful when streamlined writing is desired (for better
+    # performance or when writing GDSII as another GDSII is being read).  Be
+    # sure to either:
+    #
+    # 1. Call #write_footer after writing the header and any Element
+    # objects.  Also be sure to wrap this around Library#write_header and
+    # Library#write_footer; Or
+    # 2. Pass a block whereupon the footer will automatically be added after
+    # the block is processed.
+    #
+    # See Library#write_header for an example.
+    #
+    def write_header(file)
+      # alter the BNF to exclude Elements and ENDSTR; then write to file
+      # according to the modified BNF
+      alt_bnf = BnfSpec.new(*Structure.bnf_spec.bnf_items[0..-3])
+      self.write(file, alt_bnf)
+
+      # if block is given, then yield to that block and then write the
+      # footer afterwards
+      if block_given?
+        yield
+        self.write_footer(file)
+      end
+    end
+
+    #
+    # Writes only the Structure footer (just ENDSTR record) to file.  To be
+    # used with #write_header.
+    #
+    def write_footer(file)
+      Record.new(GRT_ENDSTR).write(file)
+    end
+  
+    #####################
+    ## PRIVATE METHODS ##
+    #####################
+    
+    private
+    
+    # Used by #create_time and #modify_time
+    def update_times()
+      if create_time and modify_time
+        self.bgnstr = build_time(create_time) + build_time(modify_time)
+      else
+        self.bgnstr = nil
+      end
+    end
+   
+  end
+
+  ############################################################################
+
+  #
+  # Class to hold a collection of Structure objects.  This is used in the
+  # Library class BNF.
+  #
+  class Structures < Group
+
+    include Access::EnumerableGroup
+    
+    #
+    # Structures BNF description:
+    #   
+    #  <structures> ::= {<structure>}*
+    #  <structure>  ::= {<boundary> | <path> | <sref> | <aref> |
+    #                   <text> | <node> | <box>}  {<property>}*  ENDEL
+    #
+    self.bnf_spec = BnfSpec.new(
+      BnfItem.new(Structure, true, true)
+    )
+
+    #
+    # Create an Structures object.
+    #
+    def initialize(structures=[])
+      super()
+      @records[Structure] = @list = structures
+    end
+    
+  end
+
+  
+end