idf_common.h 20.6 KB
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722
/**
 * @file idf_common.h
 */

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2013-2014  Cirilo Bernardo
 *
 * 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, you may find one here:
 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 * or you may search the http://www.gnu.org website for the version 2 license,
 * or you may write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
 */

#ifndef IDF_COMMON_H
#define IDF_COMMON_H

#include <list>
#include <fstream>
#include <exception>
#include <string>

#ifndef M_PI
#define M_PI 3.1415926535897932384626433832795028841
#endif

#ifndef M_PI2
#define M_PI2 ( M_PI / 2.0 )
#endif

#ifndef M_PI4
#define M_PI4 ( M_PI / 4.0 )
#endif

// differences in angle smaller than MIN_ANG are considered equal
#define MIN_ANG     (0.01)

class IDF_POINT;
class IDF_SEGMENT;
class IDF_DRILL_DATA;
class IDF_OUTLINE;
class IDF_LIB;


struct IDF_ERROR : std::exception
{
    std::string message;

    IDF_ERROR( const char* aSourceFile,
               const char* aSourceMethod,
               int         aSourceLine,
               const std::string& aMessage ) throw();

    virtual ~IDF_ERROR() throw();

    virtual const char* what() const throw();
};


namespace IDF3 {

    /**
     * ENUM FILE_STATE
     * represents state values for the IDF parser's input
     */
    enum FILE_STATE
    {
        FILE_START = 0, // no data has been read; expecting .HEADER
        FILE_HEADER,    // header has been read; expecting  .BOARD_OUTLINE
        FILE_OUTLINE,   // board outline has been read; most sections can be accepted
        FILE_PLACEMENT, // placement has been read; no further sections can be accepted
        FILE_INVALID,   // file is invalid
        FILE_ERROR      // other errors while processing the file
    };

    /**
     * ENUM IDF_VERSION
     * represents the supported IDF versions (3.0 and 2.0  ONLY)
     */
    enum IDF_VERSION
    {
        IDF_V2 = 0,     // version 2 has read support only; files written as IDFv3
        IDF_V3          // version 3 has full read/write support
    };

    /**
     * ENUM KEY_OWNER
     * represents the type of CAD which has ownership an object
     */
    enum KEY_OWNER
    {
        UNOWNED = 0,        //< either MCAD or ECAD may modify a feature
        MCAD,               //< only MCAD may modify a feature
        ECAD                //< only ECAD may modify a feature
    };

    /**
     * ENUM KEY_HOLETYPE
     * represents the purpose of an IDF hole
     */
    enum KEY_HOLETYPE
    {
        PIN = 0,            //< drill hole is for a pin
        VIA,                //< drill hole is for a via
        MTG,                //< drill hole is for mounting
        TOOL,               //< drill hole is for tooling
        OTHER               //< user has specified a custom type
    };

    /**
     * ENUM KEY_PLATING
     * represents the plating condition of a hole
     */
    enum KEY_PLATING
    {
        PTH = 0,            //< Plate-Through Hole
        NPTH                //< Non-Plate-Through Hole
    };

    /**
     * ENUM KEY_REFDES
     * represents a component's Reference Designator
     */
    enum KEY_REFDES
    {
        BOARD = 0,          //< feature is associated with the board
        NOREFDES,           //< feature is associated with a component with no RefDes
        PANEL,              //< feature is associated with an IDF panel
        REFDES              //< reference designator as assigned by the CAD software
    };

    /**
     * ENUM CAD_TYPE
     * represents the class of CAD program which is opening or modifying a file
     */
    enum CAD_TYPE
    {
        CAD_ELEC = 0,       //< An Electrical CAD is opening/modifying the file
        CAD_MECH,           //< A Mechanical CAD is opening/modifying the file
        CAD_INVALID
    };

    /**
     * ENUM IDF_LAYER
     * represents the various IDF layer classes and groupings
     */
    enum IDF_LAYER
    {
        LYR_TOP = 0,
        LYR_BOTTOM,
        LYR_BOTH,
        LYR_INNER,
        LYR_ALL,
        LYR_INVALID
    };

    /**
     * ENUM OUTLINE_TYPE
     * identifies the class of outline
     */
    enum OUTLINE_TYPE
    {
        OTLN_BOARD = 0,
        OTLN_OTHER,
        OTLN_PLACE,
        OTLN_ROUTE,
        OTLN_PLACE_KEEPOUT,
        OTLN_ROUTE_KEEPOUT,
        OTLN_VIA_KEEPOUT,
        OTLN_GROUP_PLACE,
        OTLN_COMPONENT,
        OTLN_INVALID
    };

    /**
     * ENUM COMP_TYPE
     * identifies whether a component is a mechanical or electrical part
     */
    enum COMP_TYPE
    {
        COMP_ELEC = 0,      //< Component library object is an electrical part
        COMP_MECH,          //< Component library object is a mechanical part
        COMP_INVALID
    };

    /**
     * ENUM IDF_UNIT
     * represents the native unit of the board and of component outlines
     */
    enum IDF_UNIT
    {
        UNIT_MM = 0,        //< Units in the file are in millimeters
        UNIT_THOU,          //< Units in the file are in mils (aka thou)
        UNIT_TNM,           //< Deprecated Ten Nanometer Units from IDFv2
        UNIT_INVALID
    };

    /**
     * ENUM IDF_PLACEMENT
     * represents the placement status of a component
     */
    enum IDF_PLACEMENT
    {
        PS_UNPLACED = 0,    //< component location on the board has not been specified
        PS_PLACED,          //< component location has been specified and may be modified by ECAD or MCAD
        PS_MCAD,            //< component location has been specified and may only be modified by MCAD
        PS_ECAD,            //< component location has been specified and may only be modified by ECAD
        PS_INVALID
    };

    /**
     * Function CalcAngleRad
     * calculates the angle (radians) between the horizon and the segment aStartPoint to aEndPoint
     *
     * @param aStartPoint is the start point of a line segment
     * @param aEndPoint is the end point of a line segment
     *
     * @return double: the angle in radians
     */
    double  CalcAngleRad( const IDF_POINT& aStartPoint, const IDF_POINT& aEndPoint );


    /**
     * Function CalcAngleDeg
     * calculates the angle (degrees) between the horizon and the segment aStartPoint to aEndPoint
     *
     * @param aStartPoint is the start point of a line segment
     * @param aEndPoint is the end point of a line segment
     *
     * @return double: the angle in degrees
     */
    double  CalcAngleDeg( const IDF_POINT& aStartPoint, const IDF_POINT& aEndPoint );

    /**
     * Function GetOutline
     * takes contiguous elements from 'aLines' and stuffs them into 'aOutline'; elements put
     * into the outline are deleted from aLines. This function is useful for sorting the jumbled
     * mess of line segments and arcs which represent a board outline and cutouts in KiCad.
     * The function will determine which segment element within aLines contains the leftmost
     * point and retrieve the outline of which that segment is part.
     *
     * @param aLines (input/output) is a list of IDF segments which comprise an outline and
     *        cutouts.
     * @param aOutline (output) is the ordered set of segments
     */
    void GetOutline( std::list<IDF_SEGMENT*>& aLines,
                     IDF_OUTLINE& aOutline );

#ifdef DEBUG_IDF
    // prints out segment information for debug purposes
    void PrintSeg( IDF_SEGMENT* aSegment );
#endif
}


/**
 * Class IDF_NOTE
 * represents an entry in the NOTE section of an IDF file
 */
class IDF_NOTE
{
friend class IDF3_BOARD;
private:
    std::string text;   // note text as per IDFv3
    double xpos;        // text X position as per IDFv3
    double ypos;        // text Y position as per IDFv3
    double height;      // text height as per IDFv3
    double length;      // text length as per IDFv3

    /**
     * Function readNote
     * reads a note entry from an IDFv3 file
     *
     * @param aBoardFile is an open BOARD file; the file position must be set to the start of a NOTE entry
     * @param aBoardState is the parser's current state value
     * @param aBoardUnit is the BOARD file's native units (MM or THOU)
     *
     * @return bool: true if a note item was read, false otherwise. In case of unrecoverable errors
     * an exception is thrown
     */
    bool readNote( std::ifstream& aBoardFile, IDF3::FILE_STATE& aBoardState, IDF3::IDF_UNIT aBoardUnit );

    /**
     * Function writeNote
     * writes a note entry to an IDFv3 file
     *
     * @param aBoardFile is an open BOARD file; the file position must be within a NOTE section
     * @param aBoardUnit is the BOARD file's native units (MM or THOU)
     *
     * @return bool: true if the item was successfully written, false otherwise. In case of
     * unrecoverable errors an exception is thrown
     */
    bool writeNote( std::ofstream& aBoardFile, IDF3::IDF_UNIT aBoardUnit );

public:
    IDF_NOTE();

    /**
     * Function SetText
     * sets the text to be stored as a NOTE entry
     */
    void SetText( const std::string& aText );

    /**
     * Function SetPosition
     * sets the position (mm) of the NOTE entry
     */
    void SetPosition( double aXpos, double aYpos );

    /**
     * Function SetSize
     * sets the height and length (mm) of the NOTE entry
     */
    void SetSize( double aHeight, double aLength );

    /**
     * Function GetText
     * returns the string stored in the note entry
     */
    const std::string& GetText( void );

    /**
     * Function GetText
     * returns the position (mm) of the note entry
     */
    void GetPosition( double& aXpos, double& aYpos );

    /**
     * Function GetText
     * returns the height and length (mm) of the note entry
     */
    void GetSize( double& aHeight, double& aLength );
};


/**
 * @Class IDF_DRILL_DATA
 * contains information describing a drilled hole and is responsible for
 * writing this information to a file in compliance with the IDFv3 specification.
 */
class IDF_DRILL_DATA
{
friend class IDF3_BOARD;
friend class IDF3_COMPONENT;
private:
    double dia;
    double x;
    double y;
    IDF3::KEY_PLATING plating;
    IDF3::KEY_REFDES kref;
    IDF3::KEY_HOLETYPE khole;
    std::string refdes;
    std::string holetype;
    IDF3::KEY_OWNER owner;

    /**
     * Function read
     * read a drill entry from an IDFv3 file
     *
     * @param aBoardFile is an open IDFv3 file; the file position must be within the DRILLED_HOLES section
     * @param aBoardUnit is the board file's native unit (MM or THOU)
     * @param aBoardState is the state value of the parser
     *
     * @return bool: true if data was successfully read, otherwise false. In case of an
     * unrecoverable error an exception is thrown
     */
    bool read( std::ifstream& aBoardFile, IDF3::IDF_UNIT aBoardUnit, IDF3::FILE_STATE aBoardState,
               IDF3::IDF_VERSION aIdfVersion );

    /**
     * Function write
     * writes a single line representing a hole within a .DRILLED_HOLES section
     * In case of an unrecoverable error an exception is thrown.
     *
     * @param aBoardFile is an open BOARD file
     * @param aBoardUnit is the native unit of the output file
     */
    void write( std::ofstream& aBoardFile, IDF3::IDF_UNIT aBoardUnit );

public:
    /**
     * Constructor IDF_DRILL_DATA
     * creates an empty drill entry which can be populated by the
     * read() function
     */
    IDF_DRILL_DATA();

    /**
     * Constructor IDF_DRILL_DATA
     * creates a drill entry with information compliant with the
     * IDFv3 specifications.
     * @param aDrillDia : drill diameter
     * @param aPosX : X coordinate of the drill center
     * @param aPosY : Y coordinate of the drill center
     * @param aPlating : flag, PTH or NPTH
     * @param aRefDes : component Reference Designator
     * @param aHoleType : purpose of hole
     * @param aOwner : one of MCAD, ECAD, UNOWNED
     */
    IDF_DRILL_DATA( double aDrillDia, double aPosX, double aPosY,
                    IDF3::KEY_PLATING aPlating,
                    const std::string aRefDes,
                    const std::string aHoleType,
                    IDF3::KEY_OWNER aOwner );

    /**
     * Function Matches
     * returns true if the given drill diameter and location
     * matches the diameter and location of this IDF_DRILL_DATA object
     *
     * @param aDrillDia is the drill diameter (mm)
     * @param aPosX is the X position (mm) of the drilled hole
     * @param aPosY is the Y position (mm) of the drilled hole
     *
     * @return bool: true if the diameter and position match this object
     */
    bool Matches( double aDrillDia, double aPosX, double aPosY );

    /**
     * Function GettDrillDia
     * returns the drill diameter in mm
     */
    double GetDrillDia();

    /**
     * Function GettDrillXPos
     * returns the drill's X position in mm
     */
    double GetDrillXPos();

    /**
     * Function GettDrillYPos
     * returns the drill's Y position in mm
     */
    double GetDrillYPos();

    /**
     * Function GetDrillPlating
     * returns the plating value (PTH, NPTH)
     */
    IDF3::KEY_PLATING GetDrillPlating();

    /**
     * Function GetDrillRefDes
     * returns the reference designator of the hole; this
     * may be a component reference designator, BOARD, or
     * NOREFDES as per IDFv3.
     */
    const std::string& GetDrillRefDes();

    /**
     * Function GetDrillHoleType
     * returns the classification of the hole; this may be one of
     * PIN, VIA, MTG, TOOL, or a user-specified string
     */
    const std::string& GetDrillHoleType();

    IDF3::KEY_OWNER GetDrillOwner( void )
    {
        return owner;
    }
};


/**
 * @Class IDF_POINT
 * represents a point as used by the various IDF related classes
 */
class IDF_POINT
{
public:
    double x;   // < X coordinate
    double y;   // < Y coordinate

    IDF_POINT()
    {
        x = 0.0;
        y = 0.0;
    }

    /**
     * Function Matches()
     * returns true if the given coordinate point is within the given radius
     * of the point.
     *
     * @param aPoint : coordinates of the point being compared
     * @param aRadius : radius (mm) within which the points are considered the same
     *
     * @return bool: true if this point matches the given point
     */
    bool    Matches( const IDF_POINT& aPoint, double aRadius = 1e-5 );

    /**
     * Function CalcDistance()
     * returns the Euclidean distance between this point and the given point
     *
     * @param aPoint : coordinates of the point whose distance is to be determined
     *
     * @return double: distance between this point and aPoint
     */
    double  CalcDistance( const IDF_POINT& aPoint ) const;
};


/**
 * @Class IDF_SEGMENT
 * represents a geometry segment as used in IDFv3 outlines; it may be any of
 * an arc, line segment, or circle
 */
class IDF_SEGMENT
{
private:
    /**
     * Function CalcCenterAndRadius()
     * Calculates the center, radius, and angle between center and start point given the
     * IDF compliant points and included angle.
     *
     * @var startPoint, @var endPoint, and @var angle must be set prior as per IDFv3
     */
    void CalcCenterAndRadius( void );

public:
    IDF_POINT startPoint;   ///< starting point coordinates in mm
    IDF_POINT endPoint;     ///< end point coordinates in mm
    IDF_POINT   center;     ///< center of an arc or circle; internally calculated and not to be set by the user
    double  angle;          ///< included angle (degrees) according to IDFv3 specification
    double  offsetAngle;    ///< angle between center and start of arc; internally calculated
    double  radius;         ///< radius of the arc or circle; internally calculated

    /**
     * Constructor IDF_SEGMENT
     * initializes the internal variables
     */
    IDF_SEGMENT();

    /**
     * Function IDF_SEGMENT
     * creates a straight segment
     */
    IDF_SEGMENT( const IDF_POINT& aStartPoint, const IDF_POINT& aEndPoint );

    /**
     * Constructor IDF_SEGMENT
     * creates a straight segment, arc, or circle depending on the angle
     *
     * @param aStartPoint : start point (center if using KiCad convention, otherwise IDF convention)
     * @param aEndPoint : end point (start of arc if using KiCad convention, otherwise IDF convention)
     * @param aAngle : included angle; the KiCad convention is equivalent to the IDF convention
     * @param fromKicad : set true if we need to convert from KiCad to IDF convention
     */
    IDF_SEGMENT( const IDF_POINT& aStartPoint,
                 const IDF_POINT& aEndPoint,
                 double aAngle,
                 bool aFromKicad );

    /**
     * Function MatchesStart
     * returns true if the given coordinate is within a radius 'rad'
     * of the start point.
     *
     * @param aPoint : coordinates of the point (mm) being compared
     * @param aRadius : radius (mm) within which the points are considered the same
     *
     * @return bool: true if the given point matches the start point of this segment
     */
    bool MatchesStart( const IDF_POINT& aPoint, double aRadius = 1e-3 );

    /**
     * Function MatchesEnd
     * returns true if the given coordinate is within a radius 'rad'
     * of the end point.
     *
     * @param aPoint : coordinates (mm) of the point being compared
     * @param aRadius : radius (mm) within which the points are considered the same
     *
     * @return bool: true if the given point matches the end point of this segment
     */
    bool MatchesEnd( const IDF_POINT& aPoint, double aRadius = 1e-3 );

    /**
     * Function IsCircle
     * returns true if this segment is a circle
     */
    bool IsCircle( void );

    /**
     * Function GetMinX()
     * returns the minimum X coordinate of this segment
     */
    double GetMinX( void );

    /**
     * Function SwapEnds()
     * Swaps the start and end points and alters internal
     * variables as necessary for arcs
     */
    void SwapEnds( void );
};


/**
 * @Class IDF_OUTLINE
 * contains segment and winding information for an IDF outline
 */
class IDF_OUTLINE
{
private:
    double dir;                         // accumulator to help determine winding direction
    std::list<IDF_SEGMENT*> outline;    // sequential segments comprising an outline

public:
    IDF_OUTLINE() { dir = 0.0; }
    ~IDF_OUTLINE() { Clear(); }

    /**
     * Function IsCCW
     * returns true if the current list of points represents a counterclockwise winding
     */
    bool IsCCW( void );

    /**
     * Function IsCircle
     * returns true if this outline is a circle
     */
    bool IsCircle( void );

    /**
     * Function Clear
     * clears the internal list of outline segments
     */
    void Clear( void )
    {
        dir = 0.0;

        while( !outline.empty() )
        {
            delete outline.front();
            outline.pop_front();
        }
    }

    /**
     * Function size
     * returns the size of the internal segment list
     */
    size_t size( void )
    {
        return outline.size();
    }

    /**
     * Function empty
     * returns true if the internal segment list is empty
     */
    bool empty( void )
    {
        return outline.empty();
    }

    /**
     * Function front
     * returns the front() iterator of the internal segment list
     */
    IDF_SEGMENT*& front( void )
    {
        return outline.front();
    }

    /**
     * Function back
     * returns the back() iterator of the internal segment list
     */
    IDF_SEGMENT*& back( void )
    {
        return outline.back();
    }

    /**
     * Function begin
     * returns the begin() iterator of the internal segment list
     */
    std::list<IDF_SEGMENT*>::iterator begin( void )
    {
        return outline.begin();
    }

    /**
     * Function end
     * returns the end() iterator of the internal segment list
     */
    std::list<IDF_SEGMENT*>::iterator end( void )
    {
        return outline.end();
    }

    /**
     * Function push
     * adds a segment to the internal segment list; segments must be added
     * in order so that startPoint[N] == endPoint[N - 1]
     *
     * @param item is a pointer to the segment to add to the outline
     *
     * @return bool: true if the segment was added, otherwise false
     * (outline restrictions have been violated)
     */
    bool push( IDF_SEGMENT* item );
};

#endif  // IDF_COMMON_H