# 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.

## 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 (`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`

  `elements`
  `flatten`(single_layer=None, single_datatype=None, single_texttype=None)

    Flatten all `CellReference` and `CellArray` elements in this cell into real polygons and labels, 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. single_datatype – If not `None`, all labels will be transfered to the texttype 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_labels`(depth=None)

    Returns a list with a copy of the labels in this cell.

    Parameters: | depth (integer or `None`) – If not `None`, defines from how many reference levels to retrieve labels from.
    Returns: | out – List containing the labels in this cell and its references.
    Return type: | list of `Label`

  `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 will 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

  `labels`
  `name`
  `remove_labels`(test)

    Remove labels from this cell.

    The function or callable `test` is called for each label in the cell. If its return value evaluates to `True`, the corresponding label is removed from the cell.

    Parameters: | test (callable) – Test function to query whether a label should be removed. The function is called with the label as the only argument.
    Returns: | out – This cell.
    Return type: | `Cell`

    Examples

    Remove labels in layer 1:

        >>> cell.remove_labels(lambda lbl: lbl.layer == 1)

  `remove_polygons`(test)

    Remove polygons from this cell.

    The function or callable `test` is called for each polygon in the cell. If its return value evaluates to `True`, the corresponding polygon is removed from the cell.

    Parameters: | test (callable) – Test function to query whether a polygon should be removed. The function is called with arguments: `(points, layer, datatype)`
    Returns: | out – This cell.
    Return type: | `Cell`

    Examples

    Remove polygons in layer 1:

        >>> cell.remove_polygons(lambda pts, layer, datatype:
        ...                      layer == 1)

    Remove polygons with negative x coordinates:

        >>> cell.remove_polygons(lambda pts, layer, datatype:
        ...                      any(pts[:, 0] < 0))

  `to_gds`(multiplier, timestamp=None)

    Convert this cell to a GDSII structure.

    Parameters: | multiplier (number) – A number that multiplies all dimensions written in the GDSII structure. timestamp (datetime object) – Sets the GDSII timestamp. If `None`, the current time is used.
    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_labels`(depth=None)

    Returns a list of labels created by this reference.

    Parameters: | depth (integer or `None`) – If not `None`, defines from how many reference levels to retrieve labels from.
    Returns: | out – List containing the labels in this cell and its references.
    Return type: | list of `Label`

  `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

  `magnification`
  `origin`
  `ref_cell`
  `rotation`
  `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`

  `x_reflection`

### 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

  `columns`
  `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_labels`(depth=None)

    Returns a list of labels created by this reference.

    Parameters: | depth (integer or `None`) – If not `None`, defines from how many reference levels to retrieve labels from.
    Returns: | out – List containing the labels in this cell and its references.
    Return type: | list of `Label`

  `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

  `magnification`
  `origin`
  `ref_cell`
  `rotation`
  `rows`
  `spacing`
  `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`

  `x_reflection`

### GdsLibrary

class `gdspy.``GdsLibrary`(name='library', infile=None, unit=1e-06, precision=1e-09, **kwargs)

  Bases: `object`

  GDSII library (file).

  Represent a GDSII library containing a dictionary of cells.

  Parameters: | name (string) – Name of the GDSII library. Ignored if a name is defined in infile. infile (file or string) – GDSII stream file (or path) to be imported. It must be opened for reading in binary format. kwargs (keyword arguments) – Arguments passed to read_gds.
  Variables: | name (string) – Name of the GDSII library. cell_dict (dictionary) – Dictionary of cells in this library, indexed by name. 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).

  `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, units='skip', 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. units ({'convert', 'import', 'skip'}) – Controls how to scale and use the units in the imported file. `'convert'`: the imported geometry is scaled to this library units. `'import'`: the unit and precision in this library are replaced by those from the imported file. `'skip'`: the imported geometry is not scaled and units are not replaced; the geometry is imported in the user units of the file. 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.
    Returns: | out – This object.
    Return type: | `GdsLibrary`

    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, timestamp=None)

    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. timestamp (datetime object) – Sets the GDSII timestamp. If `None`, the current time is used.

    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, timestamp=None)

  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). timestamp (datetime object) – Sets the GDSII timestamp. If `None`, the current time is used.

  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).

### gdsii_hash

`gdspy.``gdsii_hash`(filename, engine=None)

  Calculate the a hash value for a GDSII file.

  The hash is generated based only on the contents of the cells in the GDSII library, ignoring any timestamp records present in the file structure.

  Parameters: | filename (string) – Full path to the GDSII file. engine (hashlib-like engine) – The engine that executes the hashing algorithm. It must provide the methods `update` and `hexdigest` as defined in the hashlib module. If `None`, the dafault `hashlib.sha1()` is used.
  Returns: | out – The hash correponding to the library contents in hex format.
  Return type: | string

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