prefab 1.3.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

prefab/read.py

@@ -1,22 +1,52 @@
-"""Functions to create a Device from various data sources."""
+"""
+Functions to create Device objects from various data sources.
 
-import re
-from typing import TYPE_CHECKING, Optional
+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 typing import Any, cast
 
 import cv2
 import gdstk
 import numpy as np
 
 from . import geometry
-from .device import BufferSpec, Device
+from .device import Device
+
+# Conversion factor from GDS units (micrometers) to nanometers
+_GDS_UM_TO_NM = 1000
+
+
+def _binarize_if_needed(
+    device_array: np.ndarray[Any, Any], binarize: bool
+) -> np.ndarray[Any, Any]:
+    """
+    Conditionally binarize a device array.
 
-if TYPE_CHECKING:
-    import gdsfactory as gf
-    import tidy3d as td
+    Parameters
+    ----------
+    device_array : np.ndarray
+        The array to potentially binarize.
+    binarize : bool
+        If True, binarize the array using hard thresholding.
+
+    Returns
+    -------
+    np.ndarray
+        The binarized array if binarize is True, otherwise the original array.
+    """
+    if binarize:
+        return geometry.binarize_hard(np.asarray(device_array, dtype=np.float64))
+    return device_array
 
 
 def from_ndarray(
-    ndarray: np.ndarray, resolution: float = 1.0, binarize: bool = True, **kwargs
+    ndarray: np.ndarray[Any, Any],
+    resolution: float = 1.0,
+    binarize: bool = True,
+    **kwargs: Any,
 ) -> Device:
     """
     Create a Device from an ndarray.
@@ -46,13 +76,12 @@ def from_ndarray(
         device_array = cv2.resize(
             device_array, dsize=(0, 0), fx=resolution, fy=resolution
         )
-    if binarize:
-        device_array = geometry.binarize_hard(device_array)
+    device_array = _binarize_if_needed(device_array, binarize)
     return Device(device_array=device_array, **kwargs)
 
 
 def from_img(
-    img_path: str, img_width_nm: Optional[int] = None, binarize: bool = True, **kwargs
+    img_path: str, img_width_nm: int | None = None, binarize: bool = True, **kwargs: Any
 ) -> Device:
     """
     Create a Device from an image file.
@@ -83,8 +112,7 @@ def from_img(
         device_array = cv2.resize(
             device_array, dsize=(0, 0), fx=resolution, fy=resolution
         )
-    if binarize:
-        device_array = geometry.binarize_hard(device_array)
+    device_array = _binarize_if_needed(device_array, binarize)
     return Device(device_array=device_array, **kwargs)
 
 
@@ -92,8 +120,8 @@ def from_gds(
     gds_path: str,
     cell_name: str,
     gds_layer: tuple[int, int] = (1, 0),
-    bounds: Optional[tuple[tuple[float, float], tuple[float, float]]] = None,
-    **kwargs,
+    bounds: tuple[tuple[float, float], tuple[float, float]] | None = None,
+    **kwargs: Any,
 ) -> Device:
     """
     Create a Device from a GDS cell.
@@ -121,7 +149,7 @@ def from_gds(
         processing based on the specified layer.
     """
     gdstk_library = gdstk.read_gds(gds_path)
-    gdstk_cell = gdstk_library[cell_name]  # type: ignore
+    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
     )
@@ -131,9 +159,9 @@ def from_gds(
 def from_gdstk(
     gdstk_cell: gdstk.Cell,
     gds_layer: tuple[int, int] = (1, 0),
-    bounds: Optional[tuple[tuple[float, float], tuple[float, float]]] = None,
-    **kwargs,
-):
+    bounds: tuple[tuple[float, float], tuple[float, float]] | None = None,
+    **kwargs: Any,
+) -> Device:
     """
     Create a Device from a gdstk cell.
 
@@ -144,7 +172,7 @@ def from_gdstk(
     gds_layer : tuple[int, int]
         A tuple specifying the layer and datatype to be used from the cell. Defaults to
         (1, 0).
-    bounds : tuple[tuple[float, float], tuple[float, float]]
+    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.
@@ -166,8 +194,8 @@ def from_gdstk(
 def _gdstk_to_device_array(
     gdstk_cell: gdstk.Cell,
     gds_layer: tuple[int, int] = (1, 0),
-    bounds: Optional[tuple[tuple[float, float], tuple[float, float]]] = None,
-) -> np.ndarray:
+    bounds: tuple[tuple[float, float], tuple[float, float]] | None = None,
+) -> np.ndarray[Any, Any]:
     """
     Convert a gdstk.Cell to a device array.
 
@@ -195,24 +223,24 @@ def _gdstk_to_device_array(
             polygons, position=(bounds[0][1], bounds[1][1]), axis="y"
         )[1]
         bounds = (
-            (int(1000 * bounds[0][0]), int(1000 * bounds[0][1])),
-            (int(1000 * bounds[1][0]), int(1000 * bounds[1][1])),
+            (int(_GDS_UM_TO_NM * bounds[0][0]), int(_GDS_UM_TO_NM * bounds[0][1])),
+            (int(_GDS_UM_TO_NM * bounds[1][0]), int(_GDS_UM_TO_NM * bounds[1][1])),
         )
     else:
         bbox = gdstk_cell.bounding_box()
         if bbox is None:
             raise ValueError("Cell has no geometry, cannot determine bounds.")
         bounds = (
-            (float(1000 * bbox[0][0]), float(1000 * bbox[0][1])),
-            (float(1000 * bbox[1][0]), float(1000 * bbox[1][1])),
+            (float(_GDS_UM_TO_NM * bbox[0][0]), float(_GDS_UM_TO_NM * bbox[0][1])),
+            (float(_GDS_UM_TO_NM * bbox[1][0]), float(_GDS_UM_TO_NM * bbox[1][1])),
         )
     contours = [
         np.array(
             [
                 [
                     [
-                        int(1000 * vertex[0] - bounds[0][0]),
-                        int(1000 * vertex[1] - bounds[0][1]),
+                        int(_GDS_UM_TO_NM * vertex[0] - bounds[0][0]),
+                        int(_GDS_UM_TO_NM * vertex[1] - bounds[0][1]),
                     ]
                 ]
                 for vertex in polygon.points
@@ -224,280 +252,6 @@ def _gdstk_to_device_array(
         (int(bounds[1][1] - bounds[0][1]), int(bounds[1][0] - bounds[0][0])),
         dtype=np.uint8,
     )
-    cv2.fillPoly(img=device_array, pts=contours, color=(1, 1, 1))
+    _ = cv2.fillPoly(device_array, contours, (1,))
     device_array = np.flipud(device_array)
     return device_array
-
-
-def from_gdsfactory(
-    component: "gf.Component",
-    **kwargs,
-) -> Device:
-    """
-    Create a Device from a gdsfactory component.
-
-    Parameters
-    ----------
-    component : gf.Component
-        The gdsfactory component to be converted into a Device object.
-    **kwargs
-        Additional keyword arguments to be passed to the Device constructor.
-
-    Returns
-    -------
-    Device
-        A Device object representing the gdsfactory component.
-
-    Raises
-    ------
-    ImportError
-        If the gdsfactory package is not installed.
-    """
-    try:
-        import gdsfactory as gf  # noqa: F401
-    except ImportError:
-        raise ImportError(
-            "The gdsfactory package is required to use this function; "
-            "try `pip install gdsfactory`."
-        ) from None
-
-    bounds = (
-        (component.xmin * 1000, component.ymin * 1000),
-        (component.xmax * 1000, component.ymax * 1000),
-    )
-
-    polygons = [
-        polygon
-        for polygons_list in component.get_polygons_points().values()
-        for polygon in polygons_list
-    ]
-
-    contours = [
-        np.array(
-            [
-                [[int(1000 * x - bounds[0][0]), int(1000 * y - bounds[0][1])]]
-                for x, y in polygon  # type: ignore
-            ]
-        )
-        for polygon in polygons
-    ]
-
-    device_array = np.zeros(
-        (int(bounds[1][1] - bounds[0][1]), int(bounds[1][0] - bounds[0][0])),
-        dtype=np.uint8,
-    )
-    cv2.fillPoly(img=device_array, pts=contours, color=(1, 1, 1))
-    device_array = np.flipud(device_array)
-    return Device(device_array=device_array, **kwargs)
-
-
-def from_sem(
-    sem_path: str,
-    sem_resolution: Optional[float] = None,
-    sem_resolution_key: Optional[str] = None,
-    binarize: bool = False,
-    bounds: Optional[tuple[tuple[int, int], tuple[int, int]]] = None,
-    **kwargs,
-) -> Device:
-    """
-    Create a Device from a scanning electron microscope (SEM) image file.
-
-    Parameters
-    ----------
-    sem_path : str
-        The file path to the SEM image.
-    sem_resolution : Optional[float]
-        The resolution of the SEM image in nanometers per pixel. If not provided, it
-        will be extracted from the image metadata using the `sem_resolution_key`.
-    sem_resolution_key : Optional[str]
-        The key to look for in the SEM image metadata to extract the resolution.
-        Required if `sem_resolution` is not provided.
-    binarize : bool
-        If True, the SEM image will be binarized (converted to binary values) before
-        conversion to a Device object. This is needed for processing grayscale images
-        into binary masks. Defaults to False.
-    bounds : Optional[tuple[tuple[int, int], tuple[int, int]]]
-        A tuple specifying the bounds in nm for cropping the image before conversion,
-        formatted as ((min_x, min_y), (max_x, max_y)). If None, the entire image is
-        used.
-    **kwargs
-        Additional keyword arguments to be passed to the Device constructor.
-
-    Returns
-    -------
-    Device
-        A Device object representing the processed SEM image.
-
-    Raises
-    ------
-    ValueError
-        If neither `sem_resolution` nor `sem_resolution_key` is provided.
-    """
-    if sem_resolution is None and sem_resolution_key is not None:
-        sem_resolution = get_sem_resolution(sem_path, sem_resolution_key)
-    elif sem_resolution is None:
-        raise ValueError("Either sem_resolution or resolution_key must be provided.")
-
-    device_array = cv2.imread(sem_path, flags=cv2.IMREAD_GRAYSCALE)
-    device_array = cv2.resize(
-        device_array, dsize=(0, 0), fx=sem_resolution, fy=sem_resolution
-    )
-
-    if bounds is not None:
-        pad_left = max(0, -bounds[0][0])
-        pad_right = max(0, bounds[1][0] - device_array.shape[1])
-        pad_bottom = max(0, -bounds[0][1])
-        pad_top = max(0, bounds[1][1] - device_array.shape[0])
-
-        if pad_left or pad_right or pad_top or pad_bottom:
-            device_array = np.pad(
-                device_array,
-                ((pad_top, pad_bottom), (pad_left, pad_right)),
-                mode="constant",
-                constant_values=0,
-            )
-
-        start_x = max(0, bounds[0][0] + pad_left)
-        end_x = min(device_array.shape[1], bounds[1][0] + pad_left)
-        start_y = max(0, device_array.shape[0] - (bounds[1][1] + pad_top))
-        end_y = min(
-            device_array.shape[0], device_array.shape[0] - (bounds[0][1] + pad_top)
-        )
-
-        if start_x >= end_x or start_y >= end_y:
-            raise ValueError(
-                "Invalid bounds resulted in zero-size array: "
-                f"x=[{start_x}, {end_x}], "
-                f"y=[{start_y}, {end_y}]"
-            )
-
-        device_array = device_array[start_y:end_y, start_x:end_x]
-
-    if binarize:
-        device_array = geometry.binarize_sem(device_array)
-
-    buffer_spec = BufferSpec(
-        mode={
-            "top": "none",
-            "bottom": "none",
-            "left": "none",
-            "right": "none",
-        },
-        thickness={
-            "top": 0,
-            "bottom": 0,
-            "left": 0,
-            "right": 0,
-        },
-    )
-    return Device(device_array=device_array, buffer_spec=buffer_spec, **kwargs)
-
-
-def get_sem_resolution(sem_path: str, sem_resolution_key: str) -> float:
-    """
-    Extracts the resolution of a scanning electron microscope (SEM) image from its
-    metadata.
-
-    Notes
-    -----
-    This function is used internally and may not be useful for most users.
-
-    Parameters
-    ----------
-    sem_path : str
-        The file path to the SEM image.
-    sem_resolution_key : str
-        The key to look for in the SEM image metadata to extract the resolution.
-
-    Returns
-    -------
-    float
-        The resolution of the SEM image in nanometers per pixel.
-
-    Raises
-    ------
-    ValueError
-        If the resolution key is not found in the SEM image metadata.
-    """
-    with open(sem_path, "rb") as file:
-        resolution_key_bytes = sem_resolution_key.encode("utf-8")
-        for line in file:
-            if resolution_key_bytes in line:
-                line_str = line.decode("utf-8")
-                match = re.search(r"-?\d+(\.\d+)?", line_str)
-                if match:
-                    value = float(match.group())
-                    if value > 100:
-                        value /= 1000
-                    return value
-    raise ValueError(f"Resolution key '{sem_resolution_key}' not found in {sem_path}.")
-
-
-def from_tidy3d(
-    tidy3d_sim: "td.Simulation",
-    eps: float,
-    z: float,
-    freq: float,
-    buffer_width: float = 0.1,
-    **kwargs,
-) -> Device:
-    """
-    Create a Device from a Tidy3D simulation.
-
-    Parameters
-    ----------
-    tidy3d_sim : tidy3d.Simulation
-        The Tidy3D simulation object.
-    eps : float
-        The permittivity of the layer to extract from the simulation.
-    z : float
-        The z-coordinate of the layer to extract from the simulation.
-    freq : float
-        The frequency at which to extract the permittivity.
-    buffer_width : float
-        The width of the buffer region around the layer to extract from the
-        simulation. Defaults to 0.1 µm. This is useful for ensuring the inputs/outputs
-        of the simulation are not affected by prediction.
-    **kwargs
-        Additional keyword arguments to be passed to the Device constructor.
-
-    Returns
-    -------
-    Device
-        A Device object representing the permittivity cross-section at the specified
-        z-coordinate for the Tidy3D simulation.
-
-    Raises
-    ------
-    ImportError
-        If the tidy3d package is not installed.
-    """
-    try:
-        from tidy3d import Coords, Grid
-    except ImportError:
-        raise ImportError(
-            "The tidy3d package is required to use this function; "
-            "try `pip install tidy3d`."
-        ) from None
-
-    X = np.arange(
-        tidy3d_sim.bounds[0][0] - buffer_width,
-        tidy3d_sim.bounds[1][0] + buffer_width,
-        0.001,
-    )
-    Y = np.arange(
-        tidy3d_sim.bounds[0][1] - buffer_width,
-        tidy3d_sim.bounds[1][1] + buffer_width,
-        0.001,
-    )
-    Z = np.array([z])
-
-    grid = Grid(attrs={}, boundaries=Coords(attrs={}, x=X, y=Y, z=Z))
-    eps_array = np.real(
-        tidy3d_sim.epsilon_on_grid(grid=grid, coord_key="boundaries", freq=freq).values
-    )
-    device_array = geometry.binarize_hard(device_array=eps_array, eta=eps - 0.1)[
-        :, :, 0
-    ]
-    device_array = np.rot90(device_array, k=1)
-    return Device(device_array=device_array, **kwargs)