Component substitution with ODB++ PCB

[lorenzovecchietti]

This script imports ODB++ archives into Ansys Electronics Desktop (AEDT) projects, leveraging the automatic component substitution feature during IDF import. This allows you to import an ODB++ design and automatically replace generic components with detailed 3D models from your AEDT 3D component library (a3dcomp).

import os
import re
import tarfile
import tempfile
from datetime import datetime
from pathlib import Path
from typing import Union, List, Literal, Sequence

from ansys.aedt.core import Desktop, Hfss3dLayout, Icepak
from ansys.aedt.core.modules.boundary.layout_boundary import NativeComponentPCB

# RegEx patterns for parsing ODB++ files
PKG_DATA_PATTERN = re.compile(
    r"^PKG (\S+) (-?\d+\.\d+) (-?\d+\.\d+) (-?\d+\.\d+) (-?\d+\.\d+) (-?\d+\.\d+)$"
)
PKG_ID_PATTERN = re.compile(r"^# PKG (\d+)$")
CMP_DATA_PATTERN = re.compile(
    r"^CMP (\d+) (\d+\.\d+) (\d+\.\d+) (\d+) ([MN]) (\S+) (\S+) ;(\S+)$"
)
BOARD_THICKNESS_PATTERN = re.compile(r"\.board_thickness\s*=\s*(.*)")


def process_odb(
    tgz_path: Union[str, Path], output_directory: Union[str, Path]
) -> (Union[str, Path], Union[str, Path]):
    """Processes an ODB++, extracts relevant information, and generates
    .emp and .emn files.

    This function extracts a TGZ archive to a temporary directory, parses
    specific files within the extracted structure to gather board thickness,
    component placement, and package information. It then formats this
    information into two files: an .emp file for component placement details
    and an .emn file for electrical package definitions.

    Args:
        tgz_path (str): The full path to the input ODB++ file.
        output_directory (str): The path to a directory where the output files will be saved.

    Returns:
        tuple: A tuple containing two strings:
               - The full path to the generated .emp file.
               - The full path to the generated .emn file.
    """
    extracted_data = ""
    output_directory = Path(output_directory)
    tgz_path=Path(tgz_path)
    file_base_name = tgz_path.stem.replace(" ", "_")
    with tempfile.TemporaryDirectory() as extraction_dir:
        extraction_dir = Path(extraction_dir)
        with tarfile.open(tgz_path, "r:gz") as tar:
            tar.extractall(extraction_dir, filter="data")

        # Define paths for extracted ODB++
        odb_root_path = extraction_dir / "odb"
        eda_data_path = odb_root_path / "steps" / "pcb" / "eda" / "data"
        comp_top_path = (
            odb_root_path / "steps" / "pcb" / "layers" / "comp_+_top" / "components"
        )
        comp_bot_path = (
            odb_root_path / "steps" / "pcb" / "layers" / "comp_+_bot" / "components"
        )
        misc_data_path = odb_root_path / "misc" / "attrlist"

        # (1) Read board thickness
        with open(misc_data_path, "r") as f:
            content = f.read()
        match = re.search(BOARD_THICKNESS_PATTERN, content)
        thickness = match.group(1).strip()

        # (2) Process eda/data to map package IDs to names
        pkg_dict = {}
        last_pkg_id = None
        with open(eda_data_path, "r") as f:
            for line in f:
                # Try to match the # PKG line
                match_pkg_id = re.match(PKG_ID_PATTERN, line)
                if match_pkg_id:
                    last_pkg_id = match_pkg_id.group(1)
                    continue

                match_pkg_data = re.match(
                    PKG_DATA_PATTERN,
                    line,
                )
                if match_pkg_data and last_pkg_id is not None:
                    pkg_name = match_pkg_data.group(1)
                    pkg_dict[last_pkg_id] = pkg_name
                    last_pkg_id = None  # Reset for the next pair

        # (3) Process component data from top and bottom layers
        emp_list = []
        for comp_path, placement_text in [
            (comp_top_path, "TOP PLACED"),
            (comp_bot_path, "BOTTOM PLACED"),
        ]:
            if os.path.exists(comp_path):
                with open(comp_path, "r") as f:
                    line = next(f)
                    unit = line.split("=")[1].rstrip()
                    for line in f:
                        match = re.match(
                            CMP_DATA_PATTERN,
                            line,
                        )
                        if match:
                            group1 = match.group(1)
                            group2 = match.group(2)
                            group3 = match.group(3)
                            group4 = match.group(4)
                            group6 = match.group(6)
                            group7 = match.group(7)

                            emp_list_addition = f"{pkg_dict[group1]} {group7}"
                            emp_list.append(emp_list_addition)
                            extracted_data += f"{emp_list_addition} {group6}\n"
                            extracted_data += (
                                f"{group2} {group3} 0.0000 {group4} {placement_text}\n"
                            )

    now = datetime.now()
    creation_date = now.strftime("%Y/%m/%d.%H:%M:%S")

    # Default header with fictitious PCB outline for .emp file
    default_data = f""".HEADER
BOARD_FILE 3.0 "Altium DXP" {creation_date} 1
{file_base_name} {unit}
.END_HEADER
.BOARD_OUTLINE UNOWNED
{thickness}
0 0.0000 0.0000 0.0000
0 1.0000 0.0000 0.0000
0 1.0000 1.0000 0.0000
0 0.0000 1.0000 0.0000
0 0.0000 0.0000 0.0000
.END_BOARD_OUTLINE
.PLACEMENT
"""

    # Default header for .emn file
    default_data_pkg = f""".HEADER
LIBRARY_FILE 3.0 "Altium DXP" {creation_date} 1
.END_HEADER
"""

    file1 = default_data + extracted_data + ".END_PLACEMENT\n"
    file2 = default_data_pkg + "".join(
        [
            f""".ELECTRICAL
{pkg} {unit} 0.1000
0 -1 -1 0.0000
0 1 -1 0.0000
0 1 1 0.0000
0 -1 1 0.0000
0 -1 -1 0.0000
.END_ELECTRICAL
"""
            for pkg in emp_list
        ]
    )
    emp_file_path = output_directory / f"{file_base_name}.emp"
    emn_file_path = output_directory / f"{file_base_name}.emn"
    with open(emp_file_path, "w") as f:
        f.write(file2)
    with open(emn_file_path, "w") as f:
        f.write(file1)
    return emp_file_path, emn_file_path


def import_edb(
    desktop: Desktop, odb_path: Union[str, Path], project_path: Union[str, Path]
):
    """Imports an ODB++ archive into an AEDT EDB project.

    This function utilizes the AEDT Desktop's ImportExport tool to import
    the specified ODB++ file, creating a new EDB project and an associated XML file.

    Args:
        desktop (Desktop): An initialized AEDT Desktop object.
        odb_path (Union[str, Path]): The full path to the input ODB++ file.
        project_path (Union[str, Path]): The desired full path for the new AEDT project file (.aedt).
                                        The EDB and XML files will be created alongside it.
    """
    odb_path = str(os.path.abspath(odb_path))  # native API -> better use strings
    project_path = str(os.path.abspath(project_path))
    otool = desktop.odesktop.GetTool("ImportExport")
    otool.ImportODB(
        odb_path,
        project_path.replace(".aedt", ".aedb"),
        project_path.replace(".aedt", ".xml"),
    )


def import_idf(
    icepak: Icepak,
    emn: Union[str, Path],
    emp: Union[str, Path],
    component_library: Union[str, Path],
):
    """Imports IDF (Intermediate Data Format) files into an Icepak design.

    This function imports the specified .emn and .emp files, along with a component
    library, into the active Icepak design. After import, it cleans up the model
    by deleting objects not part of user-defined components and flattens the assembly.

    Args:
        icepak (Icepak): An initialized Icepak design object.
        emn (Union[str, Path]): The full path to the .emn file.
        emp (Union[str, Path]): The full path to the .emp file.
        component_library (Union[str, Path]): The path to the directory containing the component library.
    """
    emn = str(emn)
    emp = str(emp)
    component_library = str(os.path.abspath(component_library))
    icepak.import_idf(emn, emp, component_lib=component_library)

    print("Deleting objects...")
    udc_part_names = set(
        ii.name
        for o in [
            i.parts.values() for i in icepak.modeler.user_defined_components.values()
        ]
        for ii in o
    )
    icepak.modeler.delete(list(set(icepak.modeler.object_names) - udc_part_names))
    icepak.modeler.flatten_assembly()


def get_comps_in_library(component_library: Union[str, Path]) -> List[str]:
    """Retrieves a list of component names (without extensions) from a specified library directory.

    Args:
        component_library (Union[str, Path]): The path to the directory containing the component library files.

    Returns:
        List[str]: A list of strings, where each string is the name of a component
                   file found in the library, without its file extension.
    """
    all_entries = os.listdir(component_library)
    files: List[str] = []
    for entry in all_entries:
        full_path = os.path.join(component_library, entry)
        if os.path.isfile(full_path):
            filename_without_ext, _ = os.path.splitext(entry)
            files.append(str(filename_without_ext))
    return files


def add_odb_with_filtered_components(
    icepak: Icepak,
    h3dlayout: Hfss3dLayout,
    odb: Union[str, Path],
    components_to_filter: Sequence[str],
    power: str = "0W",
    extent_type: Literal["Polygon", "Bounding Box"] = "Polygon",
    trace_mapping_resolution: int = 3,
) -> NativeComponentPCB:
    """Adds an ODB++ based PCB component to an Icepak design, with optional component filtering.

    This function creates a PCB instance in Icepak by linking to an HFSS 3D Layout design
    derived from an ODB++ file. It allows for filtering specific components to be included
    or excluded from the Icepak PCB model and sets various import properties.

    Args:
        icepak (Icepak): An initialized Icepak design object.
        h3dlayout (Hfss3dLayout): An initialized HFSS 3D Layout design object, linked to the ODB++ data.
        odb (Union[str, Path]): The full path to the original ODB++ file (used for naming the component).
        components_to_filter (Sequence[str]): A sequence of component names that should be filtered.
                                               These components will be marked as 'filtered' in the PCB instance.
        power (str, optional): The total power dissipation for the PCB. Defaults to "0W".
        extent_type (Literal["Polygon", "Bounding Box"], optional): The type of extent to use for the PCB.
                                                                    Defaults to "Polygon".
        trace_mapping_resolution (int, optional): The resolution level for trace mapping. Defaults to 3.

    Returns:
        NativeComponentPCB: The created NativeComponentPCB instance in Icepak.
    """
    pcb_instance = icepak.create_pcb_from_3dlayout(
        component_name=re.sub(
            r"[^a-zA-Z0-9_]",
            "",
            os.path.splitext(os.path.basename(odb))[
                0
            ],  # only letters, numbers and _ are supported
        ),
        project_name=icepak.project_name,
        design_name=h3dlayout.design_name,
        resolution=trace_mapping_resolution,
        extent_type=extent_type,
        close_linked_project_after_import=False,
        power_in=power,
    )
    pcb_instance.auto_update = False
    pcb_instance.included_parts = "Device"

    for name in components_to_filter:
        pcb_instance.included_parts.override_definition(
            name, name, filter_component=True
        )
    pcb_instance.update()
    pcb_instance.auto_update = True
    return pcb_instance


if __name__ == "__main__":
    with tempfile.TemporaryDirectory() as tmpdir:
        # Inputs
        sample_odb = r".\data\ANSYS-HSD_V1_Thermo 1.tgz"
        comp_lib = r"./data/testlib"
        project = os.path.join(tmpdir, "test.aedt")
        pcb_power = "2W"
        trace_mapping_level = 3
        pcb_extent_type: Literal["Polygon", "Bounding Box"] = "Polygon"

        # Initialize AEDT Desktop session
        with Desktop(
            specified_version="2025.1",
            non_graphical=False,
            new_desktop_session=True,
            close_on_exit=True,
        ) as dktp:
            import_edb(dktp, sample_odb, project)
            emp_file, emn_file = process_odb(sample_odb, tmpdir)
            names_without_extension = get_comps_in_library(comp_lib)

            h3dl = Hfss3dLayout()
            ipk = Icepak()

            import_idf(ipk, emn_file, emp_file, comp_lib)
            pcb = add_odb_with_filtered_components(
                ipk,
                h3dl,
                sample_odb,
                names_without_extension,
                pcb_power,
                pcb_extent_type,
                trace_mapping_level,
            )

            ipk.save_project()