From 507a88524a8aec5ca97551c3f55fe69b6b1980a8 Mon Sep 17 00:00:00 2001 From: Wayne Stambaugh Date: Thu, 1 Jul 2021 13:46:17 -0400 Subject: [PATCH] KiCad internal library header file housekeeping. --- .../include/convert_basic_shapes_to_polygon.h | 128 +++---- libs/kimath/include/geometry/circle.h | 67 ++-- libs/kimath/include/geometry/convex_hull.h | 30 +- .../include/geometry/poly_grid_partition.h | 36 +- .../include/geometry/polygon_triangulation.h | 121 +++--- libs/kimath/include/geometry/shape_arc.h | 81 ++-- libs/kimath/include/geometry/shape_compound.h | 3 +- libs/kimath/include/geometry/shape_file_io.h | 48 +-- libs/kimath/include/geometry/shape_index.h | 113 +++--- .../include/geometry/shape_line_chain.h | 350 +++++++++--------- libs/kimath/include/geometry/shape_simple.h | 55 ++- libs/kimath/include/math/box2.h | 112 +++--- libs/kimath/include/math/matrix3x3.h | 32 +- libs/kimath/include/math/util.h | 19 +- 14 files changed, 576 insertions(+), 619 deletions(-) diff --git a/libs/kimath/include/convert_basic_shapes_to_polygon.h b/libs/kimath/include/convert_basic_shapes_to_polygon.h index b548ee952f..dc4491e373 100644 --- a/libs/kimath/include/convert_basic_shapes_to_polygon.h +++ b/libs/kimath/include/convert_basic_shapes_to_polygon.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2012 Jean-Pierre Charras, jp.charras at wanadoo.fr - * Copyright (C) 1992-2019 KiCad Developers, see change_log.txt for contributors. + * Copyright (C) 1992-2021 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 @@ -49,68 +49,70 @@ enum RECT_CHAMFER_POSITIONS : int /** - * Function TransformCircleToPolygon - * convert a circle to a polygon, using multiple straight lines - * @param aCornerBuffer = a buffer to store the polygon - * @param aCenter = the center of the circle - * @param aRadius = the radius of the circle - * @param aError = the IU allowed for error in approximation - * @param aErrorLoc = should the approximation error be placed outside or inside the polygon? + * Convert a circle to a polygon, using multiple straight lines. + * + * @param aCornerBuffer is a buffer to store the polygon. + * @param aCenter is the center of the circle. + * @param aRadius is the radius of the circle. + * @param aError is the internal units allowed for error approximation. + * @param aErrorLoc determines if the approximation error be placed outside or inside the polygon. */ void TransformCircleToPolygon( SHAPE_LINE_CHAIN& aCornerBuffer, wxPoint aCenter, int aRadius, int aError, ERROR_LOC aErrorLoc ); /** - * Function TransformCircleToPolygon - * convert a circle to a polygon, using multiple straight lines - * @param aCornerBuffer = a buffer to store the polygon - * @param aCenter = the center of the circle - * @param aRadius = the radius of the circle - * @param aError = the IU allowed for error in approximation - * @param aErrorLoc = should the approximation error be placed outside or inside the polygon? + * Convert a circle to a polygon, using multiple straight lines. + * + * @param aCornerBuffer is a buffer to store the polygon. + * @param aCenter is the center of the circle. + * @param aRadius is the radius of the circle. + * @param aError is the internal units allowed for error in approximation. + * @param aErrorLoc determines if the approximation error be placed outside or inside the polygon. */ void TransformCircleToPolygon( SHAPE_POLY_SET& aCornerBuffer, wxPoint aCenter, int aRadius, int aError, ERROR_LOC aErrorLoc ); /** - * convert a oblong shape to a polygon, using multiple segments - * It is similar to TransformRoundedEndsSegmentToPolygon, but the polygon - * is outside the actual oblong shape (a segment with rounded ends) - * It is suitable to create oblong clearance areas. - * because multiple segments create a smaller area than the circle, the - * radius of the circle to approximate must be bigger ( radius*aCorrectionFactor) - * to create segments outside the circle. - * @param aCornerBuffer = a buffer to store the polygon - * @param aStart = the first point of the segment - * @param aEnd = the second point of the segment - * @param aWidth = the width of the segment - * @param aError = the IU allowed for error in approximation - * @param aErrorLoc = should the approximation error be placed outside or inside the polygon? + * Convert a oblong shape to a polygon, using multiple segments. + * + * It is similar to TransformRoundedEndsSegmentToPolygon, but the polygon is outside the actual + * oblong shape (a segment with rounded ends). It is suitable to create oblong clearance areas + * because multiple segments create a smaller area than the circle. The radius of the circle to + * approximate must be bigger ( radius*aCorrectionFactor) to create segments outside the circle. + * + * @param aCornerBuffer is a buffer to store the polygon. + * @param aStart is the first point of the segment. + * @param aEnd is the second point of the segment. + * @param aWidth is the width of the segment. + * @param aError is the internal units allowed for error in approximation. + * @param aErrorLoc determines if the approximation error be placed outside or inside the polygon. */ void TransformOvalToPolygon( SHAPE_POLY_SET& aCornerBuffer, wxPoint aStart, wxPoint aEnd, int aWidth, int aError, ERROR_LOC aErrorLoc ); /** - * convert a rectangle with rounded corners and/or chamfered corners to a polygon + * Convert a rectangle with rounded corners and/or chamfered corners to a polygon. + * * Convert rounded corners arcs to multiple straight lines. This will generate at least - * 16 segments per circle - * @param aCornerBuffer = a buffer to store the polygon - * @param aPosition = the coordinate of the center of the rectangle - * @param aSize = the size of the rectangle - * @param aCornerRadius = radius of rounded corners (can be 0) - * @param aRotation = rotation in 0.1 degrees of the rectangle - * @param aChamferRatio = ratio between smaller rect size and chamfer value - * @param aChamferCorners = identifier of the corners to chamfer: - * 0 = no chamfer - * 1 = TOP_LEFT - * 2 = TOP_RIGHT - * 4 = BOTTOM_LEFT - * 8 = BOTTOM_RIGHT - * One can have more than one chamfered corner by ORing the corner identifers - * @param aError = the IU allowed for error in approximation - * @param aErrorLoc = should the approximation error be placed outside or inside the polygon? + * 16 segments per circle. + * + * @param aCornerBuffer is a buffer to store the polygon. + * @param aPosition is the coordinate of the center of the rectangle. + * @param aSize is the size of the rectangle. + * @param aCornerRadius is the radius of rounded corners (can be 0). + * @param aRotation is the rotation in 0.1 degrees of the rectangle. + * @param aChamferRatio is the ratio between smaller rect size and chamfer value. + * @param aChamferCorners is the identifier of the corners to chamfer: + * - 0 = no chamfer + * - 1 = TOP_LEFT + * - 2 = TOP_RIGHT + * - 4 = BOTTOM_LEFT + * - 8 = BOTTOM_RIGHT + * One can have more than one chamfered corner by ORing the corner identifiers. + * @param aError is the IU allowed for error in approximation. + * @param aErrorLoc determines if the approximation error be placed outside or inside the polygon. */ void TransformRoundChamferedRectToPolygon( SHAPE_POLY_SET& aCornerBuffer, const wxPoint& aPosition, const wxSize& aSize, @@ -119,30 +121,28 @@ void TransformRoundChamferedRectToPolygon( SHAPE_POLY_SET& aCornerBuffer, int aError, ERROR_LOC aErrorLoc ); /** - * Function TransformArcToPolygon - * Creates a polygon from an Arc - * Convert arcs to multiple straight segments - * @param aCornerBuffer = a buffer to store the polygon - * @param aCentre = centre of the arc or circle - * @param aStart = start point of the arc, or a point on the circle - * @param aArcAngle = arc angle in 0.1 degrees. For a circle, aArcAngle = 3600 - * @param aWidth = width (thickness) of the line - * @param aError = the IU allowed for error in approximation - * @param aErrorLoc = should the approximation error be placed outside or inside the polygon? + * Convert arc to multiple straight segments. + * + * @param aCornerBuffer is a buffer to store the polygon. + * @param aCentre is the center of the arc or circle. + * @param aStart is the start point of the arc or a point on the circle. + * @param aArcAngle is the arc angle in 0.1 degrees. For a circle, aArcAngle = 3600. + * @param aWidth is the width (thickness) of the line. + * @param aError is the internal units allowed for error in approximation. + * @param aErrorLoc determines if the approximation error be placed outside or inside the polygon. */ void TransformArcToPolygon( SHAPE_POLY_SET& aCornerBuffer, wxPoint aStart, wxPoint aMid, wxPoint aEnd, int aWidth, int aError, ERROR_LOC aErrorLoc ); /** - * Function TransformRingToPolygon - * Creates a polygon from a ring - * Convert arcs to multiple straight segments - * @param aCornerBuffer = a buffer to store the polygon - * @param aCentre = centre of the arc or circle - * @param aRadius = radius of the circle - * @param aWidth = width (thickness) of the ring - * @param aError = the IU allowed for error in approximation - * @param aErrorLoc = should the approximation error be placed outside or inside the polygon? + * Convert arcs to multiple straight segments. + * + * @param aCornerBuffer is a buffer to store the polygon. + * @param aCentre is the center of the arc or circle. + * @param aRadius is the radius of the circle. + * @param aWidth is the width (thickness) of the ring. + * @param aError is the internal units allowed for error in approximation. + * @param aErrorLoc determines if the approximation error be placed outside or inside the polygon. */ void TransformRingToPolygon( SHAPE_POLY_SET& aCornerBuffer, wxPoint aCentre, int aRadius, int aWidth, int aError, ERROR_LOC aErrorLoc ); diff --git a/libs/kimath/include/geometry/circle.h b/libs/kimath/include/geometry/circle.h index 89a29f631b..a7427ed903 100644 --- a/libs/kimath/include/geometry/circle.h +++ b/libs/kimath/include/geometry/circle.h @@ -27,15 +27,11 @@ class SEG; /** - * Class Circle - * Represents basic circle geometry with utility geometry functions. + * Represent basic circle geometry with utility geometry functions. */ class CIRCLE { public: - int Radius; ///< Public to make access simpler - VECTOR2I Center; ///< Public to make access simpler - CIRCLE(); CIRCLE( const VECTOR2I& aCenter, int aRadius ); @@ -43,79 +39,72 @@ public: CIRCLE( const CIRCLE& aOther ); /** - * Constructs this circle such that it is tangent to the given segments and passes through the + * Construct this circle such that it is tangent to the given segments and passes through the * given point, generating the solution which can be used to fillet both segments. * * The caller is responsible for ensuring it is providing a solvable problem. This function will * assert if this is not the case. * * @param aLineA is the first tangent line. Treated as an infinite line except for the purpose - * of selecting the solution to return. + * of selecting the solution to return. * @param aLineB is the second tangent line. Treated as an infinite line except for the purpose - * of selecting the solution to return. - * @param aP is the point to pass through - * @return *this + * of selecting the solution to return. + * @param aP is the point to pass through. + * @return this circle. */ CIRCLE& ConstructFromTanTanPt( const SEG& aLineA, const SEG& aLineB, const VECTOR2I& aP ); /** - * Function NearestPoint() - * - * Computes the point on the circumference of the circle that is the closest to aP. + * Compute the point on the circumference of the circle that is the closest to aP. * * In other words: finds the intersection point of this circle and a line that passes through * both this circle's center and aP. * - * @param aP - * @return nearest point to aP + * @param aP. + * @return nearest point to aP. */ VECTOR2I NearestPoint( const VECTOR2I& aP ) const; /** - * Function Intersect() + * Compute the intersection points between this circle and \a aCircle. * - * Computes the intersection points between this circle and aCircle. - * - * @param aCircle The other circle to intersect with this + * @param aCircle The other circle to intersect with this. * @return std::vector containing: - * - 0 elements if the circles do not intersect - * - 1 element if the circles are tangent - * - 2 elements if the circles intersect + * - 0 elements if the circles do not intersect. + * - 1 element if the circles are tangent. + * - 2 elements if the circles intersect. */ std::vector Intersect( const CIRCLE& aCircle ) const; /** - * Function Intersect() + * Compute the intersection points between this circle and \a aSeg. * - * Computes the intersection points between this circle and aSeg. - * - * @param aSeg The segment to intersect with this circle (end points ignored) - * @return std::vector containing up to two intersection points + * @param aSeg The segment to intersect with this circle (end points ignored). + * @return std::vector containing up to two intersection points. */ std::vector Intersect( const SEG& aSeg ) const; /** - * Function IntersectLine() + * Compute the intersection points between this circle and aLine. * - * Computes the intersection points between this circle and aLine. - * - * @param aLine The line to intersect with this circle (end points ignored) + * @param aLine The line to intersect with this circle (end points ignored). * @return std::vector containing: - * - 0 elements if there is no intersection - * - 1 element if the line is tangent to the circle - * - 2 elements if the line intersects the circle + * - 0 elements if there is no intersection. + * - 1 element if the line is tangent to the circle. + * - 2 elements if the line intersects the circle. */ std::vector IntersectLine( const SEG& aLine ) const; /** - * Function Contains() + * Check whether point aP is inside this circle. * - * Checks whether point aP is inside this circle. - * - * @param aP The point to check - * @return true if the point is inside, false otherwise + * @param aP The point to check. + * @return true if the point is inside, false otherwise. */ bool Contains( const VECTOR2I& aP ); + + int Radius; ///< Public to make access simpler + VECTOR2I Center; ///< Public to make access simpler }; #endif // __CIRCLE_H diff --git a/libs/kimath/include/geometry/convex_hull.h b/libs/kimath/include/geometry/convex_hull.h index 25f425020e..1da0780429 100644 --- a/libs/kimath/include/geometry/convex_hull.h +++ b/libs/kimath/include/geometry/convex_hull.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2016 Jean-Pierre Charras, jp.charras at wanadoo.fr - * Copyright (C) 1992-2016 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2021 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 @@ -27,32 +27,34 @@ #include + class wxPoint; // Defined in wxWidgets class SHAPE_POLY_SET; /** - * Calculate the convex hull of a list of points - * in counter-clockwise order. - * @param aResult = a vector to store the convex polygon. + * Calculate the convex hull of a list of points in counter-clockwise order. + * + * @param aResult is a vector to store the convex polygon. * @param aPoly is the list of points. */ -void BuildConvexHull( std::vector& aResult, const std::vector& aPoly); - +void BuildConvexHull( std::vector& aResult, const std::vector& aPoly ); /** - * Calculate the convex hull of a SHAPE_POLY_SET - * @param aResult = a vector to store the convex polygon. - * @param aPolygons = the SHAPE_POLY_SET + * Calculate the convex hull of a #SHAPE_POLY_SET. + * + * @param aResult is a vector to store the convex polygon. + * @param aPolygons is the #SHAPE_POLY_SET. */ void BuildConvexHull( std::vector& aResult, const SHAPE_POLY_SET& aPolygons ); /** - * Calculate the convex hull (rotated and moved) of a SHAPE_POLY_SET - * @param aResult = a vector to store the convex polygon. - * @param aPolygons is the set of polygons - * @param aPosition = the final position of the convex hull - * @param aRotation = the rotation of the convex hull + * Calculate the convex hull (rotated and moved) of a #SHAPE_POLY_SET. + * + * @param aResult is a vector to store the convex polygon. + * @param aPolygons is the set of polygons. + * @param aPosition is the final position of the convex hull. + * @param aRotation is the rotation of the convex hull. */ void BuildConvexHull( std::vector& aResult, const SHAPE_POLY_SET& aPolygons, wxPoint aPosition, double aRotation ); diff --git a/libs/kimath/include/geometry/poly_grid_partition.h b/libs/kimath/include/geometry/poly_grid_partition.h index bc0de2867d..eec25e0dff 100644 --- a/libs/kimath/include/geometry/poly_grid_partition.h +++ b/libs/kimath/include/geometry/poly_grid_partition.h @@ -2,6 +2,7 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2016-2017 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -38,24 +39,29 @@ #include /** - * Class POLY_GRID_PARTITION - * - * Provides a fast test for point inside polygon. + * Provide a fast test for point inside polygon. * * Takes a large poly and splits it into a grid of rectangular cells, forming a spatial hash table. * Each cell contains only the edges that 'touch it' (any point of the edge belongs to the cell). - * Edges can be marked as leading or trailing. Leading edge indicates that space to the left of it (x-wise) is outside the polygon. - * Trailing edge, conversely, means space to the right is outside the polygon. + * Edges can be marked as leading or trailing. Leading edge indicates that space to the left of + * it (x-wise) is outside the polygon. Trailing edge, conversely, means space to the right is + * outside the polygon. + * * The point inside check for point (p) works as follows: - * - determine the cell coordinates of (p) (poly2grid) - * - find the matching grid cell ( O(0), if the cell coordinates are outside the range, the point is not in the polygon ) - * - if the cell contains edges, find the first edge to the left or right of the point, whichever comes first. - * - if the edge to the left is the 'lead edge', the point is inside. if it's a trailing edge, the point is outside. - * - idem for the edge to the right of (p), just reverse the edge types - * - if the cell doesn't contain any edges, scan horizontal cells to the left and right (switching sides with each iteration) - * until an edge if found. - * NOTE: the rescale_trunc() function is used for grid<->world coordinate conversion because it rounds towards 0 (not to nearest) - * It's important as rounding to nearest (which the standard rescale() function does) will shift the grid by half a cell. + * - determine the cell coordinates of (p) (poly2grid) + * - find the matching grid cell ( O(0), if the cell coordinates are outside the range, the point + * is not in the polygon ). + * - if the cell contains edges, find the first edge to the left or right of the point, whichever + * comes first. + * - if the edge to the left is the 'lead edge', the point is inside. if it's a trailing edge, the + * point is outside. + * - idem for the edge to the right of (p), just reverse the edge types. + * - if the cell doesn't contain any edges, scan horizontal cells to the left and right (switching + * sides with each iteration) until an edge if found. + * + * @note: The rescale_trunc() function is used for grid<->world coordinate conversion because it + * rounds towards 0 (not to nearest). It's important as rounding to nearest (which the + * standard rescale() function does) will shift the grid by half a cell. */ class POLY_GRID_PARTITION @@ -108,7 +114,7 @@ private: int rescale_trunc( int aNumerator, int aValue, int aDenominator ) const; - // convertes grid cell coordinates to the polygon coordinates + // converts grid cell coordinates to the polygon coordinates const VECTOR2I grid2poly( const VECTOR2I& p ) const; int grid2polyX( int x ) const; diff --git a/libs/kimath/include/geometry/polygon_triangulation.h b/libs/kimath/include/geometry/polygon_triangulation.h index 440c899a36..2896aec1a3 100644 --- a/libs/kimath/include/geometry/polygon_triangulation.h +++ b/libs/kimath/include/geometry/polygon_triangulation.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Modifications Copyright (C) 2018-2019 KiCad Developers + * Modifications Copyright (C) 2018-2021 KiCad Developers * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -95,6 +95,7 @@ private: parent( aParent ) { } + Vertex& operator=( const Vertex& ) = delete; Vertex& operator=( Vertex&& ) = delete; @@ -106,15 +107,14 @@ private: /** - * Function split - * Splits the referenced polygon between the reference point and + * Split the referenced polygon between the reference point and * vertex b, assuming they are in the same polygon. Notes that while we * create a new vertex pointer for the linked list, we maintain the same * vertex index value from the original polygon. In this way, we have * two polygons that both share the same vertices. * - * Returns the pointer to the newly created vertex in the polygon that - * does not include the reference vertex. + * @return the newly created vertex in the polygon that does not include the + * reference vertex. */ Vertex* split( Vertex* b ) { @@ -141,8 +141,7 @@ private: } /** - * Function remove - * Removes the node from the linked list and z-ordered linked list. + * Remove the node from the linked list and z-ordered linked list. */ void remove() { @@ -151,8 +150,10 @@ private: if( prevZ ) prevZ->nextZ = nextZ; + if( nextZ ) nextZ->prevZ = prevZ; + next = NULL; prev = NULL; nextZ = NULL; @@ -166,9 +167,8 @@ private: } /** - * Function updateList * After inserting or changing nodes, this function should be called to - * remove duplicate vertices and ensure z-ordering is correct + * remove duplicate vertices and ensure z-ordering is correct. */ void updateList() { @@ -197,7 +197,7 @@ private: } /** - * Sort all vertices in this vertex's list by their Morton code + * Sort all vertices in this vertex's list by their Morton code. */ void zSort() { @@ -208,12 +208,13 @@ private: for( auto p = next; p && p != this; p = p->next ) queue.push_back( p ); - std::sort( queue.begin(), queue.end(), []( const Vertex* a, const Vertex* b) + std::sort( queue.begin(), queue.end(), []( const Vertex* a, const Vertex* b ) { return a->z < b->z; } ); Vertex* prev_elem = nullptr; + for( auto elem : queue ) { if( prev_elem ) @@ -278,8 +279,8 @@ private: } /** - * Function removeNullTriangles - * Iterates through the list to remove NULL triangles if they exist. + * Iterate through the list to remove NULL triangles if they exist. + * * This should only be called as a last resort when tesselation fails * as the NULL triangles are inserted as Steiner points to improve the * triangulation regularity of polygons @@ -315,9 +316,7 @@ private: } /** - * Function createList - * Takes a Clipper path and converts it into a circular, doubly-linked - * list for triangulation + * Take a Clipper path and converts it into a circular, doubly-linked list for triangulation. */ Vertex* createList( const ClipperLib::Path& aPath ) { @@ -358,9 +357,7 @@ private: } /** - * Function createList - * Takes the SHAPE_LINE_CHAIN and links each point into a - * circular, doubly-linked list + * Take a #SHAPE_LINE_CHAIN and links each point into a circular, doubly-linked list. */ Vertex* createList( const SHAPE_LINE_CHAIN& points ) { @@ -392,15 +389,17 @@ private: } /** - * Function: earcutList - * Walks through a circular linked list starting at aPoint. For each point, - * test to see if the adjacent points form a triangle that is completely enclosed - * by the remaining polygon (an "ear" sticking off the polygon). If the three points - * form an ear, we log the ear's location and remove the center point from the linked list. + * Walk through a circular linked list starting at \a aPoint. * - * This function can be called recursively in the case of difficult polygons. In cases where - * there is an intersection (not technically allowed by KiCad, but could exist in an edited file), - * we create a single triangle and remove both vertices before attempting to + * For each point, test to see if the adjacent points form a triangle that is completely + * enclosed by the remaining polygon (an "ear" sticking off the polygon). If the three + * points form an ear, we log the ear's location and remove the center point from the + * linked list. + * + * This function can be called recursively in the case of difficult polygons. In cases + * where there is an intersection (not technically allowed by KiCad, but could exist in + * an edited file), we create a single triangle and remove both vertices before attempting + * to. */ bool earcutList( Vertex* aPoint, int pass = 0 ) { @@ -448,9 +447,9 @@ private: aPoint = next; - /** - * We've searched the entire polygon for available ears and there are still un-sliced nodes - * remaining + /* + * We've searched the entire polygon for available ears and there are still + * un-sliced nodes remaining. */ if( aPoint == stop ) { @@ -469,20 +468,20 @@ private: } } - /** - * At this point, our polygon should be fully tesselated. + /* + * At this point, our polygon should be fully tessellated. */ return( aPoint->prev == aPoint->next ); } /** - * Function isEar - * Checks whether the given vertex is in the middle of an ear. - * This works by walking forward and backward in zOrder to the limits - * of the minimal bounding box formed around the triangle, checking whether - * any points are located inside the given triangle. + * Check whether the given vertex is in the middle of an ear. * - * Returns true if aEar is the apex point of a ear in the polygon + * This works by walking forward and backward in zOrder to the limits of the minimal + * bounding box formed around the triangle, checking whether any points are located + * inside the given triangle. + * + * @return true if aEar is the apex point of a ear in the polygon. */ bool isEar( Vertex* aEar ) const { @@ -514,6 +513,7 @@ private: && p->inTriangle( *a, *b, *c ) && area( p->prev, p, p->next ) >= 0 ) return false; + p = p->nextZ; } @@ -526,6 +526,7 @@ private: && p->inTriangle( *a, *b, *c ) && area( p->prev, p, p->next ) >= 0 ) return false; + p = p->prevZ; } @@ -533,7 +534,6 @@ private: } /** - * Function splitPolygon * If we cannot find an ear to slice in the current polygon list, we * use this to split the polygon into two separate lists and slice them each * independently. This is assured to generate at least one new ear if the @@ -542,9 +542,11 @@ private: void splitPolygon( Vertex* start ) { Vertex* origPoly = start; + do { Vertex* marker = origPoly->next->next; + while( marker != origPoly->prev ) { // Find a diagonal line that is wholly enclosed by the polygon interior @@ -559,8 +561,10 @@ private: earcutList( newPoly ); return; } + marker = marker->next; } + origPoly = origPoly->next; } while( origPoly != start ); } @@ -582,9 +586,7 @@ private: } /** - * Function area - * Returns the twice the signed area of the triangle formed by vertices - * p, q, r. + * Return the twice the signed area of the triangle formed by vertices p, q, and r. */ double area( const Vertex* p, const Vertex* q, const Vertex* r ) const { @@ -592,9 +594,9 @@ private: } /** - * Function intersects - * Checks for intersection between two segments, end points included. - * Returns true if p1-p2 intersects q1-q2 + * Check for intersection between two segments, end points included. + * + * @return true if p1-p2 intersects q1-q2. */ bool intersects( const Vertex* p1, const Vertex* q1, const Vertex* p2, const Vertex* q2 ) const { @@ -606,14 +608,15 @@ private: } /** - * Function intersectsPolygon - * Checks whether the segment from vertex a -> vertex b crosses any of the segments + * Check whether the segment from vertex a -> vertex b crosses any of the segments * of the polygon of which vertex a is a member. - * Return true if the segment intersects the edge of the polygon + * + * @return true if the segment intersects the edge of the polygon. */ bool intersectsPolygon( const Vertex* a, const Vertex* b ) const { const Vertex* p = a->next; + do { if( p->i != a->i && @@ -629,12 +632,13 @@ private: } /** - * Function locallyInside - * Checks whether the segment from vertex a -> vertex b is inside the polygon - * around the immediate area of vertex a. We don't define the exact area - * over which the segment is inside but it is guaranteed to be inside the polygon - * immediately adjacent to vertex a. - * Returns true if the segment from a->b is inside a's polygon next to vertex a + * Check whether the segment from vertex a -> vertex b is inside the polygon + * around the immediate area of vertex a. + * + * We don't define the exact area over which the segment is inside but it is guaranteed to + * be inside the polygon immediately adjacent to vertex a. + * + * @return true if the segment from a->b is inside a's polygon next to vertex a. */ bool locallyInside( const Vertex* a, const Vertex* b ) const { @@ -645,10 +649,10 @@ private: } /** - * Function insertVertex - * Creates an entry in the vertices lookup and optionally inserts the newly - * created vertex into an existing linked list. - * Returns a pointer to the newly created vertex + * Create an entry in the vertices lookup and optionally inserts the newly created vertex + * into an existing linked list. + * + * @return a pointer to the newly created vertex. */ Vertex* insertVertex( const VECTOR2I& pt, Vertex* last ) { @@ -656,6 +660,7 @@ private: m_vertices.emplace_back( m_result.GetVertexCount() - 1, pt.x, pt.y, this ); Vertex* p = &m_vertices.back(); + if( !last ) { p->prev = p; diff --git a/libs/kimath/include/geometry/shape_arc.h b/libs/kimath/include/geometry/shape_arc.h index b0986583fa..1121047c65 100644 --- a/libs/kimath/include/geometry/shape_arc.h +++ b/libs/kimath/include/geometry/shape_arc.h @@ -42,29 +42,31 @@ public: {}; /** - * SHAPE_ARC ctor using center, start, angle. Center and angle are used to calculate the mid - * and end points of the arc, and are not stored - * @param aArcCenter is the arc center - * @param aArcStartPoint is the arc start point - * @param aCenterAngle is the arc angle in degrees - * @param aWidth is the arc line thickness + * Construct and arc using center, start, angle. + * + * Center and angle are used to calculate the mid and end points of the arc, and are not + * stored. + * + * @param aArcCenter is the arc center. + * @param aArcStartPoint is the arc start point. + * @param aCenterAngle is the arc angle in degrees. + * @param aWidth is the arc line thickness. */ SHAPE_ARC( const VECTOR2I& aArcCenter, const VECTOR2I& aArcStartPoint, double aCenterAngle, int aWidth = 0 ); /** - * SHAPE_ARC ctor. - * @param aArcStart is the arc start point - * @param aArcEnd is the arc end point - * @param aArcMid is the arc mid point - * @param aWidth is the arc line thickness + * @param aArcStart is the arc start point. + * @param aArcEnd is the arc end point. + * @param aArcMid is the arc mid point. + * @param aWidth is the arc line thickness. */ SHAPE_ARC( const VECTOR2I& aArcStart, const VECTOR2I& aArcMid, const VECTOR2I& aArcEnd, int aWidth ); /** - * SHAPE_ARC ctor. - * Builds a SHAPE_ARC which is tangent to two segments and a given radius + * Build a SHAPE_ARC which is tangent to two segments and a given radius. + * * @param aSegmentA is the first segment * @param aSegmentB is the second segment * @param aRadius is the arc radius @@ -82,12 +84,13 @@ public: } /** - * Constructs this arc from the given start, end and angle. + * Construct this arc from the given start, end and angle. + * * @param aStart is the arc starting point * @param aEnd is the arc endpoint * @param aAngle is the arc included angle * @param aWidth is the arc line thickness - * @return *this + * @return this arc. */ SHAPE_ARC& ConstructFromStartEndAngle( const VECTOR2I& aStart, const VECTOR2I& aEnd, double aAngle, double aWidth = 0 ); @@ -122,10 +125,10 @@ public: void Move( const VECTOR2I& aVector ) override; /** - * Function Rotate - * rotates the arc by a given angle about a point - * @param aCenter is the rotation center - * @param aAngle rotation angle in radians + * Rotate the arc by a given angle about a point. + * + * @param aCenter is the rotation center. + * @param aAngle rotation angle in radians. */ void Rotate( double aAngle, const VECTOR2I& aCenter ) override; @@ -145,46 +148,50 @@ public: } /** - * @return the central angle of the arc shape in degrees, normalized between 0.0, 360.0 deg + * @return the central angle of the arc shape in degrees, normalized between 0.0, 360.0 deg. */ double GetCentralAngle() const; /** - * @return the start angle of the arc shape in degrees, normalized between 0.0, 360.0 deg + * @return the start angle of the arc shape in degrees, normalized between 0.0, 360.0 deg. */ double GetStartAngle() const; /** - * @return the end angle of the arc shape in degrees, normalized between 0.0, 360.0 deg + * @return the end angle of the arc shape in degrees, normalized between 0.0, 360.0 deg. */ double GetEndAngle() const; /** - * @return the length of the arc shape + * @return the length of the arc shape. */ double GetLength() const; /** - * @return a default accuray value for ConvertToPolyline() to build the polyline. - * ** Note that the default is ARC_HIGH_DEF in PCBNew units - * This is to allow common geometry collision functions - * Other programs should call this using explicit accuracy values - * TODO: unify KiCad internal units + * @note The default is #ARC_HIGH_DEF in Pcbnew units. This is to allow common geometry + * collision functions. Other programs should call this using explicit accuracy + * values. + * + * @todo Unify KiCad internal units. + * + * @return a default accuracy value for ConvertToPolyline() to build the polyline. */ static double DefaultAccuracyForPCB(){ return 0.005 * PCB_IU_PER_MM; } /** - * Constructs a SHAPE_LINE_CHAIN of segments from a given arc - * @param aAccuracy maximum divergence from true arc given in internal units - * ** Note that the default is ARC_HIGH_DEF in PCBNew units - * This is to allow common geometry collision functions - * Other programs should call this using explicit accuracy values - * TODO: unify KiCad internal units - * @param aEffectiveAccuracy is the actual divergence from true arc given + * Construct a SHAPE_LINE_CHAIN of segments from a given arc. + * + * @note The default is #ARC_HIGH_DEF in Pcbnew units. This is to allow common geometry + * collision functions. Other programs should call this using explicit accuracy + * values. + * + * @todo Unify KiCad internal units. + * + * @param aAccuracy maximum divergence from true arc given in internal units. + * @param aEffectiveAccuracy is the actual divergence from true arc given. * the approximation error is between -aEffectiveAccuracy/2 and +aEffectiveAccuracy/2 * in internal units - * - * @return a SHAPE_LINE_CHAIN + * @return a #SHAPE_LINE_CHAIN. */ const SHAPE_LINE_CHAIN ConvertToPolyline( double aAccuracy = DefaultAccuracyForPCB(), double* aEffectiveAccuracy = nullptr ) const; diff --git a/libs/kimath/include/geometry/shape_compound.h b/libs/kimath/include/geometry/shape_compound.h index 1e435f687e..9aab4ab8c3 100644 --- a/libs/kimath/include/geometry/shape_compound.h +++ b/libs/kimath/include/geometry/shape_compound.h @@ -2,6 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2016-2020 CERN + * Copyright (C) 2021 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 @@ -51,7 +52,7 @@ public: const std::string Format() const override; bool Collide( const SEG& aSeg, int aClearance = 0, int* aActual = nullptr, - VECTOR2I* aLocation = nullptr ) const override; + VECTOR2I* aLocation = nullptr ) const override; bool Collide( const SHAPE* aShape, int aClearance, VECTOR2I* aMTV ) const override { diff --git a/libs/kimath/include/geometry/shape_file_io.h b/libs/kimath/include/geometry/shape_file_io.h index 7392ffcf58..adb4b32b7a 100644 --- a/libs/kimath/include/geometry/shape_file_io.h +++ b/libs/kimath/include/geometry/shape_file_io.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2015 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -32,40 +34,38 @@ class SHAPE; /** - * SHAPE_FILE_IO - * * Helper class for saving/loading shapes from a file. */ class SHAPE_FILE_IO { - public: - enum IO_MODE - { - IOM_READ = 0, - IOM_APPEND, - IOM_WRITE - }; +public: + enum IO_MODE + { + IOM_READ = 0, + IOM_APPEND, + IOM_WRITE + }; - SHAPE_FILE_IO(); - SHAPE_FILE_IO( const std::string& aFilename, IO_MODE aMode = IOM_READ ); - ~SHAPE_FILE_IO(); + SHAPE_FILE_IO(); + SHAPE_FILE_IO( const std::string& aFilename, IO_MODE aMode = IOM_READ ); + ~SHAPE_FILE_IO(); - void BeginGroup( const std::string& aName = ""); - void EndGroup(); + void BeginGroup( const std::string& aName = ""); + void EndGroup(); - SHAPE* Read(); + SHAPE* Read(); - void Write( const SHAPE* aShape, const std::string& aName = "" ); + void Write( const SHAPE* aShape, const std::string& aName = "" ); - void Write( const SHAPE& aShape, const std::string& aName = "" ) - { - Write( &aShape, aName ); - } + void Write( const SHAPE& aShape, const std::string& aName = "" ) + { + Write( &aShape, aName ); + } - private: - FILE* m_file; - bool m_groupActive; - IO_MODE m_mode; +private: + FILE* m_file; + bool m_groupActive; + IO_MODE m_mode; }; #endif // __SHAPE_FILE_IO_H diff --git a/libs/kimath/include/geometry/shape_index.h b/libs/kimath/include/geometry/shape_index.h index 3f06b23573..83f601216b 100644 --- a/libs/kimath/include/geometry/shape_index.h +++ b/libs/kimath/include/geometry/shape_index.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Jacobo Aragunde Pérez * @author Tomasz Wlostowski * @@ -33,12 +35,12 @@ #include /** - * shapeFunctor template function + * Used by #SHAPE_INDEX to get a SHAPE* from another type. * - * It is used by SHAPE_INDEX to get a SHAPE* from another type. * By default relies on T::GetShape() method, should be specialized if the T object * doesn't allow that method. - * @param aItem generic T object + * + * @param aItem generic T object. * @return a SHAPE* object equivalent to object. */ template @@ -48,12 +50,12 @@ static const SHAPE* shapeFunctor( T aItem ) } /** - * boundingBox template method + * Used by #SHAPE_INDEX to get the bounding box of a generic T object. * - * It is used by SHAPE_INDEX to get the bounding box of a generic T object. * By default relies on T::BBox() method, should be specialized if the T object * doesn't allow that method. - * @param aObject generic T object + * + * @param aObject is a generic T object. * @return a BOX2I object containing the bounding box of the T object. */ template @@ -63,13 +65,13 @@ BOX2I boundingBox( T aObject ) } /** - * acceptVisitor template method + * Used by #SHAPE_INDEX to implement Accept(). * - * It is used by SHAPE_INDEX to implement Accept(). * By default relies on V::operation() redefinition, should be specialized if V class * doesn't have its () operation defined to accept T objects. - * @param aObject generic T object - * @param aVisitor V visitor object + * + * @param aObject is a generic T object. + * @param aVisitor is a visitor object. */ template void acceptVisitor( T aObject, V aVisitor ) @@ -78,15 +80,15 @@ void acceptVisitor( T aObject, V aVisitor ) } /** - * collide template method + * Used by #SHAPE_INDEX to implement Query(). * - * It is used by SHAPE_INDEX to implement Query(). * By default relies on T::Collide(U) method, should be specialized if the T object * doesn't allow that method. - * @param aObject generic T object - * @param aAnotherObject generic U object - * @param aMinDistance minimum collision distance - * @return if object and anotherObject collide + * + * @param aObject is a generic T object. + * @param aAnotherObject is a generic U object. + * @param aMinDistance is the minimum collision distance. + * @return true if object and anotherObject collide. */ template bool collide( T aObject, U aAnotherObject, int aMinDistance ) @@ -115,10 +117,9 @@ class SHAPE_INDEX RTreeIterator iterator; /** - * Function Init() - * * Setup the internal tree iterator. - * @param aTree pointer to a RTREE object + * + * @param aTree is a #RTREE object/ */ void Init( RTree* aTree ) { @@ -127,10 +128,9 @@ class SHAPE_INDEX public: /** - * Iterator constructor + * Create an iterator for the index object. * - * Creates an iterator for the index object - * @param aIndex SHAPE_INDEX object to iterate + * @param aIndex is a #SHAPE_INDEX object to iterate. */ Iterator( SHAPE_INDEX* aIndex ) { @@ -138,9 +138,7 @@ class SHAPE_INDEX } /** - * Operator * (prefix) - * - * Returns the next data element. + * Return the next data element. */ T operator*() { @@ -148,9 +146,7 @@ class SHAPE_INDEX } /** - * Operator ++ (prefix) - * - * Shifts the iterator to the next element. + * Shift the iterator to the next element. */ bool operator++() { @@ -158,9 +154,7 @@ class SHAPE_INDEX } /** - * Operator ++ (postfix) - * - * Shifts the iterator to the next element. + * Shift the iterator to the next element. */ bool operator++( int ) { @@ -168,10 +162,9 @@ class SHAPE_INDEX } /** - * Function IsNull() + * Check if the iterator has reached the end. * - * Checks if the iterator has reached the end. - * @return true if it is in an invalid position (data finished) + * @return true if it is in an invalid position (data finished). */ bool IsNull() const { @@ -179,10 +172,9 @@ class SHAPE_INDEX } /** - * Function IsNotNull() + * Check if the iterator has not reached the end. * - * Checks if the iterator has not reached the end. - * @return true if it is in an valid position (data not finished) + * @return true if it is in an valid position (data not finished). */ bool IsNotNull() const { @@ -190,11 +182,9 @@ class SHAPE_INDEX } /** - * Function Next() + * Return the current element of the iterator and moves to the next position. * - * Returns the current element of the iterator and moves to the next - * position. - * @return SHAPE object pointed by the iterator before moving to the next position. + * @return a #SHAPE object pointed by the iterator before moving to the next position. */ T Next() { @@ -210,40 +200,36 @@ class SHAPE_INDEX ~SHAPE_INDEX(); /** - * Function Add() + * Add a #SHAPE to the index. * - * Adds a SHAPE to the index. * @param aShape is the new SHAPE. */ void Add( T aShape ); /** - * Adds a shape with alternate BBox - * @param aShape Shape (Item) to add + * Add a shape with alternate BBox. + * + * @param aShape Shape (Item) to add. * @param aBbox alternate bounding box. This should be a subset of the item's bbox */ void Add( T aShape, const BOX2I& aBbox ); /** - * Function Remove() + * Remove a #SHAPE from the index. * - * Removes a SHAPE to the index. - * @param aShape is the new SHAPE. + * @param aShape is the #SHAPE to remove. */ void Remove( T aShape ); /** - * Function RemoveAll() - * - * Removes all the contents of the index. + * Remove all the contents of the index. */ void RemoveAll(); /** - * Function Accept() + * Accept a visitor for every #SHAPE object contained in this INDEX. * - * Accepts a visitor for every SHAPE object contained in this INDEX. - * @param aVisitor Visitor object to be run + * @param aVisitor is the visitor object to be run. */ template void Accept( V aVisitor ) @@ -259,20 +245,18 @@ class SHAPE_INDEX } /** - * Function Reindex() + * Rebuild the index. * - * Rebuilds the index. This should be used if the geometry of the objects - * contained by the index has changed. + * This should be used if the geometry of the objects contained by the index has changed. */ void Reindex(); /** - * Function Query() + * Run a callback on every #SHAPE object contained in the bounding box of (shape). * - * Runs a callback on every SHAPE object contained in the bounding box of (shape). - * @param aShape shape to search against - * @param aMinDistance distance threshold - * @param aVisitor object to be invoked on every object contained in the search area. + * @param aShape is the shape to search against. + * @param aMinDistance is the distance threshold. + * @param aVisitor is the object to be invoked on every object contained in the search area. */ template int Query( const SHAPE *aShape, int aMinDistance, V& aVisitor) const @@ -287,10 +271,9 @@ class SHAPE_INDEX } /** - * Function Begin() + * Create an iterator for the current index object. * - * Creates an iterator for the current index object - * @return iterator + * @return iterator to the first object. */ Iterator Begin(); diff --git a/libs/kimath/include/geometry/shape_line_chain.h b/libs/kimath/include/geometry/shape_line_chain.h index 8dda88fccb..b09291c622 100644 --- a/libs/kimath/include/geometry/shape_line_chain.h +++ b/libs/kimath/include/geometry/shape_line_chain.h @@ -35,13 +35,12 @@ /** - * SHAPE_LINE_CHAIN + * Represent a polyline (an zero-thickness chain of connected line segments). * - * Represents a polyline (an zero-thickness chain of connected line segments). - * I purposely didn't name it "polyline" to avoid confusion with the existing CPolyLine - * in pcbnew. + * It is purposely not named "polyline" to avoid confusion with the existing CPolyLine + * in Pcbnew. * - * SHAPE_LINE_CHAIN class shall not be used for polygons! + * @note The SHAPE_LINE_CHAIN class shall not be used for polygons! */ class SHAPE_LINE_CHAIN : public SHAPE_LINE_CHAIN_BASE { @@ -51,32 +50,36 @@ private: public: /** - * Struct INTERSECTION - * - * Represents an intersection between two line segments + * Represent an intersection between two line segments */ struct INTERSECTION { - /// point of intersection between our and their. + ///< Point of intersection between our and their. VECTOR2I p; - /// index of the intersecting corner/segment in the 'our' (== this) line + + ///< Index of the intersecting corner/segment in the 'our' (== this) line. int index_our; - /// index of the intersecting corner/segment in the 'their' (Intersect() method parameter) line + + ///< index of the intersecting corner/segment in the 'their' (Intersect() method + ///< parameter) line. int index_their; - /// when true, the corner [index_our] of the 'our' line lies exactly on 'their' line + + ///< When true, the corner [index_our] of the 'our' line lies exactly on 'their' line. bool is_corner_our; - /// when true, the corner [index_their] of the 'their' line lies exactly on 'our' line. - /// Note that when both is_corner_our and is_corner_their are set, the line chains touch with with corners + + ///< When true, the corner [index_their] of the 'their' line lies exactly on 'our' line. + ///< Note that when both is_corner_our and is_corner_their are set, the line chains touch + ///< with with corners. bool is_corner_their; - /// auxiliary flag to avoid copying intersection info to intersection refining code, used by the refining - /// code (e.g. hull handling stuff in the P&S) to reject false intersection points. + + ///< Auxiliary flag to avoid copying intersection info to intersection refining code, + ///< used by the refining code (e.g. hull handling stuff in the P&S) to reject false + ///< intersection points. bool valid; }; /** - * Class POINT_INSIDE_TRACKER - * * A dynamic state checking if a point lies within polygon with a dynamically built outline ( * with each piece of the outline added by AddPolyline () */ @@ -104,16 +107,11 @@ public: /** - * Constructor - * Initializes an empty line chain. + * Initialize an empty line chain. */ SHAPE_LINE_CHAIN() : SHAPE_LINE_CHAIN_BASE( SH_LINE_CHAIN ), m_closed( false ), m_width( 0 ) {} - /** - * Copy Constructor - */ - SHAPE_LINE_CHAIN( const SHAPE_LINE_CHAIN& aShape ) : SHAPE_LINE_CHAIN_BASE( SH_LINE_CHAIN ), m_points( aShape.m_points ), @@ -174,8 +172,7 @@ public: SHAPE* Clone() const override; /** - * Function Clear() - * Removes all points from the line chain. + * Remove all points from the line chain. */ void Clear() { @@ -186,10 +183,9 @@ public: } /** - * Function SetClosed() - * - * Marks the line chain as closed (i.e. with a segment connecting the last point with + * Mark the line chain as closed (i.e. with a segment connecting the last point with * the first point). + * * @param aClosed: whether the line chain is to be closed or not. */ void SetClosed( bool aClosed ) @@ -198,9 +194,7 @@ public: } /** - * Function IsClosed() - * - * @return aClosed: true, when our line is closed. + * @return true when our line is closed. */ bool IsClosed() const override { @@ -208,8 +202,9 @@ public: } /** - * Sets the width of all segments in the chain - * @param aWidth width in internal units + * Set the width of all segments in the chain. + * + * @param aWidth is the width in internal units. */ void SetWidth( int aWidth ) { @@ -217,8 +212,9 @@ public: } /** - * Gets the current width of the segments in the chain - * @return width in internal units + * Get the current width of the segments in the chain. + * + * @return the width in internal units. */ int Width() const { @@ -226,10 +222,9 @@ public: } /** - * Function SegmentCount() + * Return the number of segments in this line chain. * - * Returns number of segments in this line chain. - * @return number of segments + * @return the number of segments. */ int SegmentCount() const { @@ -241,17 +236,18 @@ public: } /** - * Returns the number of shapes (line segments or arcs) in this line chain. - * This is kind of like SegmentCount() but will only count arcs as 1 segment - * @return ArcCount() + the number of non-arc segments + * Return the number of shapes (line segments or arcs) in this line chain. + * + * This is kind of like SegmentCount() but will only count arcs as 1 segment. + * + * @return ArcCount() + the number of non-arc segments. */ int ShapeCount() const; /** - * Function PointCount() + * Return the number of points (vertices) in this line chain. * - * Returns the number of points (vertices) in this line chain - * @return number of points + * @return the number of points. */ int PointCount() const { @@ -259,12 +255,11 @@ public: } /** - * Function Segment() + * Return a copy of the aIndex-th segment in the line chain. * - * Returns a copy of the aIndex-th segment in the line chain. - * @param aIndex: index of the segment in the line chain. Negative values are counted from - * the end (i.e. -1 means the last segment in the line chain) - * @return SEG - aIndex-th segment in the line chain + * @param aIndex is the index of the segment in the line chain. Negative values are counted + * from the end (i.e. -1 means the last segment in the line chain). + * @return a segment at the \a aIndex in the line chain. */ SEG Segment( int aIndex ) { @@ -278,12 +273,11 @@ public: } /** - * Function CSegment() + * Return a constant copy of the \a aIndex segment in the line chain. * - * Returns a constant copy of the aIndex-th segment in the line chain. - * @param aIndex: index of the segment in the line chain. Negative values are counted from - * the end (i.e. -1 means the last segment in the line chain) - * @return const SEG - aIndex-th segment in the line chain + * @param aIndex is the index of the segment in the line chain. Negative values are counted + * from the end (i.e. -1 means the last segment in the line chain). + * @return a segment at \a aIndex in the line chain. */ const SEG CSegment( int aIndex ) const { @@ -297,13 +291,16 @@ public: } /** - * Returns the vertex index of the next shape in the chain, or -1 if aPoint is in the last shape - * If aPoint is the start of a segment, this will be ( aPoint + 1 ). - * If aPoint is part of an arc, this will be the index of the start of the next shape after the - * arc, in other words, the last point of the arc. - * @param aPointIndex is a vertex in the chain - * @param aForwards is true if the next shape is desired, false for previous shape - * @return the vertex index of the start of the next shape after aPoint's shape + * Return the vertex index of the next shape in the chain, or -1 if \a aPoint is in the last + * shape. + * + * If \a aPoint is the start of a segment, this will be ( aPoint + 1 ). If \a aPoint is + * part of an arc, this will be the index of the start of the next shape after the arc, + * in other words, the last point of the arc. + * + * @param aPointIndex is a vertex in the chain. + * @param aForwards is true if the next shape is desired, false for previous shape. + * @return the vertex index of the start of the next shape after aPoint's shape. */ int NextShape( int aPointIndex, bool aForwards = true ) const; @@ -313,9 +310,10 @@ public: } /** - * Accessor Function to move a point to a specific location - * @param aIndex Index (wrapping) of the point to move - * @param aPos New absolute location of the point + * Move a point to a specific location. + * + * @param aIndex is the index of the point to move. + * @param aPos is the new absolute location of the point. */ void SetPoint( int aIndex, const VECTOR2I& aPos ) { @@ -331,11 +329,10 @@ public: } /** - * Function Point() + * Return a reference to a given point in the line chain. * - * Returns a const reference to a given point in the line chain. - * @param aIndex index of the point - * @return const reference to the point + * @param aIndex is the index of the point. + * @return a const reference to the point. */ const VECTOR2I& CPoint( int aIndex ) const { @@ -353,7 +350,7 @@ public: } /** - * Returns the last point in the line chain. + * Return the last point in the line chain. */ const VECTOR2I& CLastPoint() const { @@ -361,7 +358,7 @@ public: } /** - * @return the vector of stored arcs + * @return the vector of stored arcs. */ const std::vector& CArcs() const { @@ -369,7 +366,7 @@ public: } /** - * @return the vector of values indicating shape type and location + * @return the vector of values indicating shape type and location. */ const std::vector& CShapes() const { @@ -402,39 +399,35 @@ public: } /** - * Function Distance() + * Compute the minimum distance between the line chain and a point \a aP. * - * Computes the minimum distance between the line chain and a point aP. - * @param aP the point + * @param aP the point. * @return minimum distance. */ int Distance( const VECTOR2I& aP, bool aOutlineOnly = false ) const; /** - * Function Reverse() + * Reverse point order in the line chain. * - * Reverses point order in the line chain. - * @return line chain with reversed point order (original A-B-C-D: returned D-C-B-A) + * @return line chain with reversed point order (original A-B-C-D: returned D-C-B-A). */ const SHAPE_LINE_CHAIN Reverse() const; /** - * Function Length() + * Return length of the line chain in Euclidean metric. * - * Returns length of the line chain in Euclidean metric. - * @return length of the line chain + * @return the length of the line chain. */ long long int Length() const; /** - * Function Append() + * Append a new point at the end of the line chain. * - * Appends a new point at the end of the line chain. - * @param aX is X coordinate of the new point - * @param aY is Y coordinate of the new point - * @param aAllowDuplication = true to append the new point - * even it is the same as the last entered point - * false (default) to skip it if it is the same as the last entered point + * @param aX is X coordinate of the new point. + * @param aY is Y coordinate of the new point. + * @param aAllowDuplication set to true to append the new point even if it is the same as + * the last entered point, false (default) to skip it if it is the same as the last + * entered point. */ void Append( int aX, int aY, bool aAllowDuplication = false ) { @@ -443,13 +436,12 @@ public: } /** - * Function Append() + * Append a new point at the end of the line chain. * - * Appends a new point at the end of the line chain. - * @param aP the new point - * @param aAllowDuplication = true to append the new point - * even it is the same as the last entered point - * false (default) to skip it if it is the same as the last entered point + * @param aP is the new point. + * @param aAllowDuplication set to true to append the new point even it is the same as the + * last entered point or false (default) to skip it if it is the same as the last + * entered point. */ void Append( const VECTOR2I& aP, bool aAllowDuplication = false ) { @@ -465,10 +457,9 @@ public: } /** - * Function Append() + * Append another line chain at the end. * - * Appends another line chain at the end. - * @param aOtherLine the line chain to be appended. + * @param aOtherLine is the line chain to be appended. */ void Append( const SHAPE_LINE_CHAIN& aOtherLine ); @@ -479,38 +470,35 @@ public: void Insert( size_t aVertex, const SHAPE_ARC& aArc ); /** - * Function Replace() + * Replace points with indices in range [start_index, end_index] with a single point \a aP. * - * Replaces points with indices in range [start_index, end_index] with a single point aP. - * @param aStartIndex start of the point range to be replaced (inclusive) - * @param aEndIndex end of the point range to be replaced (inclusive) - * @param aP replacement point + * @param aStartIndex is the start of the point range to be replaced (inclusive). + * @param aEndIndex is the end of the point range to be replaced (inclusive). + * @param aP is the replacement point. */ void Replace( int aStartIndex, int aEndIndex, const VECTOR2I& aP ); /** - * Function Replace() + * Replace points with indices in range [start_index, end_index] with the points from line + * chain \a aLine. * - * Replaces points with indices in range [start_index, end_index] with the points from line - * chain aLine. - * @param aStartIndex start of the point range to be replaced (inclusive) - * @param aEndIndex end of the point range to be replaced (inclusive) - * @param aLine replacement line chain. + * @param aStartIndex is the start of the point range to be replaced (inclusive). + * @param aEndIndex is the end of the point range to be replaced (inclusive). + * @param aLine is the replacement line chain. */ void Replace( int aStartIndex, int aEndIndex, const SHAPE_LINE_CHAIN& aLine ); /** - * Function Remove() + * Remove the range of points [start_index, end_index] from the line chain. * - * Removes the range of points [start_index, end_index] from the line chain. - * @param aStartIndex start of the point range to be replaced (inclusive) - * @param aEndIndex end of the point range to be replaced (inclusive) + * @param aStartIndex is the start of the point range to be replaced (inclusive). + * @param aEndIndex is the end of the point range to be replaced (inclusive). */ void Remove( int aStartIndex, int aEndIndex ); /** - * Function Remove() - * removes the aIndex-th point from the line chain. + * Remove the aIndex-th point from the line chain. + * * @param aIndex is the index of the point to be removed. */ void Remove( int aIndex ) @@ -519,49 +507,46 @@ public: } /** - * Removes the shape at the given index from the line chain. + * Remove the shape at the given index from the line chain. + * * If the given index is inside an arc, the entire arc will be removed. * Otherwise this is equivalent to Remove( aPointIndex ). - * @param aPointIndex is the index of the point to remove + * + * @param aPointIndex is the index of the point to remove. */ void RemoveShape( int aPointIndex ); /** - * Function Split() - * - * Inserts the point aP belonging to one of the our segments, splitting the adjacent segment + * Insert the point aP belonging to one of the our segments, splitting the adjacent segment * in two. - * @param aP the point to be inserted + * @param aP is the point to be inserted. * @return index of the newly inserted point (or a negative value if aP does not lie on - * our line) + * our line). */ int Split( const VECTOR2I& aP ); /** - * Function Find() + * Search for point \a aP. * - * Searches for point aP. - * @param aP the point to be looked for - * @return index of the corresponding point in the line chain or negative when not found. + * @param aP is the point to be looked for. + * @return the index of the corresponding point in the line chain or negative when not found. */ int Find( const VECTOR2I& aP, int aThreshold = 0 ) const; /** - * Function FindSegment() + * Search for segment containing point \a aP. * - * Searches for segment containing point aP. - * @param aP the point to be looked for + * @param aP is the point to be looked for. * @return index of the corresponding segment in the line chain or negative when not found. */ int FindSegment( const VECTOR2I& aP, int aThreshold = 1 ) const; /** - * Function Slice() + * Return a subset of this line chain containing the [start_index, end_index] range of points. * - * Returns a subset of this line chain containing the [start_index, end_index] range of points. - * @param aStartIndex start of the point range to be returned (inclusive) - * @param aEndIndex end of the point range to be returned (inclusive) - * @return cut line chain. + * @param aStartIndex is the start of the point range to be returned (inclusive). + * @param aEndIndex is the end of the point range to be returned (inclusive). + * @return the cut line chain. */ const SHAPE_LINE_CHAIN Slice( int aStartIndex, int aEndIndex = -1 ) const; @@ -582,86 +567,82 @@ public: bool Intersects( const SHAPE_LINE_CHAIN& aChain ) const; /** - * Function Intersect() + * Find all intersection points between our line chain and the segment \a aSeg. * - * Finds all intersection points between our line chain and the segment aSeg. - * @param aSeg the segment chain to find intersections with - * @param aIp reference to a vector to store found intersections. Intersection points are - * sorted with increasing distances from point aSeg.a. - * @return number of intersections found + * @param aSeg is the segment chain to find intersections with. + * @param aIp is the reference to a vector to store found intersections. Intersection points + * are sorted with increasing distances from point aSeg.a. + * @return the number of intersections found. */ int Intersect( const SEG& aSeg, INTERSECTIONS& aIp ) const; /** - * Function Intersect() + * Find all intersection points between our line chain and the line chain \a aChain. * - * Finds all intersection points between our line chain and the line chain aChain. - * @param aChain the line chain to find intersections with - * @param aIp reference to a vector to store found intersections. Intersection points are - * sorted with increasing path lengths from the starting point of aChain. - * @return number of intersections found + * @param aChain is the line chain to find intersections with. + * @param aIp is reference to a vector to store found intersections. Intersection points are + * sorted with increasing path lengths from the starting point of \a aChain. + * @return the number of intersections found. */ - int Intersect( const SHAPE_LINE_CHAIN& aChain, INTERSECTIONS& aIp, bool aExcludeColinearAndTouching = false ) const; + int Intersect( const SHAPE_LINE_CHAIN& aChain, INTERSECTIONS& aIp, + bool aExcludeColinearAndTouching = false ) const; /** - * Function PathLength() - * - * Computes the walk path length from the beginning of the line chain and the point aP + * Compute the walk path length from the beginning of the line chain and the point \a aP * belonging to our line. - * @return: path length in Euclidean metric or -1 if aP does not belong to the line chain. + * + * @return the path length in Euclidean metric or -1 if aP does not belong to the line chain. */ int PathLength( const VECTOR2I& aP, int aIndex = -1 ) const; /** - * Function CheckClearance() + * Check if point \a aP is closer to (or on) an edge or vertex of the line chain. * - * Checks if point aP is closer to (or on) an edge or vertex of the line chain. - * @param aP point to check - * @param aDist distance in internal units - * @return true if the point is equal to or closer than aDist to the line chain. + * @param aP is the point to check. + * @param aDist is the distance in internal units. + * @return true if the point is equal to or closer than \a aDist to the line chain. */ bool CheckClearance( const VECTOR2I& aP, const int aDist) const; /** - * Function SelfIntersecting() + * Check if the line chain is self-intersecting. * - * Checks if the line chain is self-intersecting. * @return (optional) first found self-intersection point. */ const OPT SelfIntersecting() const; /** - * Function Simplify() + * Simplify the line chain by removing colinear adjacent segments and duplicate vertices. * - * Simplifies the line chain by removing colinear adjacent segments and duplicate vertices. - * @param aRemoveColinear controsl the removal of colinear adjacent segments - * @return reference to self. + * @param aRemoveColinear controls the removal of colinear adjacent segments. + * @return reference to this line chain. */ SHAPE_LINE_CHAIN& Simplify( bool aRemoveColinear = true ); /** - * Converts an arc to only a point chain by removing the arc and references + * Convert an arc to only a point chain by removing the arc and references. * - * @param aArcIndex index of the arc to convert to points + * @param aArcIndex is an index of the arc to convert to points. */ void convertArc( ssize_t aArcIndex ); /** - * Creates a new Clipper path from the SHAPE_LINE_CHAIN in a given orientation + * Create a new Clipper path from the SHAPE_LINE_CHAIN in a given orientation. */ ClipperLib::Path convertToClipper( bool aRequiredOrientation ) const; /** * Find the segment nearest the given point. * - * @param aP point to compare with - * @return the index of the segment closest to the point + * @param aP is the point to compare with. + * @return the index of the segment closest to the point. */ int NearestSegment( const VECTOR2I& aP ) const; /** - * Finds a point on the line chain that is closest to point aP. - * @param aP is the point to find + * Find a point on the line chain that is closest to point \a aP. + * + * @param aP is the point to find. * @param aAllowInternalShapePoints if false will not return points internal to an arc (i.e. * only the arc endpoints are possible candidates) * @return the nearest point. @@ -669,10 +650,11 @@ public: const VECTOR2I NearestPoint( const VECTOR2I& aP, bool aAllowInternalShapePoints = true ) const; /** - * Finds a point on the line chain that is closest to the line defined by the points of - * segment aSeg, also returns the distance. - * @param aSeg Segment defining the line. - * @param dist reference receiving the distance to the nearest point. + * Find a point on the line chain that is closest to the line defined by the points of + * segment \a aSeg, also returns the distance. + * + * @param aSeg is the segment defining the line. + * @param dist is the reference receiving the distance to the nearest point. * @return the nearest point. */ const VECTOR2I NearestPoint( const SEG& aSeg, int& dist ) const; @@ -709,24 +691,26 @@ public: } /** - * Mirrors the line points about y or x (or both) - * @param aX If true, mirror about the y axis (flip X coordinate) - * @param aY If true, mirror about the x axis (flip Y coordinate) - * @param aRef sets the reference point about which to mirror + * Mirror the line points about y or x (or both). + * + * @param aX If true, mirror about the y axis (flip X coordinate). + * @param aY If true, mirror about the x axis (flip Y coordinate). + * @param aRef sets the reference point about which to mirror. */ void Mirror( bool aX = true, bool aY = false, const VECTOR2I& aRef = { 0, 0 } ); /** - * Mirrors the line points using an given axis - * @param axis Axis on which to mirror + * Mirror the line points using an given axis. + * + * @param axis is the axis on which to mirror. */ void Mirror( const SEG& axis ); /** - * Function Rotate - * rotates all vertices by a given angle - * @param aCenter is the rotation center - * @param aAngle rotation angle in radians + * Rotate all vertices by a given angle. + * + * @param aCenter is the rotation center. + * @param aAngle is the rotation angle in radians. */ void Rotate( double aAngle, const VECTOR2I& aCenter = VECTOR2I( 0, 0 ) ) override; @@ -759,7 +743,7 @@ public: bool isArc( size_t aSegment ) const { - /** + /* * A segment is part of an arc except in the special case of two arcs next to each other * but without a shared vertex. Here there is a segment between the end of the first arc * and the start of the second arc. diff --git a/libs/kimath/include/geometry/shape_simple.h b/libs/kimath/include/geometry/shape_simple.h index 57a6f26540..47f38533fe 100644 --- a/libs/kimath/include/geometry/shape_simple.h +++ b/libs/kimath/include/geometry/shape_simple.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2015 Kicad Developers, see change_log.txt for contributors. + * Copyright (C) 2015-2021 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 @@ -31,9 +31,7 @@ #include /** - * SHAPE_SIMPLE - * - * Represents a simple polygon consisting of a zero-thickness closed chain of + * Represent a simple polygon consisting of a zero-thickness closed chain of * connected line segments. * * Internally the vertices are held in a SHAPE_LINE_CHAIN, please note that @@ -44,8 +42,7 @@ class SHAPE_SIMPLE : public SHAPE_LINE_CHAIN_BASE { public: /** - * Constructor - * Creates an empty polygon + * Create an empty polygon. */ SHAPE_SIMPLE() : SHAPE_LINE_CHAIN_BASE( SH_SIMPLE ) @@ -70,8 +67,7 @@ public: } /** - * Function Clear() - * Removes all points from the polygon. + * Remove all points from the polygon. */ void Clear() { @@ -85,10 +81,9 @@ public: } /** - * Function PointCount() + * Return the number of points (vertices) in this polygon. * - * Returns the number of points (vertices) in this polygon - * @return number of points + * @return number of points. */ int PointCount() const { @@ -96,13 +91,13 @@ public: } /** - * Function Point() + * Return a const reference to a given point in the polygon. * - * Returns a const reference to a given point in the polygon. Negative - * indices count from the end of the point list, e.g. -1 means "last - * point", -2 means "second to last point" and so on. - * @param aIndex index of the point - * @return const reference to the point + * Negative indices count from the end of the point list, e.g. -1 means "last point", -2 means + * "second to last point" and so on. + * + * @param aIndex is the index of the point. + * @return the const reference to the point. */ const VECTOR2I& CPoint( int aIndex ) const { @@ -110,12 +105,10 @@ public: } /** - * Function CDPoint() + * Return a given point as a vector with elements of type double. * - * Returns a given point as a vector with elements of type double. - * - * @param aIndex index of the point - * @return the point with elements of type double + * @param aIndex is the index of the point. + * @return the point with elements of type double. */ const VECTOR2D CDPoint( int aIndex ) const { @@ -124,11 +117,9 @@ public: } /** - * Function Vertices() + * Return the list of vertices defining this simple polygon. * - * Returns the list of vertices defining this simple polygon. - * - * @return the list of vertices defining this simple polygon + * @return the list of vertices defining this simple polygon. */ const SHAPE_LINE_CHAIN& Vertices() const { @@ -136,11 +127,10 @@ public: } /** - * Function Append() + * Append a new point at the end of the polygon. * - * Appends a new point at the end of the polygon. - * @param aX is X coordinate of the new point - * @param aY is Y coordinate of the new point + * @param aX is X coordinate of the new point. + * @param aY is Y coordinate of the new point. */ void Append( int aX, int aY ) { @@ -149,10 +139,9 @@ public: } /** - * Function Append() + * Append a new point at the end of the polygon. * - * Appends a new point at the end of the polygon. - * @param aP the new point + * @param aP is the new point. */ void Append( const VECTOR2I& aP ) { diff --git a/libs/kimath/include/math/box2.h b/libs/kimath/include/math/box2.h index 2bd2c837de..485b982e40 100644 --- a/libs/kimath/include/math/box2.h +++ b/libs/kimath/include/math/box2.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck - * Copyright (C) 2012 Kicad Developers, see change_log.txt for contributors. + * Copyright (C) 2012-2021 Kicad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2013 CERN * @author Tomasz Wlostowski * @@ -35,17 +35,11 @@ #include /** - * BOX2 - * handles a 2-D bounding box, built on top of an origin point - * and size vector, both of templated class Vec + * A 2D bounding box built on top of an origin point and size vector. */ template class BOX2 { -private: - Vec m_Pos; // Rectangle Origin - Vec m_Size; // Rectangle Size - public: typedef typename Vec::coord_type coord_type; typedef typename Vec::extended_type ecoord_type; @@ -73,7 +67,7 @@ public: } /** - * @brief Compute the bounding box from a given list of points. + * Compute the bounding box from a given list of points. * * @param aPointList is the list points of the object. */ @@ -103,9 +97,9 @@ public: } /** - * Function Move - * moves the rectangle by the \a aMoveVector. - * @param aMoveVector A point that is the value to move this rectangle + * Move the rectangle by the \a aMoveVector. + * + * @param aMoveVector is a point that is the value to move this rectangle. */ void Move( const Vec& aMoveVector ) { @@ -113,8 +107,7 @@ public: } /** - * Function Normalize - * ensures that the height ant width are positive. + * Ensure that the height ant width are positive. */ BOX2& Normalize() { @@ -134,9 +127,9 @@ public: } /** - * Function Contains - * @param aPoint = the point to test - * @return true if aPoint is inside the boundary box. A point on a edge is seen as inside + * @param aPoint is the point to test. + * + * @return true if \a aPoint is inside the boundary box. A point on a edge is seen as inside. */ bool Contains( const Vec& aPoint ) const { @@ -155,21 +148,21 @@ public: rel_pos.y += size.y; } - return ( rel_pos.x >= 0 ) && ( rel_pos.y >= 0 ) && ( rel_pos.y <= size.y) && ( rel_pos.x <= size.x); + return ( rel_pos.x >= 0 ) && ( rel_pos.y >= 0 ) && ( rel_pos.y <= size.y) && + ( rel_pos.x <= size.x); } /** - * Function Contains - * @param x = the x coordinate of the point to test - * @param y = the x coordinate of the point to test - * @return true if point is inside the boundary box. A point on a edge is seen as inside + * @param x is the x coordinate of the point to test. + * @param y is the x coordinate of the point to test. + * @return true if point is inside the boundary box. A point on a edge is seen as inside. */ bool Contains( coord_type x, coord_type y ) const { return Contains( Vec( x, y ) ); } /** - * Function Contains - * @param aRect = the BOX2 to test - * @return true if aRect is Contained. A common edge is seen as contained + * @param aRect is the the area to test. + * + * @return true if \a aRect is contained. A common edge is seen as contained. */ bool Contains( const BOX2& aRect ) const { @@ -204,8 +197,7 @@ public: void Offset( coord_type dx, coord_type dy ) { m_Pos.x += dx; m_Pos.y += dy; } void Offset( const Vec& offset ) { - m_Pos.x += offset.x; m_Pos.y += - offset.y; + m_Pos.x += offset.x; m_Pos.y += offset.y; } void SetX( coord_type val ) { m_Pos.x = val; } @@ -219,9 +211,8 @@ public: } /** - * Function Intersects - * @return bool - true if the argument rectangle intersects this rectangle. - * (i.e. if the 2 rectangles have at least a common point) + * @return true if the argument rectangle intersects this rectangle. + * (i.e. if the 2 rectangles have at least a common point) */ bool Intersects( const BOX2& aRect ) const { @@ -252,8 +243,7 @@ public: } /** - * Function Intersect - * Returns the intersection of this with another rectangle. + * Return the intersection of this with another rectangle. */ BOX2 Intersect( const BOX2& aRect ) { @@ -285,8 +275,7 @@ public: } /** - * Function Inflate - * inflates the rectangle horizontally by \a dx and vertically by \a dy. If \a dx + * Inflates the rectangle horizontally by \a dx and vertically by \a dy. If \a dx * and/or \a dy is negative the rectangle is deflated. */ BOX2& Inflate( coord_type dx, coord_type dy ) @@ -357,8 +346,7 @@ public: } /** - * Function Inflate - * inflates the rectangle horizontally and vertically by \a aDelta. If \a aDelta + * Inflate the rectangle horizontally and vertically by \a aDelta. If \a aDelta * is negative the rectangle is deflated. */ BOX2& Inflate( int aDelta ) @@ -368,10 +356,9 @@ public: } /** - * Function Merge - * modifies the position and size of the rectangle in order to contain \a aRect. It is - * mainly used to calculate bounding boxes. - * @param aRect The rectangle to merge with this rectangle. + * Modify the position and size of the rectangle in order to contain \a aRect. + * + * @param aRect is the rectangle to merge with this rectangle. */ BOX2& Merge( const BOX2& aRect ) { @@ -391,16 +378,17 @@ public: } /** - * Function Merge - * modifies the position and size of the rectangle in order to contain the given point. - * @param aPoint The point to merge with the rectangle. + * Modify the position and size of the rectangle in order to contain the given point. + * + * @param aPoint is the point to merge with the rectangle. */ BOX2& Merge( const Vec& aPoint ) { Normalize(); // ensure width and height >= 0 Vec end = GetEnd(); - // Change origin and size in order to contain the given rect + + // Change origin and size in order to contain the given rectangle. m_Pos.x = std::min( m_Pos.x, aPoint.x ); m_Pos.y = std::min( m_Pos.y, aPoint.y ); end.x = std::max( end.x, aPoint.x ); @@ -410,8 +398,8 @@ public: } /** - * Function GetArea - * returns the area of the rectangle. + * Return the area of the rectangle. + * * @return The area of the rectangle. */ ecoord_type GetArea() const @@ -420,9 +408,9 @@ public: } /** - * Function GetArea - * returns the length of the diagonal of the rectangle. - * @return The area of the diagonal. + * Return the length of the diagonal of the rectangle. + * + * @return The length of the rectangle diagonal. */ ecoord_type Diagonal() const { @@ -433,8 +421,10 @@ public: { ecoord_type x2 = m_Pos.x + m_Size.x; ecoord_type y2 = m_Pos.y + m_Size.y; - ecoord_type xdiff = std::max( aP.x < m_Pos.x ? m_Pos.x - aP.x : m_Pos.x - x2, (ecoord_type) 0 ); - ecoord_type ydiff = std::max( aP.y < m_Pos.y ? m_Pos.y - aP.y : m_Pos.y - y2, (ecoord_type) 0 ); + ecoord_type xdiff = std::max( aP.x < m_Pos.x ? m_Pos.x - aP.x : m_Pos.x - x2, + (ecoord_type) 0 ); + ecoord_type ydiff = std::max( aP.y < m_Pos.y ? m_Pos.y - aP.y : m_Pos.y - y2, + (ecoord_type) 0 ); return xdiff * xdiff + ydiff * ydiff; } @@ -444,10 +434,10 @@ public: } /** - * Function SquaredDistance - * returns the square of the minimum distance between self and box aBox - * @param aBox: the other box - * @return The distance, squared + * Return the square of the minimum distance between self and box \a aBox + * + * @param aBox is the other box. + * @return The distance squared from \a aBox. */ ecoord_type SquaredDistance( const BOX2& aBox ) const { @@ -479,10 +469,10 @@ public: } /** - * Function Distance - * returns the minimum distance between self and box aBox - * @param aBox: the other box - * @return The distance + * Return the minimum distance between self and \a aBox. + * + * @param aBox is the other box to get the distance from. + * @return The distance from \a aBox. */ ecoord_type Distance( const BOX2& aBox ) const { @@ -506,6 +496,10 @@ public: t2.Normalize(); return ( t1.m_Pos != t2.m_Pos || t1.m_Size != t2.m_Size ); } + +private: + Vec m_Pos; // Rectangle Origin + Vec m_Size; // Rectangle Size }; /* Default specializations */ diff --git a/libs/kimath/include/math/matrix3x3.h b/libs/kimath/include/math/matrix3x3.h index 2e2bbb85a3..49230dc2fa 100644 --- a/libs/kimath/include/math/matrix3x3.h +++ b/libs/kimath/include/math/matrix3x3.h @@ -2,7 +2,7 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2012 Torsten Hueter, torstenhtr gmx.de - * Copyright (C) 2012 Kicad Developers, see change_log.txt for contributors. + * Copyright (C) 2012-2021 Kicad Developers, see AUTHORS.txt for contributors. * * Matrix class (3x3) * @@ -64,15 +64,11 @@ public: T m_data[3][3]; /** - * @brief Constructor - * * Initialize all matrix members to zero. */ MATRIX3x3(); /** - * @brief Constructor - * * Initialize with given matrix members * * @param a00 is the component [0,0]. @@ -88,28 +84,28 @@ public: MATRIX3x3( T a00, T a01, T a02, T a10, T a11, T a12, T a20, T a21, T a22 ); /** - * @brief Set the matrix to the identity matrix. + * Set the matrix to the identity matrix. * * The diagonal components of the matrix are set to 1. */ void SetIdentity(); /** - * @brief Set the translation components of the matrix. + * Set the translation components of the matrix. * * @param aTranslation is the translation, specified as 2D-vector. */ void SetTranslation( VECTOR2 aTranslation ); /** - * @brief Get the translation components of the matrix. + * Get the translation components of the matrix. * * @return is the translation (2D-vector). */ VECTOR2 GetTranslation() const; /** - * @brief Set the rotation components of the matrix. + * Set the rotation components of the matrix. * * The angle needs to have a positive value for an anti-clockwise rotation. * @@ -118,28 +114,28 @@ public: void SetRotation( T aAngle ); /** - * @brief Set the scale components of the matrix. + * Set the scale components of the matrix. * * @param aScale contains the scale factors, specified as 2D-vector. */ void SetScale( VECTOR2 aScale ); /** - * @brief Get the scale components of the matrix. + * Get the scale components of the matrix. * * @return the scale factors, specified as 2D-vector. */ VECTOR2 GetScale() const; /** - * @brief Compute the determinant of the matrix. + * Compute the determinant of the matrix. * * @return the determinant value. */ T Determinant() const; /** - * @brief Determine the inverse of the matrix. + * Determine the inverse of the matrix. * * The inverse of a transformation matrix can be used to revert a transformation. * @@ -151,14 +147,14 @@ public: MATRIX3x3 Inverse() const; /** - * @brief Get the transpose of the matrix. + * Get the transpose of the matrix. * * @return the transpose matrix. */ MATRIX3x3 Transpose() const; /** - * @brief Output to a stream. + * Output to a stream. */ friend std::ostream& operator<<( std::ostream& aStream, const MATRIX3x3& aMatrix ); @@ -166,13 +162,13 @@ public: // Operators -//! @brief Matrix multiplication +//! Matrix multiplication template MATRIX3x3 const operator*( MATRIX3x3 const& aA, MATRIX3x3 const& aB ); -//! @brief Multiplication with a 2D vector, the 3rd z-component is assumed to be 1 +//! Multiplication with a 2D vector, the 3rd z-component is assumed to be 1 template VECTOR2 const operator*( MATRIX3x3 const& aA, VECTOR2 const& aB ); -//! @brief Multiplication with a scalar +//! Multiplication with a scalar template MATRIX3x3 const operator*( MATRIX3x3 const& aA, T aScalar ); template MATRIX3x3 const operator*( T aScalar, MATRIX3x3 const& aMatrix ); diff --git a/libs/kimath/include/math/util.h b/libs/kimath/include/math/util.h index d6693a5c35..c9407c2086 100644 --- a/libs/kimath/include/math/util.h +++ b/libs/kimath/include/math/util.h @@ -3,6 +3,8 @@ * * Copyright (c) 2005 Michael Niedermayer * Copyright (C) CERN + * Copyright (C) 2021 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -37,14 +39,15 @@ void kimathLogDebug( const char* aFormatString, ... ); /** - * Function Clamp - * limits @a value within the range @a lower <= @a value <= @a upper. It will work - * on temporary expressions, since they are evaluated only once, and it should work - * on most if not all numeric types, string types, or any type for which "operator < ()" - * is present. The arguments are accepted in this order so you can remember the - * expression as a memory aid: + * Limit @a value within the range @a lower <= @a value <= @a upper. + * + * It will work on temporary expressions, since they are evaluated only once, and it should + * work on most if not all numeric types, string types, or any type for which "operator < ()" + * is present. The arguments are accepted in this order so you can remember the expression as + * a memory aid: *

* result is: lower <= value <= upper + *

*/ template inline const T& Clamp( const T& lower, const T& value, const T& upper ) { @@ -88,9 +91,7 @@ constexpr ret_type KiROUND( fp_type v ) #endif /** - * Function rescale() - * - * Scales a number (value) by rational (numerator/denominator). Numerator must be <= denominator. + * Scale a number (value) by rational (numerator/denominator). Numerator must be <= denominator. */ template