footprint.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2015 Jean-Pierre Charras, jp.charras at wanadoo.fr
 * Copyright The 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 2
 * 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/>.
 */
 
#ifndef FOOTPRINT_H
#define FOOTPRINT_H
 
#include <deque>
#include <map>
#include <memory>
#include <mutex>
#include <optional>
#include <unordered_set>
 
#include <template_fieldnames.h>
 
#include <board_item_container.h>
#include <board_item.h>
#include <embedded_files.h>
#include <layer_ids.h> // ALL_LAYERS definition.
#include <lset.h>
#include <lib_id.h>
#include <lib_tree_item.h>
#include <list>
 
#include <zones.h>
#include <convert_shape_list_to_polygon.h>
#include <pcb_item_containers.h>
#include <pcb_field.h>
#include <functional>
#include <math/vector3.h>
#include <case_insensitive_map.h>
#include <geometry/transform_trs.h>
#include <gal/color4d.h>
 
class LINE_READER;
class EDA_3D_CANVAS;
class PAD;
class BOARD;
class COMPONENT_CLASS;
class GENERAL_COLLECTOR;
class MSG_PANEL_ITEM;
class SHAPE;
class REPORTER;
class COMPONENT_CLASS_CACHE_PROXY;
class PCB_FOOTPRINT_FIELD_PROPERTY;
class PCB_POINT;
 
namespace KIGFX {
class VIEW;
}
 
namespace KIFONT {
class OUTLINE_FONT;
}

enum FOOTPRINT_ATTR_T
{
    FP_THROUGH_HOLE             = 0x0001,
    FP_SMD                      = 0x0002,
    FP_EXCLUDE_FROM_POS_FILES   = 0x0004,
    FP_EXCLUDE_FROM_BOM         = 0x0008,
    FP_BOARD_ONLY               = 0x0010,   // Footprint has no corresponding symbol
    FP_JUST_ADDED               = 0x0020,   // Footprint just added by netlist update
    FP_DNP                      = 0x0040,
    FP_EXCLUDE_FROM_SIM         = 0x0080
};
 
 
enum class FOOTPRINT_TYPE
{
    UNSPECIFIED,
    THROUGH_HOLE,
    SMD
};
 
 
enum class EXTRUSION_MATERIAL
{
    PLASTIC = 0,
    MATTE,
    METAL,
    COPPER
};
 
class EXTRUDED_3D_BODY
{
public:
    EXTRUDED_3D_BODY() = default;
 
    int                m_height = 0;
    int                m_standoff = 0;
    PCB_LAYER_ID       m_layer = UNDEFINED_LAYER;
    KIGFX::COLOR4D     m_color = KIGFX::COLOR4D::UNSPECIFIED;
    EXTRUSION_MATERIAL m_material = EXTRUSION_MATERIAL::PLASTIC;
    bool               m_show = true;
 
    VECTOR3D m_scale{ 1.0, 1.0, 1.0 };
    VECTOR3D m_rotation{ 0.0, 0.0, 0.0 };
    VECTOR3D m_offset{ 0.0, 0.0, 0.0 };
 
    static KIGFX::COLOR4D GetDefaultColor( EXTRUSION_MATERIAL aMaterial )
    {
        switch( aMaterial )
        {
        default:
        case EXTRUSION_MATERIAL::PLASTIC: return KIGFX::COLOR4D( 0.2, 0.2, 0.2, 1.0 );
        case EXTRUSION_MATERIAL::MATTE: return KIGFX::COLOR4D( 0.4, 0.4, 0.4, 1.0 );
        case EXTRUSION_MATERIAL::METAL: return KIGFX::COLOR4D( 0.7, 0.7, 0.7, 1.0 );
        case EXTRUSION_MATERIAL::COPPER: return KIGFX::COLOR4D( 0.72, 0.45, 0.2, 1.0 );
        }
    }
 
    bool operator==( const EXTRUDED_3D_BODY& aOther ) const
    {
        return m_height == aOther.m_height && m_standoff == aOther.m_standoff && m_layer == aOther.m_layer
               && m_color == aOther.m_color && m_material == aOther.m_material && m_scale == aOther.m_scale
               && m_rotation == aOther.m_rotation && m_offset == aOther.m_offset && m_show == aOther.m_show;
    }
 
    static uint32_t PackColorKey( const KIGFX::COLOR4D& aColor )
    {
        return ( (uint8_t) ( aColor.r * 255 ) << 24 ) | ( (uint8_t) ( aColor.g * 255 ) << 16 )
               | ( (uint8_t) ( aColor.b * 255 ) << 8 ) | (uint8_t) ( aColor.a * 255 );
    }
};
 
enum class FOOTPRINT_STACKUP
{
    EXPAND_INNER_LAYERS,
    CUSTOM_LAYERS,
};
 
class FP_3DMODEL
{
public:
    FP_3DMODEL() :
        // Initialize with sensible values
        m_Scale { 1, 1, 1 },
        m_Rotation { 0, 0, 0 },
        m_Offset { 0, 0, 0 },
        m_Opacity( 1.0 ),
        m_Show( true )
    {
    }
 
    VECTOR3D m_Scale;       
    VECTOR3D m_Rotation;    
    VECTOR3D m_Offset;      
    double   m_Opacity;
    wxString m_Filename;    
    bool     m_Show;        
 
    bool operator==( const FP_3DMODEL& aOther ) const
    {
        return m_Scale == aOther.m_Scale
                && m_Rotation == aOther.m_Rotation
                && m_Offset == aOther.m_Offset
                && m_Opacity == aOther.m_Opacity
                && m_Filename == aOther.m_Filename
                && m_Show == aOther.m_Show;
    }
};
 
 
struct FOOTPRINT_COURTYARD_CACHE_DATA
{
    SHAPE_POLY_SET front;  // Note that a footprint can have both front and back courtyards populated.
    SHAPE_POLY_SET back;
    HASH_128       front_hash;
    HASH_128       back_hash;
};
 
 
struct FOOTPRINT_GEOMETRY_CACHE_DATA
{
    BOX2I          bounding_box;
    int            bounding_box_timestamp = 0;
    BOX2I          text_excluded_bbox;
    int            text_excluded_bbox_timestamp = 0;
    SHAPE_POLY_SET hull;
    int            hull_timestamp = 0;
};
 

class FOOTPRINT_VARIANT
{
public:
    FOOTPRINT_VARIANT( const wxString& aName = wxEmptyString ) :
            m_name( aName ),
            m_dnp( false ),
            m_excludedFromBOM( false ),
            m_excludedFromSim( false ),
            m_excludedFromPosFiles( false )
    {
    }
 
    wxString GetName() const { return m_name; }
    void SetName( const wxString& aName ) { m_name = aName; }
 
    bool GetDNP() const { return m_dnp; }
    void SetDNP( bool aDNP ) { m_dnp = aDNP; }
 
    bool GetExcludedFromBOM() const { return m_excludedFromBOM; }
    void SetExcludedFromBOM( bool aExclude ) { m_excludedFromBOM = aExclude; }
 
    bool GetExcludedFromSim() const { return m_excludedFromSim; }
    void SetExcludedFromSim( bool aExclude ) { m_excludedFromSim = aExclude; }
 
    bool GetExcludedFromPosFiles() const { return m_excludedFromPosFiles; }
    void SetExcludedFromPosFiles( bool aExclude ) { m_excludedFromPosFiles = aExclude; }

    wxString GetFieldValue( const wxString& aFieldName ) const
    {
        auto it = m_fields.find( aFieldName );
 
        if( it != m_fields.end() )
            return it->second;
 
        return wxString();
    }

    void SetFieldValue( const wxString& aFieldName, const wxString& aValue )
    {
        m_fields[aFieldName] = aValue;
    }

    void RemoveFieldValue( const wxString& aFieldName )
    {
        m_fields.erase( aFieldName );
    }
 
    bool HasFieldValue( const wxString& aFieldName ) const
    {
        return m_fields.find( aFieldName ) != m_fields.end();
    }
 
    const std::map<wxString, wxString>& GetFields() const { return m_fields; }
 
    bool operator==( const FOOTPRINT_VARIANT& aOther ) const
    {
        return m_name == aOther.m_name
                && m_dnp == aOther.m_dnp
                && m_excludedFromBOM == aOther.m_excludedFromBOM
                && m_excludedFromSim == aOther.m_excludedFromSim
                && m_excludedFromPosFiles == aOther.m_excludedFromPosFiles
                && m_fields == aOther.m_fields;
    }
 
private:
    wxString                     m_name;
    bool                         m_dnp;
    bool                         m_excludedFromBOM;
    bool                         m_excludedFromSim;
    bool                         m_excludedFromPosFiles;
    std::map<wxString, wxString> m_fields;  
};
 
 
class FOOTPRINT : public BOARD_ITEM_CONTAINER, public EMBEDDED_FILES, public LIB_TREE_ITEM
{
public:
    FOOTPRINT( BOARD* parent );
 
    FOOTPRINT( const FOOTPRINT& aFootprint );
 
    // Move constructor and operator needed due to std containers inside the footprint
    FOOTPRINT( FOOTPRINT&& aFootprint );
 
    ~FOOTPRINT();
 
    FOOTPRINT& operator=( const FOOTPRINT& aOther );
    FOOTPRINT& operator=( FOOTPRINT&& aOther );
 
    void CopyFrom( const BOARD_ITEM* aOther ) override;
 
    void Serialize( google::protobuf::Any &aContainer ) const override;
    bool Deserialize( const google::protobuf::Any &aContainer ) override;
 
    static inline bool ClassOf( const EDA_ITEM* aItem )
    {
        return aItem && aItem->Type() == PCB_FOOTPRINT_T;
    }

    void InvalidateGeometryCaches();
 
    LSET GetPrivateLayers() const { return m_privateLayers; }
    void SetPrivateLayers( const LSET& aLayers ) { m_privateLayers = aLayers; }

    void Add( BOARD_ITEM* aItem, ADD_MODE aMode = ADD_MODE::INSERT,
              bool aSkipConnectivity = false ) override;

    void Remove( BOARD_ITEM* aItem, REMOVE_MODE aMode = REMOVE_MODE::NORMAL ) override;

    void ClearAllNets();

    bool FixUuids();

    BOX2I GetFpPadsLocalBbox() const;

    SHAPE_POLY_SET GetBoundingHull() const;
    SHAPE_POLY_SET GetBoundingHull( PCB_LAYER_ID aLayer ) const;
 
    bool TextOnly() const;
 
    // Virtual function
    const BOX2I GetBoundingBox() const override;
    const BOX2I GetBoundingBox( bool aIncludeText ) const;

    const BOX2I GetLayerBoundingBox( const LSET& aLayers ) const;
 
    VECTOR2I GetCenter() const override { return GetBoundingBox( false ).GetCenter(); }
 
    std::deque<PAD*>& Pads()               { return m_pads; }
    const std::deque<PAD*>& Pads() const   { return m_pads; }
 
    DRAWINGS& GraphicalItems()             { return m_drawings; }
    const DRAWINGS& GraphicalItems() const { return m_drawings; }
 
    ZONES& Zones()                         { return m_zones; }
    const ZONES& Zones() const             { return m_zones; }
 
    GROUPS& Groups()                       { return m_groups; }
    const GROUPS& Groups() const           { return m_groups; }
 
    CONSTRAINTS& Constraints()             { return m_constraints; }
    const CONSTRAINTS& Constraints() const { return m_constraints; }
 
    PCB_POINTS& Points()                   { return m_points; }
    const PCB_POINTS& Points() const       { return m_points; }
 
    bool HasThroughHolePads() const;
 
    std::vector<FP_3DMODEL>& Models()             { return m_3D_Drawings; }
    const std::vector<FP_3DMODEL>& Models() const { return m_3D_Drawings; }
 
    bool                    HasExtrudedBody() const { return m_extrudedBody != nullptr; }
    const EXTRUDED_3D_BODY* GetExtrudedBody() const { return m_extrudedBody.get(); }
    EXTRUDED_3D_BODY*       GetExtrudedBody() { return m_extrudedBody.get(); }
    EXTRUDED_3D_BODY&       EnsureExtrudedBody();
    void                    SetExtrudedBody( std::unique_ptr<EXTRUDED_3D_BODY> aBody );
    void                    ClearExtrudedBody() { m_extrudedBody.reset(); }
 
    void     SetPosition( const VECTOR2I& aPos ) override;
    VECTOR2I GetPosition() const override { return m_transform.GetTranslate(); }
 
    void SetOrientation( const EDA_ANGLE& aNewAngle );
    EDA_ANGLE GetOrientation() const { return m_transform.GetRotate(); }

    void SetLayerAndFlip( PCB_LAYER_ID aLayer );
 
    void SetLayer( PCB_LAYER_ID aLayer ) override;
 
    // A footprint's m_layer is set to F_Cu or B_Cu to encode which side of the board it's on.
    PCB_LAYER_ID GetLayer() const override { return m_layer; }
 
    const TRANSFORM_TRS& GetTransform() const { return m_transform; }
 
    void SetTransformScale( double aScaleX, double aScaleY );
 
    double GetScaleX() const { return m_transform.GetScaleX(); }
    double GetScaleY() const { return m_transform.GetScaleY(); }
 
    void SetScaleX( double aScaleX ) { SetTransformScale( aScaleX, m_transform.GetScaleY() ); }
 
    void SetScaleY( double aScaleY ) { SetTransformScale( m_transform.GetScaleX(), aScaleY ); }
 
    void RescaleAroundPoint( const VECTOR2I& aCenter, double aSx, double aSy );
 
    void SetOrientationDegrees( double aOrientation )
    {
        SetOrientation( EDA_ANGLE( aOrientation, DEGREES_T ) );
    }
    double GetOrientationDegrees() const
    {
        return m_transform.GetRotate().AsDegrees();
    }
 
    const LIB_ID& GetFPID() const { return m_fpid; }
    void          SetFPID( const LIB_ID& aFPID )
    {
        m_fpid = aFPID;
    }
 
    wxString GetFPIDAsString() const { return m_fpid.Format(); }
    void SetFPIDAsString( const wxString& aFPID ) { m_fpid.Parse( aFPID ); }
 
    // LIB_TREE_ITEM interface
    LIB_ID GetLIB_ID() const override { return m_fpid; }
    wxString GetName() const override { return m_fpid.GetLibItemName(); }
    wxString GetLibNickname() const override { return m_fpid.GetLibNickname(); }
    wxString GetDesc() override { return GetLibDescription(); }
    int GetPinCount() override { return static_cast<int>( GetNumberedPadCount() ); }
    std::vector<SEARCH_TERM>& GetSearchTerms() override;
 
    wxString GetLibDescription() const { return m_libDescription; }
    void     SetLibDescription( const wxString& aDesc ) { m_libDescription = aDesc; }
 
    wxString GetKeywords() const { return m_keywords; }
    void SetKeywords( const wxString& aKeywords ) { m_keywords = aKeywords; }
 
    const KIID_PATH& GetPath() const { return m_path; }
    void SetPath( const KIID_PATH& aPath ) { m_path = aPath; }

    bool IsWithinSchematicSheet( const KIID_PATH& aSheetPath ) const;
 
    wxString GetSheetname() const { return m_sheetname; }
    void SetSheetname( const wxString& aSheetname ) { m_sheetname = aSheetname; }
 
    wxString GetSheetfile() const { return m_sheetfile; }
    void SetSheetfile( const wxString& aSheetfile ) { m_sheetfile = aSheetfile; }
 
    wxString GetFilters() const { return m_filters; }
    void SetFilters( const wxString& aFilters ) { m_filters = aFilters; }
 
    std::optional<int> GetLocalClearance() const                 { return m_clearance; }
    void SetLocalClearance( std::optional<int> aClearance )      { m_clearance = aClearance; }
 
    std::optional<int> GetLocalSolderMaskMargin() const          { return m_solderMaskMargin; }
    void SetLocalSolderMaskMargin( std::optional<int> aMargin )  { m_solderMaskMargin = aMargin; }
 
    std::optional<int> GetLocalSolderPasteMargin() const         { return m_solderPasteMargin; }
    void SetLocalSolderPasteMargin( std::optional<int> aMargin ) { m_solderPasteMargin = aMargin; }
 
    std::optional<double> GetLocalSolderPasteMarginRatio() const { return m_solderPasteMarginRatio; }
    void SetLocalSolderPasteMarginRatio( std::optional<double> aRatio ) { m_solderPasteMarginRatio = aRatio; }
 
    void SetLocalZoneConnection( ZONE_CONNECTION aType ) { m_zoneConnection = aType; }
    ZONE_CONNECTION GetLocalZoneConnection() const { return m_zoneConnection; }

    void SetStackupMode( FOOTPRINT_STACKUP aMode );
    FOOTPRINT_STACKUP GetStackupMode() const { return m_stackupMode; }

    void SetStackupLayers( LSET aLayers );
    const LSET& GetStackupLayers() const { return m_stackupLayers; }
 
    int GetAttributes() const { return m_attributes; }
    void SetAttributes( int aAttributes ) { m_attributes = aAttributes; }
 
    FOOTPRINT_TYPE GetFootprintType() const;
    void           SetFootprintType( FOOTPRINT_TYPE aFootprintType );
 
    bool AllowMissingCourtyard() const { return m_allowMissingCourtyard; }
    void SetAllowMissingCourtyard( bool aAllow ) { m_allowMissingCourtyard = aAllow; }
 
    bool AllowSolderMaskBridges() const { return m_allowSolderMaskBridges; }
    void SetAllowSolderMaskBridges( bool aAllow ) { m_allowSolderMaskBridges = aAllow; }
 
    void SetFlag( int aFlag ) { m_arflag = aFlag; }
    void IncrementFlag() { m_arflag += 1; }
    int GetFlag() const { return m_arflag; }
 
    bool IsNetTie() const
    {
        for( const wxString& group : m_netTiePadGroups )
        {
            if( !group.IsEmpty() )
                return true;
        }
 
        return false;
    }
 
    std::optional<int> GetLocalClearance( wxString* aSource ) const
    {
        if( m_clearance.has_value() && aSource )
            *aSource = wxString::Format( _( "footprint %s" ), GetReference() );
 
        return m_clearance;
    }

    std::optional<int> GetClearanceOverrides( wxString* aSource ) const
    {
        return GetLocalClearance( aSource );
    }
 
    ZONE_CONNECTION GetZoneConnectionOverrides( wxString* aSource ) const
    {
        if( m_zoneConnection != ZONE_CONNECTION::INHERITED && aSource )
            *aSource = wxString::Format( _( "footprint %s" ), GetReference() );
 
        return m_zoneConnection;
    }

    const std::vector<wxString>& GetNetTiePadGroups() const { return m_netTiePadGroups; }
 
    void ClearNetTiePadGroups()
    {
        m_netTiePadGroups.clear();
    }
 
    void AddNetTiePadGroup( const wxString& aGroup )
    {
        m_netTiePadGroups.emplace_back( aGroup );
    }

    std::map<wxString, int> MapPadNumbersToNetTieGroups() const;

    std::vector<PAD*> GetNetTiePads( PAD* aPad ) const;

    int GetLikelyAttribute() const;
 
    void Move( const VECTOR2I& aMoveVector ) override;
 
    void Rotate( const VECTOR2I& aRotCentre, const EDA_ANGLE& aAngle ) override;
 
    void Flip( const VECTOR2I& aCentre, FLIP_DIRECTION aFlipDirection ) override;

    void MoveAnchorPosition( const VECTOR2I& aMoveVector );

    bool IsFlipped() const { return GetLayer() == B_Cu; }

    PCB_LAYER_ID GetSide() const;

    bool IsOnLayer( PCB_LAYER_ID aLayer ) const override;
 
// m_footprintStatus bits:
#define FP_is_LOCKED        0x01        
#define FP_is_PLACED        0x02        
#define FP_to_PLACE         0x04        
#define FP_PADS_are_LOCKED  0x08
 
 
    bool IsLocked() const override
    {
        return ( m_fpStatus & FP_is_LOCKED ) != 0;
    }

    bool IsLayerAgnostic() const override { return true; }

    bool FitsEnabledLayers( const LSET& aEnabledLayers, int aCopperLayerCount ) const override
    {
        return GetLayer() == F_Cu || GetLayer() == B_Cu;
    }

    void SetLocked( bool isLocked ) override
    {
        if( isLocked )
            m_fpStatus |= FP_is_LOCKED;
        else
            m_fpStatus &= ~FP_is_LOCKED;
    }

    bool IsConflicting() const;
 
    bool IsPlaced() const { return m_fpStatus & FP_is_PLACED;  }
    void SetIsPlaced( bool isPlaced )
    {
        if( isPlaced )
            m_fpStatus |= FP_is_PLACED;
        else
            m_fpStatus &= ~FP_is_PLACED;
    }
 
    bool NeedsPlaced() const { return m_fpStatus & FP_to_PLACE;  }
    void SetNeedsPlaced( bool needsPlaced )
    {
        if( needsPlaced )
            m_fpStatus |= FP_to_PLACE;
        else
            m_fpStatus &= ~FP_to_PLACE;
    }
 
    bool LegacyPadsLocked() const { return m_fpStatus & FP_PADS_are_LOCKED;  }

    void CheckFootprintAttributes( const std::function<void( const wxString& )>& aErrorHandler );

    void CheckPads( UNITS_PROVIDER* aUnitsProvider,
                    const std::function<void( const PAD*, int, const wxString& )>& aErrorHandler );

    void CheckShortingPads( const std::function<void( const PAD*, const PAD*, int aErrorCode,
                                                      const VECTOR2I& )>& aErrorHandler );

    void CheckNetTies( const std::function<void( const BOARD_ITEM* aItem,
                                                 const BOARD_ITEM* bItem,
                                                 const BOARD_ITEM* cItem,
                                                 const VECTOR2I& )>& aErrorHandler );

    void CheckNetTiePadGroups( const std::function<void( const wxString& )>& aErrorHandler );
 
    void CheckClippedSilk( const std::function<void( BOARD_ITEM* aItemA,
                                                     BOARD_ITEM* aItemB,
                                                     const VECTOR2I& aPt )>& aErrorHandler );
    void BuildNetTieCache();

    const std::set<int>& GetNetTieCache( const BOARD_ITEM* aItem ) const
    {
        static const std::set<int> emptySet;
 
        auto it = m_netTieCache.find( aItem );
 
        if( it == m_netTieCache.end() )
            return emptySet;
 
        return it->second;
    }

    void TransformPadsToPolySet( SHAPE_POLY_SET& aBuffer, PCB_LAYER_ID aLayer, int aClearance,
                                 int aMaxError, ERROR_LOC aErrorLoc ) const;

    void TransformFPShapesToPolySet( SHAPE_POLY_SET& aBuffer, PCB_LAYER_ID aLayer, int aClearance,
                                     int aError, ERROR_LOC aErrorLoc,
                                     bool aIncludeText = true,
                                     bool aIncludeShapes = true,
                                     bool aIncludePrivateItems = false ) const;

    void TransformFPTextToPolySet( SHAPE_POLY_SET& aBuffer, PCB_LAYER_ID aLayer, int aClearance,
                                   int aError, ERROR_LOC aErrorLoc ) const
    {
        TransformFPShapesToPolySet( aBuffer, aLayer, aClearance, aError, aErrorLoc, true, false );
    }

    void GetContextualTextVars( wxArrayString* aVars ) const;

    bool ResolveTextVar( wxString* token, int aDepth = 0 ) const;
    bool ResolveTextVar( wxString* token, const wxString& aVariantName, int aDepth = 0 ) const;

    void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector<MSG_PANEL_ITEM>& aList ) override;
 
    bool HitTest( const VECTOR2I& aPosition, int aAccuracy = 0 ) const override;
 
    bool Matches( const EDA_SEARCH_DATA& aSearchData, void* aAuxData ) const override;

    bool HitTestAccurate( const VECTOR2I& aPosition, int aAccuracy = 0 ) const;
 
    bool HitTest( const BOX2I& aRect, bool aContained, int aAccuracy = 0 ) const override;
 
    bool HitTest( const SHAPE_LINE_CHAIN& aPoly, bool aContained ) const override;

    bool HitTestOnLayer( const VECTOR2I& aPosition, PCB_LAYER_ID aLayer, int aAccuracy = 0 ) const;
 
    bool HitTestOnLayer( const BOX2I& aRect, bool aContained, PCB_LAYER_ID aLayer, int aAccuracy = 0 ) const;

    const wxString& GetReference() const { return Reference().GetText(); }

    void SetReference( const wxString& aReference ) { Reference().SetText( aReference ); }
 
    // Property system doesn't like const references
    wxString GetReferenceAsString() const
    {
        return GetReference();
    }

    void IncrementReference( int aDelta );
 
    bool IsAnnotated() const { return !GetReference().IsEmpty() && GetReference().Last() != '?'; }

    const wxString& GetValue() const { return Value().GetText(); }

    void SetValue( const wxString& aValue ) { Value().SetText( aValue ); }
 
    // Property system doesn't like const references
    wxString GetValueAsString() const
    {
        return GetValue();
    }

    PCB_FIELD& Value()           { return *GetField( FIELD_T::VALUE ); }
    PCB_FIELD& Reference()       { return *GetField( FIELD_T::REFERENCE ); }

    const PCB_FIELD& Value() const     { return *GetField( FIELD_T::VALUE ); }
    const PCB_FIELD& Reference() const { return *GetField( FIELD_T::REFERENCE ); }
 
    //-----<Fields>-----------------------------------------------------------

    PCB_FIELD*       GetField( FIELD_T aFieldType );
    const PCB_FIELD* GetField( FIELD_T aFieldNdx ) const;

    PCB_FIELD* GetField( const wxString& aFieldName ) const;
 
    bool HasField( const wxString& aFieldName ) const;

    void GetFields( std::vector<PCB_FIELD*>& aVector, bool aVisibleOnly ) const;

    const std::deque<PCB_FIELD*>& GetFields() const { return m_fields; }
    std::deque<PCB_FIELD*>& GetFields() { return m_fields; }

    void UpdateFields( const std::vector<PCB_FIELD>& aFields, std::vector<PCB_FIELD*>& aAdded,
                       std::vector<PCB_FIELD*>& aDetached );

    int GetNextFieldOrdinal() const;

    void ApplyDefaultSettings( const BOARD& board, bool aStyleFields, bool aStyleText,
                               bool aStyleShapes, bool aStyleDimensions, bool aStyleBarcodes );
 
    struct FP_UNIT_INFO
    {
        wxString              m_unitName; // e.g. A
        std::vector<wxString> m_pins;     // pin numbers in this unit
    };
 
    void                             SetUnitInfo( const std::vector<FP_UNIT_INFO>& aUnits ) { m_unitInfo = aUnits; }
    const std::vector<FP_UNIT_INFO>& GetUnitInfo() const { return m_unitInfo; }
 
    bool IsBoardOnly() const { return m_attributes & FP_BOARD_ONLY; }
    void SetBoardOnly( bool aIsBoardOnly = true )
    {
        if( aIsBoardOnly )
            m_attributes |= FP_BOARD_ONLY;
        else
            m_attributes &= ~FP_BOARD_ONLY;
    }
 
    bool IsExcludedFromPosFiles() const { return m_attributes & FP_EXCLUDE_FROM_POS_FILES; }
    void SetExcludedFromPosFiles( bool aExclude = true )
    {
        if( aExclude )
            m_attributes |= FP_EXCLUDE_FROM_POS_FILES;
        else
            m_attributes &= ~FP_EXCLUDE_FROM_POS_FILES;
    }
 
    bool IsExcludedFromBOM() const { return m_attributes & FP_EXCLUDE_FROM_BOM; }
    void SetExcludedFromBOM( bool aExclude = true )
    {
        if( aExclude )
            m_attributes |= FP_EXCLUDE_FROM_BOM;
        else
            m_attributes &= ~FP_EXCLUDE_FROM_BOM;
    }
 
    bool IsExcludedFromSim() const { return m_attributes & FP_EXCLUDE_FROM_SIM; }
    void SetExcludedFromSim( bool aExclude = true )
    {
        if( aExclude )
            m_attributes |= FP_EXCLUDE_FROM_SIM;
        else
            m_attributes &= ~FP_EXCLUDE_FROM_SIM;
    }
 
    bool IsDNP() const { return m_attributes & FP_DNP; }
    void SetDNP( bool aDNP = true )
    {
        if( aDNP )
            m_attributes |= FP_DNP;
        else
            m_attributes &= ~FP_DNP;
    }
 
    // =====================================================================
    // Variant Support
    // =====================================================================

    const FOOTPRINT_VARIANT* GetVariant( const wxString& aVariantName ) const;

    FOOTPRINT_VARIANT* GetVariant( const wxString& aVariantName );

    void SetVariant( const FOOTPRINT_VARIANT& aVariant );

    FOOTPRINT_VARIANT* AddVariant( const wxString& aVariantName );

    void DeleteVariant( const wxString& aVariantName );

    void RenameVariant( const wxString& aOldName, const wxString& aNewName );

    bool HasVariant( const wxString& aVariantName ) const;

    const CASE_INSENSITIVE_MAP<FOOTPRINT_VARIANT>& GetVariants() const { return m_variants; }

    bool GetDNPForVariant( const wxString& aVariantName ) const;

    bool GetExcludedFromBOMForVariant( const wxString& aVariantName ) const;

    bool GetExcludedFromSimForVariant( const wxString& aVariantName ) const;

    bool GetExcludedFromPosFilesForVariant( const wxString& aVariantName ) const;

    wxString GetFieldValueForVariant( const wxString& aVariantName, const wxString& aFieldName ) const;
 
    void SetFileFormatVersionAtLoad( int aVersion ) { m_fileFormatVersionAtLoad = aVersion; }
    int GetFileFormatVersionAtLoad() const { return m_fileFormatVersionAtLoad; }
 
    std::vector<PROPERTY_BASE*> GetDynamicProperties() const override;

    PAD* FindPadByNumber( const wxString& aPadNumber, PAD* aSearchAfterMe = nullptr ) const;
 
    PAD* FindPadByUuid( const KIID& aUuid ) const;

    PAD* GetPad( const VECTOR2I& aPosition, const LSET& aLayerMask = LSET::AllLayersMask() );
 
    std::vector<const PAD*> GetPads( const wxString& aPadNumber, const PAD* aIgnore = nullptr ) const;

    unsigned GetPadCount() const;

    std::set<wxString> GetUniquePadNumbers() const;

    unsigned GetNumberedPadCount() const;

    wxString GetNextPadNumber( const wxString& aLastPadName ) const;
 
    bool GetDuplicatePadNumbersAreJumpers() const { return m_duplicatePadNumbersAreJumpers; }
    void SetDuplicatePadNumbersAreJumpers( bool aEnabled ) { m_duplicatePadNumbersAreJumpers = aEnabled; }

    std::vector<std::set<wxString>>& JumperPadGroups() { return m_jumperPadGroups; }
    const std::vector<std::set<wxString>>& JumperPadGroups() const { return m_jumperPadGroups; }

    std::optional<const std::set<wxString>> GetJumperPadGroup( const wxString& aPadNumber ) const;

    void AutoPositionFields();

    wxString GetTypeName() const;
 
    double GetArea( int aPadding = 0 ) const;
 
    KIID GetLink() const { return m_link; }
    void SetLink( const KIID& aLink ) { m_link = aLink; }
 
    BOARD_ITEM* Duplicate( bool addToParentGroup, BOARD_COMMIT* aCommit = nullptr ) const override;

    BOARD_ITEM* DuplicateItem( bool addToParentGroup, BOARD_COMMIT* aCommit, const BOARD_ITEM* aItem,
                               bool addToFootprint = false );

    void Add3DModel( FP_3DMODEL* a3DModel );
 
    INSPECT_RESULT Visit( INSPECTOR inspector, void* testData,
                          const std::vector<KICAD_T>& aScanTypes ) override;
 
    wxString GetClass() const override
    {
        return wxT( "FOOTPRINT" );
    }
 
    wxString GetItemDescription( UNITS_PROVIDER* aUnitsProvider, bool aFull ) const override;
 
    wxString DisambiguateItemDescription( UNITS_PROVIDER* aUnitsProvider, bool aFull ) const override;
 
    BITMAPS GetMenuImage() const override;
 
    EDA_ITEM* Clone() const override;

    void RunOnChildren( const std::function<void( BOARD_ITEM* )>& aFunction, RECURSE_MODE aMode ) const override;
 
    virtual std::vector<int> ViewGetLayers() const override;
 
    double ViewGetLOD( int aLayer, const KIGFX::VIEW* aView ) const override;
 
    virtual const BOX2I ViewBBox() const override;

    static bool IsLibNameValid( const wxString& aName );

    static const wxChar* StringLibNameInvalidChars( bool aUserReadable );

    bool FootprintNeedsUpdate( const FOOTPRINT* aLibFP, int aCompareFlags = 0,
                               REPORTER* aReporter = nullptr );

    void SetInitialComments( wxArrayString* aInitialComments )
    {
        delete m_initial_comments;
        m_initial_comments = aInitialComments;
    }

    double CoverageRatio( const GENERAL_COLLECTOR& aCollector ) const;
 
    static double GetCoverageArea( const BOARD_ITEM* aItem, const GENERAL_COLLECTOR& aCollector );

    const wxArrayString* GetInitialComments() const { return m_initial_comments; }

    const SHAPE_POLY_SET& GetCourtyard( PCB_LAYER_ID aLayer ) const;

    const SHAPE_POLY_SET& GetCachedCourtyard( PCB_LAYER_ID aLayer ) const;

    void BuildCourtyardCaches( OUTLINE_ERROR_HANDLER* aErrorHandler = nullptr );
 
    // @copydoc BOARD_ITEM::GetEffectiveShape
    std::shared_ptr<SHAPE> GetEffectiveShape( PCB_LAYER_ID aLayer = UNDEFINED_LAYER,
                                              FLASHING aFlash = FLASHING::DEFAULT,
                                              DRC_CONSTRAINT_T aUsage = NULL_CONSTRAINT ) const override;
 
    EMBEDDED_FILES* GetEmbeddedFiles() override
    {
        return static_cast<EMBEDDED_FILES*>( this );
    }
 
    const EMBEDDED_FILES* GetEmbeddedFiles() const
    {
        return static_cast<const EMBEDDED_FILES*>( this );
    }

    std::set<KIFONT::OUTLINE_FONT*> GetFonts() const override;
 
    void EmbedFonts() override;
 
    double Similarity( const BOARD_ITEM& aOther ) const override;

    void SetStaticComponentClass( const COMPONENT_CLASS* aClass ) const;

    const COMPONENT_CLASS* GetStaticComponentClass() const;

    const COMPONENT_CLASS* GetComponentClass() const;

    wxString GetComponentClassAsString() const;

    void RecomputeComponentClass() const;

    void InvalidateComponentClassCache() const;

    void SetTransientComponentClassNames( const std::unordered_set<wxString>& classNames )
    {
        m_transientComponentClassNames = classNames;
    }

    const std::unordered_set<wxString>& GetTransientComponentClassNames()
    {
        return m_transientComponentClassNames;
    }

    void ClearTransientComponentClassNames() { m_transientComponentClassNames.clear(); };

    void ResolveComponentClassNames( BOARD*                              aBoard,
                                     const std::unordered_set<wxString>& aComponentClassNames );

    void FixUpPadsForBoard( BOARD* aBoard );
 
    bool operator==( const BOARD_ITEM& aOther ) const override;
    bool operator==( const FOOTPRINT& aOther ) const;
 
#if defined(DEBUG)
    virtual void Show( int nestLevel, std::ostream& os ) const override { ShowDummy( os ); }
#endif
 
    struct cmp_drawings
    {
        bool operator()( const BOARD_ITEM* itemA, const BOARD_ITEM* itemB ) const;
    };
 
    struct cmp_pads
    {
        bool operator()( const PAD* aFirst, const PAD* aSecond ) const;
    };
  // TODO(JE) padstacks -- this code isn't used anywhere though
#if 0
    struct cmp_padstack
    {
        bool operator()( const PAD* aFirst, const PAD* aSecond ) const;
    };
#endif
    struct cmp_zones
    {
        bool operator()( const ZONE* aFirst, const ZONE* aSecond ) const;
    };
 
protected:
    virtual void swapData( BOARD_ITEM* aImage ) override;
 
    void addMandatoryFields();
 
private:
    std::deque<PCB_FIELD*>  m_fields;    // Fields, mapped by name, owned by pointer
    std::deque<BOARD_ITEM*> m_drawings;  // Drawings in the footprint, owned by pointer
    std::deque<PAD*>        m_pads;      // Pads, owned by pointer
    std::vector<ZONE*>      m_zones;     // Rule area zones, owned by pointer
    std::deque<PCB_GROUP*>  m_groups;    // Groups, owned by pointer
    std::deque<PCB_CONSTRAINT*> m_constraints;  // Geometric constraints, owned by pointer
    std::deque<PCB_POINT*>  m_points;    // Points, owned by pointer
 
    TRANSFORM_TRS   m_transform;
    bool            m_flipped = false;
    LIB_ID          m_fpid;
    int             m_attributes;        // Flag bits (see FOOTPRINT_ATTR_T)
    int             m_fpStatus;          // For autoplace: flags (LOCKED, FIELDS_AUTOPLACED)
    int             m_fileFormatVersionAtLoad;

    CASE_INSENSITIVE_MAP<FOOTPRINT_VARIANT> m_variants;
 
    // Bounding box caching strategy:
    // While we attempt to notice the low-hanging fruit operations and update the bounding boxes
    // accordingly, we rely mostly on a "if anything changed then the caches are stale" approach.
    // We implement this by having PCB_BASE_FRAME's OnModify() method increment an operation
    // counter, and storing that as a timestamp for the various caches.
    // This means caches will get regenerated often -- but still far less often than if we had no
    // caches at all.  The principal opitmization would be to change to dirty flag and make sure
    // that any edit that could affect the bounding boxes (including edits to the footprint
    // children) marked the bounding boxes dirty.  It would definitely be faster -- but also more
    // fragile.
    mutable std::mutex                                     m_geometry_cache_mutex;
    mutable std::unique_ptr<FOOTPRINT_GEOMETRY_CACHE_DATA> m_geometry_cache;
 
    mutable std::map<wxString, std::unique_ptr<PCB_FOOTPRINT_FIELD_PROPERTY>> m_dynamicPropertyCache;
 
    // A list of pad groups, each of which is allowed to short nets within their group.
    // A pad group is a comma-separated list of pad numbers.
    std::vector<wxString>  m_netTiePadGroups;
 
    // A list of 1:N footprint item to allowed net numbers
    std::map<const BOARD_ITEM*, std::set<int>> m_netTieCache;

    std::vector<std::set<wxString>> m_jumperPadGroups;

    bool                  m_duplicatePadNumbersAreJumpers;
 
    bool                  m_allowMissingCourtyard;
    bool                  m_allowSolderMaskBridges;
 
    // Optional overrides
    ZONE_CONNECTION       m_zoneConnection;
    std::optional<int>    m_clearance;
    std::optional<int>    m_solderMaskMargin;       // Solder mask margin
    std::optional<int>    m_solderPasteMargin;      // Solder paste margin absolute value
    std::optional<double> m_solderPasteMarginRatio; // Solder mask margin ratio of pad size
                                                    // The final margin is the sum of these 2 values
 
    LSET              m_stackupLayers; // Layers in the stackup
    FOOTPRINT_STACKUP m_stackupMode;   // Stackup mode for this footprint
    LSET              m_privateLayers; // Layers visible only in the footprint editor
 
    wxString        m_libDescription;    // File name and path for documentation file.
    wxString        m_keywords;          // Search keywords to find footprint in library.
    KIID_PATH       m_path;              // Path to associated symbol ([sheetUUID, .., symbolUUID]).
    wxString        m_sheetname;         // Name of the sheet containing the symbol for this footprint
    wxString        m_sheetfile;         // File of the sheet containing the symbol for this footprint
    wxString        m_filters;           // Footprint filters from symbol
    timestamp_t     m_lastEditTime;
    int             m_arflag;            // Use to trace ratsnest and auto routing.
    KIID            m_link;              // Temporary logical link used during editing
 
    std::vector<FP_3DMODEL> m_3D_Drawings;       // 3D models.
 
    std::unique_ptr<EXTRUDED_3D_BODY> m_extrudedBody; // nullptr = disabled
 
    wxArrayString*          m_initial_comments;  // s-expression comments in the footprint,
                                                 //   lazily allocated only if needed for speed
 
    mutable std::unique_ptr<FOOTPRINT_COURTYARD_CACHE_DATA> m_courtyard_cache;
    mutable std::mutex                                      m_courtyard_cache_mutex;
 
    std::unordered_set<wxString> m_transientComponentClassNames;
    std::unique_ptr<COMPONENT_CLASS_CACHE_PROXY> m_componentClassCacheProxy;
 
    // Optional unit mapping information for multi-unit symbols
    std::vector<FP_UNIT_INFO> m_unitInfo;
 
    std::vector<SEARCH_TERM> m_searchTerms;
};
 
#endif     // FOOTPRINT_H