board_constraint_adapter.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * 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 BOARD_CONSTRAINT_ADAPTER_H_
#define BOARD_CONSTRAINT_ADAPTER_H_
 
#include <deque>
#include <functional>
#include <map>
#include <memory>
#include <optional>
#include <set>
#include <unordered_set>
#include <vector>
 
#include <constraints/constraint_system_2d.h>
#include <kiid.h>
#include <math/vector2d.h>
#include <snap/snap_resolver.h>
 
#include <constraints/pcb_constraint.h>
 
class BOARD;
class BOARD_ITEM;
class PCB_DIMENSION_BASE;
class PCB_DIM_ORTHOGONAL;
class PCB_SHAPE;
 
// planegcs is an Eigen-heavy implementation detail; keep its header out of this one (PIMPL).
namespace GCS
{
class System;
}
 

struct CONSTRAINT_DIAGNOSIS
{
    bool              solved = false;   
    int               freeDof = -1;     
    std::vector<KIID> conflicting;      
    std::vector<KIID> redundant;        
 
    bool IsWellConstrained() const { return solved && freeDof == 0; }
    bool IsUnderConstrained() const { return freeDof > 0; }
    bool IsOverConstrained() const { return !conflicting.empty(); }
};
 

enum class CONSTRAINT_STATE
{
    UNCONSTRAINED,       
    UNDER_CONSTRAINED,   
    WELL_CONSTRAINED,    
    OVER_CONSTRAINED,    
};
 

struct BOARD_CONSTRAINT_DIAGNOSTICS
{
    int                              totalFreeDof = 0;
    std::map<KIID, CONSTRAINT_STATE> shapeStates;
    std::vector<KIID>                conflicting;
    std::vector<KIID>                redundant;
    std::vector<KIID>                errored;   
};
 

class BOARD_CONSTRAINT_ADAPTER
{
public:
    BOARD_CONSTRAINT_ADAPTER();
    ~BOARD_CONSTRAINT_ADAPTER();
 
    BOARD_CONSTRAINT_ADAPTER( const BOARD_CONSTRAINT_ADAPTER& ) = delete;
    BOARD_CONSTRAINT_ADAPTER& operator=( const BOARD_CONSTRAINT_ADAPTER& ) = delete;

    bool Build( const std::vector<PCB_SHAPE*>& aShapes, const std::vector<PCB_CONSTRAINT*>& aConstraints,
                const std::set<KIID>* aFixedShapes = nullptr,
                const std::vector<PCB_DIMENSION_BASE*>& aDimensions = {} );

    const std::vector<KIID>& UnmappedConstraints() const { return m_unmapped; }

    bool Solve( const CONSTRAINT_MEMBER& aDragged, const VECTOR2I& aCursor, bool aStabilize = false,
                const std::set<KIID>&                                        aEdited = {},
                const std::optional<std::pair<CONSTRAINT_MEMBER, VECTOR2I>>& aCoDragged = std::nullopt,
                bool                                                         aHoldDraggedRigid = false );
    bool SolveSnapRelations( const CONSTRAINT_MEMBER& aDragged,
                             const std::vector<SNAP_CANDIDATE>& aCandidates,
                             const VECTOR2I& aCursor );
    bool SolveRigidTranslation( const std::set<KIID>& aEditedShapes,
                                const VECTOR2I& aTranslation );

    bool TravelsWhole( const std::set<KIID>& aEditedShapes ) const;
    bool SolveRigidSnapRelations( const std::set<KIID>& aEditedShapes,
                                  const VECTOR2I& aReference,
                                  const std::vector<SNAP_CANDIDATE>& aCandidates,
                                  const VECTOR2I& aCursor, VECTOR2I& aResolvedCursor );

    bool Solve( bool aStabilize = false );

    bool SolveAfterResize( const KIID& aResizedShape );

    std::vector<PCB_SHAPE*> Apply( const std::function<void( BOARD_ITEM* )>& aBeforeWrite = {} );

    void ApplyReferenceValues( const std::function<void( BOARD_ITEM* )>& aBeforeWrite = {} );

    CONSTRAINT_DIAGNOSIS Diagnose();
 
    using SNAPSHOT = CONSTRAINT_SYSTEM_2D::SNAPSHOT;
 
    SNAPSHOT Snapshot() const { return m_system.Snapshot(); }
    bool     Restore( const SNAPSHOT& aSnapshot ) { return m_system.RestorePrefix( aSnapshot ); }
    std::optional<VECTOR2I> AnchorPosition( const CONSTRAINT_MEMBER& aMember ) const;
    bool QuantizedRelationsSatisfied();
    bool CurrentRelationsSatisfied() const { return hardRelationsSatisfied(); }
 
private:
    enum class SHAPE_KIND
    {
        SEGMENT,
        BEZIER, 
        CIRCLE,
        ARC,
        ELLIPSE,
        ELLIPSE_ARC,
        POINT_PAIR, 
        RECTANGLE,  
        POLYGON     
    };

    struct SHAPE_VARS
    {
        PCB_SHAPE*          shape = nullptr;
        PCB_DIMENSION_BASE* dimension = nullptr;   
        SHAPE_KIND kind = SHAPE_KIND::SEGMENT;
        int        startX = -1;        
        int        endX = -1;          
        int        radius = -1;        
        int        focusX = -1;        
        int        arcStartX = -1;     
        int        arcEndX = -1;       
        int        startAngle = -1;    
        int        endAngle = -1;      
        int                 fixedLengthParam = -1; 

        int vertexCount = 0;

        bool startIsLeft = true;
        bool startIsTop = true;
    };

    struct ANCHOR_PARAMS
    {
        int x = -1;
        int y = -1;
 
        bool IsValid() const { return x >= 0 && y >= 0; }
    };
 
    struct RIGID_RADIUS_HOLD
    {
        int centerX;
        int radius;
    };
 
    struct RIGID_STATE
    {
        std::set<int>                  points;
        std::vector<RIGID_RADIUS_HOLD> radii;
    };

    int pushParam( double aValue );
    int temporaryParam( double aValue );
    void beginTemporaryParameters();
    bool addSnapRelations( const ANCHOR_PARAMS& aAnchor,
                           const std::vector<SNAP_CANDIDATE>& aCandidates,
                           const VECTOR2I& aOffset );
    RIGID_STATE collectRigidState( const std::set<KIID>& aEditedShapes ) const;
    void        holdRigidRadii( const std::vector<RIGID_RADIUS_HOLD>& aRadii, int aTag );

    void recordReferenceValue( PCB_CONSTRAINT* aConstraint );

    void holdFreeSegmentLengths( int aTag, const std::set<KIID>& aShapes );

    void holdFreeArcRadii( int aTag, const std::set<KIID>& aShapes );

    void holdShapesRigid( int aTag, const std::set<KIID>& aShapes );

    void holdArcRadius( const SHAPE_VARS& aVars, int aTag );

    void softPinPoint( const ANCHOR_PARAMS& aPoint, int aTag, std::optional<double> aWeight = std::nullopt );

    void softPinPoint( int aPointX, int aTag, std::optional<double> aWeight = std::nullopt );

    void holdPolygonVertices( const std::set<KIID>& aShapes, int aTag );

    void pinDraggedShapeRest( const CONSTRAINT_MEMBER& aDragged, int aTag,
                              const CONSTRAINT_MEMBER* aCoDragged = nullptr );

    void pinUneditedShapes( const std::set<KIID>& aEdited, int aTag );

    bool solveSucceeded( int aSolveResult );
    bool hardRelationsSatisfied() const;

    ANCHOR_PARAMS anchorParams( const CONSTRAINT_MEMBER& aMember ) const;

    PCB_DIM_ORTHOGONAL* orthogonalDimensionForMembers( const std::vector<CONSTRAINT_MEMBER>& aMembers ) const;

    double normalizeX( int aIU ) const { return m_system.NormalizeX( aIU ); }
    double normalizeY( int aIU ) const { return m_system.NormalizeY( aIU ); }
    double denormalizeX( double aNorm ) const { return m_system.DenormalizeX( aNorm ); }
    double denormalizeY( double aNorm ) const { return m_system.DenormalizeY( aNorm ); }
 
    CONSTRAINT_SYSTEM_2D m_system;
    GCS::System*         m_gcs;
 
    // Compatibility alias while board geometry mapping remains in this adapter.
    std::deque<double>& m_params;
 
    std::map<KIID, SHAPE_VARS>       m_shapeVars;

    std::set<int>                    m_fixedParams;
    std::map<int, KIID>              m_tagToConstraint;
    std::set<int>                    m_nonDrivingTags;       
    std::map<int, std::vector<KIID>> m_tagMembers;           
    std::vector<PCB_CONSTRAINT*>     m_referenceConstraints; 
    std::vector<KIID>                m_unmapped;             

    std::set<KIID> m_angleConstrainedShapes;
 
    double m_scale = 1.0;    
    double m_invScale = 1.0; 
 
    int m_dragTargetX = -1;   
    int m_dragTargetY = -1;   
    int m_coDragTargetX = -1; 
    int m_coDragTargetY = -1; 
    std::vector<int> m_temporaryParams;
    size_t           m_nextTemporaryParam = 0;
 
    // Hold tags reserved by Build() just past the mapped constraints' tags, so a hold can never
    // collide with (and clear) a real constraint on a large cluster.
    int m_lengthHoldTag = -1;
    int m_resizeRadiusTag = -1;
 
    bool m_built = false;
};
 

class BOARD_CONSTRAINT_SESSION
{
public:
    bool HasBaseConflict() const { return m_baseConflict; }
 
protected:
    bool buildCluster( BOARD* aBoard, const std::unordered_set<KIID>& aClusterShapes,
                       const std::vector<PCB_CONSTRAINT*>& aConstraints );

    void reset();
 
    bool usable() const { return m_adapter && !m_baseConflict; }

    bool rewind() { return m_adapter && m_adapter->Restore( m_baseline ); }

    SNAP_RESULT startResult( const SNAP_SOURCE_CONTEXT& aContext ) const;

    static void accept( SNAP_RESULT& aResult, const SNAP_CANDIDATE& aCandidate, double aResidual );
 
    BOARD*                                    m_board = nullptr;
    std::unique_ptr<BOARD_CONSTRAINT_ADAPTER> m_adapter;
    BOARD_CONSTRAINT_ADAPTER::SNAPSHOT        m_baseline;
    bool                                      m_baseConflict = false;
};
 
 
class BOARD_CONSTRAINT_DRAG_SESSION : public BOARD_CONSTRAINT_SESSION
{
public:
    bool Build( BOARD* aBoard, const CONSTRAINT_MEMBER& aDragged );
    bool Matches( const CONSTRAINT_MEMBER& aDragged ) const;
    bool IsExactFeasible( const VECTOR2I& aTarget );
    SNAP_RESULT ResolveCandidates( const SNAP_SOURCE_CONTEXT& aContext,
                                   const std::vector<SNAP_CANDIDATE>& aCandidates );
 
    CONSTRAINT_DIAGNOSIS
    Solve( const VECTOR2I& aCursor, std::vector<PCB_SHAPE*>* aModified,
           const std::function<void( BOARD_ITEM* )>& aBeforeModify, bool aIncludeDragged,
           bool aStabilize, const std::set<KIID>& aEdited = {},
           const std::optional<std::pair<CONSTRAINT_MEMBER, VECTOR2I>>& aCoDragged = std::nullopt );
 
private:
    CONSTRAINT_MEMBER m_dragged;
    PCB_SHAPE*        m_draggedShape = nullptr;
};
 
 
class BOARD_CONSTRAINT_MOVE_SESSION : public BOARD_CONSTRAINT_SESSION
{
public:
    bool Build( BOARD* aBoard, const std::vector<PCB_SHAPE*>& aEditedShapes,
                const VECTOR2I& aReference );
    SNAP_RESULT ResolveCandidates( const SNAP_SOURCE_CONTEXT& aContext,
                                   const std::vector<SNAP_CANDIDATE>& aCandidates );
    bool Solve( const VECTOR2I& aTarget, std::vector<PCB_SHAPE*>* aModified,
                const std::function<void( BOARD_ITEM* )>& aBeforeModify );
 
private:
    bool feasibleAt( const VECTOR2I& aTarget );
 
    VECTOR2I       m_reference;
    std::set<KIID> m_edited;
};
 

CONSTRAINT_DIAGNOSIS
SolveCluster( BOARD* aBoard, const CONSTRAINT_MEMBER& aDragged, const VECTOR2I& aCursor,
              std::vector<PCB_SHAPE*>*                  aModified = nullptr,
              const std::function<void( BOARD_ITEM* )>& aBeforeModify = {}, bool aIncludeDragged = false,
              bool aStabilize = false, const std::set<KIID>& aEdited = {},
              const std::optional<std::pair<CONSTRAINT_MEMBER, VECTOR2I>>& aCoDragged = std::nullopt,
              const std::set<KIID>& aFixedShapes = {}, bool aHoldDraggedRigid = false );
 

std::set<KIID> ConstraintReferenceShapes( BOARD* aBoard, const PCB_CONSTRAINT* aConstraint );
 

CONSTRAINT_DIAGNOSIS ApplyConstraintImmediately( BOARD* aBoard, const PCB_CONSTRAINT* aConstraint,
                                                 std::vector<PCB_SHAPE*>*                  aModified = nullptr,
                                                 const std::function<void( BOARD_ITEM* )>& aBeforeModify = {},
                                                 const std::set<KIID>&                     aFixedShapes = {} );
 

bool BoardHasConstraints( BOARD* aBoard );
 

bool ConstraintItemIsLocked( const BOARD_ITEM* aItem );
 

void ReSolveShapeClusters( BOARD* aBoard, const std::vector<PCB_SHAPE*>& aShapes,
                           std::vector<PCB_SHAPE*>*                  aModified = nullptr,
                           const std::function<void( BOARD_ITEM* )>& aBeforeModify = {} );
 

bool ReSolveShapeClustersHoldingEdited( BOARD* aBoard, const std::vector<PCB_SHAPE*>& aEditedShapes,
                                        std::vector<PCB_SHAPE*>*                  aModified = nullptr,
                                        const std::function<void( BOARD_ITEM* )>& aBeforeModify = {} );
 

void ReSolveAfterShapeResize( BOARD* aBoard, PCB_SHAPE* aShape, std::vector<PCB_SHAPE*>* aModified = nullptr,
                              const std::function<void( BOARD_ITEM* )>& aBeforeModify = {} );
 

BOARD_CONSTRAINT_DIAGNOSTICS DiagnoseBoardConstraints( BOARD* aBoard );
 

struct CLUSTER_DIAGNOSIS
{
    CONSTRAINT_STATE  state = CONSTRAINT_STATE::WELL_CONSTRAINED;
    std::vector<KIID> shapeIds;          
    std::vector<KIID> dimensionIds;      
    int               freeDof = 0;       
    std::vector<KIID> conflicting;
    std::vector<KIID> redundant;
    std::vector<KIID> erroredUnmapped;   
};
 

class BOARD_CONSTRAINT_DIAGNOSER
{
public:
    BOARD_CONSTRAINT_DIAGNOSTICS Diagnose( BOARD* aBoard );

    void Clear();

    std::size_t SolveCount() const { return m_solveCount; }
 
private:
    struct CACHE_ENTRY
    {
        std::size_t       hash = 0;
        CLUSTER_DIAGNOSIS result;
    };
 
    // Keyed by the cluster sorted constraint-id set which is stable across a geometry or value
    // edit and changes only when a constraint is added to or removed from the cluster
    std::map<std::vector<KIID>, CACHE_ENTRY> m_cache;
    std::size_t                              m_solveCount = 0;
};
 
#endif // BOARD_CONSTRAINT_ADAPTER_H_