include/basegfx/polygon/b2dpolypolygontools.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #pragma once
  21
  22 #include <basegfx/point/b2dpoint.hxx>
  23 #include <basegfx/polygon/b3dpolypolygon.hxx>
  24 #include <com/sun/star/drawing/PointSequenceSequence.hpp>
  25 #include <vector>
  26 #include <set>
  27 #include <basegfx/basegfxdllapi.h>
  28 #include <o3tl/sorted_vector.hxx>
  29
  30 namespace com::sun::star::drawing { struct PolyPolygonBezierCoords; }
  31
  32 namespace basegfx
  33 {
  34     class B2DPolyPolygon;
  35     class B2DRange;
  36 }
  37
  38 namespace basegfx::utils
  39 {
  40         // B2DPolyPolygon tools
  41
  42         // Check and evtl. correct orientations of all contained Polygons so that
  43         // the orientations of contained polygons will variate to express areas and
  44         // holes
  45         BASEGFX_DLLPUBLIC B2DPolyPolygon correctOrientations(const B2DPolyPolygon& rCandidate);
  46
  47         // make sure polygon with index 0L is not a hole. This may evtl. change the
  48         // sequence of polygons, but allows to use polygon with index 0L to
  49         // get the correct normal for the whole polyPolygon
  50         BASEGFX_DLLPUBLIC B2DPolyPolygon correctOutmostPolygon(const B2DPolyPolygon& rCandidate);
  51
  52         // Subdivide all contained curves. Use distanceBound value if given.
  53         BASEGFX_DLLPUBLIC B2DPolyPolygon adaptiveSubdivideByDistance(const B2DPolyPolygon& rCandidate, double fDistanceBound);
  54
  55         // Subdivide all contained curves. Use distanceBound value if given. Else, a convenient one
  56         // is created.
  57         BASEGFX_DLLPUBLIC B2DPolyPolygon adaptiveSubdivideByAngle(const B2DPolyPolygon& rCandidate, double fAngleBound = 0.0);
  58
  59         // isInside test for B2dPoint. On border is not inside as long as not true is given
  60         // in bWithBorder flag. It is assumed that the orientations of the given polygon are correct.
  61         BASEGFX_DLLPUBLIC bool isInside(const B2DPolyPolygon& rCandidate, const B2DPoint& rPoint, bool bWithBorder = false);
  62
  63         /** Get the range of a polyPolygon
  64
  65             For detailed description look at getRange(const B2DPolygon&).
  66             This method just expands by the range of every sub-Polygon.
  67
  68             @param rCandidate
  69             The B2DPolyPolygon possibly containing bezier segments
  70
  71             @return
  72             The outer range of the polygon
  73         */
  74         BASEGFX_DLLPUBLIC B2DRange getRange(const B2DPolyPolygon& rCandidate);
  75
  76         // get signed area of polygon
  77         BASEGFX_DLLPUBLIC double getSignedArea(const B2DPolyPolygon& rCandidate);
  78
  79         // get area of polygon
  80         BASEGFX_DLLPUBLIC double getArea(const B2DPolyPolygon& rCandidate);
  81
  82         /** Apply given LineDashing to given polyPolygon
  83
  84             For a description see applyLineDashing in b2dpolygontoos.hxx
  85         */
  86         BASEGFX_DLLPUBLIC void applyLineDashing(
  87             const B2DPolyPolygon& rCandidate,
  88             const ::std::vector<double>& rDotDashArray,
  89             B2DPolyPolygon* pLineTarget,
  90             double fFullDashDotLen = 0.0);
  91
  92         // test if point is inside epsilon-range around the given PolyPolygon. Can be used
  93         // for HitTesting. The epsilon-range is defined to be the tube around the PolyPolygon
  94         // with distance fDistance and rounded edges (start and end point).
  95         BASEGFX_DLLPUBLIC bool isInEpsilonRange(const B2DPolyPolygon& rCandidate, const B2DPoint& rTestPosition, double fDistance);
  96
  97         /** Helper class to transport PointIndices to a PolyPolygon,
  98             with an operator< for convenient sorting in a std::set usage
  99          */
 100         class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC PointIndex
 101         {
 102         private:
 103             sal_uInt32 mnPolygonIndex;
 104             sal_uInt32 mnPointIndex;
 105
 106         public:
 107             PointIndex(sal_uInt32 nPolygonIndex, sal_uInt32 nPointIndex)
 108             :   mnPolygonIndex(nPolygonIndex),
 109                 mnPointIndex(nPointIndex)
 110             {}
 111
 112             sal_uInt32 getPolygonIndex() const { return mnPolygonIndex; }
 113             sal_uInt32 getPointIndex() const { return mnPointIndex; }
 114             bool operator<(const PointIndex& rComp) const;
 115         };
 116
 117         /** the PointIndexSet itself; it allows to define a 'selection'of
 118             points in a tools::PolyPolygon by giving the polygon and point index.
 119             Adding points double makes no sense, hence the std::set
 120          */
 121         typedef o3tl::sorted_vector< PointIndex > PointIndexSet;
 122
 123         /** Read poly-polygon from SVG.
 124
 125             This function imports a poly-polygon from an SVG-D
 126             attribute.
 127
 128             @param o_rPolyPoly
 129             The output poly-polygon
 130
 131             @param rSvgDAttribute
 132             A valid SVG-D attribute string
 133
 134             @param bHandleRelativeNextPointCompatible
 135             If set to true, the old error that after a relative 'z' command
 136             the current point was not reset to the first point of the current
 137             polygon is kept; this is needed to read odf files.
 138             If false, pure svg is used; this is needed for svg import.
 139
 140             @param pHelpPointIndexSet
 141             If given, all points created in the target PolyPolygon
 142             which are only helper points are added here using their
 143             point indices; this are currently points created from
 144             import of the 'a' and 'A' svg:d statements which create
 145             bezier curve info as representation and maybe points
 146             which are no 'real' svg:d points, but helper points. It
 147             is necessary to identify these e.g. when markers need to
 148             be created in the svg import
 149
 150             @return true, if the string was successfully parsed
 151          */
 152         BASEGFX_DLLPUBLIC bool importFromSvgD(
 153             B2DPolyPolygon& o_rPolyPoly,
 154             const OUString& rSvgDAttribute,
 155             bool bHandleRelativeNextPointCompatible,
 156             PointIndexSet* pHelpPointIndexSet);
 157
 158         // grow for polyPolygon. Move all geometry in each point in the direction of the normal in that point
 159         // with the given amount. Value may be negative.
 160         BASEGFX_DLLPUBLIC B2DPolyPolygon growInNormalDirection(const B2DPolyPolygon& rCandidate, double fValue);
 161
 162         // force all sub-polygons to a point count of nSegments
 163         BASEGFX_DLLPUBLIC B2DPolyPolygon reSegmentPolyPolygon(const B2DPolyPolygon& rCandidate, sal_uInt32 nSegments);
 164
 165         // create polygon state at t from 0.0 to 1.0 between the two polygons. Both polygons must have the same
 166         // organisation, e.g. same amount of polygons
 167         BASEGFX_DLLPUBLIC B2DPolyPolygon interpolate(const B2DPolyPolygon& rOld1, const B2DPolyPolygon& rOld2, double t);
 168
 169         // create 3d tools::PolyPolygon from given 2d PolyPolygon. The given fZCoordinate is used to expand the
 170         // third coordinate.
 171         BASEGFX_DLLPUBLIC B3DPolyPolygon createB3DPolyPolygonFromB2DPolyPolygon(const B2DPolyPolygon& rCandidate, double fZCoordinate = 0.0);
 172
 173         // create 2d tools::PolyPolygon from given 3d PolyPolygon. All coordinates are transformed using the given
 174         // matrix and the resulting x,y is used to form the new polygon.
 175         BASEGFX_DLLPUBLIC B2DPolyPolygon createB2DPolyPolygonFromB3DPolyPolygon(const B3DPolyPolygon& rCandidate, const B3DHomMatrix& rMat);
 176
 177         // for each contained edge in each contained polygon calculate the smallest distance. Return the index to the smallest
 178         // edge in rEdgeIndex and the index to the polygon in rPolygonIndex. The relative position on the edge is returned in rCut.
 179         // If nothing was found (e.g. empty input plygon), DBL_MAX is returned.
 180         BASEGFX_DLLPUBLIC double getSmallestDistancePointToPolyPolygon(const B2DPolyPolygon& rCandidate, const B2DPoint& rTestPoint, sal_uInt32& rPolygonIndex, sal_uInt32& rEdgeIndex, double& rCut);
 181
 182         // distort PolyPolygon. rOriginal describes the original range, where the given points describe the distorted
 183         // corresponding points.
 184         BASEGFX_DLLPUBLIC B2DPolyPolygon distort(const B2DPolyPolygon& rCandidate, const B2DRange& rOriginal, const B2DPoint& rTopLeft, const B2DPoint& rTopRight, const B2DPoint& rBottomLeft, const B2DPoint& rBottomRight);
 185
 186         // expand all segments (which are not yet) to curve segments. This is done with setting the control
 187         // vectors on the 1/3 resp. 2/3 distances on each segment.
 188         BASEGFX_DLLPUBLIC B2DPolyPolygon expandToCurve(const B2DPolyPolygon& rCandidate);
 189
 190         /** Predicate whether a given poly-polygon is a rectangle.
 191
 192             @param rPoly
 193             tools::PolyPolygon to check
 194
 195             @return true, if the poly-polygon describes a rectangle
 196             (contains exactly one polygon, polygon is closed, and the
 197             points are either cw or ccw enumerations of a rectangle's
 198             vertices). Note that intermediate points and duplicate
 199             points are ignored.
 200          */
 201         BASEGFX_DLLPUBLIC bool isRectangle( const B2DPolyPolygon& rPoly );
 202
 203         /** Export poly-polygon to SVG.
 204
 205             This function exports a poly-polygon into an SVG-D
 206             statement. Currently, output of relative point sequences
 207             is not yet supported (might cause slightly larger output)
 208
 209             @param rPolyPoly
 210             The poly-polygon to export
 211
 212             @param bUseRelativeCoordinates
 213             When true, all coordinate values are exported as relative
 214             to the current position. This tends to save some space,
 215             since fewer digits needs to be written.
 216
 217             @param bDetectQuadraticBeziers
 218             When true, the export tries to detect cubic bezier
 219             segments in the input polygon, which can be represented by
 220             quadratic bezier segments. Note that the generated string
 221             causes versions prior to OOo2.0 to crash.
 222
 223             @param bHandleRelativeNextPointCompatible
 224             If set to true, the old error that after a relative 'z' command
 225             the current point was not reset to the first point of the current
 226             polygon is kept; this is needed to read odf files.
 227             If false, pure svg is used; this is needed for svg import.
 228
 229             @param bOOXMLMotionPath
 230             If set to true, export string format that is acceptable for
 231             for animation motion path for PowerPoint: always space delimited,
 232             never neglect command char, always end with E, and do not export
 233             H or V.
 234
 235             @return the generated SVG-D statement (the XML d attribute
 236             value alone, without any "<path ...>" or "d="...")
 237          */
 238         BASEGFX_DLLPUBLIC OUString exportToSvgD(
 239             const B2DPolyPolygon& rPolyPoly,
 240             bool bUseRelativeCoordinates,
 241             bool bDetectQuadraticBeziers,
 242             bool bHandleRelativeNextPointCompatible,
 243             bool bOOXMLMotionPath = false);
 244
 245         // #i76891# Try to remove existing curve segments if they are simply edges
 246         BASEGFX_DLLPUBLIC B2DPolyPolygon simplifyCurveSegments(const B2DPolyPolygon& rCandidate);
 247
 248         /** Creates polypolygon for seven-segment display number
 249
 250             This function takes an integer number between 0 and 9 and
 251             convert it into the well-known seven-segment display
 252             number (like most digital clocks show their numbers). The
 253             digit will exactly fit the unit rectangle. The polypolygon
 254             will be a line polygon, i.e. if you need the segment parts
 255             to have width, use createAreaGeometry() on the result.
 256
 257             @param cNumber
 258             Number from '0' to '9' as ASCII char, or '-', 'E' and '.'
 259             to convert to 7 segment code
 260
 261             @param bLitSegments
 262             When true, return a polygon containing the segments that
 263             are 'lit' for the given number. Return un-lit segments
 264             otherwise.
 265          */
 266         B2DPolyPolygon createSevenSegmentPolyPolygon(char cNumber, bool bLitSegments);
 267
 268         /** snap some polygon coordinates to discrete coordinates
 269
 270             This method allows to snap some polygon points to discrete (integer) values
 271             which equals e.g. a snap to discrete coordinates. It will snap points of
 272             horizontal and vertical edges
 273
 274             @param rCandidate
 275             The source polygon
 276
 277             @return
 278             The modified version of the source polygon
 279         */
 280         BASEGFX_DLLPUBLIC B2DPolyPolygon snapPointsOfHorizontalOrVerticalEdges(const B2DPolyPolygon& rCandidate);
 281
 282         /// converters for css::drawing::PointSequence
 283         BASEGFX_DLLPUBLIC B2DPolyPolygon UnoPointSequenceSequenceToB2DPolyPolygon(
 284             const css::drawing::PointSequenceSequence& rPointSequenceSequenceSource);
 285         BASEGFX_DLLPUBLIC void B2DPolyPolygonToUnoPointSequenceSequence(
 286             const B2DPolyPolygon& rPolyPolygon,
 287             css::drawing::PointSequenceSequence& rPointSequenceSequenceRetval);
 288
 289         /// converters for css::drawing::PolyPolygonBezierCoords (curved polygons)
 290         BASEGFX_DLLPUBLIC B2DPolyPolygon UnoPolyPolygonBezierCoordsToB2DPolyPolygon(
 291             const css::drawing::PolyPolygonBezierCoords& rPolyPolygonBezierCoordsSource);
 292         BASEGFX_DLLPUBLIC void B2DPolyPolygonToUnoPolyPolygonBezierCoords(
 293             const B2DPolyPolygon& rPolyPolygon,
 294             css::drawing::PolyPolygonBezierCoords& rPolyPolygonBezierCoordsRetval);
 295
 296 } // end of namespace basegfx::utils
 297
 298 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */