{"id":9003,"library":"gdstk","title":"GDSII Tool Kit (gdstk)","description":"gdstk is a C++/Python library designed for the creation and manipulation of GDSII and OASIS files, commonly used in microelectronics design. It serves as a modern successor to the Gdspy library, offering key features such as Boolean operations, polygon offsetting, and efficient point-in-polygon queries. The current version is 1.0.0, with an irregular release cadence, focusing on robust geometric operations for CAD layouts. [1, 3, 7]","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/heitzmann/gdstk","tags":["EDA","GDSII","OASIS","layout","CAD","chip design"],"install":[{"cmd":"pip install gdstk","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for file compression/decompression in GDSII/OASIS files.","package":"zlib","optional":false},{"reason":"Required for geometric computations, specifically convex hulls and other operations.","package":"qhull","optional":false},{"reason":"Used for numerical operations and array handling within the Python interface.","package":"numpy","optional":false}],"imports":[{"note":"The entire library is typically imported as 'gdstk'.","symbol":"gdstk","correct":"import gdstk"},{"note":"Commonly used classes like Cell, Library, and Polygon are accessed directly as attributes of the 'gdstk' module.","symbol":"gdstk.Cell","correct":"cell = gdstk.Cell('my_cell')"}],"quickstart":{"code":"import gdstk\n\n# Create a new library\nlib = gdstk.Library()\n\n# Create a new cell and add it to the library\ncell = lib.new_cell('FIRST')\n\n# Create a rectangle and add it to the cell\nrectangle = gdstk.rectangle((0, 0), (2, 2), layer=1, datatype=0)\ncell.add(rectangle)\n\n# Create a polygon from vertices and add it to the cell\npolygon_points = [(3, 0), (5, 2), (5, 0)]\npolygon = gdstk.Polygon(polygon_points, layer=2)\ncell.add(polygon)\n\n# Save the library to a GDSII file\nlib.write_gds('first.gds')\n\nprint(\"Generated first.gds with a rectangle and a polygon.\")","lang":"python","description":"This quickstart creates a simple GDSII file named 'first.gds' containing a library with a single cell named 'FIRST'. This cell contains a rectangle on layer 1 and a triangle (polygon) on layer 2. It demonstrates the basic steps of creating a library, adding a cell, adding geometric shapes, and writing the output to a GDSII file. [6, 9]"},"warnings":[{"fix":"When writing GDSII files, set the `max_points` argument in `lib.write_gds(..., max_points=199)` to ensure polygons are fractured if they exceed this limit, ensuring compatibility with older GDSII readers. Alternatively, verify target tool chain supports modern GDSII.","message":"Older GDSII formats have a hard limit of 199 vertices per polygon. While gdstk supports modern GDSII which often ignores this, generated files for older systems might fail to open or render incorrectly if this limit is exceeded. [6]","severity":"gotcha","affected_versions":"<=1.0.0"},{"fix":"Be aware that complex paths might be converted to polygons upon saving. Use `gdstk.boolean` and `gdstk.offset` operations carefully to manage complex geometries and ensure they conform to GDSII's weakly simple polygon definition.","message":"GDSII files only support 'weakly simple' polygons (segments can intersect but not cross). Complex shapes with holes or self-intersecting boundaries are not directly supported as GDSII paths and might be stored as polygonal objects, losing path information. [6]","severity":"gotcha","affected_versions":"<=1.0.0"},{"fix":"Where possible, collect all polygons into lists and perform boolean operations on entire lists of polygons at once. This allows `gdstk` to optimize the underlying C++ computations. For example, `gdstk.boolean(list_of_polygons_1, list_of_polygons_2, 'or')`.","message":"Performing boolean operations (`gdstk.boolean`) inside a Python loop for many individual polygons can be significantly slower than expected compared to batch processing or native CAD tools. This is a common performance bottleneck. [11]","severity":"gotcha","affected_versions":"<=1.0.0"},{"fix":"Verify the integrity of OASIS files after read/write cycles, especially with complex or high-volume designs, by comparing with original files or performing design rule checks. Monitor GitHub issues for updates and consider upgrading to versions with specific fixes for OASIS file handling.","message":"Some users have reported issues with OASIS files losing paths or containing missing shapes after being read and then written back by gdstk, potentially leading to DRC errors in production flows. [12]","severity":"breaking","affected_versions":"0.9.x, 1.0.0 (potentially resolved in future minor updates for 1.0.0)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"To access cells by name, convert `lib.cells` to a dictionary or iterate through the list. Example: `cells_by_name = {c.name: c for c in lib.cells}; my_cell = cells_by_name['CELL_NAME']` or `for cell in lib.cells: if cell.name == 'CELL_NAME': my_cell = cell; break`.","cause":"Attempting to access elements of a GDSII/OASIS library (e.g., cells) using square brackets directly on the `Library.cells` attribute, which is a list, not a dictionary. `lib.cells` returns a list of Cell objects. [5]","error":"TypeError: 'builtin_function_or_method' object is not subscriptable"},{"fix":"Ensure the GDSII file is valid and not corrupted. Try opening it with a different GDSII viewer (e.g., KLayout) to confirm its integrity. If generated by another tool, check that tool's output settings.","cause":"The GDSII file being read is either malformed, corrupted, or not a valid GDSII format, preventing gdstk from parsing it correctly.","error":"gdstk.gdstk.GdsError: Invalid GDSII file or corrupted stream."},{"fix":"Always provide non-negative integer values for `layer` and `datatype` parameters when creating GDSII elements. For example, `gdstk.rectangle((0,0), (1,1), layer=0, datatype=0)`.","cause":"Layer or datatype arguments to geometric functions (e.g., `gdstk.rectangle`, `gdstk.Polygon`) were provided with `None` or a non-integer value.","error":"ValueError: Layer or datatype must be a non-negative integer."}]}