sch_io_pads.cpp

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2025 KiCad Developers, see AUTHORS.txt for contributors.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 3
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#include <sch_io/pads/sch_io_pads.h>
#include <sch_io/pads/pads_sch_parser.h>
#include <sch_io/pads/pads_sch_symbol_builder.h>
#include <sch_io/pads/pads_sch_schematic_builder.h>
#include <sch_io/pads/pads_sch_binary_reader.h>
 
#include <libraries/symbol_library_adapter.h>
 
#include <lib_symbol.h>
#include <page_info.h>
#include <sch_junction.h>
#include <sch_label.h>
#include <sch_line.h>
#include <sch_pin.h>
#include <sch_screen.h>
#include <sch_shape.h>
#include <sch_sheet.h>
#include <sch_sheet_path.h>
#include <sch_symbol.h>
#include <sch_text.h>
#include <schematic.h>
#include <schematic_settings.h>
#include <wildcards_and_files_ext.h>
 
#include <math/util.h>
#include <stroke_params.h>
 
#include <advanced_config.h>
#include <io/pads/pads_binary_utils.h>
#include <io/pads/pads_common.h>
#include <locale_io.h>
#include <progress_reporter.h>
#include <reporter.h>
#include <trace_helpers.h>
 
#include <fstream>
#include <map>
#include <set>
#include <wx/filename.h>
#include <wx/log.h>
 

static std::string extractConnectorPinNumber( const std::string& aRef )
{
    size_t sepPos = aRef.rfind( '-' );
 
    if( sepPos == std::string::npos )
        sepPos = aRef.rfind( '.' );
 
    if( sepPos != std::string::npos
            && sepPos + 1 < aRef.size()
            && std::isdigit( static_cast<unsigned char>( aRef[sepPos + 1] ) ) )
    {
        return aRef.substr( sepPos + 1 );
    }
 
    return "";
}
 

static std::string extractConnectorBaseRef( const std::string& aRef )
{
    size_t sepPos = aRef.rfind( '-' );
 
    if( sepPos == std::string::npos )
        sepPos = aRef.rfind( '.' );
 
    if( sepPos != std::string::npos
            && sepPos + 1 < aRef.size()
            && std::isdigit( static_cast<unsigned char>( aRef[sepPos + 1] ) ) )
    {
        return aRef.substr( 0, sepPos );
    }
 
    return aRef;
}
 

static std::string stripGateSuffix( const std::string& aRef )
{
    size_t sepPos = aRef.rfind( '-' );
 
    if( sepPos == std::string::npos )
        sepPos = aRef.rfind( '.' );
 
    if( sepPos != std::string::npos
            && sepPos + 1 < aRef.size()
            && std::isalpha( static_cast<unsigned char>( aRef[sepPos + 1] ) ) )
    {
        return aRef.substr( 0, sepPos );
    }
 
    return aRef;
}
 
 
static SCH_TEXT* createSchText( const PADS_SCH::TEXT_ITEM& aText, const VECTOR2I& aPos )
{
    SCH_TEXT* schText = new SCH_TEXT( aPos, wxString::FromUTF8( aText.content ) );
 
    if( aText.height > 0 )
    {
        int scaledSize = schIUScale.MilsToIU( aText.height );
        int charHeight = static_cast<int>( scaledSize * ADVANCED_CFG::GetCfg().m_PadsSchTextHeightScale );
        int charWidth = static_cast<int>( scaledSize * ADVANCED_CFG::GetCfg().m_PadsSchTextWidthScale );
        schText->SetTextSize( VECTOR2I( charWidth, charHeight ) );
    }
 
    if( aText.width_factor > 0 )
        schText->SetTextThickness( schIUScale.MilsToIU( aText.width_factor ) );
 
    GR_TEXT_H_ALIGN_T hJustify = GR_TEXT_H_ALIGN_LEFT;
    GR_TEXT_V_ALIGN_T vJustify = GR_TEXT_V_ALIGN_BOTTOM;
    PADS_COMMON::DecodeJustification( aText.justification, hJustify, vJustify );
    schText->SetHorizJustify( hJustify );
    schText->SetVertJustify( vJustify );
 
    if( aText.rotation != 0 )
        schText->SetTextAngleDegrees( aText.rotation * 90.0 );
 
    return schText;
}
 

static int computePowerOrientation( const std::string& aOpcId, const std::vector<PADS_SCH::SCH_SIGNAL>& aSignals,
                                    const VECTOR2I& aOpcPos, bool aPinUp, int aPageHeightIU )
{
    // Find the wire endpoint matching this OPC and get the adjacent vertex
    std::string opcRef = "@@@O" + aOpcId;
    VECTOR2I    adjPos = aOpcPos;
    bool        found = false;
 
    for( const PADS_SCH::SCH_SIGNAL& signal : aSignals )
    {
        for( const auto& wire : signal.wires )
        {
            if( wire.vertices.size() < 2 )
                continue;
 
            if( wire.endpoint_a == opcRef )
            {
                adjPos = VECTOR2I( schIUScale.MilsToIU( KiROUND( wire.vertices[1].x ) ),
                                   aPageHeightIU - schIUScale.MilsToIU( KiROUND( wire.vertices[1].y ) ) );
                found = true;
                break;
            }
 
            if( wire.endpoint_b == opcRef )
            {
                size_t last = wire.vertices.size() - 1;
                adjPos = VECTOR2I( schIUScale.MilsToIU( KiROUND( wire.vertices[last - 1].x ) ),
                                   aPageHeightIU - schIUScale.MilsToIU( KiROUND( wire.vertices[last - 1].y ) ) );
                found = true;
                break;
            }
        }
 
        if( found )
            break;
    }
 
    if( !found )
        return SYMBOL_ORIENTATION_T::SYM_ORIENT_0;
 
    // Wire goes from aOpcPos toward adjPos
    int dx = adjPos.x - aOpcPos.x;
    int dy = adjPos.y - aOpcPos.y;
 
    // Determine which direction the wire approaches from (relative to OPC position).
    // The symbol body should face AWAY from the wire.
    // In KiCad Y-down coordinates: dy > 0 means wire goes down from OPC.
 
    if( std::abs( dx ) >= std::abs( dy ) )
    {
        // Horizontal wire
        if( dx > 0 )
        {
            // Wire goes right → body should face left
            return aPinUp ? SYMBOL_ORIENTATION_T::SYM_ORIENT_90 : SYMBOL_ORIENTATION_T::SYM_ORIENT_270;
        }
        else
        {
            // Wire goes left → body should face right
            return aPinUp ? SYMBOL_ORIENTATION_T::SYM_ORIENT_270 : SYMBOL_ORIENTATION_T::SYM_ORIENT_90;
        }
    }
    else
    {
        // Vertical wire
        if( dy > 0 )
        {
            // Wire goes down → body should face up
            return aPinUp ? SYMBOL_ORIENTATION_T::SYM_ORIENT_0 : SYMBOL_ORIENTATION_T::SYM_ORIENT_180;
        }
        else
        {
            // Wire goes up → body should face down
            return aPinUp ? SYMBOL_ORIENTATION_T::SYM_ORIENT_180 : SYMBOL_ORIENTATION_T::SYM_ORIENT_0;
        }
    }
}
 
 
SCH_IO_PADS::SCH_IO_PADS() :
        SCH_IO( wxS( "PADS Logic" ) )
{
}
 
 
SCH_IO_PADS::~SCH_IO_PADS()
{
}
 
 
bool SCH_IO_PADS::CanReadSchematicFile( const wxString& aFileName ) const
{
    if( !SCH_IO::CanReadSchematicFile( aFileName ) )
        return false;
 
    // Keep the shared header predicate ASCII-only because binary import is schematic-only
    return checkFileHeader( aFileName ) || isBinarySchematicFile( aFileName );
}
 
 
bool SCH_IO_PADS::CanReadLibrary( const wxString& aFileName ) const
{
    if( !SCH_IO::CanReadLibrary( aFileName ) )
        return false;
 
    return checkFileHeader( aFileName );
}
 
 
static void appendGraphicPrimitive( SCH_SCREEN* aScreen, const PADS_SCH::SYMBOL_GRAPHIC& aPrim, double aOx, double aOy,
                                    int aPageHeightIU )
{
    int strokeWidth = aPrim.line_width > 0.0 ? schIUScale.MilsToIU( KiROUND( aPrim.line_width ) ) : 0;
 
    LINE_STYLE lineStyle = PADS_COMMON::PadsLineStyleToKiCad( aPrim.line_style );
 
    if( aPrim.type == PADS_SCH::GRAPHIC_TYPE::CIRCLE )
    {
        VECTOR2I center( schIUScale.MilsToIU( KiROUND( aOx + aPrim.center.x ) ),
                         aPageHeightIU - schIUScale.MilsToIU( KiROUND( aOy + aPrim.center.y ) ) );
        int      radius = schIUScale.MilsToIU( KiROUND( aPrim.radius ) );
 
        SCH_SHAPE* circle = new SCH_SHAPE( SHAPE_T::CIRCLE );
        circle->SetStart( center );
        circle->SetEnd( VECTOR2I( center.x + radius, center.y ) );
        circle->SetStroke( STROKE_PARAMS( strokeWidth, lineStyle ) );
 
        if( aPrim.filled )
            circle->SetFillMode( FILL_T::FILLED_SHAPE );
 
        aScreen->Append( circle );
    }
    else if( aPrim.type == PADS_SCH::GRAPHIC_TYPE::RECTANGLE && aPrim.points.size() == 2 )
    {
        VECTOR2I pos( schIUScale.MilsToIU( KiROUND( aOx + aPrim.points[0].coord.x ) ),
                      aPageHeightIU - schIUScale.MilsToIU( KiROUND( aOy + aPrim.points[0].coord.y ) ) );
        VECTOR2I end( schIUScale.MilsToIU( KiROUND( aOx + aPrim.points[1].coord.x ) ),
                      aPageHeightIU - schIUScale.MilsToIU( KiROUND( aOy + aPrim.points[1].coord.y ) ) );
 
        SCH_SHAPE* rect = new SCH_SHAPE( SHAPE_T::RECTANGLE );
        rect->SetPosition( pos );
        rect->SetEnd( end );
        rect->SetStroke( STROKE_PARAMS( strokeWidth, lineStyle ) );
 
        if( aPrim.filled )
            rect->SetFillMode( FILL_T::FILLED_SHAPE );
 
        aScreen->Append( rect );
    }
    else if( aPrim.points.size() >= 2 )
    {
        for( size_t p = 0; p + 1 < aPrim.points.size(); p++ )
        {
            VECTOR2I start( schIUScale.MilsToIU( KiROUND( aOx + aPrim.points[p].coord.x ) ),
                            aPageHeightIU - schIUScale.MilsToIU( KiROUND( aOy + aPrim.points[p].coord.y ) ) );
            VECTOR2I end( schIUScale.MilsToIU( KiROUND( aOx + aPrim.points[p + 1].coord.x ) ),
                          aPageHeightIU - schIUScale.MilsToIU( KiROUND( aOy + aPrim.points[p + 1].coord.y ) ) );
 
            if( start == end )
                continue;
 
            if( aPrim.points[p].arc.has_value() )
            {
                const PADS_SCH::ARC_DATA& ad = *aPrim.points[p].arc;
                double                    cx = ( ad.bbox_x1 + ad.bbox_x2 ) / 2.0;
                double                    cy = ( ad.bbox_y1 + ad.bbox_y2 ) / 2.0;
                VECTOR2I                  center( schIUScale.MilsToIU( KiROUND( aOx + cx ) ),
                                                  aPageHeightIU - schIUScale.MilsToIU( KiROUND( aOy + cy ) ) );
 
                VECTOR2I midPt = PADS_SCH::padsSchArcMidpoint( start, end, center );
 
                if( ad.angle < 0 )
                {
                    midPt.x = 2 * center.x - midPt.x;
                    midPt.y = 2 * center.y - midPt.y;
                }
 
                SCH_SHAPE* arc = new SCH_SHAPE( SHAPE_T::ARC );
                arc->SetArcGeometry( start, midPt, end );
                arc->SetStroke( STROKE_PARAMS( strokeWidth, lineStyle ) );
 
                if( aPrim.filled )
                    arc->SetFillMode( FILL_T::FILLED_SHAPE );
 
                aScreen->Append( arc );
            }
            else
            {
                SCH_LINE* line = new SCH_LINE( start, SCH_LAYER_ID::LAYER_NOTES );
                line->SetEndPoint( end );
                line->SetStroke( STROKE_PARAMS( strokeWidth, lineStyle ) );
                aScreen->Append( line );
            }
        }
    }
}
 
 
SCH_SHEET* SCH_IO_PADS::LoadSchematicFile( const wxString& aFileName, SCHEMATIC* aSchematic, SCH_SHEET* aAppendToMe,
                                           const std::map<std::string, UTF8>* aProperties )
{
    wxCHECK( !aFileName.IsEmpty() && aSchematic, nullptr );
 
    LOCALE_IO setlocale;
 
    // Adopting a whole document cannot satisfy the hierarchical-sheet loader's contract that the
    // caller owns the returned sheet, and both branches below replace the live top-level sheets
    if( aProperties && aProperties->count( "hierarchical_sheet_load" ) )
    {
        THROW_IO_ERROR( wxString::Format( _( "'%s' contains a complete PADS Logic schematic and "
                                             "cannot be loaded as a hierarchical sheet. Use File > Import > "
                                             "Non-KiCad Schematic... instead." ),
                                          aFileName ) );
    }
 
    // The proprietary binary .sch is read by a separate structural path; the
    // ASCII export remains the route for net-label and free-text bindings.
    if( isBinarySchematicFile( aFileName ) )
        return loadBinarySchematicFile( aFileName, aSchematic, aAppendToMe, aProperties );
 
    SCH_SHEET* rootSheet = nullptr;
 
    if( aAppendToMe )
    {
        wxCHECK_MSG( aSchematic->IsValid(), nullptr, "Can't append to a schematic with no root!" );
        rootSheet = aAppendToMe;
    }
    else
    {
        rootSheet = new SCH_SHEET( aSchematic );
        rootSheet->SetFileName( aFileName );
        aSchematic->SetTopLevelSheets( { rootSheet } );
    }
 
    if( !rootSheet->GetScreen() )
    {
        SCH_SCREEN* screen = new SCH_SCREEN( aSchematic );
        screen->SetFileName( aFileName );
        rootSheet->SetScreen( screen );
 
        rootSheet->SyncUuidToScreen();
    }
 
    SCH_SHEET_PATH rootPath;
    rootPath.push_back( rootSheet );
 
    SCH_SCREEN* rootScreen = rootSheet->GetScreen();
    wxCHECK( rootScreen, nullptr );
 
    SCH_SHEET_INSTANCE sheetInstance;
    sheetInstance.m_Path = rootPath.Path();
    sheetInstance.m_PageNumber = wxT( "#" );
    rootScreen->m_sheetInstances.emplace_back( sheetInstance );
 
    if( m_progressReporter )
        m_progressReporter->SetNumPhases( 3 );
 
    PADS_SCH::PADS_SCH_PARSER parser;
    std::string               filename( aFileName.ToUTF8() );
 
    if( !parser.Parse( filename ) )
        THROW_IO_ERRORF( _( "Failed to parse PADS file: %s" ), aFileName );
 
    if( m_progressReporter )
        m_progressReporter->BeginPhase( 1 );
 
    const PADS_SCH::PARAMETERS&          params = parser.GetParameters();
    PADS_SCH::PADS_SCH_SYMBOL_BUILDER    symbolBuilder( params );
    PADS_SCH::PADS_SCH_SCHEMATIC_BUILDER schBuilder( params, aSchematic );
 
    // Detect gate suffix separator from multi-gate part references (e.g. U17-A → '-')
    for( const auto& part : parser.GetPartPlacements() )
    {
        const std::string& ref = part.reference;
        size_t             dashPos = ref.rfind( '-' );
        size_t             dotPos = ref.rfind( '.' );
        size_t             sepPos = std::string::npos;
 
        if( dashPos != std::string::npos )
            sepPos = dashPos;
        else if( dotPos != std::string::npos )
            sepPos = dotPos;
 
        if( sepPos != std::string::npos && sepPos + 1 < ref.size()
            && std::isalpha( static_cast<unsigned char>( ref[sepPos + 1] ) ) )
        {
            aSchematic->Settings().m_SubpartIdSeparator = static_cast<int>( ref[sepPos] );
            aSchematic->Settings().m_SubpartFirstId = 'A';
            break;
        }
    }
 
    // Set KiCad page size to match the PADS drawing sheet
    PAGE_INFO pageInfo;
 
    if( !params.sheet_size.name.empty() )
        pageInfo.SetType( wxString::FromUTF8( params.sheet_size.name ) );
    else
        pageInfo.SetType( PAGE_SIZE_TYPE::A );
 
    // PADS Y-up to KiCad Y-down: Y_kicad = pageHeight - Y_pads
    const int pageHeightIU = pageInfo.GetHeightIU( schIUScale.IU_PER_MILS );
 
    // Build LIB_SYMBOL objects from all CAEDECAL definitions
    for( const PADS_SCH::SYMBOL_DEF& symDef : parser.GetSymbolDefs() )
        symbolBuilder.GetOrCreateSymbol( symDef );
 
    std::set<int> sheetNumbers = parser.GetSheetNumbers();
 
    if( sheetNumbers.empty() )
        sheetNumbers.insert( 1 );
 
    bool isSingleSheet = ( sheetNumbers.size() == 1 );
 
    // Map sheet number -> (SCH_SHEET*, SCH_SCREEN*, SCH_SHEET_PATH)
    struct SheetContext
    {
        SCH_SHEET*     sheet = nullptr;
        SCH_SCREEN*    screen = nullptr;
        SCH_SHEET_PATH path;
    };
 
    std::map<int, SheetContext> sheetContexts;
 
    if( isSingleSheet )
    {
        int          sheetNum = *sheetNumbers.begin();
        SheetContext ctx;
        ctx.sheet = rootSheet;
        ctx.screen = rootScreen;
        ctx.path = rootPath;
        ctx.screen->SetPageSettings( pageInfo );
        sheetContexts[sheetNum] = ctx;
    }
    else
    {
        // Multi-sheet: root is a container with sub-sheets
        int totalSheets = static_cast<int>( sheetNumbers.size() );
 
        for( int sheetNum : sheetNumbers )
        {
            SCH_SHEET* subSheet = schBuilder.CreateHierarchicalSheet( sheetNum, totalSheets, rootSheet, aFileName );
 
            if( !subSheet )
                continue;
 
            // Find the sheet name from parser headers
            for( const PADS_SCH::SHEET_HEADER& hdr : parser.GetSheetHeaders() )
            {
                if( hdr.sheet_num == sheetNum && !hdr.sheet_name.empty() )
                {
                    subSheet->GetField( FIELD_T::SHEET_NAME )->SetText( wxString::FromUTF8( hdr.sheet_name ) );
 
                    break;
                }
            }
 
            SCH_SHEET_PATH subPath;
            subPath.push_back( rootSheet );
            subPath.push_back( subSheet );
 
            wxString pageNo = wxString::Format( wxT( "%d" ), sheetNum );
            subPath.SetPageNumber( pageNo );
 
            SCH_SHEET_INSTANCE subInstance;
            subInstance.m_Path = subPath.Path();
            subInstance.m_PageNumber = pageNo;
            subSheet->GetScreen()->m_sheetInstances.emplace_back( subInstance );
 
            SheetContext ctx;
            ctx.sheet = subSheet;
            ctx.screen = subSheet->GetScreen();
            ctx.path = subPath;
            ctx.screen->SetPageSettings( pageInfo );
            sheetContexts[sheetNum] = ctx;
        }
    }
 
    if( m_progressReporter )
        m_progressReporter->BeginPhase( 2 );
 
    // Track connector base references for wire-endpoint label creation
    std::set<std::string> connectorBaseRefs;
 
    // Pre-scan connector placements to group pins by base reference.
    // Each group becomes one multi-unit connector symbol in KiCad.
    struct ConnectorGroup
    {
        std::vector<std::string>   pinNumbers;
        std::map<std::string, int> pinToUnit;
        std::string                partType;
    };
 
    std::map<std::string, ConnectorGroup> connectorGroups;
 
    for( const auto& [sheetNum, ctx] : sheetContexts )
    {
        std::vector<PADS_SCH::PART_PLACEMENT> sheetParts = parser.GetPartsOnSheet( sheetNum );
 
        for( const PADS_SCH::PART_PLACEMENT& part : sheetParts )
        {
            auto ptIt = parser.GetPartTypes().find( part.part_type );
 
            if( ptIt == parser.GetPartTypes().end() || !ptIt->second.is_connector )
                continue;
 
            std::string pinNum = extractConnectorPinNumber( part.reference );
 
            if( pinNum.empty() )
                continue;
 
            std::string     baseRef = extractConnectorBaseRef( part.reference );
            ConnectorGroup& group = connectorGroups[baseRef];
            group.partType = part.part_type;
            group.pinNumbers.push_back( pinNum );
        }
    }
 
    for( auto& [baseRef, group] : connectorGroups )
    {
        std::sort( group.pinNumbers.begin(), group.pinNumbers.end(),
                   []( const std::string& a, const std::string& b )
                   {
                       return std::stoi( a ) < std::stoi( b );
                   } );
 
        for( size_t i = 0; i < group.pinNumbers.size(); i++ )
            group.pinToUnit[group.pinNumbers[i]] = static_cast<int>( i + 1 );
    }
 
    // Place symbols on each sheet
    for( auto& [sheetNum, ctx] : sheetContexts )
    {
        std::vector<PADS_SCH::PART_PLACEMENT> parts = parser.GetPartsOnSheet( sheetNum );
 
        for( const PADS_SCH::PART_PLACEMENT& part : parts )
        {
            auto ptIt = parser.GetPartTypes().find( part.part_type );
 
            LIB_SYMBOL* libSymbol = nullptr;
            bool        isMultiGate = false;
            bool        isConnector = false;
            bool        isPower = false;
            std::string libItemName;
            std::string connectorPinNumber;
 
            if( ptIt != parser.GetPartTypes().end() )
            {
                const PADS_SCH::PARTTYPE_DEF& ptDef = ptIt->second;
 
                if( ptDef.gates.size() > 1 )
                {
                    // Multi-gate PARTTYPE: composite multi-unit symbol
                    libSymbol = symbolBuilder.GetOrCreateMultiUnitSymbol( ptDef, parser.GetSymbolDefs() );
                    libItemName = ptDef.name;
                    isMultiGate = true;
                }
                else if( !ptDef.gates.empty() )
                {
                    const PADS_SCH::GATE_DEF& gate = ptDef.gates[0];
                    int                       idx = std::max( 0, part.gate_index );
                    std::string               decalName;
 
                    if( idx < static_cast<int>( gate.decal_names.size() ) )
                        decalName = gate.decal_names[idx];
                    else if( !gate.decal_names.empty() )
                        decalName = gate.decal_names[0];
 
                    const PADS_SCH::SYMBOL_DEF* symDef = parser.GetSymbolDef( decalName );
 
                    connectorPinNumber =
                            ptDef.is_connector ? extractConnectorPinNumber( part.reference ) : std::string();
 
                    if( symDef && !connectorPinNumber.empty() )
                    {
                        // Multi-unit connector placement (e.g. J12-15 → unit of J12).
                        // All pins of the same connector share one multi-unit symbol.
                        std::string baseRef = extractConnectorBaseRef( part.reference );
                        auto        groupIt = connectorGroups.find( baseRef );
 
                        if( groupIt != connectorGroups.end() )
                        {
                            std::string cacheKey = ptDef.name + ":conn:" + baseRef;
 
                            libSymbol = symbolBuilder.GetOrCreateMultiUnitConnectorSymbol( ptDef, *symDef,
                                                                                           groupIt->second.pinNumbers,
                                                                                           cacheKey );
                            libItemName = ptDef.name + "_" + baseRef;
                            isConnector = true;
                            isMultiGate = true;
 
                            connectorBaseRefs.insert( baseRef );
                        }
                    }
                    else if( symDef )
                    {
                        libSymbol = symbolBuilder.GetOrCreatePartTypeSymbol( ptDef, *symDef );
                        libItemName = decalName;
                    }
                }
                else if( !ptDef.special_variants.empty() )
                {
                    // Power/ground symbols
                    int idx = std::max( 0, part.gate_index );
                    idx = std::min( idx, static_cast<int>( ptDef.special_variants.size() ) - 1 );
                    std::string decalName = ptDef.special_variants[idx].decal_name;
 
                    const PADS_SCH::SYMBOL_DEF* symDef = parser.GetSymbolDef( decalName );
 
                    if( symDef )
                    {
                        libSymbol = symbolBuilder.GetOrCreateSymbol( *symDef );
                        libItemName = decalName;
                    }
                }
 
                if( !ptDef.special_keyword.empty() && ptDef.special_keyword != "OFF" )
                    isPower = true;
            }
 
            // Fallback: resolve directly by CAEDECAL name
            if( !libSymbol )
            {
                const PADS_SCH::SYMBOL_DEF* symDef = parser.GetSymbolDef( part.symbol_name );
 
                if( !symDef )
                {
                    m_errorMessages.emplace( wxString::Format( wxT( "PADS Import: symbol '%s' not found,"
                                                                    " part '%s' skipped" ),
                                                               wxString::FromUTF8( part.symbol_name ),
                                                               wxString::FromUTF8( part.reference ) ),
                                             RPT_SEVERITY_WARNING );
                    continue;
                }
 
                libSymbol = symbolBuilder.GetOrCreateSymbol( *symDef );
                libItemName = symDef->name;
            }
 
            if( !libSymbol )
                continue;
 
            if( ptIt != parser.GetPartTypes().end() && !ptIt->second.sigpins.empty() )
                symbolBuilder.AddHiddenPowerPins( libSymbol, ptIt->second.sigpins );
 
            if( !isPower )
                isPower = PADS_SCH::PADS_SCH_SYMBOL_BUILDER::IsPowerSymbol( part.part_type );
 
            // Resolve power symbol style. Prefer the PARTTYPE variant decal style
            // (e.g. +BUBBLE → +VDC) which preserves the original PADS symbol shape,
            // falling back to net-name matching (e.g. GND → GND, +5V → +5V).
            std::string powerStyle;
 
            if( isPower && ptIt != parser.GetPartTypes().end() && !ptIt->second.special_variants.empty() )
            {
                int varIdx = std::max( 0, part.gate_index );
                varIdx = std::min( varIdx, static_cast<int>( ptIt->second.special_variants.size() ) - 1 );
                const PADS_SCH::PARTTYPE_DEF::SPECIAL_VARIANT& variant = ptIt->second.special_variants[varIdx];
 
                powerStyle = PADS_SCH::PADS_SCH_SYMBOL_BUILDER::GetPowerStyleFromVariant( variant.decal_name,
                                                                                          variant.pin_type );
            }
 
            std::optional<LIB_ID> powerLibId;
 
            if( isPower )
            {
                std::string rawNetName = part.power_net_name.empty() ? part.symbol_name : part.power_net_name;
 
                powerLibId = PADS_SCH::PADS_SCH_SYMBOL_BUILDER::GetKiCadPowerSymbolId( rawNetName );
            }
 
            if( isPower && powerStyle.empty() )
            {
                if( powerLibId )
                    powerStyle = std::string( powerLibId->GetLibItemName().c_str() );
            }
 
            auto        symbolPtr = std::make_unique<SCH_SYMBOL>();
            SCH_SYMBOL* symbol = symbolPtr.get();
            LIB_SYMBOL* instanceSymbol = nullptr;
 
            if( isPower && !powerStyle.empty() )
            {
                instanceSymbol = symbolBuilder.BuildKiCadPowerSymbol( powerStyle );
 
                if( !powerLibId.has_value() )
                    powerLibId = LIB_ID( wxT( "power" ), wxString::FromUTF8( powerStyle ) );
 
                symbol->SetLibId( powerLibId.value() );
            }
            else
            {
                LIB_ID libId;
                libId.SetLibNickname( wxT( "pads_import" ) );
                libId.SetLibItemName( wxString::FromUTF8( libItemName ) );
                symbol->SetLibId( libId );
 
                instanceSymbol = new LIB_SYMBOL( *libSymbol );
 
                if( isPower )
                    instanceSymbol->SetGlobalPower();
            }
 
            symbol->SetLibSymbol( instanceSymbol );
            symbol->SetPosition( VECTOR2I( schIUScale.MilsToIU( KiROUND( part.position.x ) ),
                                           pageHeightIU - schIUScale.MilsToIU( KiROUND( part.position.y ) ) ) );
 
            int orientation = SYMBOL_ORIENTATION_T::SYM_ORIENT_0;
 
            if( part.rotation == 90.0 )
                orientation = SYMBOL_ORIENTATION_T::SYM_ORIENT_90;
            else if( part.rotation == 180.0 )
                orientation = SYMBOL_ORIENTATION_T::SYM_ORIENT_180;
            else if( part.rotation == 270.0 )
                orientation = SYMBOL_ORIENTATION_T::SYM_ORIENT_270;
 
            if( part.mirror_flags & 1 )
                orientation |= SYMBOL_ORIENTATION_T::SYM_MIRROR_Y;
 
            if( part.mirror_flags & 2 )
                orientation |= SYMBOL_ORIENTATION_T::SYM_MIRROR_X;
 
            symbol->SetOrientation( orientation );
 
            if( isConnector && !connectorPinNumber.empty() )
            {
                std::string baseRef = extractConnectorBaseRef( part.reference );
                auto        groupIt = connectorGroups.find( baseRef );
 
                if( groupIt != connectorGroups.end() )
                {
                    auto unitIt = groupIt->second.pinToUnit.find( connectorPinNumber );
 
                    if( unitIt != groupIt->second.pinToUnit.end() )
                        symbol->SetUnit( unitIt->second );
                    else
                        symbol->SetUnit( 1 );
                }
                else
                {
                    symbol->SetUnit( 1 );
                }
            }
            else if( isMultiGate )
            {
                symbol->SetUnit( part.gate_index + 1 );
            }
            else
            {
                symbol->SetUnit( 1 );
            }
 
            // Assign deterministic UUID so PCB cross-probe can match footprints
            // to symbols. Only the primary gate (index 0) or the first connector
            // pin gets the deterministic UUID since one footprint maps to one
            // symbol instance.
            bool isPrimaryUnit = isConnector ? ( symbol->GetUnit() == 1 ) : ( !isMultiGate || part.gate_index == 0 );
 
            if( !isPower && isPrimaryUnit )
            {
                std::string baseRef =
                        isConnector ? extractConnectorBaseRef( part.reference ) : stripGateSuffix( part.reference );
 
                const_cast<KIID&>( symbol->m_Uuid ) = PADS_COMMON::GenerateDeterministicUuid( baseRef );
            }
 
            symbol->SetRef( &ctx.path, wxString::FromUTF8( part.reference ) );
 
            schBuilder.ApplyPartAttributes( symbol, part );
            schBuilder.CreateCustomFields( symbol, part );
 
            // For connectors, override reference to the base (e.g. "J12" not "J12-1").
            // Must happen after ApplyPartAttributes which only strips alpha suffixes.
            if( isConnector )
            {
                std::string baseRef = extractConnectorBaseRef( part.reference );
                symbol->SetRef( &ctx.path, wxString::FromUTF8( baseRef ) );
            }
 
            // For multi-gate parts, strip the alpha gate suffix (e.g. "U1-A" → "U1")
            // so KiCad recognizes all units as belonging to the same part.
            if( isMultiGate && !isConnector )
            {
                std::string baseRef = stripGateSuffix( part.reference );
                symbol->SetRef( &ctx.path, wxString::FromUTF8( baseRef ) );
            }
 
            // For passive components, override Value with VALUE1 parametric value
            // so that e.g. C10 shows "0.1uF" instead of the generic "CAPMF0805".
            // Also apply the VALUE1 attribute position.
            if( ptIt != parser.GetPartTypes().end() )
            {
                const std::string& cat = ptIt->second.category;
 
                if( cat == "CAP" || cat == "RES" || cat == "IND" )
                {
                    auto valIt = part.attr_overrides.find( "VALUE" );
 
                    if( valIt == part.attr_overrides.end() )
                        valIt = part.attr_overrides.find( "VALUE1" );
 
                    if( valIt != part.attr_overrides.end() && !valIt->second.empty() )
                    {
                        symbol->SetValueFieldText( wxString::FromUTF8( valIt->second ) );
 
                        for( const auto& attr : part.attributes )
                        {
                            if( attr.name == "VALUE" || attr.name == "VALUE1" || attr.name == "Value1" )
                            {
                                SCH_FIELD* valField = symbol->GetField( FIELD_T::VALUE );
                                int        fx = schIUScale.MilsToIU( KiROUND( attr.position.x ) );
 
                                if( part.mirror_flags & 1 )
                                    fx = -fx;
 
                                VECTOR2I fieldPos( fx, -schIUScale.MilsToIU( KiROUND( attr.position.y ) ) );
                                valField->SetPosition( symbol->GetPosition() + fieldPos );
 
                                int fieldTextSize = schIUScale.MilsToIU( 50 );
                                valField->SetTextSize( VECTOR2I( fieldTextSize, fieldTextSize ) );
 
                                // Keep the PADS-authored alignment instead of forcing
                                // center; otherwise this override undoes the justification
                                // applied by ApplyFieldSettings.
                                GR_TEXT_H_ALIGN_T hJustify = GR_TEXT_H_ALIGN_LEFT;
                                GR_TEXT_V_ALIGN_T vJustify = GR_TEXT_V_ALIGN_BOTTOM;
                                PADS_COMMON::DecodeJustification( attr.justification, hJustify, vJustify );
 
                                if( part.mirror_flags & 1 )
                                    hJustify = GetFlippedAlignment( hJustify );
 
                                valField->SetHorizJustify( hJustify );
                                valField->SetVertJustify( vJustify );
                                break;
                            }
                        }
                    }
                }
            }
 
            if( isPower )
            {
                symbol->GetField( FIELD_T::REFERENCE )->SetVisible( false );
 
                wxString netName = part.power_net_name.empty() ? wxString::FromUTF8( part.symbol_name )
                                                               : wxString::FromUTF8( part.power_net_name );
 
                if( netName.StartsWith( wxT( "/" ) ) )
                    netName = wxT( "~{" ) + netName.Mid( 1 ) + wxT( "}" );
 
                symbol->GetField( FIELD_T::VALUE )->SetText( netName );
                symbol->GetField( FIELD_T::VALUE )->SetVisible( true );
            }
 
            {
                std::string hierRef;
 
                if( isConnector )
                    hierRef = extractConnectorBaseRef( part.reference );
                else if( isMultiGate )
                    hierRef = stripGateSuffix( part.reference );
                else
                    hierRef = part.reference;
 
                symbol->AddHierarchicalReference( ctx.path.Path(), wxString::FromUTF8( hierRef ), symbol->GetUnit() );
            }
 
            symbol->ClearFlags();
 
            // For connector pins, create a local label at the pin position
            // before transferring ownership to the screen.
            // The matching label at the wire endpoint creates the electrical connection.
            if( isConnector && !connectorPinNumber.empty() )
            {
                std::string baseRef = extractConnectorBaseRef( part.reference );
                wxString    labelText = wxString::Format( wxT( "%s.%s" ), wxString::FromUTF8( baseRef ),
                                                          wxString::FromUTF8( connectorPinNumber ) );
 
                VECTOR2I              pinPos = symbol->GetPosition();
                std::vector<SCH_PIN*> pins = symbol->GetPins();
 
                if( !pins.empty() )
                    pinPos = pins[0]->GetPosition();
 
                SCH_LABEL* label = new SCH_LABEL( pinPos, labelText );
                int        labelSize = schIUScale.MilsToIU( 50 );
                label->SetTextSize( VECTOR2I( labelSize, labelSize ) );
                label->SetSpinStyle( SPIN_STYLE::RIGHT );
                label->SetFlags( IS_NEW );
                ctx.screen->Append( label );
            }
 
            ctx.screen->Append( symbolPtr.release() );
        }
    }
 
    // Build set of power signal names so we can suppress duplicate global labels
    // where a power symbol is placed instead.  Non-power signal labels are handled
    // by CreateNetLabels which places them at dangling wire endpoints.
    std::set<std::string> powerSignalNames;
 
    for( const PADS_SCH::OFF_PAGE_CONNECTOR& opc : parser.GetOffPageConnectors() )
    {
        if( opc.signal_name.empty() )
            continue;
 
        auto ptIt = parser.GetPartTypes().find( opc.symbol_lib );
 
        if( ptIt != parser.GetPartTypes().end() && !ptIt->second.special_keyword.empty()
            && ptIt->second.special_keyword != "OFF" && !ptIt->second.special_variants.empty() )
        {
            int idx = std::max( 0, opc.flags2 );
            idx = std::min( idx, static_cast<int>( ptIt->second.special_variants.size() ) - 1 );
            const PADS_SCH::PARTTYPE_DEF::SPECIAL_VARIANT& variant = ptIt->second.special_variants[idx];
 
            if( !PADS_SCH::PADS_SCH_SYMBOL_BUILDER::GetPowerStyleFromVariant( variant.decal_name, variant.pin_type )
                         .empty() )
            {
                powerSignalNames.insert( opc.signal_name );
            }
        }
    }
 
    // Build set of OPC reference IDs for non-power signal OPCs. Each entry
    // corresponds to a wire endpoint reference like "@@@O48" that should receive
    // its own global label with orientation derived from the wire direction.
    std::set<std::string> signalOpcIds;
 
    for( const PADS_SCH::OFF_PAGE_CONNECTOR& opc : parser.GetOffPageConnectors() )
    {
        if( opc.signal_name.empty() || powerSignalNames.count( opc.signal_name ) )
            continue;
 
        signalOpcIds.insert( "@@@O" + std::to_string( opc.id ) );
    }
 
    // Map each off-page anchor (@@@O..) to its *NETNAMES* entry. PADS authors the label
    // side there, which is the authoritative orientation when the stub wire is degenerate.
    std::map<std::string, PADS_SCH::NETNAME_LABEL> netNameLabels;
 
    for( const PADS_SCH::NETNAME_LABEL& nn : parser.GetNetNameLabels() )
    {
        if( !nn.anchor_ref.empty() )
            netNameLabels[nn.anchor_ref] = nn;
    }
 
    // PADS power ports carry no reference designator, so the importer invents one
    // A per-sheet counter restarts at #PWR0001 on sheet two and collides
    int pwrIndex = aAppendToMe ? PADS_SCH::PADS_SCH_SYMBOL_BUILDER::NextFreePowerOrdinal( aAppendToMe ) : 1;
 
    // Create wires and connectivity on each sheet
    for( auto& [sheetNum, ctx] : sheetContexts )
    {
        std::vector<PADS_SCH::SCH_SIGNAL> sheetSignals = parser.GetSignalsOnSheet( sheetNum );
 
        // Create wire segments from vertex data
        for( const PADS_SCH::SCH_SIGNAL& signal : sheetSignals )
        {
            for( const PADS_SCH::WIRE_SEGMENT& wire : signal.wires )
            {
                if( wire.vertices.size() < 2 )
                    continue;
 
                // Each consecutive pair of vertices becomes a wire segment
                for( size_t v = 0; v + 1 < wire.vertices.size(); v++ )
                {
                    VECTOR2I start( schIUScale.MilsToIU( KiROUND( wire.vertices[v].x ) ),
                                    pageHeightIU - schIUScale.MilsToIU( KiROUND( wire.vertices[v].y ) ) );
                    VECTOR2I end( schIUScale.MilsToIU( KiROUND( wire.vertices[v + 1].x ) ),
                                  pageHeightIU - schIUScale.MilsToIU( KiROUND( wire.vertices[v + 1].y ) ) );
 
                    if( start == end )
                        continue;
 
                    SCH_LINE* line = new SCH_LINE( start, SCH_LAYER_ID::LAYER_WIRE );
                    line->SetEndPoint( end );
                    line->SetConnectivityDirty();
                    ctx.screen->Append( line );
                }
            }
        }
 
        // Create local labels at wire endpoints that reference connector pins
        for( const PADS_SCH::SCH_SIGNAL& signal : sheetSignals )
        {
            for( const PADS_SCH::WIRE_SEGMENT& wire : signal.wires )
            {
                if( wire.vertices.size() < 2 )
                    continue;
 
                // Check endpoint_a for connector pin reference
                if( wire.endpoint_a.find( '.' ) != std::string::npos
                    && wire.endpoint_a.find( "@@@" ) == std::string::npos )
                {
                    size_t      dotPos = wire.endpoint_a.find( '.' );
                    std::string ref = wire.endpoint_a.substr( 0, dotPos );
 
                    if( connectorBaseRefs.count( ref ) )
                    {
                        const PADS_SCH::POINT& vtx = wire.vertices.front();
                        VECTOR2I               pos( schIUScale.MilsToIU( KiROUND( vtx.x ) ),
                                                    pageHeightIU - schIUScale.MilsToIU( KiROUND( vtx.y ) ) );
 
                        // Compute label orientation from adjacent vertex
                        const PADS_SCH::POINT& adj = wire.vertices[1];
                        VECTOR2I               adjPos( schIUScale.MilsToIU( KiROUND( adj.x ) ),
                                                       pageHeightIU - schIUScale.MilsToIU( KiROUND( adj.y ) ) );
 
                        SPIN_STYLE orient =
                                PADS_SCH::PADS_SCH_SCHEMATIC_BUILDER::computeLabelOrientation( pos, adjPos );
 
                        wxString   labelText = wxString::FromUTF8( wire.endpoint_a );
                        SCH_LABEL* label = new SCH_LABEL( pos, labelText );
                        int        labelSize = schIUScale.MilsToIU( 50 );
                        label->SetTextSize( VECTOR2I( labelSize, labelSize ) );
                        label->SetSpinStyle( orient );
                        label->SetFlags( IS_NEW );
                        ctx.screen->Append( label );
                    }
                }
 
                // Check endpoint_b for connector pin reference
                if( wire.endpoint_b.find( '.' ) != std::string::npos
                    && wire.endpoint_b.find( "@@@" ) == std::string::npos )
                {
                    size_t      dotPos = wire.endpoint_b.find( '.' );
                    std::string ref = wire.endpoint_b.substr( 0, dotPos );
 
                    if( connectorBaseRefs.count( ref ) )
                    {
                        const PADS_SCH::POINT& vtx = wire.vertices.back();
                        VECTOR2I               pos( schIUScale.MilsToIU( KiROUND( vtx.x ) ),
                                                    pageHeightIU - schIUScale.MilsToIU( KiROUND( vtx.y ) ) );
 
                        // Compute label orientation from adjacent vertex
                        size_t                  lastIdx = wire.vertices.size() - 1;
                        const PADS_SCH::POINT& adj = wire.vertices[lastIdx - 1];
                        VECTOR2I               adjPos( schIUScale.MilsToIU( KiROUND( adj.x ) ),
                                                       pageHeightIU - schIUScale.MilsToIU( KiROUND( adj.y ) ) );
 
                        SPIN_STYLE orient =
                                PADS_SCH::PADS_SCH_SCHEMATIC_BUILDER::computeLabelOrientation( pos, adjPos );
 
                        wxString   labelText = wxString::FromUTF8( wire.endpoint_b );
                        SCH_LABEL* label = new SCH_LABEL( pos, labelText );
                        int        labelSize = schIUScale.MilsToIU( 50 );
                        label->SetTextSize( VECTOR2I( labelSize, labelSize ) );
                        label->SetSpinStyle( orient );
                        label->SetFlags( IS_NEW );
                        ctx.screen->Append( label );
                    }
                }
            }
        }
 
        // Create junctions from TIEDOTS for this sheet
        for( const PADS_SCH::TIED_DOT& dot : parser.GetTiedDots() )
        {
            if( dot.sheet_number != sheetNum )
                continue;
 
            VECTOR2I pos( schIUScale.MilsToIU( KiROUND( dot.position.x ) ),
                          pageHeightIU - schIUScale.MilsToIU( KiROUND( dot.position.y ) ) );
 
            SCH_JUNCTION* junction = new SCH_JUNCTION( pos );
            ctx.screen->Append( junction );
        }
 
        // Create net labels, skipping power nets that get dedicated symbols
        schBuilder.CreateNetLabels( sheetSignals, ctx.screen, signalOpcIds, powerSignalNames, netNameLabels );
 
        // Place off-page connectors: power/ground types become SCH_SYMBOL with
        // KiCad standard power graphics; signal types become SCH_GLOBALLABEL.
        for( const PADS_SCH::OFF_PAGE_CONNECTOR& opc : parser.GetOffPageConnectors() )
        {
            if( opc.source_sheet != sheetNum )
                continue;
 
            if( opc.signal_name.empty() )
                continue;
 
            VECTOR2I pos( schIUScale.MilsToIU( KiROUND( opc.position.x ) ),
                          pageHeightIU - schIUScale.MilsToIU( KiROUND( opc.position.y ) ) );
 
            // Resolve power style from the PARTTYPE variant definition
            std::string powerStyle;
            auto        opcPtIt = parser.GetPartTypes().find( opc.symbol_lib );
 
            if( opcPtIt != parser.GetPartTypes().end() && !opcPtIt->second.special_keyword.empty()
                && opcPtIt->second.special_keyword != "OFF" && !opcPtIt->second.special_variants.empty() )
            {
                int idx = std::max( 0, opc.flags2 );
                idx = std::min( idx, static_cast<int>( opcPtIt->second.special_variants.size() ) - 1 );
                const PADS_SCH::PARTTYPE_DEF::SPECIAL_VARIANT& variant = opcPtIt->second.special_variants[idx];
 
                powerStyle = PADS_SCH::PADS_SCH_SYMBOL_BUILDER::GetPowerStyleFromVariant( variant.decal_name,
                                                                                          variant.pin_type );
            }
 
            if( !powerStyle.empty() )
            {
                LIB_SYMBOL* pwrSym = symbolBuilder.BuildKiCadPowerSymbol( powerStyle );
 
                if( pwrSym )
                {
                    std::unique_ptr<SCH_SYMBOL> symbol = std::make_unique<SCH_SYMBOL>();
 
                    std::optional<LIB_ID> libId =
                            PADS_SCH::PADS_SCH_SYMBOL_BUILDER::GetKiCadPowerSymbolId( opc.signal_name );
 
                    if( !libId.has_value() )
                        libId = LIB_ID( wxT( "power" ), wxString::FromUTF8( powerStyle ) );
 
                    symbol->SetLibId( libId.value() );
                    symbol->SetLibSymbol( pwrSym );
                    symbol->SetPosition( pos );
                    symbol->SetUnit( 1 );
 
                    // VCC and PWR_TRIANGLE have pin pointing up (body above pin).
                    // All others (GND, GNDD, PWR_BAR, VEE, Earth) have pin pointing down.
                    bool pinUp = ( powerStyle == "VCC" || powerStyle == "PWR_TRIANGLE" );
                    int  orient =
                            computePowerOrientation( std::to_string( opc.id ), sheetSignals, pos, pinUp, pageHeightIU );
 
                    symbol->SetOrientation( orient );
 
                    wxString netName = wxString::FromUTF8( opc.signal_name );
 
                    if( netName.StartsWith( wxT( "/" ) ) )
                        netName = wxT( "~{" ) + netName.Mid( 1 ) + wxT( "}" );
 
                    symbol->GetField( FIELD_T::VALUE )->SetText( netName );
                    symbol->GetField( FIELD_T::VALUE )->SetVisible( true );
 
                    wxString pwrRef = wxString::Format( wxT( "#PWR%04d" ), pwrIndex++ );
                    symbol->SetRef( &ctx.path, pwrRef );
                    symbol->GetField( FIELD_T::REFERENCE )->SetVisible( false );
 
                    symbol->ClearFlags();
                    ctx.screen->Append( symbol.release() );
                }
            }
 
            // Non-power signal OPCs don't create labels here.  CreateNetLabels
            // handles all signal net labels, placing them at dangling wire endpoints
            // rather than at OPC positions (which may not land on a wire).
        }
    }
 
    // Resolve a parsed item's sheet number to its screen, falling back to the
    // first sheet when the number is unknown. Each *SHT* section in PADS Logic
    // is followed by its own *TEXT* and *LINES* blocks, so items are tagged with
    // the sheet number current at parse time.
    auto screenForSheet = [&]( int aSheetNumber ) -> SCH_SCREEN*
    {
        auto ctxIt = sheetContexts.find( aSheetNumber );
 
        return ctxIt != sheetContexts.end() ? ctxIt->second.screen : sheetContexts.begin()->second.screen;
    };
 
    // Place free text items from *TEXT* section on the correct sheet.
    if( !sheetContexts.empty() )
    {
        for( const PADS_SCH::TEXT_ITEM& textItem : parser.GetTextItems() )
        {
            if( textItem.content.empty() )
                continue;
 
            SCH_SCREEN* textScreen = screenForSheet( textItem.sheet_number );
 
            VECTOR2I pos( schIUScale.MilsToIU( KiROUND( textItem.position.x ) ),
                          pageHeightIU - schIUScale.MilsToIU( KiROUND( textItem.position.y ) ) );
 
            textScreen->Append( createSchText( textItem, pos ) );
        }
    }
 
    // Place graphic lines from *LINES* section (skip the border template) on
    // the sheet they belong to.
    if( !sheetContexts.empty() )
    {
        for( const PADS_SCH::LINES_ITEM& linesItem : parser.GetLinesItems() )
        {
            if( linesItem.name == params.border_template )
                continue;
 
            SCH_SCREEN* linesScreen = screenForSheet( linesItem.sheet_number );
 
            double ox = linesItem.origin.x;
            double oy = linesItem.origin.y;
 
            for( const PADS_SCH::SYMBOL_GRAPHIC& prim : linesItem.primitives )
                appendGraphicPrimitive( linesScreen, prim, ox, oy, pageHeightIU );
 
            // Render text items within this LINES group
            for( const PADS_SCH::TEXT_ITEM& textItem : linesItem.texts )
            {
                if( textItem.content.empty() )
                    continue;
 
                VECTOR2I pos( schIUScale.MilsToIU( KiROUND( ox + textItem.position.x ) ),
                              pageHeightIU - schIUScale.MilsToIU( KiROUND( oy + textItem.position.y ) ) );
 
                linesScreen->Append( createSchText( textItem, pos ) );
            }
        }
    }
 
    // Set title block from parsed parameters
    schBuilder.CreateTitleBlock( rootScreen );
 
    // Finalize all sheets
    SCH_SCREENS allSheets( rootSheet );
    allSheets.UpdateSymbolLinks();
    allSheets.ClearEditFlags();
 
    if( m_reporter )
    {
        for( const auto& [msg, severity] : m_errorMessages )
            m_reporter->Report( msg, severity );
    }
 
    m_errorMessages.clear();
 
    return rootSheet;
}
 
 
SCH_SHEET* SCH_IO_PADS::loadBinarySchematicFile( const wxString& aFileName, SCHEMATIC* aSchematic,
                                                 SCH_SHEET*                         aAppendToMe,
                                                 const std::map<std::string, UTF8>* aProperties )
{
    std::vector<uint8_t> data;
 
    if( !PADS_SCH_BINARY::PADS_SCH_BINARY_READER::ReadFile( aFileName, data ) )
        THROW_IO_ERROR( wxString::Format( _( "Cannot read file '%s'." ), aFileName ) );
 
    PADS_SCH_BINARY::PADS_SCH_BINARY_READER reader;
 
    if( !reader.Parse( data, aFileName ) )
        THROW_IO_ERROR( wxString::Format( _( "'%s' is not a valid PADS Logic binary schematic." ), aFileName ) );
 
    PADS_SCH_BINARY::BUILD_RESULT result = reader.BuildSchematic( aSchematic, aAppendToMe, aFileName );
 
    if( m_reporter )
    {
        using DIAGNOSTIC = PADS_SCH_BINARY::PARSER_DIAGNOSTIC;
        std::map<std::pair<wxString, SEVERITY>, std::pair<const DIAGNOSTIC*, size_t>> diagnostics;
        auto collectDiagnostics = [&]( const std::vector<DIAGNOSTIC>& aDiagnostics )
        {
            for( const DIAGNOSTIC& diagnostic : aDiagnostics )
            {
                auto& [first, count] = diagnostics[{ diagnostic.message, diagnostic.severity }];
 
                if( !first )
                    first = &diagnostic;
 
                ++count;
            }
        };
 
        collectDiagnostics( reader.GetModel().diagnostics );
        collectDiagnostics( result.diagnostics );
 
        for( const auto& [key, group] : diagnostics )
        {
            const auto& [message, severity] = key;
            const auto& [first, count] = group;
            wxString report = message;
 
            if( count > 1 )
                report += wxString::Format( _( " (%zu occurrences)" ), count );
 
            m_reporter->Report( PADS_SCH_BINARY::FormatParserError( first->source, report ), severity );
        }
 
        wxLogTrace( tracePadsIo,
                    wxS( "Imported PADS Logic binary schematic '%s': %zu sheets, %zu symbols, %zu wires, %zu buses, "
                         "%zu bus entries, %zu junctions, %zu labels, %zu texts, %zu graphics, %zu images." ),
                    aFileName, result.counts.sheets, result.counts.symbols, result.counts.wires, result.counts.buses,
                    result.counts.busEntries, result.counts.junctions, result.counts.labels, result.counts.texts,
                    result.counts.graphics, result.counts.images );
    }
 
    return aAppendToMe ? aAppendToMe : aSchematic->GetTopLevelSheet();
}
 
 
void SCH_IO_PADS::EnumerateSymbolLib( wxArrayString& aSymbolNameList, const wxString& aLibraryPath,
                                      const std::map<std::string, UTF8>* aProperties )
{
    ensureLoadedLibrary( aLibraryPath );
 
    bool powerSymbolsOnly = aProperties && aProperties->contains( SYMBOL_LIBRARY_ADAPTER::PropPowerSymsOnly );
 
    for( const auto& [name, symbol] : m_librarySymbols )
    {
        if( powerSymbolsOnly && !symbol->IsPower() )
            continue;
 
        aSymbolNameList.Add( name );
    }
}
 
 
void SCH_IO_PADS::EnumerateSymbolLib( std::vector<LIB_SYMBOL*>& aSymbolList, const wxString& aLibraryPath,
                                      const std::map<std::string, UTF8>* aProperties )
{
    ensureLoadedLibrary( aLibraryPath );
 
    bool powerSymbolsOnly = aProperties && aProperties->contains( SYMBOL_LIBRARY_ADAPTER::PropPowerSymsOnly );
 
    for( const auto& [name, symbol] : m_librarySymbols )
    {
        if( powerSymbolsOnly && !symbol->IsPower() )
            continue;
 
        aSymbolList.push_back( symbol.get() );
    }
}
 
 
LIB_SYMBOL* SCH_IO_PADS::LoadSymbol( const wxString& aLibraryPath, const wxString& aPartName,
                                     const std::map<std::string, UTF8>* aProperties )
{
    ensureLoadedLibrary( aLibraryPath );
 
    auto it = m_librarySymbols.find( aPartName );
 
    if( it != m_librarySymbols.end() )
        return it->second.get();
 
    return nullptr;
}
 
 
long long SCH_IO_PADS::getLibraryTimestamp( const wxString& aLibraryPath ) const
{
    wxFileName fn( aLibraryPath );
 
    if( fn.IsFileReadable() && fn.GetModificationTime().IsValid() )
        return fn.GetModificationTime().GetValue().GetValue();
 
    return 0;
}
 
 
void SCH_IO_PADS::ensureLoadedLibrary( const wxString& aLibraryPath )
{
    long long timestamp = getLibraryTimestamp( aLibraryPath );
 
    if( m_libraryCacheValid && aLibraryPath == m_cachedLibraryPath && timestamp == m_cachedLibraryTimestamp )
    {
        return;
    }
 
    m_librarySymbols.clear();
    m_libraryCacheValid = false;
    m_cachedLibraryPath = aLibraryPath;
    m_cachedLibraryTimestamp = timestamp;
 
    if( !checkFileHeader( aLibraryPath ) )
        THROW_IO_ERRORF( _( "'%s' is not a PADS Logic ASCII file." ), aLibraryPath );
 
    LOCALE_IO setlocale;
 
    PADS_SCH::PADS_SCH_PARSER parser;
    std::string               filename( aLibraryPath.ToUTF8() );
 
    if( !parser.Parse( filename ) )
        THROW_IO_ERRORF( _( "Failed to parse PADS Logic file '%s'." ), aLibraryPath );
 
    const PADS_SCH::PARAMETERS&       params = parser.GetParameters();
    PADS_SCH::PADS_SCH_SYMBOL_BUILDER symbolBuilder( params );
 
    std::set<std::string> referencedDecals;
 
    // Build a LIB_SYMBOL per PARTTYPE: multi-gate parts become multi-unit symbols,
    // single-gate parts apply PARTTYPE pin overrides to the CAEDECAL graphics,
    // and power/ground special variants are skipped (they map to KiCad power lib).
    for( const auto& [ptName, ptDef] : parser.GetPartTypes() )
    {
        if( !ptDef.special_keyword.empty() && ptDef.special_keyword != "OFF" )
            continue;
 
        LIB_SYMBOL* built = nullptr;
        wxString    libName = wxString::FromUTF8( ptDef.name );
 
        if( ptDef.gates.size() > 1 )
        {
            built = symbolBuilder.BuildMultiUnitSymbol( ptDef, parser.GetSymbolDefs() );
 
            for( const PADS_SCH::GATE_DEF& gate : ptDef.gates )
            {
                for( const std::string& decalName : gate.decal_names )
                    referencedDecals.insert( decalName );
            }
        }
        else if( !ptDef.gates.empty() )
        {
            const PADS_SCH::GATE_DEF& gate = ptDef.gates[0];
            std::string               decalName;
 
            if( !gate.decal_names.empty() )
                decalName = gate.decal_names[0];
 
            const PADS_SCH::SYMBOL_DEF* symDef = parser.GetSymbolDef( decalName );
 
            if( symDef && ptDef.is_connector && !gate.pins.empty() )
            {
                // Connectors declare one CAEDECAL shared by every pin. Build a
                // multi-unit library symbol so each PARTTYPE pin is representable
                // without assuming a particular schematic placement grouping.
                std::vector<std::string> pinNumbers;
                pinNumbers.reserve( gate.pins.size() );
 
                for( const PADS_SCH::PARTTYPE_PIN& pin : gate.pins )
                    pinNumbers.push_back( pin.pin_id );
 
                built = symbolBuilder.BuildMultiUnitConnectorSymbol( ptDef, *symDef, pinNumbers );
                referencedDecals.insert( decalName );
            }
            else if( symDef )
            {
                // GetOrCreatePartTypeSymbol caches inside the builder and returns a
                // non-owning pointer; clone it so the library owns its own copy.
                LIB_SYMBOL* cached = symbolBuilder.GetOrCreatePartTypeSymbol( ptDef, *symDef );
 
                if( cached )
                    built = new LIB_SYMBOL( *cached );
 
                referencedDecals.insert( decalName );
            }
        }
 
        if( !built )
            continue;
 
        built->SetName( libName );
 
        if( !ptDef.sigpins.empty() )
            symbolBuilder.AddHiddenPowerPins( built, ptDef.sigpins );
 
        m_librarySymbols[libName] = std::unique_ptr<LIB_SYMBOL>( built );
    }
 
    // Also expose any CAEDECAL entries that no PARTTYPE referenced, so the user
    // still sees orphan decal graphics that ship with the PADS library.
    for( const PADS_SCH::SYMBOL_DEF& symDef : parser.GetSymbolDefs() )
    {
        if( referencedDecals.count( symDef.name ) )
            continue;
 
        wxString libName = wxString::FromUTF8( symDef.name );
 
        if( libName.IsEmpty() || m_librarySymbols.count( libName ) )
            continue;
 
        LIB_SYMBOL* built = symbolBuilder.BuildSymbol( symDef );
 
        if( !built )
            continue;
 
        m_librarySymbols[libName] = std::unique_ptr<LIB_SYMBOL>( built );
    }
 
    m_libraryCacheValid = true;
}
 
 
bool SCH_IO_PADS::checkFileHeader( const wxString& aFileName ) const
{
    try
    {
        std::ifstream file( aFileName.fn_str() );
 
        if( !file.is_open() )
            return false;
 
        std::string line;
 
        if( std::getline( file, line ) )
        {
            if( line.find( "*PADS-POWERLOGIC" ) != std::string::npos )
                return true;
 
            if( line.find( "*PADS-LOGIC" ) != std::string::npos )
                return true;
        }
    }
    catch( ... )
    {
        // An unreadable or short file is simply not an ASCII PADS schematic; fall through to the
        // binary probe rather than surface the error.
    }
 
    return false;
}
 
 
bool SCH_IO_PADS::isBinarySchematicFile( const wxString& aFileName ) const
{
    try
    {
        std::vector<uint8_t> header;
 
        // Recognition intentionally does not test the version.  A PADS binary from an unsupported
        // producer belongs to this importer and must receive the binary parser's version diagnostic.
        return PADS_IO::ReadFileHeader( aFileName, header, 2 )
               && PADS_SCH_BINARY::PADS_SCH_BINARY_READER::IsBinaryFamily( header );
    }
    catch( ... )
    {
        // An unreadable or malformed file is not a binary PADS schematic, so the probe is false.
    }
 
    return false;
}