ruby-gdsii 1.0.0

data/bin/rgds2rb

@@ -0,0 +1,99 @@
+#!/usr/bin/env ruby
+##############################################################################
+#
+# == gds2rb.rb
+#
+# Reads a GDSII file and then generates the corresponding Ruby code necessary
+# to recreate the GDSII.
+#
+# === Author
+#
+# James D. Masters (james.d.masters@gmail.com)
+#
+# === History
+#
+# * 03/26/2007 (jdm): Initial version
+#
+##############################################################################
+
+require 'getoptlong'
+require 'gdsii/record.rb'
+include Gdsii
+
+usage = "
+Reads a GDSII file and then generates the corresponding Ruby code necessary
+to recreate the GDSII.
+
+Usage: gds2rb.rb [options] <gds-file> <rb-file> <gds-out-file>
+
+Options:
+
+ -s, --structs    Specify structure(s) in a space separated list to process.
+                  The default behavior is to process all structures.
+ -f, --force      Force existing Ruby file if it exists.
+ -h, --help       Displays this usage message.
+
+"
+
+# Get command-line arguments
+structs = []
+force = false
+
+opts = GetoptLong.new(
+  ['--structs',     '-s', GetoptLong::OPTIONAL_ARGUMENT],
+  ['--force',       '-f', GetoptLong::OPTIONAL_ARGUMENT|GetoptLong::NO_ARGUMENT],
+  ['--help',        '-h', GetoptLong::OPTIONAL_ARGUMENT|GetoptLong::NO_ARGUMENT]
+)
+
+opts.each do |option, argument|
+  case option
+  when '--help'      : abort usage
+  when '--structs'   : structs = argument.split(/\s+/)
+  when '--force'     : force = true
+  end
+end
+
+# Get GDSII file directory from command line
+gds_file, rb_file, gds_out_file = ARGV
+unless (gds_file and rb_file and gds_out_file)
+  abort usage
+end
+
+# Fail if the Ruby file exists and force isn't enabled
+if File.exists? rb_file and not force
+  abort "\nRuby file exists: #{rb_file} (use -f or --force to ignore)"
+end
+
+space_before = [GRT_BOUNDARY, GRT_PATH, GRT_TEXT, GRT_NODE,
+                GRT_BOX, GRT_ENDSTR, GRT_ENDLIB]
+
+# Open Ruby file for write
+File.open(rb_file, 'w') do |rbf|
+  # Write the header information
+  rbf.puts "require 'gdsii'"
+  rbf.puts
+  rbf.puts "File.open('#{gds_out_file}', 'wb') do |outf|"
+  rbf.puts
+  
+  # Read the GDSII file and write out resulting GDSII files
+  File.open(gds_file, 'rb') do |inf|
+    # Read each record in the GDSII file
+    Record.read_each(inf) do |record|
+      rbf.puts if space_before.member?(record.type)
+      if record.type == GRT_BGNSTR
+        strname = Record.peek(inf).data_value
+        rbf.puts
+        rbf.puts '  ' + '#' * 76
+        rbf.puts '  # STRUCTURE: ' + strname.to_s
+        rbf.puts '  ' + '#' * 76
+        rbf.puts
+      end
+      rbf.puts "  Gdsii::Record.new(Gdsii::GRT_#{record.name}, #{record.data_value.inspect}).write(outf)"
+    end
+  end
+  
+  rbf.puts
+  rbf.puts "end"
+end
+
+

data/lib/gdsii.rb

@@ -0,0 +1,137 @@
+#
+# There are two approaches to interacting with a GDSII file using this module:
+#
+# 1. At the record level (low-level)
+# 2. At the record group level (high-level)
+#
+#
+# = Approach #1
+#
+# (See Record class for details)
+#
+# Interaction at the record level is intended for streamlined file processing
+# where the author has a good knowledge of the GDSII structure.  A typical
+# usage might be to streamline changes to a GDSII file such as changing
+# bus bit characters on a node name from <> to [] format (see the samples
+# directory of this library installation for an example).  Here is a simple
+# way to dump the all strings in a GDSII file using the Record class:
+#
+#  require 'gdsii'
+#
+#  # Note: 'rb' is required for DOS/Windows compatibility
+#  File.open('mydesign.gds', 'rb') do |file|
+#    Gds::Record.read_each(file) do |record|
+#      puts record.data[0] if record.is_string?
+#    end
+#  end
+#
+#
+# = Approach #2
+#
+# (See Group, Library, Structure, Element, Boundary, Path, Text, SRef, ARef,
+# Node, and Box classes for details)
+#
+# The second approach offers a high-level interface to the GDSII format which
+# might be ideal in cases where the author may not be familiar with the details
+# of the GDSII format.  This example will write a small transistor cell:
+#
+#  require 'gdsii'
+#  
+#  Gdsii::Library.new('MYLIB.DB') do |lib|
+#    
+#    Gdsii::Structure.new('trans') do |struct|
+#      
+#      # Diffusion layer
+#      struct.add Gdsii::Boundary.new(1, 0, [-2000,0, -2000,4000, 2000,4000, 2000,0, -2000,0])
+#  
+#      # Gate layer... add a property labling as "gate"
+#      Gdsii::Path.new(2, 0, 0, 800, [0,-600, 0,4600]) do |path|
+#        path.add Gdsii::Property.new(1, 'gate')
+#        struct.add path
+#      end
+#  
+#      # Add this structure to the library
+#      lib.add struct
+#
+#    end
+#  
+#    # Write the library to a file
+#    lib.write('trans.gds')
+#    
+#  end
+# 
+#
+# = Important notes
+#
+# == Look at inherited and mixed-in methods
+#
+# The high-level classes in this GDSII library rely heavily upon inheritance
+# and mixed-in modules to reduce code.  When reviewing documentation, be sure
+# to be aware of methods defined implicitly through class inheritance and
+# through Module#include and Module#extend.
+#
+# == Use 'b' during R/W of files
+#
+# Be sure to always use the 'b' read/write attribute when reading and writing
+# GDSII files to ensure that read/write happens properly on DOS/Windows
+# systems.  For example (see IO#open for more details):
+#
+#  inf = File.open('mydesign.gds', 'rb')
+#  outf = File.open('mydesign.gds', 'wb')
+#
+# == Improving performance
+#
+# The low-level GDSII methods will offer significantly better GDSII read/write
+# performance as compared to the high-level methods.  For most streamlined
+# manipulations of GDSII files, the low-level methods are probably the best
+# option.  For smaller GDSII files or when code re-use/readability is
+# important, then the performance hit with the high-level methods may not be
+# a concern.
+#
+# Here are some benchmarks using both low and high level methods to read and
+# immediately write a GDSII file:
+#
+# * GDSII file size: 7 MB
+# * WinXP machine: Intel(R) Pentium(R) M (Centrino) 1.6 Ghz @ 1 GB RAM
+# * Linux machine (SuSE): 2x Intel(R) Pentium(R) 4 3.4 Ghz @ 1 GB RAM
+#
+#                           Linux      WinXP
+#                          -------    -------
+#  High-level methods:      8m 45s    11m 23s
+#  Low-level methods:       0m 45s     1m 29s
+#
+module Gdsii
+  # Empty module here as a placeholder for rdoc
+end
+
+# Require byte order, constants, and mixins
+require 'gdsii/byte_order.rb'
+require 'gdsii/record/consts.rb'
+require 'gdsii/mixins.rb'
+
+# Require low-level files (data types and records)
+require 'gdsii/record/datatypes/bitarray.rb'
+require 'gdsii/record/datatypes/int4.rb'
+require 'gdsii/record/datatypes/nodata.rb'
+require 'gdsii/record/datatypes/real4.rb'
+require 'gdsii/record/datatypes/ascii.rb'
+require 'gdsii/record/datatypes/data.rb'
+require 'gdsii/record/datatypes/real8.rb'
+require 'gdsii/record/datatypes/int2.rb'
+require 'gdsii/record.rb'
+
+# Require high-level files
+require 'gdsii/bnf.rb'
+require 'gdsii/group.rb'
+require 'gdsii/element.rb'
+require 'gdsii/property.rb'
+require 'gdsii/strans.rb'
+require 'gdsii/boundary.rb'
+require 'gdsii/path.rb'
+require 'gdsii/text.rb'
+require 'gdsii/box.rb'
+require 'gdsii/node.rb'
+require 'gdsii/sref.rb'
+require 'gdsii/aref.rb'
+require 'gdsii/structure.rb'
+require 'gdsii/library.rb'

data/lib/gdsii/aref.rb

@@ -0,0 +1,243 @@
+require 'gdsii/element'
+require 'gdsii/group'
+require 'gdsii/strans'
+
+module Gdsii
+
+  #
+  # Represents a GDSII structure array reference (ARef) element.  Most
+  # methods are from Element or from the various included Access module
+  # methods.
+  #
+  class ARef < Element
+
+    # Include various record accessors
+    include Access::ELFlags
+    include Access::Plex
+    include Access::StransGroup
+    include Access::Sname
+
+    #
+    # ARef BNF description:
+    #
+    #  <aref> ::= AREF [ELFLAGS] [PLEX] SNAME [<strans>] COLROW XY
+    #
+    self.bnf_spec = BnfSpec.new(
+      BnfItem.new(GRT_AREF),
+      BnfItem.new(GRT_ELFLAGS, true),
+      BnfItem.new(GRT_PLEX, true),
+      BnfItem.new(GRT_SNAME),
+      BnfItem.new(Strans, true),
+      BnfItem.new(GRT_COLROW),
+      BnfItem.new(GRT_XY),
+      BnfItem.new(Properties, true),
+      BnfItem.new(GRT_ENDEL)
+    )
+    
+    #
+    # Create a new structure array reference (ARef) to be used within a
+    # Structure object.  The structure name is a String or anything that has
+    # a #to_s method.  The ref_xy is a *single* set of x/y coordinates
+    # that the placement of the ARef (note this is _NOT_ the same as the
+    # XY record for ARef - see #xy_record for more details).  The colrow is an
+    # array of a number of columns and rows respectively.  The colrow_spc is
+    # an array of spacing values for columns and rows respectively.
+    #
+    #  # Create an ARef at coordinates (0,0) with 2 columns and 8 rows.  The
+    #  # spacing between columns is 200 units and between rows is 300 units.
+    #  aref = ARef.new('array', [0,0], [2,8], [200, 300])
+    #
+    # Note, the #ref_xy, #column_space, and #row_space are required.
+    # See #xy_record for details.
+    #
+    def initialize(sname=nil, ref_xy=nil, colrow=nil, colrow_spc=nil)
+      super()      
+      @records[GRT_AREF] = Record.new(GRT_AREF)
+      self.sname = sname unless sname.nil?
+      self.colrow = colrow unless colrow.nil?
+      self.ref_xy = ref_xy unless ref_xy.nil?
+      self.column_space = colrow_spc[0] if colrow_spc.class == Array
+      self.row_space = colrow_spc[1] if colrow_spc.class == Array
+      yield self if block_given?
+    end
+
+    #
+    # Get the colrow record (returns Record)
+    #
+    def colrow_record() @records.get(GRT_COLROW); end
+
+    #
+    # Get the colrow array of numbers (returns 2-element Array of Fixnum)
+    # where the first number is columns and the second is rows [col, row].
+    # Alternatively, the #rows and #columns method may also be used.
+    #
+    #  aref.colrow  #=> [2, 8]
+    #
+    def colrow() @records.get_data(GRT_COLROW); end
+
+    #
+    # Set the colrow number (see #colrow for format details).  Alternatively,
+    # the #rows= and #columns= methods may be used.
+    #
+    #  aref.colrow = [2, 8]
+    #
+    def colrow=(val) @records.set(GRT_COLROW, val); end   
+
+    #
+    # Set the columns number in the COLROW record (Fixnum)
+    #
+    #  aref.columns = 2
+    #
+    def columns=(val)
+      if (cr=colrow)
+        @records.set(GRT_COLROW, [val, cr[1]])
+      else
+        @records.set(GRT_COLROW, [val, nil])
+      end
+    end
+  	  
+    #
+    # Get the columns number in the COLROW record (returns Fixnum)
+    #
+    #  aref.columns  #=> 2
+    #
+    def columns()
+      (cr=@records.get(GRT_COLROW)) ? cr[0] : nil
+    end
+    
+    #
+    # Set the rows number in the COLROW record
+    #
+    #  aref.rows = 8
+    #
+    def rows=(val)
+      if (cr=colrow)
+        @records.set(GRT_COLROW, [cr[0], val])
+      else
+        @records.set(GRT_COLROW, [nil, val])
+      end
+    end
+  	  
+    #
+    # Get the rows number in the COLROW record (returns Fixnum)
+    #
+    #  aref.rows  #=> 8
+    #
+    def rows()
+      (cr=@records.get(GRT_COLROW)) ? cr[1] : nil
+    end
+
+    #
+    # Defines the placement XY coordinate for this ARef.  See #xy_record for
+    # details on how the XY record is used in ARef.
+    #
+    #  aref.ref_xy = [10, 20]
+    #
+    def ref_xy=(val)
+      if val.class == Array and val.length == 2
+        @ref_xy = val
+        update_xy
+      else
+        raise TypeError, "Expected Array of length 2"
+      end
+    end
+
+    #
+    # Returns the placement XY coordinate for this ARef.  See #xy_record for
+    # details on how the XY record is used in ARef.
+    #
+    #  aref.ref_xy  #=> [10, 20]
+    #
+    def ref_xy(); @ref_xy; end
+
+    #
+    # Defines the column spacing (in units) for this ARef.  Internally this
+    # value is stored in the XY record.  See #xy_record for details on how the
+    # XY record is used in ARef.
+    #
+    #  aref.column_space = 200
+    #
+    def column_space=(val)
+      @column_space = val
+      update_xy
+    end
+
+    #
+    # Returns the placement XY coordinate for this ARef.  See #xy_record for
+    # details on how the XY record is used in ARef.
+    #
+    #  aref.column_space  #=> 200
+    #
+    def column_space(); @column_space; end
+
+    #
+    # Defines the row spacing (in units) for this ARef.  Internally this
+    # value is stored in the XY record.  See #xy_record for details on how the
+    # XY record is used in ARef.
+    #
+    #  aref.row_space = 300
+    #
+    def row_space=(val)
+      @row_space = val
+      update_xy
+    end
+
+    #
+    # Returns the placement XY coordinate for this ARef.  See #xy_record for
+    # details on how the XY record is used in ARef.
+    #
+    #  aref.row_space  #=> 300
+    #
+    def row_space(); @row_space; end
+
+    #
+    # Gets the ARef record for XY.
+    #
+    # Important note on the XY record (i.e. #xy, #xy_record): the GDSII
+    # specification calls for exactly 3 XY records for ARef.  Because of this
+    # specification, there is no #xy= method available for the ARef class.
+    # Instead, the XY record is created dynamically when all three of these
+    # components are set.  Otherwise, the XY record will not exist.
+    #
+    # The XY record data specification is as follows:
+    #
+    # * 1:  ARef reference point (#ref_xy)
+    # * 2:  column_space*columns+reference_x (#ref_xy, #columns, and #column_space)
+    # * 3:  row_space*rows+reference_y (#ref_xy, #rows, and #row_space)
+    #
+    def xy_record() @records.get(GRT_XY); end
+
+    #
+    # Gets an xy point record (returns an Array).  Note, it is probably easier
+    # to use #ref_xy, #column_space, or #row_space instead; see #xy_record for
+    # details on how the XY record is used for ARef.
+    #
+    def xy() @records.get_data(GRT_XY); end
+
+    
+    #####################
+    ## PRIVATE METHODS ##
+    #####################
+    
+    private
+
+    #
+    # Update the GRT_XY record if all prerequisites are met (#ref_xy,
+    # #column_space, and #row_space).
+    #
+    def update_xy()
+      if ((pxy=ref_xy) and (cs=column_space) and (rs=row_space) and (cr=colrow).length == 2)
+        # see #xy_record for an explanation of this formula
+        array = pxy + [pxy[0]+cs*cr[0], pxy[1]] + [pxy[0], pxy[1]+rs*cr[1]]
+        @records.set(GRT_XY, array)
+      else
+        @records.set(GRT_XY, nil)
+      end
+    end
+
+  end
+end
+
+
+
+