[occt.git] / src / Geom2d / Geom2d_TrimmedCurve.cdl

-- Created on: 1993-03-24
-- Created by: JCV
-- Copyright (c) 1993-1999 Matra Datavision
-- Copyright (c) 1999-2014 OPEN CASCADE SAS
--
-- This file is part of Open CASCADE Technology software library.
--
-- This library is free software; you can redistribute it and/or modify it under
-- the terms of the GNU Lesser General Public License version 2.1 as published
-- by the Free Software Foundation, with special exception defined in the file
-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
-- distribution for complete text of the license and disclaimer of any warranty.
--
-- Alternatively, this file may be used under the terms of Open CASCADE
-- commercial license or contractual agreement.

class TrimmedCurve from Geom2d inherits BoundedCurve from Geom2d

        --- Purpose :
        --  Defines a portion of a curve limited by two values of 
        --  parameters inside the parametric domain of the curve.
        -- The trimmed curve is defined by:
    	-- - the basis curve, and
    	-- - the two parameter values which limit it.
    	--  The trimmed curve can either have the same
    	-- orientation as the basis curve or the opposite orientation.

uses Ax2d     from gp,
     Pnt2d    from gp, 
     Trsf2d   from gp,
     Vec2d    from gp,
     Curve    from Geom2d,
     Geometry from Geom2d,
     Shape    from GeomAbs


raises ConstructionError   from Standard,
       RangeError          from Standard,
       NoSuchObject        from Standard,
       UndefinedDerivative from Geom2d,
       UndefinedValue      from Geom2d


is

  Create (C : Curve; U1, U2 : Real; Sense : Boolean = Standard_True;
          theAdjustPeriodic : Boolean = Standard_True)
     returns TrimmedCurve
        --- Purpose :
        --  Creates a trimmed curve from the basis curve C limited between 
        --  U1 and U2.
        --  
        --  . U1 can be greater or lower than U2.
        --  . The returned curve is oriented from U1 to U2.
        --  . If the basis curve C is periodic there is an ambiguity 
        --    because two parts are available. In this case by default
        --    the trimmed curve has the same orientation as the basis
        --    curve (Sense = True). If Sense = False then the orientation
        --    of the trimmed curve is opposite to the orientation of the
        --    basis curve C.
        --  If the curve is closed but not periodic it is not possible
        --    to keep the part of the curve including the junction point
        --    (except if the junction point is at the beginning or
        --    at the end of the trimmed curve) because you could lose the
        --    fundamental characteristics of the basis curve which are 
        --    used for example to compute the derivatives of the trimmed
        --    curve. So for a closed curve the rules are the same as for 
        --    a open curve.
        -- Warnings :
        --  In this package the entities are not shared. The TrimmedCurve is
        --  built with a copy of the curve C. So when C is modified the
        --  TrimmedCurve is not modified
   	--  Warnings :
        -- If <C> is periodic and <theAdjustPeriodic> is True, parametrics 
        -- bounds of the TrimmedCurve, can be different to [<U1>;<U2>}, 
        -- if <U1> or <U2> are not in the principal period.
        -- Include :
        --  For more explanation see the scheme given with this class. 
    	--    Raises ConstructionError the C is not periodic and U1 or U2 are out of 
        --  the bounds of C.
        --  Raised if U1 = U2.
     raises ConstructionError;
     

  Reverse (me : mutable);
        --- Purpose :
        --  Changes the direction of parametrization of <me>. The first and
        --  the last parametric values are modified. The "StartPoint"
        --  of the initial curve becomes the "EndPoint" of the reversed
        --  curve and the "EndPoint" of the initial curve becomes the
        --  "StartPoint" of the reversed curve.
    	-- Example  -   If the trimmed curve is defined by:
    	-- - a basis curve whose parameter range is [ 0.,1. ], and
    	-- - the two trim values U1 (first parameter) and U2 (last parameter),
    	--   the reversed trimmed curve is defined by:
    	-- - the reversed basis curve, whose parameter range is still [ 0.,1. ], and
    	-- - the two trim values 1. - U2 (first parameter)
    	--   and 1. - U1 (last parameter).

  ReversedParameter(me; U : Real) returns Real;
	---Purpose: Returns the  parameter on the  reversed  curve for
	--          the point of parameter U on <me>.
	--          
	--          returns UFirst + ULast - U


  SetTrim (me : mutable; U1, U2 : Real; Sense : Boolean = Standard_True;
           theAdjustPeriodic : Boolean = Standard_True)
    	--- Purpose : Changes this trimmed curve, by redefining the
    	-- parameter values U1 and U2, which limit its basis curve.
    	-- Note: If the basis curve is periodic, the trimmed curve
    	-- has the same orientation as the basis curve if Sense
    	-- is true (default value) or the opposite orientation if Sense is false.
    	-- Warning
    	-- If the basis curve is periodic and theAdjustPeriodic is True, 
    	-- the bounds of the trimmed curve may be different from U1 and U2 if the
    	-- parametric origin of the basis curve is within the arc
    	-- of the trimmed curve. In this case, the modified
    	-- parameter will be equal to U1 or U2 plus or minus the period.
        -- If theAdjustPeriodic is False, parameters U1 and U2 will stay unchanged.
    	-- Exceptions
    	-- Standard_ConstructionError if:
    	-- - the basis curve is not periodic, and either U1 or U2
    	--   are outside the bounds of the basis curve, or
    	-- - U1 is equal to U2. 
     raises ConstructionError;
      

  BasisCurve (me)    returns Curve;
        --- Purpose : Returns the basis curve. 
        -- Warning
    	-- This function does not return a constant reference.
    	-- Consequently, any modification of the returned value
    	-- directly modifies the trimmed curve.


  Continuity (me)  returns Shape from GeomAbs;
        --- Purpose :
        --  Returns the global continuity of the basis curve of this trimmed curve.
        -- C0 : only geometric continuity,
        -- C1 : continuity of the first derivative all along the Curve,
        -- C2 : continuity of the second derivative all along the Curve,
        -- C3 : continuity of the third derivative all along the Curve,
        -- CN : the order of continuity is infinite.


  IsCN (me; N : Integer)   returns Boolean
        --- Purpose 
        --  Returns True if the order of continuity of the 
        --  trimmed curve is N. A trimmed curve is at least "C0" continuous.
        --  Warnings :
        --  The continuity of the trimmed curve can be greater than
        --  the continuity of the basis curve because you consider
        --  only a part of the basis curve.
     raises RangeError;
        --- Purpose :  Raised if N < 0.


  EndPoint (me)   returns Pnt2d;
	--- Purpose :
	--  Returns the end point of <me>. This point is the
	--  evaluation of the curve for the "LastParameter".


  FirstParameter (me)   returns Real;
        --- Purpose :
	--  Returns the value of the first parameter of <me>. 
        --  The first parameter is the parameter of the "StartPoint"
        --  of the trimmed curve.


  IsClosed (me)  returns Boolean;
        --- Purpose :
        --  Returns True if the distance between the StartPoint and
        --  the EndPoint is lower or equal to Resolution from package
        --  gp.


  IsPeriodic (me)   returns Boolean;
        --- Purpose : Returns true if the basis curve of this trimmed curve is periodic.


  Period (me) returns Real from Standard
    	---Purpose: Returns the period of the basis curve of this trimmed curve.
    	-- Exceptions
    	-- Standard_NoSuchObject if the basis curve is not periodic.
          raises
    	NoSuchObject from Standard
  is redefined;
  
  
  LastParameter (me)  returns Real;
	--- Purpose :
	--  Returns the value of the last parameter of <me>.
        --  The last parameter is the parameter of the "EndPoint" of the
        --  trimmed curve.


  StartPoint (me)  returns Pnt2d;
	--- Purpose :
	--  Returns the start point of <me>.
	--  This point is the evaluation of the curve from the 
	--  "FirstParameter".

        --- Purpose  : value and derivatives
        --- Warnings :
        --  The returned derivatives have the same orientation as the
        --  derivatives of the basis curve.


  D0 (me; U : Real; P : out Pnt2d)
     raises UndefinedValue;
        --- Purpose:
        --  If the basis curve is an OffsetCurve sometimes it is not 
        --  possible to do the evaluation of the curve at the parameter
        --  U (see class OffsetCurve).


  D1 (me; U : Real; P : out Pnt2d; V1 : out Vec2d)
     raises UndefinedDerivative;
        --- Purpose : Raised if the continuity of the curve is not C1.


  D2 (me; U : Real; P : out Pnt2d; V1, V2 : out Vec2d)
     raises UndefinedDerivative;
        --- Purpose : Raised if the continuity of the curve is not C2.


  D3 (me; U : Real; P : out Pnt2d; V1, V2, V3 : out Vec2d)
     raises UndefinedDerivative;
        --- Purpose : Raised if the continuity of the curve is not C3.
        

  DN (me; U : Real; N : Integer)  returns Vec2d
        --- Purpose  : For the point of parameter U of this trimmed curve,
    	-- computes the vector corresponding to the Nth derivative.
    	-- Warning
    	-- The returned derivative vector has the same
    	-- orientation as the derivative vector of the basis curve,
    	-- even if the trimmed curve does not have the same
    	-- orientation as the basis curve.
    	-- Exceptions
    	-- Standard_RangeError if N is less than 1.
    raises  UndefinedDerivative,
                   RangeError;


        --- Purpose : geometric transformations

  Transform (me : mutable; T : Trsf2d);
        --- Purpose : Applies the transformation T to this trimmed curve.
    	-- Warning The basis curve is also modified.

  TransformedParameter(me; U : Real; T : Trsf2d from gp) returns Real
	---Purpose: Returns the  parameter on the  transformed  curve for
	--          the transform of the point of parameter U on <me>.
	--          
	--          me->Transformed(T)->Value(me->TransformedParameter(U,T))
	--          
	--          is the same point as
	--          
	--          me->Value(U).Transformed(T)
	--          
	--          This methods calls the basis curve method.
     is redefined;  

  ParametricTransformation(me; T : Trsf2d from gp) returns Real
	---Purpose: Returns a  coefficient to compute the parameter on
	--          the transformed  curve  for  the transform  of the
	--          point on <me>.
	--          
	--          Transformed(T)->Value(U * ParametricTransformation(T))
	--          
	--          is the same point as
	--          
	--          Value(U).Transformed(T)
	--          
	--          This methods calls the basis curve method.
     is redefined;  


  Copy (me)  returns like me;
---Purpose:
-- Creates a new object, which is a copy of this trimmed curve. 
    
fields

    basisCurve : Curve from Geom2d;
    uTrim1     : Real;
    uTrim2     : Real;

end;
Commit	Line	Data
b311480e	1	-- Created on: 1993-03-24
	2	-- Created by: JCV
	3	-- Copyright (c) 1993-1999 Matra Datavision
973c2be1	4	-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e	5	--
973c2be1	6	-- This file is part of Open CASCADE Technology software library.
b311480e	7	--
d5f74e42	8	-- This library is free software; you can redistribute it and/or modify it under
d5f74e42	9	-- the terms of the GNU Lesser General Public License version 2.1 as published
973c2be1	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.
b311480e	13	--
973c2be1	14	-- Alternatively, this file may be used under the terms of Open CASCADE
973c2be1	15	-- commercial license or contractual agreement.
7fd59977	16
	17	class TrimmedCurve from Geom2d inherits BoundedCurve from Geom2d
	18
	19	--- Purpose :
	20	-- Defines a portion of a curve limited by two values of
	21	-- parameters inside the parametric domain of the curve.
	22	-- The trimmed curve is defined by:
	23	-- - the basis curve, and
	24	-- - the two parameter values which limit it.
	25	-- The trimmed curve can either have the same
	26	-- orientation as the basis curve or the opposite orientation.
	27
	28	uses Ax2d from gp,
	29	Pnt2d from gp,
	30	Trsf2d from gp,
	31	Vec2d from gp,
	32	Curve from Geom2d,
	33	Geometry from Geom2d,
	34	Shape from GeomAbs
	35
	36
	37	raises ConstructionError from Standard,
	38	RangeError from Standard,
	39	NoSuchObject from Standard,
	40	UndefinedDerivative from Geom2d,
	41	UndefinedValue from Geom2d
	42
	43
	44	is
	45
8ac0cf52	46	Create (C : Curve; U1, U2 : Real; Sense : Boolean = Standard_True;
8ac0cf52	47	theAdjustPeriodic : Boolean = Standard_True)
6e33d3ce	48	returns TrimmedCurve
7fd59977	49	--- Purpose :
	50	-- Creates a trimmed curve from the basis curve C limited between
	51	-- U1 and U2.
	52	--
	53	-- . U1 can be greater or lower than U2.
	54	-- . The returned curve is oriented from U1 to U2.
	55	-- . If the basis curve C is periodic there is an ambiguity
	56	-- because two parts are available. In this case by default
	57	-- the trimmed curve has the same orientation as the basis
	58	-- curve (Sense = True). If Sense = False then the orientation
	59	-- of the trimmed curve is opposite to the orientation of the
	60	-- basis curve C.
	61	-- If the curve is closed but not periodic it is not possible
	62	-- to keep the part of the curve including the junction point
	63	-- (except if the junction point is at the beginning or
	64	-- at the end of the trimmed curve) because you could lose the
	65	-- fundamental characteristics of the basis curve which are
	66	-- used for example to compute the derivatives of the trimmed
	67	-- curve. So for a closed curve the rules are the same as for
	68	-- a open curve.
	69	-- Warnings :
	70	-- In this package the entities are not shared. The TrimmedCurve is
	71	-- built with a copy of the curve C. So when C is modified the
	72	-- TrimmedCurve is not modified
	73	-- Warnings :
8ac0cf52	74	-- If <C> is periodic and <theAdjustPeriodic> is True, parametrics
	75	-- bounds of the TrimmedCurve, can be different to [<U1>;<U2>},
	76	-- if <U1> or <U2> are not in the principal period.
7fd59977	77	-- Include :
	78	-- For more explanation see the scheme given with this class.
	79	-- Raises ConstructionError the C is not periodic and U1 or U2 are out of
	80	-- the bounds of C.
	81	-- Raised if U1 = U2.
	82	raises ConstructionError;
	83
	84
	85
	86
	87	Reverse (me : mutable);
	88	--- Purpose :
	89	-- Changes the direction of parametrization of <me>. The first and
	90	-- the last parametric values are modified. The "StartPoint"
	91	-- of the initial curve becomes the "EndPoint" of the reversed
	92	-- curve and the "EndPoint" of the initial curve becomes the
	93	-- "StartPoint" of the reversed curve.
	94	-- Example - If the trimmed curve is defined by:
	95	-- - a basis curve whose parameter range is [ 0.,1. ], and
	96	-- - the two trim values U1 (first parameter) and U2 (last parameter),
	97	-- the reversed trimmed curve is defined by:
	98	-- - the reversed basis curve, whose parameter range is still [ 0.,1. ], and
	99	-- - the two trim values 1. - U2 (first parameter)
	100	-- and 1. - U1 (last parameter).
	101
	102	ReversedParameter(me; U : Real) returns Real;
	103	---Purpose: Returns the parameter on the reversed curve for
	104	-- the point of parameter U on <me>.
	105	--
	106	-- returns UFirst + ULast - U
	107
	108
8ac0cf52	109	SetTrim (me : mutable; U1, U2 : Real; Sense : Boolean = Standard_True;
8ac0cf52	110	theAdjustPeriodic : Boolean = Standard_True)
7fd59977	111	--- Purpose : Changes this trimmed curve, by redefining the
	112	-- parameter values U1 and U2, which limit its basis curve.
	113	-- Note: If the basis curve is periodic, the trimmed curve
	114	-- has the same orientation as the basis curve if Sense
	115	-- is true (default value) or the opposite orientation if Sense is false.
	116	-- Warning
8ac0cf52	117	-- If the basis curve is periodic and theAdjustPeriodic is True,
8ac0cf52	118	-- the bounds of the trimmed curve may be different from U1 and U2 if the
7fd59977	119	-- parametric origin of the basis curve is within the arc
	120	-- of the trimmed curve. In this case, the modified
	121	-- parameter will be equal to U1 or U2 plus or minus the period.
8ac0cf52	122	-- If theAdjustPeriodic is False, parameters U1 and U2 will stay unchanged.
7fd59977	123	-- Exceptions
	124	-- Standard_ConstructionError if:
	125	-- - the basis curve is not periodic, and either U1 or U2
	126	-- are outside the bounds of the basis curve, or
	127	-- - U1 is equal to U2.
	128	raises ConstructionError;
	129
	130
	131
	132	BasisCurve (me) returns Curve;
	133	--- Purpose : Returns the basis curve.
	134	-- Warning
	135	-- This function does not return a constant reference.
	136	-- Consequently, any modification of the returned value
	137	-- directly modifies the trimmed curve.
	138
	139
	140	Continuity (me) returns Shape from GeomAbs;
	141	--- Purpose :
	142	-- Returns the global continuity of the basis curve of this trimmed curve.
	143	-- C0 : only geometric continuity,
	144	-- C1 : continuity of the first derivative all along the Curve,
	145	-- C2 : continuity of the second derivative all along the Curve,
	146	-- C3 : continuity of the third derivative all along the Curve,
	147	-- CN : the order of continuity is infinite.
	148
	149
	150	IsCN (me; N : Integer) returns Boolean
	151	--- Purpose
	152	-- Returns True if the order of continuity of the
	153	-- trimmed curve is N. A trimmed curve is at least "C0" continuous.
	154	-- Warnings :
	155	-- The continuity of the trimmed curve can be greater than
	156	-- the continuity of the basis curve because you consider
	157	-- only a part of the basis curve.
	158	raises RangeError;
	159	--- Purpose : Raised if N < 0.
	160
	161
	162	EndPoint (me) returns Pnt2d;
	163	--- Purpose :
	164	-- Returns the end point of <me>. This point is the
	165	-- evaluation of the curve for the "LastParameter".
	166
	167
	168	FirstParameter (me) returns Real;
	169	--- Purpose :
	170	-- Returns the value of the first parameter of <me>.
	171	-- The first parameter is the parameter of the "StartPoint"
	172	-- of the trimmed curve.
	173
	174
	175	IsClosed (me) returns Boolean;
	176	--- Purpose :
	177	-- Returns True if the distance between the StartPoint and
	178	-- the EndPoint is lower or equal to Resolution from package
	179	-- gp.
	180
	181
	182	IsPeriodic (me) returns Boolean;
	183	--- Purpose : Returns true if the basis curve of this trimmed curve is periodic.
	184
	185
	186	Period (me) returns Real from Standard
187	---Purpose: Returns the period of the basis curve of this trimmed curve.
188	-- Exceptions
189	-- Standard_NoSuchObject if the basis curve is not periodic.
190	raises
191	NoSuchObject from Standard
192	is redefined;
193
194
195	LastParameter (me) returns Real;
196	--- Purpose :
197	-- Returns the value of the last parameter of <me>.
198	-- The last parameter is the parameter of the "EndPoint" of the
199	-- trimmed curve.
200
201
202	StartPoint (me) returns Pnt2d;
203	--- Purpose :
204	-- Returns the start point of <me>.
205	-- This point is the evaluation of the curve from the
206	-- "FirstParameter".
207
208	--- Purpose : value and derivatives
209	--- Warnings :
210	-- The returned derivatives have the same orientation as the
211	-- derivatives of the basis curve.
212
213
214	D0 (me; U : Real; P : out Pnt2d)
215	raises UndefinedValue;
216	--- Purpose:
217	-- If the basis curve is an OffsetCurve sometimes it is not
218	-- possible to do the evaluation of the curve at the parameter
219	-- U (see class OffsetCurve).
220
221
222	D1 (me; U : Real; P : out Pnt2d; V1 : out Vec2d)
223	raises UndefinedDerivative;
224	--- Purpose : Raised if the continuity of the curve is not C1.
225
226
227	D2 (me; U : Real; P : out Pnt2d; V1, V2 : out Vec2d)
228	raises UndefinedDerivative;
229	--- Purpose : Raised if the continuity of the curve is not C2.
230
231
232	D3 (me; U : Real; P : out Pnt2d; V1, V2, V3 : out Vec2d)
233	raises UndefinedDerivative;
234	--- Purpose : Raised if the continuity of the curve is not C3.
235
236
237	DN (me; U : Real; N : Integer) returns Vec2d
238	--- Purpose : For the point of parameter U of this trimmed curve,
239	-- computes the vector corresponding to the Nth derivative.
240	-- Warning
241	-- The returned derivative vector has the same
242	-- orientation as the derivative vector of the basis curve,
243	-- even if the trimmed curve does not have the same
244	-- orientation as the basis curve.
245	-- Exceptions
246	-- Standard_RangeError if N is less than 1.
247	raises UndefinedDerivative,
248	RangeError;
249
250
251	--- Purpose : geometric transformations
252
253	Transform (me : mutable; T : Trsf2d);
254	--- Purpose : Applies the transformation T to this trimmed curve.
255	-- Warning The basis curve is also modified.
256
257	TransformedParameter(me; U : Real; T : Trsf2d from gp) returns Real
258	---Purpose: Returns the parameter on the transformed curve for
259	-- the transform of the point of parameter U on <me>.
260	--
261	-- me->Transformed(T)->Value(me->TransformedParameter(U,T))
262	--
263	-- is the same point as
264	--
265	-- me->Value(U).Transformed(T)
266	--
267	-- This methods calls the basis curve method.
268	is redefined;
269
270	ParametricTransformation(me; T : Trsf2d from gp) returns Real
271	---Purpose: Returns a coefficient to compute the parameter on
272	-- the transformed curve for the transform of the
273	-- point on <me>.
274	--
275	-- Transformed(T)->Value(U * ParametricTransformation(T))
276	--
277	-- is the same point as
278	--
279	-- Value(U).Transformed(T)
280	--
281	-- This methods calls the basis curve method.
282	is redefined;
283
284
285
6e33d3ce	286	Copy (me) returns like me;
7fd59977	287	---Purpose:
	288	-- Creates a new object, which is a copy of this trimmed curve.
	289
	290	fields
	291
	292	basisCurve : Curve from Geom2d;
	293	uTrim1 : Real;
	294	uTrim2 : Real;
	295
	296	end;