GDSII Library

gdspy is a Python module that allows the creation of GDSII stream files.

Many features of the GDSII format are implemented, such as cell references and arrays, but the support for fonts is quite limited. Text is only available through polygonal objects.

If the Python Imaging Library is installed, it can be used to output the geometry created to an image file.

Classes

Cell

class gdspy.Cell(name, exclude_from_current=False)

Bases: object

Collection of elements, both geometric objects and references to other cells.

Parameters:
  • name (string) – The name of the cell.
  • exclude_from_current (bool) – If True, the cell will not be automatically included in the current library.
Variables:
  • name (string) – The name of this cell.
  • elements (list) – List of cell elements (Polygon, PolygonSet, CellReference, CellArray).
  • labels (list) – List of Label.
add(element)

Add a new element or list of elements to this cell.

Parameters:element (object, list) – The element or list of elements to be inserted in this cell.
Returns:out – This cell.
Return type:Cell
area(by_spec=False)

Calculate the total area of the elements on this cell, including cell references and arrays.

Parameters:by_spec (bool) – If True, the return value is a dictionary with the areas of each individual pair (layer, datatype).
Returns:out – Area of this cell.
Return type:number, dictionary
copy(name, exclude_from_current=False, deep_copy=False)

Creates a copy of this cell.

Parameters:
  • name (string) – The name of the cell.
  • exclude_from_current (bool) – If True, the cell will not be included in the global list of cells maintained by gdspy.
  • deep_copy (bool) – If False, the new cell will contain only references to the existing elements. If True, copies of all elements are also created.
Returns:

out – The new copy of this cell.

Return type:

Cell

flatten(single_layer=None, single_datatype=None)

Flatten all CellReference and CellArray elements in this cell into real polygons, instead of references.

Parameters:
  • single_layer (integer or None) – If not None, all polygons will be transfered to the layer indicated by this number.
  • single_datatype (integer or None) – If not None, all polygons will be transfered to the datatype indicated by this number.
Returns:

out – This cell.

Return type:

Cell

get_bounding_box()

Returns the bounding box for this cell.

Returns:out – Bounding box of this cell [[x_min, y_min], [x_max, y_max]], or None if the cell is empty.
Return type:Numpy array[2,2] or None
get_datatypes()

Returns a set of datatypes in this cell.

Returns:out – Set of the datatypes used in this cell.
Return type:set
get_dependencies(recursive=False)

Returns a list of the cells included in this cell as references.

Parameters:recursive (bool) – If True returns cascading dependencies.
Returns:out – List of the cells referenced by this cell.
Return type:set of Cell
get_layers()

Returns a set of layers in this cell.

Returns:out – Set of the layers used in this cell.
Return type:set
get_polygons(by_spec=False, depth=None)

Returns a list of polygons in this cell.

Parameters:
  • by_spec (bool) – If True, the return value is a dictionary with the polygons of each individual pair (layer, datatype).
  • depth (integer or None) – If not None, defines from how many reference levels to retrieve polygons. References below this level will result in a bounding box. If by_spec is True the key wil be the name of this cell.
Returns:

out – List containing the coordinates of the vertices of each polygon, or dictionary with the list of polygons (if by_spec is True).

Return type:

list of array-like[N][2] or dictionary

to_gds(multiplier)

Convert this cell to a GDSII structure.

Parameters:multiplier (number) – A number that multiplies all dimensions written in the GDSII structure.
Returns:out – The GDSII binary string that represents this cell.
Return type:string

CellReference

class gdspy.CellReference(ref_cell, origin=(0, 0), rotation=None, magnification=None, x_reflection=False, ignore_missing=False)

Bases: object

Simple reference to an existing cell.

Parameters:
  • ref_cell (Cell or string) – The referenced cell or its name.
  • origin (array-like[2]) – Position where the reference is inserted.
  • rotation (number) – Angle of rotation of the reference (in degrees).
  • magnification (number) – Magnification factor for the reference.
  • x_reflection (bool) – If True the reference is reflected parallel to the x direction before being rotated.
  • ignore_missing (bool) – If False a warning is issued when the referenced cell is not found.
area(by_spec=False)

Calculate the total area of the referenced cell with the magnification factor included.

Parameters:by_spec (bool) – If True, the return value is a dictionary with the areas of each individual pair (layer, datatype).
Returns:out – Area of this cell.
Return type:number, dictionary
get_bounding_box()

Returns the bounding box for this reference.

Returns:out – Bounding box of this cell [[x_min, y_min], [x_max, y_max]], or None if the cell is empty.
Return type:Numpy array[2,2] or None
get_polygons(by_spec=False, depth=None)

Returns a list of polygons created by this reference.

Parameters:
  • by_spec (bool) – If True, the return value is a dictionary with the polygons of each individual pair (layer, datatype).
  • depth (integer or None) – If not None, defines from how many reference levels to retrieve polygons. References below this level will result in a bounding box. If by_spec is True the key will be the name of the referenced cell.
Returns:

out – List containing the coordinates of the vertices of each polygon, or dictionary with the list of polygons (if by_spec is True).

Return type:

list of array-like[N][2] or dictionary

to_gds(multiplier)

Convert this object to a GDSII element.

Parameters:multiplier (number) – A number that multiplies all dimensions written in the GDSII element.
Returns:out – The GDSII binary string that represents this object.
Return type:string
translate(dx, dy)

Move the reference from one place to another

Parameters:
  • dx (float) – distance to move in the x-direction
  • dy (float) – distance to move in the y-direction
Returns:

out – This object.

Return type:

CellReference

CellArray

class gdspy.CellArray(ref_cell, columns, rows, spacing, origin=(0, 0), rotation=None, magnification=None, x_reflection=False, ignore_missing=False)

Bases: object

Multiple references to an existing cell in an array format.

Parameters:
  • ref_cell (Cell or string) – The referenced cell or its name.
  • columns (positive integer) – Number of columns in the array.
  • rows (positive integer) – Number of columns in the array.
  • spacing (array-like[2]) – distances between adjacent columns and adjacent rows.
  • origin (array-like[2]) – Position where the cell is inserted.
  • rotation (number) – Angle of rotation of the reference (in degrees).
  • magnification (number) – Magnification factor for the reference.
  • x_reflection (bool) – If True, the reference is reflected parallel to the x direction before being rotated.
  • ignore_missing (bool) – If False a warning is issued when the referenced cell is not found.
area(by_spec=False)

Calculate the total area of the cell array with the magnification factor included.

Parameters:by_spec (bool) – If True, the return value is a dictionary with the areas of each individual pair (layer, datatype).
Returns:out – Area of this cell.
Return type:number, dictionary
get_bounding_box()

Returns the bounding box for this reference.

Returns:out – Bounding box of this cell [[x_min, y_min], [x_max, y_max]], or None if the cell is empty.
Return type:Numpy array[2,2] or None
get_polygons(by_spec=False, depth=None)

Returns a list of polygons created by this reference.

Parameters:
  • by_spec (bool) – If True, the return value is a dictionary with the polygons of each individual pair (layer, datatype).
  • depth (integer or None) – If not None, defines from how many reference levels to retrieve polygons. References below this level will result in a bounding box. If by_spec is True the key will be name of the referenced cell.
Returns:

out – List containing the coordinates of the vertices of each polygon, or dictionary with the list of polygons (if by_spec is True).

Return type:

list of array-like[N][2] or dictionary

to_gds(multiplier)

Convert this object to a GDSII element.

Parameters:multiplier (number) – A number that multiplies all dimensions written in the GDSII element.
Returns:out – The GDSII binary string that represents this object.
Return type:string
translate(dx, dy)

Move the reference from one place to another

Parameters:
  • dx (float) – distance to move in the x-direction
  • dy (float) – distance to move in the y-direction
Returns:

out – This object.

Return type:

CellArray

GdsLibrary

class gdspy.GdsLibrary(name='library')

Bases: object

GDSII library (file).

Represent a GDSII library containing a dictionary of cells.

Parameters:

name (string) – Name of the GDSII library.

Variables:
  • name (string) – Name of the GDSII library.
  • cell_dict (dictionary) – Dictionary of cells in this library, indexed by name.
add(cell, overwrite_duplicate=False)

Add one or more cells to the library.

Parameters:
  • cell (Cell of list of Cell) – Cells to be included in the library.
  • overwrite_duplicate (bool) – If True an existing cell with the same name in the library will be overwritten.
Returns:

out – This object.

Return type:

GdsLibrary

extract(cell)

Extract a cell from the this GDSII file and include it in the current global library, including referenced dependencies.

Parameters:cell (Cell or string) – Cell or name of the cell to be extracted from the imported file. Referenced cells will be automatically extracted as well.
Returns:out – The extracted cell.
Return type:Cell
read_gds(infile, unit=None, rename={}, layers={}, datatypes={}, texttypes={})

Read a GDSII file into this library.

Parameters:
  • infile (file or string) – GDSII stream file (or path) to be imported. It must be opened for reading in binary format.
  • unit (number) – Unit (in meters) to use for the imported structures. If None, the units used to create the GDSII file will be used.
  • rename (dictionary) – Dictionary used to rename the imported cells. Keys and values must be strings.
  • layers (dictionary) – Dictionary used to convert the layers in the imported cells. Keys and values must be integers.
  • datatypes (dictionary) – Dictionary used to convert the datatypes in the imported cells. Keys and values must be integers.
  • texttypes (dictionary) – Dictionary used to convert the text types in the imported cells. Keys and values must be integers.

Notes

Not all features from the GDSII specification are currently supported. A warning will be produced if any unsuported features are found in the imported file.

top_level()

Output the top level cells from the GDSII data.

Top level cells are those that are not referenced by any other cells.

Returns:out – List of top level cells.
Return type:list
write_gds(outfile, cells=None, unit=1e-06, precision=1e-09)

Write the GDSII library to a file.

The dimensions actually written on the GDSII file will be the dimensions of the objects created times the ratio unit/precision. For example, if a circle with radius 1.5 is created and we set unit=1.0e-6 (1 um) and precision=1.0e-9 (1 nm), the radius of the circle will be 1.5 um and the GDSII file will contain the dimension 1500 nm.

Parameters:
  • outfile (file or string) – The file (or path) where the GDSII stream will be written. It must be opened for writing operations in binary format.
  • cells (array-like) – The list of cells or cell names to be included in the library. If None, all cells are used.
  • unit (number) – Unit size for the objects in the library (in meters).
  • precision (number) – Precision for the dimensions of the objects in the library (in meters).

Notes

Only the specified cells are written. The user is responsible for ensuring all cell dependencies are satisfied.

GdsWriter

class gdspy.GdsWriter(outfile, name='library', unit=1e-06, precision=1e-09)

Bases: object

GDSII strem library writer.

The dimensions actually written on the GDSII file will be the dimensions of the objects created times the ratio unit/precision. For example, if a circle with radius 1.5 is created and we set unit=1.0e-6 (1 um) and precision=1.0e-9 (1 nm), the radius of the circle will be 1.5 um and the GDSII file will contain the dimension 1500 nm.

Parameters:
  • outfile (file or string) – The file (or path) where the GDSII stream will be written. It must be opened for writing operations in binary format.
  • name (string) – Name of the GDSII library (file).
  • unit (number) – Unit size for the objects in the library (in meters).
  • precision (number) – Precision for the dimensions of the objects in the library (in meters).

Notes

This class can be used for incremental output of the geometry in case the complete layout is too large to be kept in memory all at once.

Examples

>>> writer = gdspy.GdsWriter('out-file.gds', unit=1.0e-6, precision=1.0e-9)
>>> for i in range(10):
...     cell = gdspy.Cell('C{}'.format(i), True)
...     # Add the contents of this cell...
...     writer.write_cell(cell)
...     # Clear the memory: erase Cell objects and any other objects
...     # that won't be needed.
...     del cell
>>> writer.close()
close()

Finalize the GDSII stream library.

write_cell(cell)

Write the specified cell to the file.

Parameters:cell (Cell) – Cell to be written.

Notes

Only the specified cell is written. Dependencies must be manually included.

Returns:out – This object.
Return type:GdsWriter

LayoutViewer

class gdspy.LayoutViewer(library=None, cells=None, hidden_types=[], depth=0, color={}, pattern={}, background='#202020', width=800, height=600)

Provide a GUI where the layout can be viewed.

The view can be scrolled vertically with the mouse wheel, and horizontally by holding the shift key and using the mouse wheel. Dragging the 2nd mouse button also scrolls the view, and if control is held down, it scrolls 10 times faster.

You can zoom in or out using control plus the mouse wheel, or drag a rectangle on the window with the 1st mouse button to zoom into that area.

A ruler is available by clicking the 1st mouse button anywhere on the view and moving the mouse around. The distance is shown in the status area.

Double-clicking on any polygon gives some information about it.

Color and pattern for each layer/datatype specification can be changed by left and right clicking on the icon in the layer/datatype list. Left and right clicking the text label changes the visibility.

Parameters:
  • library (GdsLibrary) – GDSII library to display. If None, the current library is used.
  • cells (Cell, string or array-like) – The array of cells to be included in the view. If None, all cells listed in the current library are used.
  • hidden_types (array-like) – The array of tuples (layer, datatype) to start in hidden state.
  • depth (integer) – Initial depth of referenced cells to be displayed.
  • color (dictionary) – Dictionary of colors for each tuple (layer, datatype). The colors must be strings in the format #rrggbb. A value with key default will be used as default color.
  • pattern (dictionary) – Dictionary of patterns for each tuple (layer, datatype). The patterns must be integers between 0 and 9, inclusive. A value with key default will be used as default pattern.
  • background (string) – Canvas background color in the format #rrggbb.
  • width (integer) – Horizontal size of the viewer canvas.
  • height (integer) – Vertical size of the viewer canvas.

Examples

White background, filled shapes:

>>> gdspy.LayoutViewer(pattern={'default':8}, background='#FFFFFF')

No filling, black color for layer 0, datatype 1, automatic for others:

>>> gdspy.LayoutViewer(pattern={'default':9}, color={(0,1):'#000000'})

Functions

write_gds

gdspy.write_gds(outfile, cells=None, name='library', unit=1e-06, precision=1e-09)

Write the current GDSII library to a file.

The dimensions actually written on the GDSII file will be the dimensions of the objects created times the ratio unit/precision. For example, if a circle with radius 1.5 is created and we set unit=1.0e-6 (1 um) and precision=1.0e-9 (1 nm), the radius of the circle will be 1.5 um and the GDSII file will contain the dimension 1500 nm.

Parameters:
  • outfile (file or string) – The file (or path) where the GDSII stream will be written. It must be opened for writing operations in binary format.
  • cells (array-like) – The list of cells or cell names to be included in the library. If None, all cells are used.
  • name (string) – Name of the GDSII library.
  • unit (number) – Unit size for the objects in the library (in meters).
  • precision (number) – Precision for the dimensions of the objects in the library (in meters).

Attributes

gdspy.current_library = <gdspy.GdsLibrary object>

Current GdsLibrary instance for automatic creation of GDSII files.

This variable can be freely overwritten by the user with a new instance of GdsLibrary.