1 -- Copyright (c) 1991-1999 Matra Datavision
2 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
4 -- The content of this file is subject to the Open CASCADE Technology Public
5 -- License Version 6.5 (the "License"). You may not use the content of this file
6 -- except in compliance with the License. Please obtain a copy of the License
7 -- at http://www.opencascade.org and read it completely before using this file.
9 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
10 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
12 -- The Original Code and all software distributed under the License is
13 -- distributed on an "AS IS" basis, without warranty of any kind, and the
14 -- Initial Developer hereby disclaims all such warranties, including without
15 -- limitation, any warranties of merchantability, fitness for a particular
16 -- purpose or non-infringement. Please see the License for the specific terms
17 -- and conditions governing the rights and limitations under the License.
20 class Ax2 from gp inherits Storable
23 -- Describes a right-handed coordinate system in 3D space.
24 -- A coordinate system is defined by:
25 -- - its origin (also referred to as its "Location point"), and
26 -- - three orthogonal unit vectors, termed respectively the
27 -- "X Direction", the "Y Direction" and the "Direction" (also
28 -- referred to as the "main Direction").
29 -- The "Direction" of the coordinate system is called its
30 -- "main Direction" because whenever this unit vector is
31 -- modified, the "X Direction" and the "Y Direction" are
32 -- recomputed. However, when we modify either the "X
33 -- Direction" or the "Y Direction", "Direction" is not modified.
34 -- The "main Direction" is also the "Z Direction".
35 -- Since an Ax2 coordinate system is right-handed, its
36 -- "main Direction" is always equal to the cross product of
37 -- its "X Direction" and "Y Direction". (To define a
38 -- left-handed coordinate system, use gp_Ax3.)
39 -- A coordinate system is used:
40 -- - to describe geometric entities, in particular to position
41 -- them. The local coordinate system of a geometric
42 -- entity serves the same purpose as the STEP function
43 -- "axis placement two axes", or
44 -- - to define geometric transformations.
45 -- Note: we refer to the "X Axis", "Y Axis" and "Z Axis",
46 -- respectively, as to axes having:
47 -- - the origin of the coordinate system as their origin, and
48 -- - the unit vectors "X Direction", "Y Direction" and "main
49 -- Direction", respectively, as their unit vectors.
50 -- The "Z Axis" is also the "main Axis".
59 raises ConstructionError from Standard
66 --- Purpose : Creates an object corresponding to the reference
67 -- coordinate system (OXYZ).
70 Create (P : Pnt; N, Vx : Dir) returns Ax2
73 -- Creates an axis placement with an origin P such that:
74 -- - N is the Direction, and
75 -- - the "X Direction" is normal to N, in the plane
76 -- defined by the vectors (N, Vx): "X
77 -- Direction" = (N ^ Vx) ^ N,
78 -- Exception: raises ConstructionError if N and Vx are parallel (same or opposite orientation).
79 raises ConstructionError;
82 Create (P : Pnt; V : Dir) returns Ax2;
84 -- Creates - a coordinate system with an origin P, where V
85 -- gives the "main Direction" (here, "X Direction" and "Y
86 -- Direction" are defined automatically).
88 SetAxis (me : in out; A1 : Ax1)
89 --- Purpose : Assigns the origin and "main Direction" of the axis A1 to
90 -- this coordinate system, then recomputes its "X Direction" and "Y Direction".
91 -- Note: The new "X Direction" is computed as follows:
92 -- new "X Direction" = V1 ^(previous "X Direction" ^ V)
93 -- where V is the "Direction" of A1.
95 -- Standard_ConstructionError if A1 is parallel to the "X
96 -- Direction" of this coordinate system.
97 raises ConstructionError
102 SetDirection (me : in out; V : Dir)
104 -- Changes the "main Direction" of this coordinate system,
105 -- then recomputes its "X Direction" and "Y Direction".
106 -- Note: the new "X Direction" is computed as follows:
107 -- new "X Direction" = V ^ (previous "X Direction" ^ V)
109 -- Standard_ConstructionError if V is parallel to the "X
110 -- Direction" of this coordinate system.
111 raises ConstructionError
115 SetLocation (me : in out; P : Pnt) is static;
117 -- Changes the "Location" point (origin) of <me>.
120 SetXDirection (me : in out; Vx : Dir)
122 -- Changes the "Xdirection" of <me>. The main direction
123 -- "Direction" is not modified, the "Ydirection" is modified.
124 -- If <Vx> is not normal to the main direction then <XDirection>
125 -- is computed as follows XDirection = Direction ^ (Vx ^ Direction).
127 -- Standard_ConstructionError if Vx or Vy is parallel to
128 -- the "main Direction" of this coordinate system.
129 raises ConstructionError
133 SetYDirection(me : in out; Vy : Dir)
135 -- Changes the "Ydirection" of <me>. The main direction is not
136 -- modified but the "Xdirection" is changed.
137 -- If <Vy> is not normal to the main direction then "YDirection"
138 -- is computed as follows
139 -- YDirection = Direction ^ (<Vy> ^ Direction).
141 -- Standard_ConstructionError if Vx or Vy is parallel to
142 -- the "main Direction" of this coordinate system.
143 raises ConstructionError
147 Angle (me; Other : Ax2) returns Real is static;
149 -- Computes the angular value, in radians, between the main direction of
150 -- <me> and the main direction of <Other>. Returns the angle
151 -- between 0 and PI in radians.
154 Axis (me) returns Ax1 is static;
157 -- Returns the main axis of <me>. It is the "Location" point
158 -- and the main "Direction".
159 ---C++: return const&
162 Direction (me) returns Dir is static;
165 -- Returns the main direction of <me>.
166 ---C++: return const&
169 Location (me) returns Pnt is static;
172 -- Returns the "Location" point (origin) of <me>.
173 ---C++: return const&
176 XDirection (me) returns Dir is static;
179 -- Returns the "XDirection" of <me>.
180 ---C++: return const&
183 YDirection(me) returns Dir is static;
186 -- Returns the "YDirection" of <me>.
187 ---C++: return const&
190 IsCoplanar (me; Other : Ax2; LinearTolerance, AngularTolerance : Real)
194 -- - the "main Direction" of this coordinate system is parallel to:
195 -- - the "main Direction" of the coordinate system Other, or
196 -- - the Direction of axis A1, and
198 -- Note: the tolerance criterion for angular equality is given by AngularTolerance.
201 IsCoplanar (me; A1 : Ax1; LinearTolerance, AngularTolerance : Real)
207 -- . the distance between <me> and the "Location" point of A1
208 -- is lower of equal to LinearTolerance and
209 -- . the main direction of <me> and the direction of A1 are normal.
210 -- Note: the tolerance criterion for angular equality is given by AngularTolerance.
212 Mirror (me : in out; P : Pnt) is static;
215 -- Performs a symmetrical transformation of this coordinate
216 -- system with respect to:
217 -- - the point P, and assigns the result to this coordinate system.
219 -- This transformation is always performed on the origin.
220 -- In case of a reflection with respect to a point:
221 -- - the main direction of the coordinate system is not changed, and
222 -- - the "X Direction" and the "Y Direction" are simply reversed
223 -- In case of a reflection with respect to an axis or a plane:
224 -- - the transformation is applied to the "X Direction"
225 -- and the "Y Direction", then
226 -- - the "main Direction" is recomputed as the cross
227 -- product "X Direction" ^ "Y Direction".
228 -- This maintains the right-handed property of the
229 -- coordinate system.
231 Mirrored (me; P : Pnt) returns Ax2 is static;
233 -- Performs a symmetrical transformation of this coordinate
234 -- system with respect to:
235 -- - the point P, and creates a new one.
237 -- This transformation is always performed on the origin.
238 -- In case of a reflection with respect to a point:
239 -- - the main direction of the coordinate system is not changed, and
240 -- - the "X Direction" and the "Y Direction" are simply reversed
241 -- In case of a reflection with respect to an axis or a plane:
242 -- - the transformation is applied to the "X Direction"
243 -- and the "Y Direction", then
244 -- - the "main Direction" is recomputed as the cross
245 -- product "X Direction" ^ "Y Direction".
246 -- This maintains the right-handed property of the
247 -- coordinate system.
251 Mirror (me : in out; A1 : Ax1) is static;
253 -- Performs a symmetrical transformation of this coordinate
254 -- system with respect to:
255 -- - the axis A1, and assigns the result to this coordinate systeme.
257 -- This transformation is always performed on the origin.
258 -- In case of a reflection with respect to a point:
259 -- - the main direction of the coordinate system is not changed, and
260 -- - the "X Direction" and the "Y Direction" are simply reversed
261 -- In case of a reflection with respect to an axis or a plane:
262 -- - the transformation is applied to the "X Direction"
263 -- and the "Y Direction", then
264 -- - the "main Direction" is recomputed as the cross
265 -- product "X Direction" ^ "Y Direction".
266 -- This maintains the right-handed property of the
267 -- coordinate system.
269 Mirrored (me; A1 : Ax1) returns Ax2 is static;
272 -- Performs a symmetrical transformation of this coordinate
273 -- system with respect to:
274 -- - the axis A1, and creates a new one.
276 -- This transformation is always performed on the origin.
277 -- In case of a reflection with respect to a point:
278 -- - the main direction of the coordinate system is not changed, and
279 -- - the "X Direction" and the "Y Direction" are simply reversed
280 -- In case of a reflection with respect to an axis or a plane:
281 -- - the transformation is applied to the "X Direction"
282 -- and the "Y Direction", then
283 -- - the "main Direction" is recomputed as the cross
284 -- product "X Direction" ^ "Y Direction".
285 -- This maintains the right-handed property of the
286 -- coordinate system.
290 Mirror (me : in out; A2 : Ax2) is static;
292 -- Performs a symmetrical transformation of this coordinate
293 -- system with respect to:
294 -- - the plane defined by the origin, "X Direction" and "Y
295 -- Direction" of coordinate system A2 and assigns the result to this coordinate systeme.
297 -- This transformation is always performed on the origin.
298 -- In case of a reflection with respect to a point:
299 -- - the main direction of the coordinate system is not changed, and
300 -- - the "X Direction" and the "Y Direction" are simply reversed
301 -- In case of a reflection with respect to an axis or a plane:
302 -- - the transformation is applied to the "X Direction"
303 -- and the "Y Direction", then
304 -- - the "main Direction" is recomputed as the cross
305 -- product "X Direction" ^ "Y Direction".
306 -- This maintains the right-handed property of the
307 -- coordinate system.
309 Mirrored (me; A2 : Ax2) returns Ax2 is static;
311 -- Performs a symmetrical transformation of this coordinate
312 -- system with respect to:
313 -- - the plane defined by the origin, "X Direction" and "Y
314 -- Direction" of coordinate system A2 and creates a new one.
316 -- This transformation is always performed on the origin.
317 -- In case of a reflection with respect to a point:
318 -- - the main direction of the coordinate system is not changed, and
319 -- - the "X Direction" and the "Y Direction" are simply reversed
320 -- In case of a reflection with respect to an axis or a plane:
321 -- - the transformation is applied to the "X Direction"
322 -- and the "Y Direction", then
323 -- - the "main Direction" is recomputed as the cross
324 -- product "X Direction" ^ "Y Direction".
325 -- This maintains the right-handed property of the
326 -- coordinate system.
331 Rotate (me : in out; A1 : Ax1; Ang : Real) is static;
334 Rotated (me; A1 : Ax1; Ang : Real) returns Ax2 is static;
338 -- Rotates an axis placement. <A1> is the axis of the
339 -- rotation . Ang is the angular value of the rotation
343 Scale (me : in out; P : Pnt; S : Real) is static;
345 Scaled (me; P : Pnt; S : Real) returns Ax2 is static;
348 -- Applies a scaling transformation on the axis placement.
349 -- The "Location" point of the axisplacement is modified.
351 -- If the scale <S> is negative :
352 -- . the main direction of the axis placement is not changed.
353 -- . The "XDirection" and the "YDirection" are reversed.
354 -- So the axis placement stay right handed.
357 Transform (me : in out; T : Trsf) is static;
359 Transformed (me; T : Trsf) returns Ax2 is static;
362 -- Transforms an axis placement with a Trsf.
363 -- The "Location" point, the "XDirection" and the
364 -- "YDirection" are transformed with T. The resulting
365 -- main "Direction" of <me> is the cross product between
366 -- the "XDirection" and the "YDirection" after transformation.
369 Translate (me : in out; V : Vec)
373 Translated (me; V : Vec) returns Ax2 is static;
376 -- Translates an axis plaxement in the direction of the vector
377 -- <V>. The magnitude of the translation is the vector's magnitude.
380 Translate (me : in out; P1, P2 : Pnt)
384 Translated (me; P1, P2 : Pnt) returns Ax2 is static;
387 -- Translates an axis placement from the point <P1> to the