-- Created on: 1993-03-10
-- Created by: JCV
-- Copyright (c) 1993-1999 Matra Datavision
-- Copyright (c) 1999-2012 OPEN CASCADE SAS
--
-- The content of this file is subject to the Open CASCADE Technology Public
-- License Version 6.5 (the "License"). You may not use the content of this file
-- except in compliance with the License. Please obtain a copy of the License
-- at http://www.opencascade.org and read it completely before using this file.
--
-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
--
-- The Original Code and all software distributed under the License is
-- distributed on an "AS IS" basis, without warranty of any kind, and the
-- Initial Developer hereby disclaims all such warranties, including without
-- limitation, any warranties of merchantability, fitness for a particular
-- purpose or non-infringement. Please see the License for the specific terms
-- and conditions governing the rights and limitations under the License.



class Hyperbola from Geom inherits Conic from Geom

        ---Purpose : Describes a branch of a hyperbola in 3D space.
    	-- A hyperbola is defined by its major and minor radii
    	-- and, as with any conic curve, is positioned in space
    	-- with a right-handed coordinate system (gp_Ax2 object) where:
    	-- - the origin is the center of the hyperbola,
    	-- - the "X Direction" defines the major axis, and
    	-- - the "Y Direction" defines the minor axis.
    	-- The origin, "X Direction" and "Y Direction" of this
    	-- coordinate system define the plane of the hyperbola.
    	-- The coordinate system is the local coordinate
    	-- system of the hyperbola.
    	-- The branch of the hyperbola described is the one
    	-- located on the positive side of the major axis.
    	-- The "main Direction" of the local coordinate system is
    	-- a vector normal to the plane of the hyperbola. The
    	-- axis, of which the origin and unit vector are
    	-- respectively the origin and "main Direction" of the
    	-- local coordinate system, is termed the "Axis" or "main
    	-- Axis" of the hyperbola.
    	-- The "main Direction" of the local coordinate system
    	-- gives an explicit orientation to the hyperbola,
    	-- determining the direction in which the parameter
    	-- increases along the hyperbola.
    	-- The Geom_Hyperbola hyperbola is parameterized as follows:
    	-- P(U) = O + MajRad*Cosh(U)*XDir + MinRad*Sinh(U)*YDir, where:
    	-- - P is the point of parameter U,
    	-- - O, XDir and YDir are respectively the origin, "X
    	--   Direction" and "Y Direction" of its local coordinate system,
    	-- - MajRad and MinRad are the major and minor radii of the hyperbola.
    	-- The "X Axis" of the local coordinate system therefore
    	-- defines the origin of the parameter of the hyperbola.
    	-- The parameter range is ] -infinite, +infinite [.
    	-- The following diagram illustrates the respective
    	-- positions, in the plane of the hyperbola, of the three
    	-- branches of hyperbolas constructed using the
    	-- functions OtherBranch, ConjugateBranch1 and
    	-- ConjugateBranch2: Defines the main branch of an hyperbola.
	--                      ^YAxis                
        --                         |                   
        --                  FirstConjugateBranch     
        --                         |        
        --        Other            |                Main
        --   --------------------- C ------------------------------>XAxis
        --        Branch           |                Branch
        --                         |         
        --                   SecondConjugateBranch
        --                         |         
        -- Warning
    	-- The value of the major radius (on the major axis) can
    	-- be less than the value of the minor radius (on the minor axis).
     

uses Ax1      from gp,
     Ax2      from gp,
     Hypr     from gp, 
     Pnt      from gp, 
     Trsf     from gp, 
     Vec      from gp,
     Geometry from Geom


raises ConstructionError from Standard, 
       DomainError       from Standard,
       RangeError        from Standard


is

 Create (H : Hypr)   returns mutable Hyperbola;
        ---Purpose : Constructs a hyperbola by conversion of the gp_Hypr hyperbola H.
       

  Create (A2 : Ax2; MajorRadius, MinorRadius : Real)
     returns mutable Hyperbola
    	---Purpose : Constructs a hyperbola defined by its major and
    	-- minor radii, MajorRadius and MinorRadius, where A2 locates the
    	--   hyperbola and defines its orientation in 3D space such that:
    	--   - the center of the hyperbola is the origin of A2,
    	--   - the "X Direction" of A2 defines the major axis
    	--    of the hyperbola, i.e. the major radius
    	--    MajorRadius is measured along this axis,
    	--   - the "Y Direction" of A2 defines the minor axis
    	--    of the hyperbola, i.e. the minor radius
    	--    MinorRadius is measured along this axis,
    	--   - A2 is the local coordinate system of the   hyperbola.
    	-- Exceptions
    	-- Standard_ConstructionError if:
    	-- - MajorRadius is less than 0.0,
    	-- - MinorRadius is less than 0.0.   
     raises ConstructionError;
	
  SetHypr (me : mutable; H : Hypr)
        ---Purpose: Converts the gp_Hypr hyperbola H into this hyperbola.   
  is static;


  SetMajorRadius (me : mutable; MajorRadius : Real)
     raises ConstructionError
    	---Purpose : Assigns a value to the major radius of this hyperbola.
    	-- Exceptions
    	-- Standard_ConstructionError if:
    	-- - MajorRadius is less than 0.0, or
    	-- - MinorRadius is less than 0.0.Raised if MajorRadius < 0.0
  is static;
  

  SetMinorRadius (me : mutable; MinorRadius : Real)
     raises ConstructionError
    	---Purpose : Assigns a value to the minor radius of this hyperbola.
    	-- Exceptions
    	-- Standard_ConstructionError if:
    	-- - MajorRadius is less than 0.0, or
    	-- - MinorRadius is less than 0.0.Raised if MajorRadius < 0.0
  is static;
  

  Hypr (me)  returns Hypr
        ---Purpose :
        --  returns the non transient parabola from gp with the same 
        --  geometric properties as <me>.
  is static;
  

  ReversedParameter(me; U : Real) returns Real is redefined static;
    	---Purpose: Computes the parameter on the reversed hyperbola,
    	-- for the point of parameter U on this hyperbola.
    	-- For a hyperbola, the returned value is: -U.

  FirstParameter (me)   returns Real is redefined static;
        ---Purpose : Returns RealFirst from Standard.


  LastParameter (me)   returns Real is redefined static;
        ---Purpose : returns RealLast from Standard.


  IsClosed (me)   returns Boolean is redefined static;
        ---Purpose : Returns False.


  IsPeriodic (me)   returns Boolean is redefined static;
        ---Purpose : return False for an hyperbola.


  Asymptote1 (me)  returns Ax1
	---Purpose :
	--  In the local coordinate system of the hyperbola the equation of
	--  the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
        --  equation of the first asymptote is Y = (B/A)*X.
    	--  Raises ConstructionError if MajorRadius = 0.0
    raises ConstructionError;


  Asymptote2 (me)    returns Ax1
	---Purpose :
	--  In the local coordinate system of the hyperbola the equation of
	--  the hyperbola is (X*X)/(A*A) - (Y*Y)/(B*B) = 1.0 and the
        --  equation of the first asymptote is Y = -(B/A)*X.
    	-- Raises ConstructionError if MajorRadius = 0.0
     raises ConstructionError;



  ConjugateBranch1 (me)   returns Hypr;
	---Purpose :
	--  This branch of hyperbola is on the positive side of the 
	--  YAxis of <me>.


  ConjugateBranch2 (me)  returns Hypr;
	---Purpose :
	--  This branch of hyperbola is on the negative side of the 
	--  YAxis of <me>.
    	-- Note: The diagram given under the class purpose
    	-- indicates where these two branches of hyperbola are
    	-- positioned in relation to this branch of hyperbola.
        

  Directrix1 (me)   returns Ax1;
        ---Purpose :
        --  This directrix is the line normal to the XAxis of the hyperbola
        --  in the local plane (Z = 0) at a distance d = MajorRadius / e 
        --  from the center of the hyperbola, where e is the eccentricity of
        --  the hyperbola.
        --  This line is parallel to the YAxis. The intersection point between
        --  directrix1 and the XAxis is the location point of the directrix1.
        --  This point is on the positive side of the XAxis.


  Directrix2 (me)   returns Ax1;
        ---Purpose :
        --  This line is obtained by the symmetrical transformation 
        --  of "directrix1" with respect to the YAxis of the hyperbola.


  Eccentricity (me)   returns Real
	---Purpose :
	--  Returns the excentricity of the hyperbola (e > 1).
    	--  If f is the distance between the location of the hyperbola
    	--  and the Focus1 then the eccentricity e = f / MajorRadius.
     raises ConstructionError is redefined static;
        ---Purpose : raised if MajorRadius = 0.0


  Focal (me)   returns Real;
	---Purpose :
	--  Computes the focal distance. It is the distance between the
        --  two focus of the hyperbola.


  Focus1 (me)   returns Pnt;
	---Purpose :
	--  Returns the first focus of the hyperbola. This focus is on the
        --  positive side of the XAxis of the hyperbola.


  Focus2 (me)  returns Pnt;
        ---Purpose :
	--  Returns the second focus of the hyperbola. This focus is on the
        --  negative side of the XAxis of the hyperbola.


  MajorRadius (me)  returns Real;

    	---Purpose: Returns the major or minor radius of this hyperbola.
    	-- The major radius is also the distance between the
    	-- center of the hyperbola and the apex of the main
    	-- branch (located on the "X Axis" of the hyperbola).
    
  MinorRadius (me)  returns Real;
    	---Purpose: Returns the major or minor radius of this hyperbola.
    	-- The minor radius is also the distance between the
    	-- center of the hyperbola and the apex of a conjugate
    	-- branch (located on the "Y Axis" of the hyperbola).

  OtherBranch (me)   returns Hypr;
    	---Purpose : Computes the "other" branch of this hyperbola. This
    	-- is the symmetrical branch with respect to the center of this hyperbola.
	-- Note: The diagram given under the class purpose
    	-- indicates where the "other" branch is positioned in
    	-- relation to this branch of the hyperbola.



  Parameter (me)  returns Real
        ---Purpose :
        --  Returns p = (e * e - 1) * MajorRadius where e is the 
        --  eccentricity of the hyperbola.
     raises DomainError;
        ---Purpose : raised if MajorRadius = 0.0


  D0(me; U : Real; P : out Pnt) is redefined static;
	---Purpose: Returns in P the point of parameter U.
        --  P = C + MajorRadius * Cosh (U) * XDir +
        --          MinorRadius * Sinh (U) * YDir
        --  where C is the center of the hyperbola , XDir the XDirection and
        --  YDir the YDirection of the hyperbola's local coordinate system.


  D1 (me; U : Real; P : out Pnt; V1 : out Vec) is redefined static;
        ---Purpose :
        --  Returns the point P of parameter U and the first derivative V1.


  D2 (me; U : Real; P : out Pnt; V1, V2 : out Vec) is redefined static;
        ---Purpose :
        --  Returns the point P of parameter U, the first and second 
        --  derivatives V1 and V2.


  D3 (me; U : Real; P : out Pnt; V1, V2, V3 : out Vec) is redefined static;
        ---Purpose :
        --  Returns the point P of parameter U, the first second and 
        --  third derivatives V1 V2 and V3.
  

  DN (me; U : Real; N : Integer)   returns Vec
        ---Purpose :
        --  The returned vector gives the value of the derivative for the 
        --  order of derivation N.
    raises RangeError 
    is redefined static;
        ---Purpose : Raised if N < 1.   


  Transform (me : mutable; T : Trsf) is redefined static;
    	---Purpose: Applies the transformation T to this hyperbola.


  Copy (me)  returns mutable like me is redefined static;

    	---Purpose: Creates a new object which is a copy of this hyperbola.
fields

     majorRadius : Real;
     minorRadius : Real;

end;