Python package for EDA / lithography mask design.
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
jan b33c632569 cache base64encode calls since it's actually fairly slow 1 month ago
examples remove todo 6 months ago
masque cache base64encode calls since it's actually fairly slow 1 month ago
.flake8 style and type fixes (per flake8) 4 years ago
.gitignore add .oas.gz to .gitignore 4 years ago Add license 8 years ago add note about github mirror 3 weeks ago
pyproject.toml update required python version 6 months ago


Masque is a Python module for designing lithography masks.

The general idea is to implement something resembling the GDSII file-format, but with some vectorized element types (eg. circles, not just polygons) and the ability to output to multiple formats.



  • python >= 3.11
  • numpy
  • klamath (used for GDSII i/o)

Optional requirements:

  • ezdxf (DXF i/o): ezdxf
  • oasis (OASIS i/o): fatamorgana
  • svg (SVG output): svgwrite
  • visualization (shape plotting): matplotlib
  • text (Text shape): matplotlib, freetype

Install with pip:

pip install 'masque[oasis,dxf,svg,visualization,text]'


A layout consists of a hierarchy of Patterns stored in a single Library. Each Pattern can contain Refs pointing at other patterns, Shapes, Labels, and Ports.

masque departs from several "classic" GDSII paradigms:

  • A Pattern object does not store its own name. A name is only assigned when the pattern is placed into a Library, which is effectively a name->Pattern mapping.
  • Layer info for Shapess and Labels is not stored in the individual shape and label objects. Instead, the layer is determined by the key for the container dict (e.g. pattern.shapes[layer]).
    • This simplifies many common tasks: filtering Shapes by layer, remapping layers, and checking if a layer is empty.
    • Technically, this allows reusing the same shape or label object across multiple layers. This isn't part of the standard workflow since a mixture of single-use and multi-use shapes could be confusing.
    • This is similar to the approach used in KLayout
  • Ref target names are also determined in the key of the container dict (e.g. pattern.refs[target_name]).
    • This similarly simplifies filtering Refs by target name, updating to a new target, and checking if a given Pattern is referenced.
  • Pattern names are set by their containing Library and are not stored in the Pattern objects.
    • This guarantees that there are no duplicate pattern names within any given Library.
    • Likewise, enumerating all the names (and all the Patterns) in a Library is straightforward.
  • Each Ref, Shape, or Label can be repeated multiple times by attaching a repetition object to it.
    • This is similar to how OASIS reptitions are handled, and provides extra flexibility over the GDSII approach of only allowing arrays through AREF (Ref + repetition).
  • Labels do not have an orientation or presentation
    • This is in line with how they are used in practice, and how they are represented in OASIS.
  • Non-polygonal Shapes are allowed. For example, elliptical arcs are a basic shape type.
    • This enables compatibility with OASIS (e.g. circles) and other formats.
    • Shapes provide a .to_polygons() method for GDSII compatibility.
  • Most coordinate values are stored as 64-bit floats internally.
    • 1 earth radii in nanometers (6e15) is still represented without approximation (53 bit mantissa -> 2^53 > 9e15)
    • Operations that would otherwise clip/round on are still represented approximately.
    • Memory usage is usually dominated by other Python overhead.
  • Pattern objects also contain Port information, which can be used to "snap" together multiple sub-components by matching up the requested port offsets and rotations.
    • Port rotations are defined as counter-clockwise angles from the +x axis.
    • Ports point into the interior of their associated device.
    • Port rotations may be None in the case of non-oriented ports.
    • Ports have a ptype string which is compared in order to catch mismatched connections at build time.
    • Ports can be exported into/imported from Labels stored directly in the layout, editable from standard tools (e.g. KLayout). A default format is provided.

In one important way, masque stays very orthodox: References are accomplished by listing the target's name, not its Pattern object.

  • The main downside of this is that any operations that traverse the hierarchy require both the Pattern and the Library which is contains its reference targets.
  • This guarantees that names within a Library remain unique at all times.
    • Since this can be tedious in cases where you don't actually care about the name of a pattern, patterns whose names start with SINGLE_USE_PREFIX (default: an underscore) may be silently renamed in order to maintain uniqueness. See masque.library.SINGLE_USE_PREFIX, masque.library._rename_patterns(), and ILibrary.add() for more details.
  • Having all patterns accessible through the Library avoids having to perform a tree traversal for every operation which needs to touch all Pattern objects (e.g. deleting a layer everywhere or scaling all patterns).
  • Since Pattern doesn't know its own name, you can't create a reference by passing in a Pattern object -- you need to know its name.
  • You can reference a Pattern before it is created, so long as you have already decided on its name.
  • Functions like and Pattern.plug() need to receive a pattern's name in order to create a reference, but they also need to access the pattern's ports.
    • One way to provide this data is through an Abstract, generated via Library.abstract() or through a Library.abstract_view().
    • Another way is use or Builder.plug(), which automatically creates an Abstract from its internally-referenced Library.


  • Library: A collection of named cells. OASIS or GDS "library" or file.
  • Tree: Any {name: pattern} mapping which has only one topcell.
  • Pattern: A collection of geometry, text labels, and reference to other patterns. OASIS or GDS "Cell", DXF "Block".
  • Ref: A reference to another pattern. GDS "AREF/SREF", OASIS "Placement".
  • Shape: Individual geometric entity. OASIS or GDS "Geometry element", DXF "LWPolyline" or "Polyline".
  • repetition: Repetition operation. OASIS "repetition". GDS "AREF" is a Ref combined with a Grid repetition.
  • Label: Text label. Not rendered into geometry. OASIS, GDS, DXF "Text".
  • annotation: Additional metadata. OASIS or GDS "property".

Syntax, shorthand, and design patterns

Most syntax and behavior should follow normal python conventions. There are a few exceptions, either meant to catch common mistakes or to provide a shorthand for common operations:

Library objects don't allow overwriting already-existing patterns

library['mycell'] = pattern0
library['mycell'] = pattern1   # Error! 'mycell' already exists and can't be overwritten
del library['mycell']          # We can explicitly delete it
library['mycell'] = pattern1   # And now it's ok to assign a new value
library.delete('mycell')       # This also deletes all refs pointing to 'mycell' by default

Insert a newly-made hierarchical pattern (with children) into a layout

# Let's say we have a function which returns a new library containing one topcell (and possibly children)
tree = make_tree(...)

# To reference this cell in our layout, we have to add all its children to our `library` first:
top_name =              # get the name of the topcell
name_mapping = library.add(tree)   # add all patterns from `tree`, renaming elgible conflicting patterns
new_name = name_mapping.get(top_name, top_name)    # get the new name for the cell (in case it was auto-renamed)
my_pattern.ref(new_name, ...)       # instantiate the cell

# This can be accomplished as follows
new_name = library << tree       # Add `tree` into `library` and return the top cell's new name
my_pattern.ref(new_name, ...)       # instantiate the cell

# In practice, you may do lots of
my_pattern.ref(lib << make_tree(...), ...)

# With a `Builder` and `place()`/`plug()` the `lib <<` portion can be implicit:
my_builder = Builder(library=lib, ...)

We can also use this shorthand to quickly add and reference a single flat (as yet un-named) pattern:

anonymous_pattern = Pattern(...)
my_pattern.ref(lib << {'_tentative_name': anonymous_pattern}, ...)

Place a hierarchical pattern into a layout, preserving its port info

# As above, we have a function that makes a new library containing one topcell (and possibly children)
tree = make_tree(...)

# We need to go get its port info to `place()` it into our existing layout,
new_name = library << tree          # Add the tree to the library and return its name (see `<<` above)
abstract = library.abstract(tree)   # An `Abstract` stores a pattern's name and its ports (but no geometry), ...)

# With shorthand,
abstract = library <= tree, ...)

# or << make_tree(...), ...)

### Quickly add geometry, labels, or refs:
The long form for adding elements can be overly verbose:
my_pattern.shapes[layer].append(Polygon(vertices, ...))
my_pattern.labels[layer] += [Label('my text')]
my_pattern.refs[target_name].append(Ref(offset=..., ...))

There is shorthand for the most common elements:

my_pattern.polygon(layer=layer, vertices=vertices, ...)
my_pattern.rect(layer=layer, xctr=..., xmin=..., ymax=..., ly=...)  # rectangle; pick 4 of 6 constraints
my_pattern.rect(layer=layer, ymin=..., ymax=..., xctr=..., lx=...)
my_pattern.label(layer, 'my_text')
my_pattern.ref(target_name, offset=..., ...)

Accessing ports

# Square brackets pull from the underlying `.ports` dict:
assert pattern['input'] is pattern.ports['input']

# And you can use them to read multiple ports at once:
assert pattern[('input', 'output')] == {
    'input': pattern.ports['input'],
    'output': pattern.ports['output'],

# But you shouldn't use them for anything except reading
pattern['input'] = Port(...)   # Error!
has_input = ('input' in pattern)   # Error!

Building patterns

library = Library(...)
my_pattern_name, my_pattern = library.mkpat(some_name_generator())
def _make_my_subpattern() -> str:
    #   This function can draw from the outer scope (e.g. `library`) but will not pollute the outer scope
    # (e.g. the variable `subpattern` will not be accessible from outside the function; you must load it
    # from within `library`).
    subpattern_name, subpattern = library.mkpat(...)
    return subpattern_name
my_pattern.ref(_make_my_subpattern(), offset=..., ...)


  • Better interface for polygon operations (e.g. with pyclipper)
    • de-embedding
    • boolean ops
  • Tests tests tests
  • check renderpather
  • pather and renderpather examples