Read

Functions to create Device objects from various data sources.

This module provides utilities for loading device geometries from multiple formats, including image files, numpy arrays, and GDS layout files. All functions return Device objects with optional preprocessing capabilities.

from_gds(gds_path, cell_name, gds_layer=(1, 0), bounds=None, **kwargs)

Create a Device from a GDS cell.

Parameters:

Name	Type	Description	Default
gds_path	str	The file path to the GDS file.	required
cell_name	str	The name of the cell within the GDS file to be converted into a Device object.	required
gds_layer	tuple[int, int]	A tuple specifying the layer and datatype to be used from the GDS file. Defaults to (1, 0).	(1, 0)
bounds	Optional[tuple[tuple[float, float], tuple[float, float]]]	A tuple specifying the bounds for cropping the cell before conversion, formatted as ((min_x, min_y), (max_x, max_y)), in units of the GDS file. If None, the entire cell is used.	None
**kwargs	Any	Additional keyword arguments to be passed to the Device constructor.	{}

Returns:

Type	Description
Device	A Device object representing the specified cell from the GDS file, after processing based on the specified layer.

Source code in prefab/read.py

def from_gds(
    gds_path: str,
    cell_name: str,
    gds_layer: tuple[int, int] = (1, 0),
    bounds: tuple[tuple[float, float], tuple[float, float]] | None = None,
    **kwargs: Any,
) -> Device:
    """
    Create a Device from a GDS cell.

    Parameters
    ----------
    gds_path : str
        The file path to the GDS file.
    cell_name : str
        The name of the cell within the GDS file to be converted into a Device object.
    gds_layer : tuple[int, int]
        A tuple specifying the layer and datatype to be used from the GDS file. Defaults
        to (1, 0).
    bounds : Optional[tuple[tuple[float, float], tuple[float, float]]]
        A tuple specifying the bounds for cropping the cell before conversion, formatted
        as ((min_x, min_y), (max_x, max_y)), in units of the GDS file. If None, the
        entire cell is used.
    **kwargs
        Additional keyword arguments to be passed to the Device constructor.

    Returns
    -------
    Device
        A Device object representing the specified cell from the GDS file, after
        processing based on the specified layer.
    """
    gdstk_library = gdstk.read_gds(gds_path)
    gdstk_cell = cast(gdstk.Cell, gdstk_library[cell_name])  # pyright: ignore[reportIndexIssue]
    device_array = _gdstk_to_device_array(
        gdstk_cell=gdstk_cell, gds_layer=gds_layer, bounds=bounds
    )
    return Device(device_array=device_array, **kwargs)

from_gdstk(gdstk_cell, gds_layer=(1, 0), bounds=None, **kwargs)

Create a Device from a gdstk cell.

Parameters:

Name	Type	Description	Default
gdstk_cell	Cell	The gdstk.Cell object to be converted into a Device object.	required
gds_layer	tuple[int, int]	A tuple specifying the layer and datatype to be used from the cell. Defaults to (1, 0).	(1, 0)
bounds	Optional[tuple[tuple[float, float], tuple[float, float]]]	A tuple specifying the bounds for cropping the cell before conversion, formatted as ((min_x, min_y), (max_x, max_y)), in units of the GDS cell. If None, the entire cell is used.	None
**kwargs	Any	Additional keyword arguments to be passed to the Device constructor.	{}

Returns:

Type	Description
Device	A Device object representing the gdstk.Cell, after processing based on the specified layer.

Source code in prefab/read.py

def from_gdstk(
    gdstk_cell: gdstk.Cell,
    gds_layer: tuple[int, int] = (1, 0),
    bounds: tuple[tuple[float, float], tuple[float, float]] | None = None,
    **kwargs: Any,
) -> Device:
    """
    Create a Device from a gdstk cell.

    Parameters
    ----------
    gdstk_cell : gdstk.Cell
        The gdstk.Cell object to be converted into a Device object.
    gds_layer : tuple[int, int]
        A tuple specifying the layer and datatype to be used from the cell. Defaults to
        (1, 0).
    bounds : Optional[tuple[tuple[float, float], tuple[float, float]]]
        A tuple specifying the bounds for cropping the cell before conversion, formatted
        as ((min_x, min_y), (max_x, max_y)), in units of the GDS cell. If None, the
        entire cell is used.
    **kwargs
        Additional keyword arguments to be passed to the Device constructor.

    Returns
    -------
    Device
        A Device object representing the gdstk.Cell, after processing based on the
        specified layer.
    """
    device_array = _gdstk_to_device_array(
        gdstk_cell=gdstk_cell, gds_layer=gds_layer, bounds=bounds
    )
    return Device(device_array=device_array, **kwargs)

from_img(img_path, img_width_nm=None, binarize=True, **kwargs)

Create a Device from an image file.

Parameters:

Name	Type	Description	Default
img_path	str	The path to the image file to be converted into a Device object.	required
img_width_nm	Optional[int]	The width of the image in nanometers. If specified, the Device will be resized to this width while maintaining aspect ratio. If None, no resizing is performed.	None
binarize	bool	If True, the image will be binarized (converted to binary values) before conversion to a Device object. This is useful for processing grayscale images into binary masks. Defaults to True.	True
**kwargs	Any	Additional keyword arguments to be passed to the Device constructor.	{}

Returns:

Type	Description
Device	A Device object representing the processed image, after optional resizing and binarization.

Source code in prefab/read.py

def from_img(
    img_path: str, img_width_nm: int | None = None, binarize: bool = True, **kwargs: Any
) -> Device:
    """
    Create a Device from an image file.

    Parameters
    ----------
    img_path : str
        The path to the image file to be converted into a Device object.
    img_width_nm : Optional[int]
        The width of the image in nanometers. If specified, the Device will be resized
        to this width while maintaining aspect ratio. If None, no resizing is performed.
    binarize : bool
        If True, the image will be binarized (converted to binary values) before
        conversion to a Device object. This is useful for processing grayscale images
        into binary masks. Defaults to True.
    **kwargs
        Additional keyword arguments to be passed to the Device constructor.

    Returns
    -------
    Device
        A Device object representing the processed image, after optional resizing and
        binarization.
    """
    device_array = cv2.imread(img_path, flags=cv2.IMREAD_GRAYSCALE) / 255
    if img_width_nm is not None:
        resolution = img_width_nm / device_array.shape[1]
        device_array = cv2.resize(
            device_array, dsize=(0, 0), fx=resolution, fy=resolution
        )
    device_array = _binarize_if_needed(device_array, binarize)
    return Device(device_array=device_array, **kwargs)

from_ndarray(ndarray, resolution=1.0, binarize=True, **kwargs)

Create a Device from an ndarray.

Parameters:

Name	Type	Description	Default
ndarray	ndarray	The input array representing the device geometry.	required
resolution	float	The resolution of the ndarray in nanometers per pixel, defaulting to 1.0 nm per pixel. If specified, the input array will be resized based on this resolution to match the desired physical size.	1.0
binarize	bool	If True, the input array will be binarized (converted to binary values) before conversion to a Device object. This is useful for processing grayscale arrays into binary masks. Defaults to True.	True
**kwargs	Any	Additional keyword arguments to be passed to the Device constructor.	{}

Returns:

Type	Description
Device	A Device object representing the input array, after resizing and binarization.

Source code in prefab/read.py

def from_ndarray(
    ndarray: np.ndarray[Any, Any],
    resolution: float = 1.0,
    binarize: bool = True,
    **kwargs: Any,
) -> Device:
    """
    Create a Device from an ndarray.

    Parameters
    ----------
    ndarray : np.ndarray
        The input array representing the device geometry.
    resolution : float
        The resolution of the ndarray in nanometers per pixel, defaulting to 1.0 nm per
        pixel. If specified, the input array will be resized based on this resolution to
        match the desired physical size.
    binarize : bool
        If True, the input array will be binarized (converted to binary values) before
        conversion to a Device object. This is useful for processing grayscale arrays
        into binary masks. Defaults to True.
    **kwargs
        Additional keyword arguments to be passed to the Device constructor.

    Returns
    -------
    Device
        A Device object representing the input array, after resizing and binarization.
    """
    device_array = ndarray
    if resolution != 1.0:
        device_array = cv2.resize(
            device_array, dsize=(0, 0), fx=resolution, fy=resolution
        )
    device_array = _binarize_if_needed(device_array, binarize)
    return Device(device_array=device_array, **kwargs)