HM_ExtAPI::SurfaceTorusGetData()
Returns parameters that define torus surface.
Syntax
bool SurfaceTorusGetData(
const HM_EntityGeometrySurface & surface,
HM_Point& origin,
HM_Vector& unit_normal,
HM_Vector& unit_uorigin_dir,
double& base_radius,
double& tube_radius,
double& tube_phase,
bool& reverse_u
);
Type
HyperMesh Ext API
Description
The function expects that the type of surface object is HM_ExtAPI::TORUS(). Application should call the function HM_ExtAPI::GeomSurfaceGetType() to verify the type before calling SurfaceTorusGetData function.
The torus is defined by a circular spine and a circular cross-section at each point of the spine. The spine of a torus is defined by a center point C, normal n, and radius R. The circular cross-section is defined by a minor radius r.
The torus is parameterized by angular parameters U and V. The V-parameter is the latitude with positive direction in the direction of the torus normal n. The value V = φ corresponds to the largest V-isoparametric circle on the tube of the torus.
The U-parameter is the longitude with positive direction in counter clockwise direction around the torus normal n in case the SurfaceTorusGetData function returns false in reverse_u parameter. The direction of U-parameter is in clockwise direction around the torus normal n in case the value of reverse_u parameter is true. The vector u defines the direction from the center of the torus C to the circle of constant U=0 parametric isoline of the torus.
The figure below clarifies the meaning of torus parameter and shows the fragment of the torus surface for the case when reverse_u is false.
Figure 1.
| Parameters returned by SurfaceTorusGetData | Torus parameters shown on the figure |
|---|---|
| origin | C |
| unit_normal | n |
| unit_uorigin_dir | u |
| base_radius | R |
| tube_radius | r |
| tube_phase | φ |
| reverse_u | If false then q = n X u, If true then q = u X n |
The points on the surface of the torus can be calculated parametrically as
S(U, V) = C + r n sin(V-φ) + [ R + r cos(V-φ) ] [ u cos U + q sin U ]
If the function succeeds, the return value is true. If the function fails, the return value is false. To get extended value information, call HM_ExtAPI::GetLastErrorCode().
Requires including hm_extapi.h.
Inputs
- surface
- [in] - Handle to surface object that was returned by previous calls to API functions.
- origin
- [out] - Center point on torus circular spine.
- unit_normal
- [out] - Unit length vector normal to the plane of the spine.
- unit_uorigin_dir
- [out] - Unit length vector in the plane of the spine that defines position of the tube circle corresponding to U=0 parameter.
- base_radius
- [out] - Spine circle radius.
- tube_radius
- [out] - Tube radius.
- tube_phase
- [out] - Parameter shift on the tube. See Description above.
- reverse_u
- [out] - Flag that defines direction of constant V parametric lines along the tube of the torus. The value of false indicates counter clockwise direction of constant V parametric lines with respect to the normal direction. The value of true indicates clockwise direction of constant V parametric lines.
Errors
None.