GDSII for Python
================

Gdspy is a Python  module for creating GDSII stream files, usually
CAD layouts. 

It includes a layout viewer for the geometries created, and it can also
be used to import and merge GDSII files.

.. note::

    As of version 0.5 gdspy is **NOT** backwards compatible with older
    versions.  The main incompatibility is that the ``layer`` argument
    in all applicable classes and functions has been moved to a position
    just before ``datatype`` in the argument list.  The ``LayoutViewer``
    has also been extensively improved.  See the changes history for all
    compatibility changes.


Requirements
------------

* `Python <http://www.python.org>`_ -- tested with 2.7 and 3.3
* `Numpy <http://numpy.scipy.org>`_

On Windows we encourage the use of the `WinPython
<http://code.google.com/p/winpython/>`_ distribution, which takes care
Numpy dependency and comes with "batteries included".

Download and Install
--------------------

There are 3 options for installing gdspy, listed below.


Option 1 (Windows only)
***********************

Use the binary installer from `gdspy at Sourceforge
<http://sourceforge.net/projects/gdspy/>`_. Make sure to download the
installer that matches your installed Python version and your machine
architecture.

.. note::

   If you used the easy_install method below to install earlier versions
   of gdspy you have to run ``easy_install -mxN gdspy`` to remove the
   older version from the Python path before installing the new one.


Option 2
********

If you have `setuptools <http://pypi.python.org/pypi/setuptools>`_
installed, just use (``sudo`` if necessary)::

   easy_install -U gdspy

.. note::

   Windows users will need a development environment setup for Python
   extensions, such as Microsoft Visual C++ 2008 Express Edition.


Option 3
********

Download the source files from `gdspy at Sourceforge
<http://sourceforge.net/projects/gdspy/>`_ and extract it to any folder.

Execute the following command in a terminal window from within the
extracted folder (``sudo`` if necessary)::

   python setup.py install


Documentation
-------------

.. toctree::
   :maxdepth: 2

   tutorial
   main
   io

Changes History 
---------------

**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 ``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.
