########################################################################
##                                                                    ##
##  Copyright 2009-2013 Lucas Heitzmann Gabrielli                     ##
##                                                                    ##
##  This file is part of gdspy.                                       ##
##                                                                    ##
##  gdspy is free software: you can redistribute it and/or modify it  ##
##  under the terms of the GNU General Public License as published    ##
##  by the Free Software Foundation, either version 3 of the          ##
##  License, or any later version.                                    ##
##                                                                    ##
##  gdspy is distributed in the hope that it will be useful, but      ##
##  WITHOUT ANY WARRANTY; without even the implied warranty of        ##
##  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the     ##
##  GNU General Public License for more details.                      ##
##                                                                    ##
##  You should have received a copy of the GNU General Public         ##
##  License along with gdspy.  If not, see                            ##
##  <http://www.gnu.org/licenses/>.                                   ##
##                                                                    ##
########################################################################

Version: 0.5
Author: Lucas Heitzmann Gabrielli


1. Installation

You will need to have the Python programming language installed in your
system (tested in version 2.7, but 2.6 should work as well):
  * http://www.python.org/

You will also need the modules numpy, and, optionally, Python Imaging
Library (needed only if you want to output the geometry to an image
file):
  * http://numpy.scipy.org/
  * http://www.pythonware.com/products/pil/index.htm

To install gdspy execute the following command in the folder where you
uncompressed the gdspy distribution:

    python setup.py install

Windows users will need a development environment to compile the boolean
extension module (automatically performed by the install command above).
For 32-bit systems, Microsoft Visual C++ 2008 Express Edition has been
used successfully.


2. Usage

The file gdspy-sample.py is a sample script to show the features
provided by this module.  The complete module reference can be found in
the html folder or online at:
  * http://gdspy.sourceforge.net/


3. History of changes

Version 0.5 (October 30, 2013) -- NOT COMPATIBLE WITH PREVIOUS VERSIONS
  * Major LayoutViewer improvements (not backwards compatible).
  * The layer argument has been repositioned in the argument list in all
  functions (not backwards compatible).
  * Renamed argument by_layer to by_spec (not backwards compatible).
  * Error is raised for polygons with more vertices than possible in the
  GDSII format.
  * Removed the global state variable for default datatype.
  * Added get_datatypes to Cell.
  * Added argument single_datatype to Cell.flatten.
  * Removed gds_image and dropped the optional PIL dependency.

Version 0.4.1 (June 5, 2013)
  * Added argument axis_offset to Path.segment allowing creation of
  asymmetric tapers.
  * Added missing argument x_reflection to Label.
  * Created a global state variable to override the default datatype.
  * Bug fix in CellArray.get_bounding_box (thanks to George McLean for the
  fix)

Version 0.4 (October 25, 2012)
  * Cell.get_bounding_box returns None for empty cells.
  * Added a cache for bounding boxes for faster computation, especially for
  references.
  * Added support for text elements with Label class.
  * Improved the emission of warnings.
  * Added a tolerance parameter to boolean.
  * Added better print descriptions to classes.
  * Bug fixes in boolean involving results with multiple holes.

Version 0.3.1 (May 24, 2012)
  * Bug fix in the fracture method for PolygonSet.

Version 0.3a (May 03, 2012)
  * Bug fix in the fracture method for Polygon and PolygonSet.

Version 0.3 (April 25, 2012) - Thanks to Gene Hilton for the contributions
  * Support for Python 3.2 and 2.7
  * Further improvements to the boolean function via caching.
  * Added methods get_bounding_box and get_layers to Cell.
  * Added method top_level to GdsImport.
  * Added support for importing GDSII path elements.
  * Added an argument to control the verbosity of the import function.
  * Layer -1 (referenced cells) sent to the bottom of the layer list by
  default in LayoutViewer
  * The text and background of the layer list in LayoutViewer now reflect
  the colors of the outlines and canvas backgroung.
  * Changed default background color in LayoutViewer

Version 0.2.9 (December 14, 2011)
  * Attribute Cell.cell_list changed to Cell.cell_dict.
  * Changed the signature of the operation in boolean.
  * Order of cells passed to LayoutViewer is now respected in the GUI.
  * Complete re-implementation of the boolean function as a C extension
  for improved performance.
  * Removed precision argument in boolean. It is fixed at 1e-13 for
  merging close points, otherwise machine precision is used.
  * gds_image now accepts cell names as input.
  * Added optional argument depth to get_polygons
  * Added option to convert layers and datatypes in imported GDSII cells.
  * Argument exclude_layers from LayoutViewer changed to hidden_layers
  and behavior changed accordingly. 
  * Shift + Right-clicking on a layer the layer-list of LayoutViewer
  hides/unhides all other layers.
  * New buttons to zoom in and out in LayoutViewer.
  * Referenced cells below a configurable depth are now represented by
  theirs bounding boxes in LayoutViewer.

Version 0.2.8 (June 21, 2011)
  * GDSII file import.
  * GDSII output automatically include required referenced cells.
  * gds_print also accepts file name as input.
  * Outlines are visible by default in LayoutViewer.
  * Added background color option in LayoutViewer.
  * Right-clicking on the layer list hides/unhides the target layer in
  LayoutViewer.
  * Cell.cell_list is now a dictionary indexed by name, instead of a
  list.
  * Added option to exclude created cells from the global list of cells
  kept in Cell.cell_list.
  * CellReference and CellArray accept name of cells as input.
  * Submodules lost their own __version__.

Version 0.2.7 (April 2, 2011)
  * Bug fixed in the boolean, which affected the way polygons with more
  vertices then the maximum were fractured.
  * gds_image accepts an extra color argument for the image background.
  * Screenshots takes from LayoutViewer have the same background color
  as the viewer.
  * The functions boolean and slice now also accept CellReference and
  CellArray as input.
  * Added the method fracture to Polygon and PolygonSet to automatically
  slice polygons into parts with a predefined maximal number of
  vertices.
  * Added the method fillet to Polygon and PolygonSet to round corners
  of polygons.

Version 0.2.6 (February 28, 2011)
  * When saving a GDSII file, ValueError is raised if cell names are
  duplicated.
  * Save screenshot from LayoutViewer.
  * gds_image accepts cells, instead of lists.
  * Outlines supported by gds_image.
  * LayoutViewer stores bounding box information for all visited layers
  to save rendering time.

Version 0.2.5 (December 10, 2010)
  * Empty cells no longer break the LayoutViewer.
  * Removed the gds_view function, superseded by the LayoutViewer, along
  with all dependencies to matplotlib.
  * Fixed a bug in boolean which affected polygons with series of
  collinear vertices.
  * Added a function to slice polygons along straight lines parallel to
  an axis.

Version 0.2.4 (September 04, 2010)
  * Added shortcut to Extents in LayoutViewer: 'Home' or 'a' keys.
  * PolygonSet is the new base class for Round, which might bring some
  incompatibility issues with older scripts.
  * Round elements, PolyPath, L1Path, and Path arc, turn and parametric
  sections are now automatically fractured into pieces defined by a
  maximal number of points.
  * Default value for max_points in boolean changed to 199.
  * Removed the flag to disable the warning about polygons with more
  than 199 vertices.  The warning is shown only for Polygon and
  PolygonSet.
  * Fixed a bug impeding parallel parametric paths to change their
  distance to each other.

Version 0.2.3 (August 09, 2010)
  * Added the PolyPath class to easily create paths with sharp corners.
  * Allow None as item in the colors parameter of LayoutViewer to make
  layers invisible.
  * Added color outline mode to LayoutViewer (change outline color with
  the shift key pressed)
  * Increased the scroll region of the LayoutViewer canvas
  * Added a fast scroll mode: control + drag 2nd mouse button
  * Created a new sample script

Version 0.2.2 (July 29, 2010)
  * Changed the cursor inside LayoutViewer to standard arrow.
  * Fixed bugs with the windows version of LayoutViewer (mouse wheel and
  ruler tool).

Version 0.2.1 (July 29, 2010)
  * Bug fix: gds_image displays an error message instead of crashing
  when PIL is not found.
  * Added class LayoutViewer, which uses Tkinter (included in all python
  distributions) to display the GDSII layout with better controls then
  the gds_view function. This eliminates the matplotlib requirement for
  the viewer functionality.
  * New layer colors extending layers 0 to 63.

Version 0.2.0 (July 19, 2010)
  * Fixed a bug on the turn method of Path.
  * Fixed a bug on the boolean function that would give an error when
  not using Polygon or PolygonSet as input objects.
  * Added the method get_polygons to Cell, CellReference and CellArray.
  * Added a copy method to Cell.
  * Added a flatten method to Cell to remove references (or array
  references) to other cells.
  * Fracture boolean output polygons based on the number of vertices to
  respect the 199 GDSII limit.
                                       
Version 0.1.9 (June 04, 2010)
  * Added L1Path class for Manhattan geometry (L1 norm) paths.

Version 0.1.8 (May 10, 2010)
  * Removed the argument fill from the function gds_view and added a
  more flexible one: style.
  * Fixed a rounding error on the boolean operator affecting polygons
  with holes.
  * Added a rotate method to PolygonSet.
  * Added a warning when PolygonSet has more than 199 points
  * Added a flag to disable the warning about polygons with more than
  199 points.
  * Added a turn method to Path, which is easier to use than arc.
  * Added a direction attribute to Path to keep the information used by
  the segment and turn methods.

Version 0.1.7 (April 12, 2010)
  * New visualization option: save the geometry directly to an image
  file (lower memory use).
  * New functionality added: boolean operations on polygons (polygon
  clipping).
  * All classes were adapted to work with the boolean operations.
  * The attribute size in the initializer of class Text does not have a
  default value any longer.
  * The name of the argument format in the function gds_view was changed
  to fill (to avoid confusion with the built-in function format).

Version 0.1.6 (December 15,  2009)
  * Sample script now include comments and creates an easier to
  understand GDSII example.
  * Improved floating point to integer rounding, which fixes the unit
  errors at the last digit of the precision in the GDSII file.
  * Fixed the font for character 5.
  * Added a flag to gds_view to avoid the automatic call to
  matplotlib.pyplot.show()
  * In gds_view, if a layer number is greater than the number of formats
  defined, the formats are cycled.

Version 0.1.5a (November 15, 2009)
  * Class Text correctly interprets '\n' and '\t' characters.
  * Better documentation format, using the Sphinx engine and the numpy
  format.

Version 0.1.4 (October 5, 2009)
  * Class Text re-written with a different font with no overlaps and
  correct size.

Version 0.1.3a (July 29 2009)
  * Fixed the function to_gds of class Rectangle.

Version 0.1.3 (July 27, 2009)
  * Added the datatype field to all elements of the GDSII structure.

Version 0.1.2 (July 11, 2009)
  * Added the gds_view function to display the GDSII structure using the
  matplotlib module.
  * Fixed a rotation bug in the CellArray class.
  * Module published under the GNU General Public License (GPL)

Version 0.1.1 (May 12, 2009)
  * Added attribute cell_list to class Cell to hold a list of all Cell
  created.
  * Set the default argument cells=Cell.cell_list in the function
  gds_print.
  * Added member to calculate the area for each element type.
  * Added member to calculate the total area of a Cell or the area by
  layer.
  * Included the possibility of creating objects in user-defined units,
  not only nanometers.

Version 0.1.0 (May 1, 2009)
  * Initial release.
