src/BRepBuilderAPI/BRepBuilderAPI_MakePolygon.cdl

   1 -- Created on: 1993-07-29
   2 -- Created by: Remi LEQUETTE
   3 -- Copyright (c) 1993-1999 Matra Datavision
   4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 --
   6 -- This file is part of Open CASCADE Technology software library.
   7 --
   8 -- This library is free software; you can redistribute it and/or modify it under
   9 -- the terms of the GNU Lesser General Public License version 2.1 as published
  10 -- by the Free Software Foundation, with special exception defined in the file
  11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  12 -- distribution for complete text of the license and disclaimer of any warranty.
  13 --
  14 -- Alternatively, this file may be used under the terms of Open CASCADE
  15 -- commercial license or contractual agreement.
  16
  17 class MakePolygon from BRepBuilderAPI  inherits MakeShape from BRepBuilderAPI
  18
  19         ---Purpose: Describes functions to build polygonal wires. A
  20         -- polygonal wire can be built from any number of points
  21         -- or vertices, and consists of a sequence of connected
  22         -- rectilinear edges.
  23         --          When a point or vertex is added to the  polygon if
  24         --          it is identic  to the previous  point no  edge  is
  25         --          built. The method added can be used to test it.
  26         -- Construction of a Polygonal Wire
  27         -- You can construct:
  28         --   -   a complete polygonal wire by defining all its points
  29         --   or vertices (limited to four), or
  30         -- -   an empty polygonal wire and add its points or
  31         --   vertices in sequence (unlimited number).
  32         -- A MakePolygon object provides a framework for:
  33         -- -   initializing the construction of a polygonal wire,
  34         -- -   adding points or vertices to the polygonal wire under construction, and
  35         -- -   consulting the result.
  36
  37 uses
  38     Wire        from TopoDS,
  39     Edge        from TopoDS,
  40     Vertex      from TopoDS,
  41     Pnt         from gp,
  42     MakePolygon from BRepLib
  43
  44 raises
  45     NotDone           from StdFail
  46
  47 is
  48     Create
  49     returns MakePolygon from BRepBuilderAPI;
  50         ---Purpose: Initializes an empty polygonal wire, to which points or
  51         -- vertices are added using the Add function.
  52         -- As soon as the polygonal wire under construction
  53         -- contains vertices, it can be consulted using the Wire function.
  54
  55     Create(P1, P2 : Pnt from gp)
  56         ---Level: Public
  57     returns MakePolygon from BRepBuilderAPI;
  58
  59     Create(P1, P2, P3 : Pnt from gp;
  60            Close : Boolean = Standard_False)
  61         ---Level: Public
  62     returns MakePolygon from BRepBuilderAPI;
  63
  64     Create(P1, P2, P3, P4 : Pnt from gp;
  65            Close : Boolean = Standard_False)
  66         ---Level: Public
  67     returns MakePolygon from BRepBuilderAPI;
  68         ---Purpose: Constructs a polygonal wire from 2, 3 or 4 points. Vertices are
  69         -- automatically created on the given points. The polygonal wire is
  70         -- closed if Close is true; otherwise it is open. Further vertices can
  71         -- be added using the Add function. The polygonal wire under
  72         -- construction can be consulted at any time by using the Wire function.
  73         -- Example
  74         -- //an open polygon from four points
  75         -- TopoDS_Wire W = BRepBuilderAPI_MakePolygon(P1,P2,P3,P4);
  76         -- Warning: The process is equivalent to:
  77         --   - initializing an empty polygonal wire,
  78         --   - and adding the given points in sequence.
  79         -- Consequently, be careful when using this function: if the
  80         -- sequence of points p1 - p2 - p1 is found among the arguments of the
  81         -- constructor, you will create a polygonal wire with two
  82         -- consecutive coincident edges.
  83
  84     Create(V1, V2 : Vertex from TopoDS)
  85         ---Level: Public
  86     returns MakePolygon from BRepBuilderAPI;
  87
  88     Create(V1, V2, V3 : Vertex from TopoDS;
  89            Close : Boolean = Standard_False)
  90         ---Level: Public
  91     returns MakePolygon from BRepBuilderAPI;
  92
  93     Create(V1, V2, V3, V4 : Vertex from TopoDS;
  94            Close : Boolean = Standard_False)
  95         ---Level: Public
  96     returns MakePolygon from BRepBuilderAPI;
  97         ---Purpose: Constructs a polygonal wire from
  98         -- 2, 3 or 4 vertices. The polygonal wire is closed if Close is true;
  99         -- otherwise it is open (default value). Further vertices can be
 100         -- added using the Add function. The polygonal wire under
 101         -- construction can be consulted at any time by using the Wire function.
 102         -- Example
 103         -- //a closed triangle from three vertices
 104         -- TopoDS_Wire W = BRepBuilderAPI_MakePolygon(V1,V2,V3,Standard_True);
 105         -- Warning
 106         -- The process is equivalent to:
 107         -- -      initializing an empty polygonal wire,
 108         -- -      then adding the given points in sequence.
 109         -- So be careful, as when using this function, you could create a
 110         -- polygonal wire with two consecutive coincident edges if
 111         -- the sequence of vertices v1 - v2 - v1 is found among the
 112         -- constructor's arguments.
 113
 114     Add(me : in out; P : Pnt from gp)
 115         ---Level: Public
 116     is static;
 117
 118     Add(me : in out; V : Vertex from TopoDS)
 119         ---Level: Public
 120     is static;
 121         --- Purpose:
 122         -- Adds the point P or the vertex V at the end of the
 123         -- polygonal wire under construction. A vertex is
 124         -- automatically created on the point P.
 125         -- Warning
 126         -- -   When P or V is coincident to the previous vertex,
 127         --   no edge is built. The method Added can be used to
 128         --   test for this. Neither P nor V is checked to verify
 129         --   that it is coincident with another vertex than the last
 130         --   one, of the polygonal wire under construction. It is
 131         --   also possible to add vertices on a closed polygon
 132         --   (built for example by using a constructor which
 133         --   declares the polygon closed, or after the use of the Close function).
 134         --  Consequently, be careful using this function: you might create:
 135         -- -      a polygonal wire with two consecutive coincident edges, or
 136         -- -      a non manifold polygonal wire.
 137         -- -      P or V is not checked to verify if it is
 138         --    coincident with another vertex but the last one, of
 139         --    the polygonal wire under construction. It is also
 140         --    possible to add vertices on a closed polygon (built
 141         --    for example by using a constructor which declares
 142         --    the polygon closed, or after the use of the Close function).
 143         -- Consequently, be careful when using this function: you might create:
 144         --   -   a polygonal wire with two consecutive coincident edges, or
 145         --   -   a non-manifold polygonal wire.
 146
 147     Added(me) returns Boolean
 148         ---Purpose: Returns true if the last vertex added to the constructed
 149         -- polygonal wire is not coincident with the previous one.
 150     is static;
 151
 152     Close(me : in out)
 153         ---Purpose: Closes the polygonal wire under construction. Note - this
 154         -- is equivalent to adding the first vertex to the polygonal
 155         -- wire under construction.
 156     is static;
 157
 158     FirstVertex(me) returns Vertex from TopoDS
 159         ---C++: return const &
 160         ---Level: Public
 161     is static;
 162
 163     LastVertex(me) returns Vertex from TopoDS
 164         ---C++: return const &
 165         ---Level: Public
 166     is static;
 167         ---Purpose: Returns the first or the last vertex of the polygonal wire under construction.
 168         -- If the constructed polygonal wire is closed, the first and the last vertices are identical.
 169
 170     IsDone(me) returns Boolean
 171         ---Level: Public
 172     is redefined;
 173         ---Purpose:
 174         -- Returns true if this algorithm contains a valid polygonal
 175         -- wire (i.e. if there is at least one edge).
 176         -- IsDone returns false if fewer than two vertices have
 177         -- been chained together by this construction algorithm.
 178
 179     Edge(me) returns Edge from TopoDS
 180         ---Purpose: Returns the edge built between the last two points or
 181         -- vertices added to the constructed polygonal wire under construction.
 182         -- Warning
 183         -- If there is only one vertex in the polygonal wire, the result is a null edge.
 184         ---C++: return const &
 185         ---C++: alias "Standard_EXPORT operator TopoDS_Edge() const;"
 186   raises
 187         NotDone from StdFail
 188     is static;
 189
 190     Wire(me) returns Wire from TopoDS
 191         ---Purpose:
 192         -- Returns the constructed polygonal wire, or the already
 193         -- built part of the polygonal wire under construction.
 194         -- Exceptions
 195         -- StdFail_NotDone if the wire is not built, i.e. if fewer than
 196         -- two vertices have been chained together by this construction algorithm.
 197         ---C++: return const &
 198         ---C++: alias "Standard_EXPORT operator TopoDS_Wire() const;"
 199   raises
 200         NotDone from StdFail
 201     is static;
 202
 203 fields
 204
 205     myMakePolygon : MakePolygon from BRepLib;
 206
 207 end MakePolygon;