CartoType C++ API 7.8.2, 2022-03-25
for Windows, Linux, Qt and other platforms supporting C++ development
Public Member Functions | List of all members
CartoType::MContour Class Referenceabstract

#include <cartotype_path.h>

Inheritance diagram for CartoType::MContour:
CartoType::MPath CartoType::MWritableContour CartoType::TContour CartoType::TFixedSizeContour< aPointCount, aClosed > CartoType::CContourBase< TOutlinePoint > CartoType::CContourBase< TPoint > CartoType::CContourBase< T > CartoType::TSimpleContourData CartoType::TWritableContour CartoType::CContour CartoType::COnCurveContour

Public Member Functions

virtual size_t Points () const =0
 
virtual TOutlinePoint Point (size_t aIndex) const =0
 
virtual bool Closed () const =0
 
 operator TContour () const
 
size_t Contours () const
 
TOutlinePoint LastPoint () const
 
TOutlinePoint FractionalPoint (double aIndex) const
 
bool IsGridOrientedRectangle (TRect *aRect=nullptr) const
 
bool Anticlockwise () const
 
bool Contains (double aX, double aY) const
 
bool Contains (const TPoint &aPoint) const
 
COutline ClippedContour (const TRect &aClip) const
 
void AppendClippedContour (COutline &aDest, const TRect &aClip) const
 
size_t AppendSplitContour (COutline &aDest, const TPointFP &aLineStart, const TPointFP &aLineVector)
 
CContour TruncatedContour (double aStart, double aEnd) const
 
CContour SubContourBetweenFractionalPoints (double aStartIndex, double aEndIndex) const
 
CContour SubContourBetweenNearestPoints (const TPointFP *aStartPoint, const TPointFP *aEndPoint) const
 
CContour CentralPath (std::shared_ptr< CEngine > aEngine, const TRect &aClip, bool aFractionalPixels, TLine &aFallbackLine, bool aFallbackMustBeHorizontal) const
 
CContour Smooth (double aRadius) const
 
bool MayIntersect (const TRect &aRect) const
 
bool Intersects (const TRect &aRect) const
 
TPathIntersectionType IntersectionType (const MContour &aOther, double *aDistance=nullptr, TPointFP *aNearest1=nullptr, TPointFP *aNearest2=nullptr) const
 
TPathIntersectionInfo IntersectionInfo (const MContour &aOther) const
 
double DistanceFrom (const MContour &aOther, TPointFP *aNearest1=nullptr, TPointFP *aNearest2=nullptr, TPathIntersectionType *aType=nullptr) const
 
double DistanceFromPoint (const TPointFP &aPoint, TPointFP *aNearest=nullptr, double *aNearestLength=nullptr, bool *aLeft=nullptr, size_t *aLineIndex=nullptr, double *aFractionalLineIndex=nullptr, bool aTreatAsOpen=false) const
 
TPointFP PointAtLength (double aLength, double aOffset=0, int32_t *aLineIndex=nullptr) const
 
void GetOrientation (const TPoint &aCenter, TPoint &aOrientation) const
 
void GetPrincipalAxis (TPointFP &aCenter, TPointFP &aVector) const
 
void Write (TDataOutputStream &aOutput) const
 
void GetAngles (double aDistance, double &aStartAngle, double &aEndAngle)
 
- Public Member Functions inherited from CartoType::MPath
virtual ~MPath ()
 
virtual size_t Contours () const =0
 
virtual TContour Contour (size_t aIndex) const =0
 
virtual bool MayHaveCurves () const =0
 
template<class MPathTraverser >
void Traverse (MPathTraverser &aTraverser, const TRect &aClip) const
 
template<class MPathTraverser >
void Traverse (MPathTraverser &aTraverser, const TRect *aClip=nullptr) const
 
bool operator== (const MPath &aOther) const
 
TRect CBox () const
 
bool CBoxBiggerThan (int32_t aSize) const
 
bool IsContainedIn (const TRect &aRect) const
 
bool Contains (double aX, double aY) const
 
bool Contains (const TPoint &aPoint) const
 
bool Contains (const TPointFP &aPoint) const
 
bool MayIntersect (const TRect &aRect) const
 
bool MayIntersect (const TRect &aRect, int32_t aBorder) const
 
bool Intersects (const TRect &aRect) const
 
bool Intersects (const MPath &aPath, const TRect *aBounds=nullptr) const
 
int32_t MaxDistanceFromOrigin () const
 
TPathIntersectionType IntersectionType (const MPath &aOther, double *aDistance=nullptr, TPointFP *aNearest1=nullptr, TPointFP *aNearest2=nullptr) const
 
TPathIntersectionInfo IntersectionInfo (const MPath &aOther) const
 
double DistanceFrom (const MPath &aOther, TPointFP *aNearest1=nullptr, TPointFP *aNearest2=nullptr, TPathIntersectionType *aType=nullptr) const
 
double DistanceFromPoint (const TPointFP &aPoint, TPointFP *aNearest=nullptr, size_t *aContourIndex=nullptr, size_t *aLineIndex=nullptr, double *aFractionaLineIndex=nullptr, bool aTreatAsOpen=false) const
 
bool IsClippingNeeded (const TRect &aClip) const
 
COutline Copy () const
 
COutline ClippedPath (const TRect &aClip) const
 
COutline ClippedPath (const MPath &aClip) const
 
COutline ClippedPath (const TClipRegion &aClip) const
 
COutline Clip (TClipOperation aClipOperation, const MPath &aClip) const
 
COutline Envelope (double aOffset) const
 
bool IsSmoothingNeeded () const
 
COutline SmoothPath () const
 
COutline FlatPath (double aMaxDistance) const
 
COutline TruncatedPath (double aStart, double aEnd) const
 
COutline OffsetPath (double aOffset) const
 
COutline TransformedPath (const TTransform &aTransform) const
 
COutline TransformedPath (TDrawResult &aError, MPointTransformer &aTransformer, int32_t aFractionalBits) const
 
std::array< TLine, 3 > GetHorizontalPaths (int32_t aPathLength, int32_t aLabelHeight, const TPointFP &aUpVector, const TRect *aBounds, const TRect *aClip) const
 
TPointFP CenterOfGravity () const
 
void GetCenterOfGravity (TPoint &aCenter) const
 
double Length () const
 
double Area () const
 
TPointFP PointAtLength (double aPos) const
 
std::pair< TPoint, bool > End () const
 
void Write (TDataOutputStream &aOutput) const
 
bool IsEmpty () const
 
bool IsPoint () const
 
bool IsGridOrientedRectangle (TRect *aRect=nullptr) const
 
void GetSphericalAreaAndLength (const CProjection &aProjection, double *aArea, double *aLength) const
 
TClipType ClipType (const TRect &aRect) const
 
bool HasCurves () const
 
ConstIter begin () const
 
ConstIter end () const
 

Detailed Description

An MContour is an abstract interface to a sequence of integer points representing a line or polygon. The points may be on-curve or off-curve. Off-curve points are control points for quadratic or cubic spline curves. A contour may be open or closed.

Member Function Documentation

◆ Anticlockwise()

bool CartoType::MContour::Anticlockwise ( ) const

Return whether the contour has an anticlockwise orientation (assuming x coordinates go right and y coordinates go up). Algorithm from comp.graphics.algorithms FAQ 2.07.

◆ AppendClippedContour()

void CartoType::MContour::AppendClippedContour ( COutline aDest,
const TRect aClip 
) const

Appends this contour to aDest, clipped to aClip.

◆ AppendSplitContour()

size_t CartoType::MContour::AppendSplitContour ( COutline aDest,
const TPointFP aLineStart,
const TPointFP aLineVector 
)

Splits the contour using a line from aLineStart in the direction aLineVector and appends the split parts to aDest. The return value is the number of returned contours that are to the left of the line.

◆ CentralPath()

CContour CartoType::MContour::CentralPath ( std::shared_ptr< CEngine >  aEngine,
const TRect aClip,
bool  aFractionalPixels,
TLine aFallbackLine,
bool  aFallbackMustBeHorizontal 
) const

Creates a central path for a contour.

As a fallback to be used if the central path is too short for a label, the function returns a straight line intersecting the polygon in aFallbackLine; if the fallback line is (0,0) - (0,0), no fallback line could be created.

If aFallbackMustBeHorizontal is true force the fallback line to be horizontal.

◆ ClippedContour()

COutline CartoType::MContour::ClippedContour ( const TRect aClip) const

Clips the contour to the specified rectangle.

All generated points are within or on the edge of the the rectangle, using the Sutherland Hodgman polygon clipping algorithm (http://www.cs.fit.edu/~wds/classes/graphics/Clip/clip/clip.html) This version is slightly modified for efficiency and considers two edges at the same time, in order to save creation of intermediate contours on the heap.

◆ Closed()

virtual bool CartoType::MContour::Closed ( ) const
pure virtual

◆ Contains() [1/2]

bool CartoType::MContour::Contains ( const TPoint aPoint) const
inline

Returns true if this contour contains aPoint.

◆ Contains() [2/2]

bool CartoType::MContour::Contains ( double  aX,
double  aY 
) const

Return true if the contour contains the point (aX,aY).

◆ Contours()

size_t CartoType::MContour::Contours ( ) const
inlinevirtual

◆ DistanceFrom()

double CartoType::MContour::DistanceFrom ( const MContour aOther,
TPointFP aNearest1 = nullptr,
TPointFP aNearest2 = nullptr,
TPathIntersectionType aType = nullptr 
) const

Finds the distance between two contours. aNearest1 and aNearest2, if non-null, are used to return the nearest points on this contour and the other contour respectively. aType, if non-null, is used to return the intersection type.

This function ignores curves, and does not handle self-intersecting paths.

If one of the contours contains or intersects the other, the distance returned is zero, and aNearest1 and aNearest2 are both set to the first intersection if there is one, or to the first point of the contained contour if not.

If either contour is empty, this function returns CT_DBL_MAX (the largest possible number).

◆ DistanceFromPoint()

double CartoType::MContour::DistanceFromPoint ( const TPointFP aPoint,
TPointFP aNearest = nullptr,
double *  aNearestLength = nullptr,
bool *  aLeft = nullptr,
size_t *  aLineIndex = nullptr,
double *  aFractionalLineIndex = nullptr,
bool  aTreatAsOpen = false 
) const

Find the distance from a point to a contour.

This function ignores curves. It treats the contour as a series of straight lines.

If the contour is open (a polyline) the distance is to the nearest point on a line segment. If the contour is closed (a polygon) the distance is zero if the point is inside, otherwise it is the distance to the nearest point on an edge.

If aNearest is non-null use it to return the coordinates of the nearest point on the contour, or the original point if the contour is closed and the point is inside.

If aNearestLength is non-null return the length, measured along the path, of the nearest point.

If aLeft is non-null return a value indicating whether the point is left of the line or right of it.

If aLineIndex is non-null return the index of the line containing the nearest point, or npos if there are fewer than 2 points. If aFractionalLineIndex is non-null return the fractional line index (e.g., 4.5 if the point is half way between points 4 and 5) of the nearest point, or 0 if there are fewer than 2 points or the contour is closed and the point is inside.

If aTreatAsOpen is true, treat the contour as open even if it is closed, and therefore return a non-zero distance even if the point is inside the contour.

If the contour is empty return CT_DBL_MAX (the largest possible number).

◆ FractionalPoint()

TOutlinePoint CartoType::MContour::FractionalPoint ( double  aIndex) const

Return a point selected by a fractional index. The fraction is the proportion of the length between one point and the next. The point returned is always on-curve; this function is not usable for curved contours.

◆ GetAngles()

void CartoType::MContour::GetAngles ( double  aDistance,
double &  aStartAngle,
double &  aEndAngle 
)

Get the start and end angles of a path in radians. The start angle is the bearing from the start point to a point aDistance along the path, or to the end of the path if aDistance is longer than the path. The start angle is the bearing from the end point to a point aDistance back along the path, or to the start of the path if aDistance is longer than the path.

◆ GetOrientation()

void CartoType::MContour::GetOrientation ( const TPoint aCenter,
TPoint aOrientation 
) const

Return the orientation of the contour, given the center of gravity. This is also called the Principal axis transformation of the polygon. Algorithm based on the following quote from comp.graphics.algorithms (slightly edited), full thread called "polygon major axis anyone", by Hans-Bernard Broeker : The calculation of the (centered) second moments is what gives you the angle. There are actually 3 independent second moments: Ixx, Iyy, and Ixy. These form a symmetric 2x2 matrix:

    (Ixx   Ixy)
    (Ixy   Iyy)

The "second moments" are actually the principal second moments, i.e. the second moments in a coordinate system (x', y') that has been rotated relative to the present one such that Ix'y' is zero, and optionally also Ix'x' >= Iy'y'.

They're found by doing an eigenvector/eigenvalue analysis on that 2x2 matrix, also known as the 'principal axis transformation' in this context. -end of quote

Also refer to: http://kwon3d.com/theory/moi/prin.html for an explanation of principal axis.

◆ GetPrincipalAxis()

void CartoType::MContour::GetPrincipalAxis ( TPointFP aCenter,
TPointFP aVector 
) const

Get the principal axis of a contour, which must be a closed contour with at least 3 points, in the form of its center of gravity and a vector pointing in the direction of the axis.

◆ IntersectionInfo()

TPathIntersectionInfo CartoType::MContour::IntersectionInfo ( const MContour aOther) const

Returns information about the intersection of this contour with another one.

◆ IntersectionType()

TPathIntersectionType CartoType::MContour::IntersectionType ( const MContour aOther,
double *  aDistance = nullptr,
TPointFP aNearest1 = nullptr,
TPointFP aNearest2 = nullptr 
) const

Returns the relationship between two contours as a path intersection type.

Other information can optionally be obtained.

If aDistance is non-null it is used to return the distance between the two contours, or zero if they intersect.

aNearest1 and aNearest2, if non-null, are used to return the nearest points on this contour and the other contour respectively.

This function ignores curves, and does not handle self-intersecting paths.

If one of the contours contains or intersects the other, the distance returned is zero, and aNearest1 and aNearest2 are both set to the first intersection if there is one, or to the first point of the contained contour if not.

If either contour is empty, this function returns TPathIntersectionType::Separate, and sets the other return values to CT_DBL_MAX (the largest possible number).

◆ Intersects()

bool CartoType::MContour::Intersects ( const TRect aRect) const

Return true if the path intersects a specified rectangle. For single points, this is true if the point is inside the rectangle. For open paths, this is true if at least one line intersects the rectangle. For closed paths, the polygon defined by the control points must intersect the rectangle.

◆ IsGridOrientedRectangle()

bool CartoType::MContour::IsGridOrientedRectangle ( TRect aRect = nullptr) const

Determine whether a contour is a grid-oriented rectangle and return the rectangle if so, and if aRect is non-null.

◆ LastPoint()

TOutlinePoint CartoType::MContour::LastPoint ( ) const
inline

Returns the last point of the contour.

◆ MayIntersect()

bool CartoType::MContour::MayIntersect ( const TRect aRect) const

Return true if the contour may possibly intersect the specified rectangle.

Return false if there is definitely no intersection. For contours with a single point, the return value is whether the point is in the rectangle.

A closed contour is treated as a polygon. The return value indicates whether the bounding box of the path's control points intersects the rectangle.

An unclosed contour is treated as a point or a line. The return value indicates whether the bounding box of the control points of the line segments and curves making up the line intersects the rectangle.

◆ operator TContour()

CartoType::MContour::operator TContour ( ) const
inline

Returns a TContour object representing this contour.

◆ Point()

virtual TOutlinePoint CartoType::MContour::Point ( size_t  aIndex) const
pure virtual

◆ PointAtLength()

TPointFP CartoType::MContour::PointAtLength ( double  aLength,
double  aOffset = 0,
int32_t *  aLineIndex = nullptr 
) const

Get a point at a certain length, measured along the contour. If aLength is negative, return the first point. If aLength is greater than the length of the contour, return the last point.

If aOffset is non-zero, offset the point from the contour by that amount, which may be positive (for offsets to the left) or negative (for offsets to the right). The meanings of 'right' and 'left' assume that Y coordinates increase upwards.

If aLineIndex is non-null return the index of the line containing the point, or -1 if there are fewer than 2 points.

◆ Points()

virtual size_t CartoType::MContour::Points ( ) const
pure virtual

◆ Smooth()

CContour CartoType::MContour::Smooth ( double  aRadius) const

Creates a smoothed version of a contour.

Simplification consists in removing all points with an area less than aResolutionArea. A point's area is the area of the triangle made by the point and its two neighbours.

The start and end of an open contour are not removed. Closed contours may be reduced to nothing.

◆ SubContourBetweenFractionalPoints()

CContour CartoType::MContour::SubContourBetweenFractionalPoints ( double  aStartIndex,
double  aEndIndex 
) const

Creates a subcontour of this contour from one fractional point index to another. If this contour has more than one point the returned contour contains at least two points.

◆ SubContourBetweenNearestPoints()

CContour CartoType::MContour::SubContourBetweenNearestPoints ( const TPointFP aStartPoint,
const TPointFP aEndPoint 
) const

Creates a subcontour of this contour between the nearest points on the contour to two points. If aStartPoint is null the first point is used. If aEndPoint is null the last point is used.

◆ TruncatedContour()

CContour CartoType::MContour::TruncatedContour ( double  aStart,
double  aEnd 
) const

Returns a version of the contour truncated by removing a length equal to aStart at the start, and a length equal to aEnd at the end.

Either aStart or aEnd may be zero or negative; negative values cause extension instead of truncation.

This function treats all points as on-curve points, and therefore does not work properly for contours containing curves.

◆ Write()

void CartoType::MContour::Write ( TDataOutputStream aOutput) const

Writes this contour in serialized form.


The documentation for this class was generated from the following files: