torus

List of:	Classes
Subjects:	Construction Geometry, SAT Save and Restore
Contents:	Kernel

Purpose:

Represents tori.

Derivation:

torus : surface : ACIS_OBJECT : -

SAT Identifier:

"torus"

Filename:

kern/kernel/kerngeom/surface/tordef.hxx

Description:

A torus is defined by a circular spine and a circular cross-section at each point on the spine. The spine of a torus is defined by a center point, normal, and major radius. The circular cross-section is defined by a minor radius.

A normal torus (donut) is defined when the major radius is larger than the minor radius. Special degenerate cases (lemon, vortex, and apple) occur if the major radius is smaller than or equal to the minor radius. Two data members define the parameterization of the torus:

uv_oridir is the direction from the center of the torus to the origin of parameter space. This is a SPAunit_vector.

reverse_v is a flag indicating the direction of the constant u-parameter lines, which are circles around the torus axis. The direction is normally clockwise, but reversed if this flag is true.

The u-parameter is the latitude, with zero on the circle of greatest radius about the torus axis, and the positive direction in the direction of the torus axis. The u-parameter range depends upon the relative values of the major and minor radii. For a doughnut, where the major radius is greater than the magnitude of the minor, it runs from -pi to pi, and is periodic. For degenerate tori, where the magnitude of the major axis is less than that of the minor, it runs from -U to U, where:

U = arccos(-maj / |min|)

and the surface is singular at each end of the range. The v-parameter is the longitude, running from -pi to pi, with 0 on the meridian containing uv_oridir, and increasing in a clockwise direction around the torus axis, unless reverse_v is TRUE, when it increases in an counterclockwise direction.

Let N be normal and Quv_oridir, and let R be N x Q, negated if reverse_v is TRUE. Let r be the absolute value of the minor radius. Then:

pos = center + r* sinu* N +

(major_radius + (r* cosu)) * (cosv* Q + sinv R)

This parameterization is left-handed for a convex torus and right-handed for a hollow one, if reverse_v is FALSE, and reversed if it is TRUE. When the torus is transformed, the sense of reverse_v is inverted if the transform includes a reflection. No special action is required for a negation.

In summary:

-

Tori are not true parametric surfaces.

-

Tori are closed in v but can or can not be closed in u.

-

Degenerate tori are not periodic in u; nondegenerate tori are periodic in u (-pi to pi with period 2pi).

-

All tori are periodic in v (with range -pi to pi, and period 2pi).

-

Degenerate tori are singular in u at the poles (apices); all other values of u and v are nonsingular.

References:

by KERN

TORUS

BASE

SPAposition, SPAunit_vector

Data:

public logical reverse_v;

The v-parameter is normally measured clockwise about the torus normal. If this logical is TRUE, it is to be measured counterclockwise.

public SPAposition centre;

The center of the circular spine.

public double major_radius;

The radius of the spine curve. This is normally positive, but it can be negative (and smaller in magnitude than the minor radius) for the inner portion (i.e., a lemon as opposed to an apple).

public double minor_radius;

The absolute value of this value specifies the radius of a cross-sectional circle of the ring. If this is negative, then the torus is a void. If this value is 0, then the torus is undefined.

public SPAunit_vector normal;

The normal to the plane of the spine.

public SPAunit_vector uv_oridir;

The direction from the center toward the origin of parameter space. The v-parameter measures the azimuth angle about the normal and so defines a cross-sectional circle. The u-parameter measures the evaluation angle around that circle.

Constructor:

public: torus::torus ();

C++ allocation constructor requests memory for this object but does not populate it.

public: torus::torus (

SPAposition const&,

// center

SPAunit_vector const&,

// normal

double,

// major radius

double

// minor radius

);

C++ initialize constructor requests memory for this object and populates it with the data supplied as arguments.

Creates a torus with the given center, normal and radii.

public: torus::torus (

torus const&

// existing torus

);

C++ copy constructor requests memory for this object and populates it with the data from the object supplied as an argument.

Destructor:

public: torus::~torus ();

C++ destructor, deleting a torus.

Methods:

public: virtual int torus::accurate_derivs (

SPApar_box const&

// parameter box

= * (SPApar_box* ) NULL_REF

) const;

Returns the number of derivatives that evaluate finds accurately and directly, rather than by finite differencing, over the given portion of the surface. If there is no limit to the number of accurate derivatives, as is the case with a torus, this method returns the ALL_SURFACE_DERIVATIVES value.

public: double torus::apex_dist () const;

Returns the positive distance along the torus axis from the center to the apices. This method returns 0 if the torus is nondegenerate (i.e., it has no apices).

public: logical torus::apple () const;

Returns TRUE if the torus is an apple shape. This is true if the major radius of the torus is greater than zero and if the major radius is less than the absolute value of the minor radius minus SPAresabs:

0 < major_radius <= (|minor_radius| - SPAresabs)

public: virtual SPAbox torus::bound (

SPAbox const&,

// box

SPAtransf const&

// transformation

= * (SPAtransf* ) NULL_REF

) const;

Returns a box around a surface bounded in object space. This box need not be the smallest box that contains the specified portion of the surface.

public: virtual SPAbox torus::bound (

SPApar_box const&

// parameter box

= * (SPApar_box* ) NULL_REF,

SPAtransf const&

// transformation

= * (SPAtransf* ) NULL_REF

) const;

Returns a box around a surface bounded in parameter space. This box need not be the smallest box that contains the specified portion of the surface.

public: virtual logical torus::closed_u () const;

Determines whether the surface is closed, smoothly or not, in the u-parameter direction. A torus may or may not be closed in the u-direction.

public: virtual logical torus::closed_v () const;

Determines whether the surface is closed, smoothly or not, in the v-parameter direction. A torus is closed in the v-direction.

public: virtual void torus::debug (

char const*,

// lead string

FILE*

// pointer

= debug_file_ptr

) const;

Prints the details about the torus to the debug file or to the specified file.

public: virtual surface* torus::deep_copy (

pointer_map* pm

// list of items within

= NULL

// the entity that are

// already deep copied

) const;

Creates a copy of an item that does not share any data with the original. Allocates new storage for all member data and any pointers. Returns a pointer to the copied item.

public: logical torus::degenerate () const;

Returns TRUE if the torus is degenerate (i.e., it has apices).

public: logical torus::doughnut () const;

Returns TRUE if the torus is a doughnut shape. This is true if the major radius of the torus is greater than or equal to the absolute value of the minor radius plus SPAresabs:

major_radius >= (|minor_radius| + SPAresabs)

public: virtual void torus::eval (

SPApar_pos const&,

// parameter position

SPAposition&,

// position

SPAvector*

// first derivatives

= NULL,

SPAvector*

// second derivatives

= NULL

) const;

Finds the point on a parametric surface with given parameter values. I may also retain the first and second derivatives as well.

public: virtual int torus::evaluate (

SPApar_pos const&,

// parameter

SPAposition&,

// point on

// surface

SPAvector**

// array of ptrs

= NULL,

// to arrays

// of vectors

int = 0,

// Number of

// derivatives

// required

evaluate_surface_quadrant

// eval. location

= evaluate_surface_unknown

) const;

Calculates derivatives, of any order up to the number requested, and stores them in vectors provided by the user. This method returns the number of derivatives it was able to calculate; usually, this equals the requested number. A certain number are evaluated directly and accurately; higher derivatives are automatically calculated by finite differencing. The accuracy of these decreases with the order of the derivative as the cost increases. Any of the pointers may be NULL, in which case the corresponding derivatives will not be returned. Otherwise they must point to arrays long enough for all the derivatives of that order; i.e., 2 for the first derivatives, 3 for the second, etc.

public: virtual SPAunit_vector torus::eval_normal (

SPApar_pos const&

// parameter position

) const;

Finds the normal to a parametric surface at a point with the given parameter values.

public: surf_princurv torus::eval_prin_curv (

SPApar_pos const& param

// parameter position

) const;

Finds the principle axes of curvature of the surface at a point with the given parameter values.

public: virtual void torus::eval_prin_curv (

SPApar_pos const&,

// parameter position

SPAunit_vector&,

// first axis direction

double&,

// 1st direction

// curvature

SPAunit_vector&,

// second axis direction

double&

// 2nd direction

// curvature

) const;

Finds the principle axes of curvature of the surface at a point with the given parameter values. It also returns the curvatures in those directions.

public: virtual curve* torus::get_path () const;

Returns the sweep path for a torus.

public: virtual curve* torus::get_profile (

double param

// parameter

) const;

Returns the torus sweep information.

public: virtual sweep_path_type

torus::get_path_type () const;

Returns the sweep path type for a torus.

public: virtual law*

torus::get_rail () const;

Returns the rail law for the sweep path for a torus.

public: logical torus::hollow () const;

Returns TRUE if the minor radius of the torus is less than zero.

public: virtual logical

torus::left_handed_uv () const;

Indicates whether the parameter coordinate system of the surface is right-handed or left-handed. With a right-handed system, the output normal at any point is given by the cross product of the increasing u-direction with the increasing v-direction, in that order. With a left-handed system, the outward normal is in the opposite direction from this cross product.

public: logical torus::lemon () const;

Returns TRUE if the torus is a lemon shape. This is true if the major radius of the torus is less than or equal to 0.

public: virtual surface* torus::make_copy () const;

Makes a copy of this torus on the heap, and return a pointer to it.

public: virtual surface& torus::negate ();

Negates this torus; i.e., reverse the direction of the surface normal.

public: virtual surf_normcone torus::normal_cone (

SPApar_box const&,

// parameter bounds

logical

// approximate

= FALSE,

// results OK?

SPAtransf const&

// transformation

= * (SPAtransf* ) NULL_REF

) const;

Returns a cone bounding the normal direction of the surface. The cone has its apex at the origin, and it has a given axis direction and positive half-angle. If logical is TRUE, then this method finds a quick approximation. The approximate result may lie wholly within or wholly outside the guaranteed bound (obtained with a FALSE argument), but it may not cross from inside to outside. Flags in the turned object indicate whether the cone is the best available, and if this result is inside or outside the best cone.

public: virtual surface& torus::operator*= (

SPAtransf const&

// transformation

);

Transforms the torus by the given transformation.

public: torus torus::operator- () const;

Returns a torus that is a copy of the torus being negated (i.e., the new torus has the opposite normal).

public: virtual logical torus::operator== (

surface const&

// surface

) const;

Tests two surfaces for equality. This method does not guarantee equality for effectively-equal surface, but it is guaranteed to determine inequality if the two surfaces are not equal. Use this result for optimization.

public: SPAunit_vector torus::origin_dir () const;

Returns the origin of the coordinates, constructing one if necessary.

public: virtual SPApar_pos torus::param (

SPAposition const&,

// point

SPApar_pos const&

// first guess

= * (SPApar_pos* ) NULL_REF

) const;

Finds the parameter values of a point on a surface, given an optional first guess.

public: virtual logical torus::parametric () const;

Returns whether the torus is a parametric surface. Tori are not considered to be parametric surfaces because their surface properties are easy to find in object space.

public: virtual double

torus::param_period_u () const;

Returns the period of a periodic parametric surface. If the surface is not periodic in the u-parameter or is not parametric, this method returns 0. If the torus is periodic in the u-direction, (i.e., it is a doughnut) its period is 2pi.

public: virtual double

torus::param_period_v () const;

Returns the period of a periodic parametric surface. A torus always has a period of 2pi in the v-direction.

public: virtual SPApar_box torus::param_range (

SPAbox const&

// box

= * (SPAbox* ) NULL_REF

) const;

Return the parameter range.

public: virtual SPAinterval torus::param_range_u (

SPAbox const&

// box

= * (SPAbox* ) NULL_REF

) const;

Returns the principle parameter range of a surface in the u-parameter direction. A periodic surface is defined for all parameter values in the periodic direction by reducing the given parameter modulo the period into this principle range. For a surface that is open or nonperiodic in the chosen direction, the surface evaluation functions are defined only for the parameter values in the returned range.

If a box is provided, the parameter range returned may be restricted to a portion of the surface that is guaranteed to contain all portions of the surface that lie within the region of interest. If none is provided and the parameter range in some direction is unbounded, then this method returns an empty interval.

public: virtual SPAinterval torus::param_range_v (

SPAbox const&

// box

= * (SPAbox* ) NULL_REF

) const;

Returns the principle parameter range of a surface in the v-parameter direction. A periodic surface is defined for all parameter values in the periodic direction by reducing the given parameter modulo the period into this principle range. For a surface that is open or nonperiodic in the chosen direction, the surface evaluation functions are defined only for the parameter values in the returned range.

If a box is provided, the parameter range returned may be restricted to a portion of the surface that is guaranteed to contain all portions of the surface that lie within the region of interest. If none is provided and the parameter range in some direction is unbounded, then this method returns an empty interval.

public: virtual SPApar_vec torus::param_unitvec (

SPAunit_vector const&,

// unit velocity

SPApar_pos const&

// parameter position

) const;

Finds the rate of change in the surface parameter corresponding to a unit velocity in a given object-space direction at a given position in parameter space.

public: virtual logical torus::periodic_u () const;

Determines if the surface is periodic in the u-parameter direction (i.e., it is smoothly closed so that faces can run over the seam). A torus is periodic in the u-direction if it is nondegenerate.

public: virtual logical torus::periodic_v () const;

Determines if the surface is periodic in the v-parameter direction (i.e., it is smoothly closed so that faces can run over the seam). A torus is always periodic in the v-direction.

public: virtual SPAunit_vector torus::point_normal (

SPAposition const&,

// given point

SPApar_pos const&

// not used

= * (SPApar_pos* ) NULL_REF

) const;

Finds the normal to the surface at a point on the surface nearest to the given point. The SPApar_pos argument is not used in the torus implementation of this function.

public: virtual SPAunit_vector torus::point_outdir (

SPAposition const&,

// given point

SPApar_pos const&

// not used

= * (SPApar_pos* ) NULL_REF

) const;

Finds the outward direction from the surface at a point with the given parameter values. This method usually is the normal, but if the nearest point is an apex of a degenerate torus, this method still returns an outward direction. The SPApar_pos argument is not used in the torus implementation of this function.

public: virtual void torus::point_perp (

SPAposition const&,

// given point

SPAposition&,

// position on

// surface

SPAunit_vector&,

// normal to

// surface

surf_princurv&,

// principle

// curvatures

SPApar_pos const&

// guess value

= * (SPApar_pos* ) NULL_REF,

SPApar_pos&

// actual value

= * (SPApar_pos* ) NULL_REF,

logical f_weak

// weak flag

= FALSE

) const;

Finds the point on the surface nearest to the given point and optionally, the normal to and the principle curvatures of the surface at that point. If the surface is parametric, this method also returns the parameter values at the found point.

public: void torus::point_perp (

SPAposition const& pos,

// given point

SPAposition& foot,

// foot

SPApar_pos const&

// param position

param_guess

// guess value

= * (SPApar_pos* ) NULL_REF,

SPApar_pos& param_actual

// actual value

= * (SPApar_pos* ) NULL_REF,

logical f_weak

// weak flag

= FALSE

) const;

Finds the point on the surface nearest to the given point and optionally, the normal to and the principle curvatures of the surface at that point. If the surface is parametric, this method also returns the parameter values at the found point.

public: void torus::point_perp (

SPAposition const& pos,

// given point

SPAposition& foot,

// foot

SPAunit_vector& norm,

// normal to

// surface

SPApar_pos const&

// param position

param_guess

// guess value

= * (SPApar_pos* ) NULL_REF,

SPApar_pos& param_actual

// actual value

= * (SPApar_pos* ) NULL_REF,

logical f_weak

// weak flag

= FALSE

) const;

Finds the point on the surface nearest to the given point and optionally, the normal to and the principle curvatures of the surface at that point. If the surface is parametric, this method also returns the parameter values at the found point.

public: surf_princurv torus::point_prin_curv (

SPAposition const& pos,

// point

SPApar_pos const&

// parameter position

param_guess

// guess value

= * (SPApar_pos* ) NULL_REF

) const;

Returns the principle axes of curvature of the surface at a given point and the curvatures in those directions in a structure defined for the purpose.

public: virtual void torus::point_prin_curv (

SPAposition const&,

// position

SPAunit_vector&,

// 1st axis direction

double&,

// 1st direction

// curvature

SPAunit_vector&,

// 2nd axis direction

double&,

// 2nd direction

// curvature

SPApar_pos const&

// guess value

= * (SPApar_pos* ) NULL_REF

) const;

Finds the principle axes of curvature of the surface at a given point and the curvatures in those directions.

public: void torus::restore_data ();

Restore the data for a torus from a save file.

read_position

Center of torus

read_unit_vector

Normal vector

read_real

major radius

read_real

minor radius

if (restore_version_number < SURFACE_VERSION)

// Old style - that is all to read.

else

read_unit_vector

uv origin direction

read_logical

Either "forward_v" or "reversed_v"

surface::restore_data

Remaining surface data

public: virtual void torus::save () const;

Saves the type of id, then calls save_data.

public: void torus::save_data () const;

Save the information for the torus to a save file.

public: virtual logical torus::singular_u (

double

// u-parameter value

) const;

Determines whether the surface parameterization is singular at the specified u-parameter value. The only singularity recognized is where every value of the nonconstant parameter generates the same object-space point, and these can only occur at the ends of the parameter range. A degenerate torus is singular in the u-direction at the poles.

public: virtual logical torus::singular_v (

double

// v-parameter value

) const;

Determines whether the surface parameterization is singular at the specified v-parameter value. A degenerate torus is not singular in the v-direction.

public: virtual logical torus::test_point_tol (

SPAposition const&,

// point

double

// tolerance

= 0,

SPApar_pos const&

// not used

= * (SPApar_pos* ) NULL_REF,

SPApar_pos&

// not used

= * (SPApar_pos* ) NULL_REF

) const;

Determines whether a point lies on the surface to the given tolerance. The two SPApar_pos arguments are not used in the torus implementations of this function.

public: virtual int torus::type () const;

Returns the type of torus.

public: virtual char const*

torus::type_name () const;

Returns the string "torus".

public: virtual logical torus::undef () const;

Determines whether the torus is properly defined.

public: virtual curve* torus::u_param_line (

double

// constant v parameter

) const;

Constructs a parameter line on the surface. A u-parameter line runs in the direction of increasing u-parameter, at constant v. The parameterization in the nonconstant direction matches that of the surface, and it has the range obtained by the use of param_range_u. The new curve is constructed in free storage, so it is the responsibility of the caller to ensure that it is correctly deleted.

public: logical torus::vortex () const;

Returns TRUE if the torus is a vortex shape. This is true if the absolute value of the difference between the major radius of the torus and the absolute value of the minor radius is less than SPAresabs:

|(major_radius - |minor_radius|)| < SPAresabs

public: virtual curve* torus::v_param_line (

double

// constant u parameter

) const;

Constructs a parameter line on the surface. A v-parameter line runs in the direction of increasing v-parameter, at constant u. The parameterization in the nonconstant direction matches that of the surface, and it has the range obtained by the use of param_range_v. The new curve is constructed in free storage, so it is the responsibility of the caller to ensure that it is correctly deleted.

Internal Use:

full_size

Related Fncs:

restore_cone

friend: torus operator* (

torus const&,

// torus

SPAtransf const&

// transformation

);

Transforms a tensor by a general transformation. This method does a matrix multiplication for the rotation part, and then multiplies it by the scaling factor twice any translation part is ignored.

PDF/KERN/38CLT.PDF
HTM/DATA/KERN/KERN/38CLT/0009.HTM