haskal
/
kicad
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
kicad/utils/idftools/idf_common.h

716 lines
20 KiB
C++
Raw Blame History

/**
* @file idf_common.h
*/
/*
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2013-2017 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>
#include <cmath>
// 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 ) noexcept;
virtual ~IDF_ERROR() noexcept;
virtual const char* what() const noexcept override;
};
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
}
/**
* 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::istream& 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::ostream& 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();
/**
* 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::istream& 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::ostream& 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 ) const;
/**
* Function GetDrillDia
* returns the drill diameter in mm
*/
double GetDrillDia() const;
/**
* Function GetDrillXPos
* returns the drill's X position in mm
*/
double GetDrillXPos() const;
/**
* Function GetDrillYPos
* returns the drill's Y position in mm
*/
double GetDrillYPos() const;
/**
* 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() const
{
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;
}
IDF_POINT( double aX, double aY )
{
x = aX;
y = aY;
}
/**
* 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 ) const;
/**
* 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();
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();
/**
* Function GetMinX()
* returns the minimum X coordinate of this segment
*/
double GetMinX();
/**
* Function SwapEnds()
* Swaps the start and end points and alters internal
* variables as necessary for arcs
*/
void SwapEnds();
};
/**
* @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();
/**
* Function IsCircle
* returns true if this outline is a circle
*/
bool IsCircle();
/**
* Function Clear
* clears the internal list of outline segments
*/
void Clear()
{
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()
{
return outline.size();
}
/**
* Function empty
* returns true if the internal segment list is empty
*/
bool empty()
{
return outline.empty();
}
/**
* Function front
* returns the front() iterator of the internal segment list
*/
IDF_SEGMENT*& front()
{
return outline.front();
}
/**
* Function back
* returns the back() iterator of the internal segment list
*/
IDF_SEGMENT*& back()
{
return outline.back();
}
/**
* Function begin
* returns the begin() iterator of the internal segment list
*/
std::list<IDF_SEGMENT*>::iterator begin()
{
return outline.begin();
}
/**
* Function end
* returns the end() iterator of the internal segment list
*/
std::list<IDF_SEGMENT*>::iterator end()
{
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
Reference in New Issue View Git Blame Copy Permalink