padstack.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2024 Jon Evans <[email protected]>
 * 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 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/>.
 */
 
#pragma once
 
#include <memory>
#include <optional>
#include <wx/string.h>
 
#include <api/serializable.h>
#include <geometry/eda_angle.h>
#include <layer_ids.h>
#include <lset.h>
#include <math/vector2d.h>
#include <properties/property.h>
#include <zones.h>
 
class BOARD_ITEM;
class PCB_SHAPE;
 
namespace kiapi::board::types
{
    class PadStack;
    class PadStackLayer;
}
 

enum class PAD_SHAPE : int
{
    CIRCLE,
    RECTANGLE,      // do not use just RECT: it collides in a header on MSYS2
    OVAL,
    TRAPEZOID,
    ROUNDRECT,
 
    // Rectangle with a chamfered corner ( and with rounded other corners).
    CHAMFERED_RECT,
    CUSTOM            // A shape defined by user, using a set of basic shapes
                      // (thick segments, circles, arcs, polygons).
};

enum class PAD_DRILL_SHAPE
{
    UNDEFINED,
    CIRCLE,
    OBLONG,
};
 
enum class PAD_DRILL_POST_MACHINING_MODE
{
    UNKNOWN,
    NOT_POST_MACHINED,
    COUNTERBORE,
    COUNTERSINK
};
 
enum class BACKDRILL_MODE
{
    NO_BACKDRILL,
    BACKDRILL_BOTTOM,
    BACKDRILL_TOP,
    BACKDRILL_BOTH
};

enum class PAD_ATTRIB
{
    PTH,        
    SMD,        
    CONN,       
    NPTH,       
};
 

enum class PAD_PROP
{
    NONE,                  
    BGA,                   
    FIDUCIAL_GLBL,         
    FIDUCIAL_LOCAL,        
    TESTPOINT,             
    HEATSINK,              
    CASTELLATED,           
    MECHANICAL,            
    PRESSFIT               
};
 
 
enum class UNCONNECTED_LAYER_MODE
{
    KEEP_ALL,
    START_END_ONLY,
    REMOVE_ALL,
    REMOVE_EXCEPT_START_AND_END
};
 
 
enum class CUSTOM_SHAPE_ZONE_MODE
{
    OUTLINE,
    CONVEXHULL
};
 

class PADSTACK : public SERIALIZABLE
{
public:
    enum class TYPE
    {
        NORMAL,     
        VIA,        
        MOUNTING    
    };

    enum class MODE
    {
        NORMAL,           
        FRONT_INNER_BACK, 
        CUSTOM            
    };

    static constexpr PCB_LAYER_ID TEMP_ALL_LAYERS = F_Cu;

    static constexpr PCB_LAYER_ID ALL_LAYERS = F_Cu;

    static constexpr PCB_LAYER_ID INNER_LAYERS = In1_Cu;

    struct SHAPE_PROPS
    {
        PAD_SHAPE shape;          
        PAD_SHAPE anchor_shape;   
        VECTOR2I  size;           
 
        /*
         * Most of the time the hole is the center of the shape (m_Offset = 0). But some designers
         * use oblong/rect pads with a hole moved to one of the oblong/rect pad shape ends.
         * In all cases the hole is at the pad position.  This offset is from the hole to the center
         * of the pad shape (ie: the copper area around the hole).
         * ShapePos() returns the board shape position according to the offset and the pad rotation.
         */
        VECTOR2I  offset; 
 
        double    round_rect_radius_ratio;
        double    chamfered_rect_ratio;        
        int       chamfered_rect_positions;    

        VECTOR2I  trapezoid_delta_size;
 
        SHAPE_PROPS();
        bool operator==( const SHAPE_PROPS& aOther ) const;
        int Compare( const SHAPE_PROPS& aOther ) const;
    };

    struct COPPER_LAYER_PROPS
    {
        SHAPE_PROPS                             shape;
        std::optional<ZONE_CONNECTION>          zone_connection;
        std::optional<int>                      thermal_spoke_width;
        std::optional<EDA_ANGLE>                thermal_spoke_angle;
        std::optional<int>                      thermal_gap;
        std::optional<int>                      clearance;
 
        /*
         * Editing definitions of primitives for custom pad shapes.  In local coordinates relative
         * to m_Pos (NOT shapePos) at orient 0.
         */
        std::vector<std::shared_ptr<PCB_SHAPE>> custom_shapes;
 
        bool operator==( const COPPER_LAYER_PROPS& aOther ) const;
        int Compare( const COPPER_LAYER_PROPS& aOther ) const;
 
        double Similarity( const COPPER_LAYER_PROPS& aOther ) const;
    };

    struct MASK_LAYER_PROPS
    {
        std::optional<int>    solder_mask_margin;
        std::optional<int>    solder_paste_margin;
        std::optional<double> solder_paste_margin_ratio;
 
        std::optional<bool>   has_solder_mask;   
        std::optional<bool>   has_solder_paste;  
        std::optional<bool>   has_covering;      
        std::optional<bool>   has_plugging;      
 
        bool operator==( const MASK_LAYER_PROPS& aOther ) const;
        int Compare( const MASK_LAYER_PROPS& aOther ) const;
    };

    struct DRILL_PROPS
    {
        VECTOR2I            size;                            
        PAD_DRILL_SHAPE     shape = PAD_DRILL_SHAPE::UNDEFINED;
        PCB_LAYER_ID        start = UNDEFINED_LAYER;
        PCB_LAYER_ID        end   = UNDEFINED_LAYER;
 
        std::optional<bool> is_filled; 
        std::optional<bool> is_capped; 
 
        bool operator==( const DRILL_PROPS& aOther ) const;
        int Compare( const DRILL_PROPS& aOther ) const;
    };
 
    struct POST_MACHINING_PROPS
    {
        std::optional<PAD_DRILL_POST_MACHINING_MODE> mode;
        int                                          size = 0;
        int                                          depth = 0;
        int                                          angle = 0;
 
        bool operator==( const POST_MACHINING_PROPS& aOther ) const;
        int Compare( const POST_MACHINING_PROPS& aOther ) const;
    };
 
public:
    PADSTACK( BOARD_ITEM* aParent );
    virtual ~PADSTACK() = default;
    PADSTACK( const PADSTACK& aOther );
    PADSTACK& operator=( const PADSTACK &aOther );
 
    bool operator==( const PADSTACK& aOther ) const;
    bool operator!=( const PADSTACK& aOther ) const { return !operator==( aOther ); }
 
    void Serialize( google::protobuf::Any &aContainer ) const override;
    bool Deserialize( const google::protobuf::Any &aContainer ) override;
 
    void Serialize( kiapi::board::types::PadStack& aOutput ) const;
    bool Deserialize( const kiapi::board::types::PadStack& aInput );

    static int Compare( const PADSTACK* aPadstackRef, const PADSTACK* aPadstackCmp );

    bool HasExplicitDefinitionForLayer( PCB_LAYER_ID aLayer ) const;

    double Similarity( const PADSTACK& aOther ) const;
 
    const LSET& LayerSet() const { return m_layerSet; }
    LSET& LayerSet() { return m_layerSet; }
    void SetLayerSet( const LSET& aSet ) { m_layerSet = aSet; }

    void FlipLayers( BOARD* aBoard );
 
    PCB_LAYER_ID StartLayer() const;
    PCB_LAYER_ID EndLayer() const;
 
    MODE Mode() const { return m_mode; }
    void SetMode( MODE aMode );

    wxString Name() const;
 
    const wxChar* CustomName() const;
    void SetCustomName( const wxString& aCustomName );
 
    EDA_ANGLE GetOrientation() const { return m_orientation; }
 
    void SetOrientation( EDA_ANGLE aAngle )
    {
        m_orientation = aAngle;
        m_orientation.Normalize();
    }
 
    DRILL_PROPS& Drill() { return m_drill; }
    const DRILL_PROPS& Drill() const { return m_drill; }
 
    DRILL_PROPS& SecondaryDrill() { return m_secondaryDrill; }
    const DRILL_PROPS& SecondaryDrill() const { return m_secondaryDrill; }
 
    DRILL_PROPS& TertiaryDrill() { return m_tertiaryDrill; }
    const DRILL_PROPS& TertiaryDrill() const { return m_tertiaryDrill; }
 
    POST_MACHINING_PROPS& FrontPostMachining() { return m_frontPostMachining; }
    const POST_MACHINING_PROPS& FrontPostMachining() const { return m_frontPostMachining; }
 
    POST_MACHINING_PROPS& BackPostMachining() { return m_backPostMachining; }
    const POST_MACHINING_PROPS& BackPostMachining() const { return m_backPostMachining; }
 
    int GetMaxHoleSize() const;
 
    UNCONNECTED_LAYER_MODE UnconnectedLayerMode() const { return m_unconnectedLayerMode; }
    void SetUnconnectedLayerMode( UNCONNECTED_LAYER_MODE aMode ) { m_unconnectedLayerMode = aMode; }
 
    COPPER_LAYER_PROPS& CopperLayer( PCB_LAYER_ID aLayer );
    const COPPER_LAYER_PROPS& CopperLayer( PCB_LAYER_ID aLayer ) const;
 
    MASK_LAYER_PROPS& FrontOuterLayers() { return m_frontMaskProps; }
    const MASK_LAYER_PROPS& FrontOuterLayers() const { return m_frontMaskProps; }
 
    MASK_LAYER_PROPS& BackOuterLayers() { return m_backMaskProps; }
    const MASK_LAYER_PROPS& BackOuterLayers() const { return m_backMaskProps; }

    std::optional<bool> IsTented( PCB_LAYER_ID aSide ) const;
 
    std::optional<bool> IsCovered( PCB_LAYER_ID aSide ) const;
 
    std::optional<bool> IsPlugged( PCB_LAYER_ID aSide ) const;
 
    std::optional<bool> IsCapped() const;
 
    std::optional<bool> IsFilled() const;
 
    CUSTOM_SHAPE_ZONE_MODE CustomShapeInZoneMode() const { return m_customShapeInZoneMode; }
    void SetCustomShapeInZoneMode( CUSTOM_SHAPE_ZONE_MODE aM ) { m_customShapeInZoneMode = aM; }

    void ForEachUniqueLayer( const std::function<void( PCB_LAYER_ID )>& aMethod ) const;
 
    std::vector<PCB_LAYER_ID> UniqueLayers() const;

    PCB_LAYER_ID EffectiveLayerFor( PCB_LAYER_ID aLayer ) const;

    LSET RelevantShapeLayers( const PADSTACK& aOther ) const;
 
    // The following section has convenience getters for the padstack properties on a given layer.
 
    PAD_SHAPE Shape( PCB_LAYER_ID aLayer ) const;
    void SetShape( PAD_SHAPE aShape, PCB_LAYER_ID aLayer );
 
    // Setter rather than direct access to enforce only positive sizes
    void SetSize( const VECTOR2I& aSize, PCB_LAYER_ID aLayer );
    const VECTOR2I& Size( PCB_LAYER_ID aLayer ) const;
 
    PAD_DRILL_SHAPE DrillShape() const;
    void SetDrillShape( PAD_DRILL_SHAPE aShape );
 
    VECTOR2I& Offset( PCB_LAYER_ID aLayer );
    const VECTOR2I& Offset( PCB_LAYER_ID aLayer ) const;
    void SetOffset( const VECTOR2I& aOffset, PCB_LAYER_ID aLayer );
 
    PAD_SHAPE AnchorShape( PCB_LAYER_ID aLayer ) const;
    void SetAnchorShape( PAD_SHAPE aShape, PCB_LAYER_ID aLayer );
 
    VECTOR2I& TrapezoidDeltaSize( PCB_LAYER_ID aLayer );
    const VECTOR2I& TrapezoidDeltaSize( PCB_LAYER_ID aLayer ) const;
 
    double RoundRectRadiusRatio( PCB_LAYER_ID aLayer ) const;
    void SetRoundRectRadiusRatio( double aRatio, PCB_LAYER_ID aLayer );
 
    int RoundRectRadius( PCB_LAYER_ID aLayer ) const;
    void SetRoundRectRadius( double aRadius, PCB_LAYER_ID aLayer );
 
    double ChamferRatio( PCB_LAYER_ID aLayer ) const;
    void SetChamferRatio( double aRatio, PCB_LAYER_ID aLayer );
 
    int& ChamferPositions( PCB_LAYER_ID aLayer );
    const int& ChamferPositions( PCB_LAYER_ID aLayer ) const;
    void SetChamferPositions( int aPositions, PCB_LAYER_ID aLayer );
 
    std::optional<int>& Clearance( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<int>& Clearance( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    std::optional<int>& SolderMaskMargin( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<int>& SolderMaskMargin( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    std::optional<int>& SolderPasteMargin( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<int>& SolderPasteMargin( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    std::optional<double>& SolderPasteMarginRatio( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<double>& SolderPasteMarginRatio( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    std::optional<ZONE_CONNECTION>& ZoneConnection( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<ZONE_CONNECTION>& ZoneConnection( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    std::optional<int>& ThermalSpokeWidth( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<int>& ThermalSpokeWidth( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    std::optional<int>& ThermalGap( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<int>& ThermalGap( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    EDA_ANGLE DefaultThermalSpokeAngleForShape( PCB_LAYER_ID aLayer = F_Cu ) const;
    EDA_ANGLE ThermalSpokeAngle( PCB_LAYER_ID aLayer = F_Cu ) const;
    void SetThermalSpokeAngle( EDA_ANGLE aAngle, PCB_LAYER_ID aLayer = F_Cu );
 
    std::vector<std::shared_ptr<PCB_SHAPE>>& Primitives( PCB_LAYER_ID aLayer );
    const std::vector<std::shared_ptr<PCB_SHAPE>>& Primitives( PCB_LAYER_ID aLayer ) const;

    void AddPrimitive( PCB_SHAPE* aShape, PCB_LAYER_ID aLayer );

    void AppendPrimitives( const std::vector<std::shared_ptr<PCB_SHAPE>>& aPrimitivesList, PCB_LAYER_ID aLayer );

    void ReplacePrimitives( const std::vector<std::shared_ptr<PCB_SHAPE>>& aPrimitivesList, PCB_LAYER_ID aLayer );
 
    void ClearPrimitives( PCB_LAYER_ID aLayer );
 
    BACKDRILL_MODE GetBackdrillMode() const;
    void SetBackdrillMode( BACKDRILL_MODE aMode );
 
    std::optional<int> GetBackdrillSize( bool aTop ) const;
    void SetBackdrillSize( bool aTop, std::optional<int> aSize );
 
    PCB_LAYER_ID GetBackdrillEndLayer( bool aTop ) const;
    void SetBackdrillEndLayer( bool aTop, PCB_LAYER_ID aLayer );
 
private:
    const DRILL_PROPS* findBackdrillDrill( bool aTop ) const;
    DRILL_PROPS*       findBackdrillDrill( bool aTop );

    DRILL_PROPS& backdrillWriteSlot( bool aTop );

    void clearBackdrillSide( bool aTop );
 
    bool unpackCopperLayer( const kiapi::board::types::PadStackLayer& aProto );
 
private:
    BOARD_ITEM*               m_parent;

    MODE                      m_mode;

    LSET                      m_layerSet;

    std::unique_ptr<wxString> m_customName;

    EDA_ANGLE                 m_orientation;
 
    std::unordered_map<PCB_LAYER_ID, COPPER_LAYER_PROPS> m_copperProps;

    MASK_LAYER_PROPS                                     m_frontMaskProps;

    MASK_LAYER_PROPS                                     m_backMaskProps;
 
    UNCONNECTED_LAYER_MODE m_unconnectedLayerMode;

    CUSTOM_SHAPE_ZONE_MODE m_customShapeInZoneMode;

    DRILL_PROPS            m_drill;

    DRILL_PROPS            m_secondaryDrill;

    DRILL_PROPS            m_tertiaryDrill;
 
    POST_MACHINING_PROPS   m_frontPostMachining;
    POST_MACHINING_PROPS   m_backPostMachining;
};
 
DECLARE_ENUM_TO_WXANY( PAD_DRILL_POST_MACHINING_MODE );
DECLARE_ENUM_TO_WXANY( UNCONNECTED_LAYER_MODE );
DECLARE_ENUM_TO_WXANY( BACKDRILL_MODE );