curve

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

Purpose:

Provides methods and data common to all curve subclasses.

Derivation:

curve : ACIS_OBJECT : -

Filename:

kern/kernel/kerngeom/curve/curdef.hxx

Description:

The curve class is a base class from which all specific curve geometry classes (straight, ellipse, and intcurve) are derived. It defines a large variety of virtual functions for generic interaction with curves.

Consider each curve in ACIS as a parametric curve that maps an interval of the real line into a 3D vector space (object space). The mapping is continuous and one-to-one, except for closed curves.

Considered as a function of its parameter, a curve is assumed to have a continuous first derivative whose length is bounded above and below by nonzero constants. There is no hard and fast rule about the values of these bounds or about the rate of change of the length of the derivative.

The curve class defines the following virtual functions:

-

Determine the parameter range of the curve.

-

Determine if the curve is periodic.

-

Determine the parameter value on the curve corresponding to a point on the curve.

-

Determine position, direction, and curvature at a point or parameter value on the curve. Split a curve at a parameter value.

-

Determine the type of the curve. Print the curve data to a file.

References:

by KERN

BDY_GEOM_PCURVE, BDY_GEOM_PLANE, ELEM1D, blend_spl_sur, blend_support, bounded_curve, curve_law_data, off_surf_int_cur, offset_int_cur, offset_int_interp, pcur_int_cur, pipe_spl_sur, proj_int_cur, proj_int_interp, rot_spl_sur, stripc, subset_int_cur, sum_spl_sur, surf_surf_int, sweep_spl_sur, taper_spl_sur, tube_spl_sur, var_blend_spl_sur, wire_law_data

BASE

SPAinterval

Data:

protected SPAinterval subset_range;

Any curve may be subsetted to a given parameter range.

Constructor:

public: curve::curve ();

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

Destructor:

public: virtual curve::~curve ();

C++ destructor, deleting a curve. Ensures a derived class destructor is consulted when destroying a curve.

Methods:

public: virtual int curve::accurate_derivs (

SPAinterval const&

// portion of curve

= * (SPAinterval*) NULL_REF

) const;

Returns the number of derivatives found by evaluate accurately and relatively directly, rather than by finite differencing over the given portion of the curve. If there is no limit to the number of accurate derivatives, returns the value ALL_CURVE_DERIVATIVES.

public: virtual const double*

curve::all_discontinuities (

int& n_discont,

// number of

// discontinuities

int order

// order

);

Returns the number and parameter values of discontinuities of the curve, up to the given order (maximum three). The array is read-only.

public: virtual double curve::approx_error () const;

Returns the maximum error between the approximate evaluation of a curve and the true evaluation of the curve.

public: SPAbox curve::bound (

double start,

// start parameter

double end,

// end parameter

SPAtransf const& t

// transformation

= * (SPAtransf* ) NULL_REF

) const;

Retained temporarily for historical reasons.

public: virtual SPAbox curve::bound (

SPAbox const&,

// region of interest

SPAtransf const&

// transformation

= * (SPAtransf* ) NULL_REF

) const = 0;

Returns an object space bounding box surrounding the portion of the curve within the given box. There is no guarantee that the box will be minimal.

public: virtual SPAbox curve::bound (

SPAinterval const&,

// given range

SPAtransf const&

// transformation

= * (SPAtransf* ) NULL_REF

) const = 0;

Returns a box surrounding the portion of the curve between two parameter values. The resulting box is not necessarily the minimal one.

public: virtual SPAbox curve::bound (

SPAposition const&,

// first

SPAposition const&,

// second position

SPAtransf const&

// transformation

= * (SPAtransf* ) NULL_REF

) const = 0;

Finds a box around the curve, or portion thereof, bounded by points on the curve increasing in parameter value. The points lie on the curve as supplied, not as transmitted. The resulting box is not necessarily the minimal one.

public: virtual void curve::change_event ();

Notifies the derived type that the curve has been changed, such as when the subset_range has changed, so that it can update itself. The default version of the function does nothing.

public: virtual check_status_list* curve::check (

const check_fix& input

// set of flags

= * (const check_fix*)

// for fixes

NULL_REF,

// allowed

check_fix& result = * (check_fix*)

NULL_REF,

// fixes applied

const check_status_list*

// checks to be

= (const check_status_list*)

// made, default

NULL_REF

// is none

);

Checks for any data errors in the curve, and corrects the errors if possible. The various arguments provide control over which checks are made, which fixes can be applied and which fixes were actually applied. The function returns a list of errors that remain in the curve on exit.

The default for allowed fixes is none (nothing fixed). If the list of checks to be made is null, then every possible check will be made. Otherwise, the function will only check for things in the list. The return value for the function will then be a subset of this list.

public: virtual logical curve::closed () const = 0;

Indicates whether a curve is closed; i.e.,joins itself (smoothly or not) at the ends of its principal parameter range. This function should always return TRUE if periodic returns TRUE.

public: virtual void curve::closest_point (

SPAposition const& pos,

// position

SPAposition& foot,

// foot position

SPAparameter const& param_guess

// input guess

= * (SPAparameter* )NULL_REF,// value of

// param

SPAparameter& param_actual

// actual value

= * (SPAparameter* )NULL_REF

// for param

) const;

Finds the closest point on the curve (the foot) to the given point, and optionally its parameter value. If an input parameter value is supplied (as the first parameter argument), the foot found is only a local solution nearest to the supplied parameter position. Any of the return value arguments may be a NULL reference, in which case it is simply ignored.

public: curve* curve::copy_curve () const;

Makes a copy of the given curve.

public: virtual void curve::debug (

char const*,

// leader

FILE*

// file pointer

= debug_file_ptr

) const = 0;

Displays a description of the curve.

public: virtual curve* curve::deep_copy (

pointer_map* pm

// list of items within

= NULL

// the entity that are

// already deep copied

) const = 0;

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.

In a deep copy, all the information about the copied item is self-contained in a new memory block. By comparison, a shallow copy stores only the first instance of the item in memory, and increments the reference count for each copy.

The pointer_map keeps a list of all pointers in the original object that have already been deep copied. For example, a deep_copy of a complex model results in self contained data, but identical sub-parts within the model are allowed to share a single set of data.

public: virtual const double*

curve::discontinuities (

int& n_discont,

// number of

// discontinuities

int order

// order of curve

) const;

Returns the number and parameter values of discontinuities of the curve, of the given order (maximum three), in a read-only array.

public: virtual int curve::discontinuous_at (

double t

// parameter value

) const;

Determines whether a particular parameter value is a discontinuity.

public: virtual curve_boundcyl

curve::enclosing_cylinder (

SPAinterval const&

// parameter interval

= * (SPAinterval*) NULL_REF

) const = 0;

Returns a cylinder that encloses the portion of the curve bounded by the given parameter interval.

public: virtual void curve::eval (

double,

// parameter

SPAposition&,

// position

SPAvector&

// first derivative

= * (SPAvector* ) NULL_REF,

SPAvector&

// second derivative

= * (SPAvector* ) NULL_REF,

logical

// repeat

= FALSE,

logical

// approx. return ok

= FALSE

) const;

Evaluate a curve at a given parameter value, giving position and first and second derivatives (all optionally). The first logical argument, if TRUE, is a guarantee from the calling code that the most recent call to any curve or surface member function was in fact to the routine for the same curve as the current call. It allows an implementation to cache useful intermediate results to speed up repeated calculations, but must be used with extreme care.

The second logical argument may be set to TRUE if an approximate return value is acceptable. Here approximate is not well-defined, but may be assumed to be sufficient for visual inspection of the curve.

public: virtual int curve::evaluate (

double,

// parameter

// value

SPAposition&,

// point on curve

// at given

// parameter

SPAvector**

// pointers to

= NULL,

// derivative

// vectors, size

// nd. Any ptrs

// may be NULL,

// ==> the

// corresponding

// derivative

// won't be

// returned.

int

// # derivatives

= 0,

// required (nd)

evaluate_curve_side

// the evaluation

= evaluate_curve_unknown

// location -

// above or below

) const;

Calculates derivatives, of any order up to the number requested, and store them in vectors provided by the user. This function returns the number it was able to calculate; this is equal to the number requested in all but the most exceptional circumstances. A certain number are evaluated directly and (more or less) accurately; higher derivatives are automatically calculated by finite differencing. The accuracy of these decreases with the order of the derivative, as the cost increases.

public: virtual int curve::evaluate_iter (

double,

// parameter

curve_evaldata*,

// supplying

// initial

// values, and

// set to reflect

// the results of

// the evaluation

SPAposition&,

// point on curve

// at given

// parameter

SPAvector**

// pointers to

= NULL,

// derivative

// vectors, size

// nd. Any ptrs

// may be NULL,

// ==> the

// corresponding

// derivative

// won't be

// returned.

int

// # derivatives

= 0,

// required (nd)

evaluate_curve_side

// the evaluation

= evaluate_curve_unknown

// location -

// above or below

) const;

The evaluate_iter function is just like evaluate, but is supplied with a data object which contains results from a previous close evaluation, for use as initial values for any iteration involved. The default implementation simply ignores this value and calls evaluate.

public: virtual SPAvector curve::eval_curvature (

double,

// parameter

logical

// repeat

= FALSE,

logical

// approximate return ok

= FALSE

) const;

Finds the curvature at the given parameter value on the curve. Refer to eval for description of logical arguments.

public: virtual SPAvector curve::eval_deriv (

double,

// parameter

logical

// repeat

= FALSE,

logical

// approximate return ok

= FALSE

) const;

Finds the derivative (direction and magnitude) at the given parameter value on the curve. Refer to eval for description of logical arguments.

public: virtual double curve::eval_deriv_len (

double,

// parameter

logical

// repeat

= FALSE,

logical

// approximate return ok

= FALSE

) const;

Finds the magnitude of the derivative at the given parameter value on the curve. Refer to eval for description of logical arguments.

public: virtual SPAunit_vector curve::eval_direction (

double,

// parameter

logical

// repeat

= FALSE,

logical

// approximate return ok

= FALSE

) const;

Finds the tangent direction at the given parameter value on the curve. This function is not virtual; it always just takes the direction of the derivative. Refer to eval for description of logical arguments.

public: virtual SPAposition curve::eval_position (

double,

// parameter value

logical

// repeat

= FALSE,

logical

// approximate return ok

= FALSE

) const;

Finds the point on a curve corresponding to a given parameter value. Refer to eval for description of logical arguments.

public: virtual curve_extremum* curve::find_extrema (

SPAunit_vector const&

// direction

) const = 0;

Finds the extrema of a curve in a given direction.

protected: virtual int

curve::finite_difference_derivatives (

double,

// parameter

SPAposition&,

// pt of curve at given

// parameter

SPAvector**,

// ptrs to vectors, size

// nd. Any ptrs may be

// NULL ==> corresponding

// derivative won't be

// returned.

int,

// number of derivatives

// required

int,

// number of derivatives

// already evaluated and

// directly evaluable in

// neighborhood of param

// (nfound)

double,

// finite differencing

// step to use

evaluate_curve_side

// evaluation location -

// above, below or don't

// care

) const;

Evaluate higher derivatives than are available accurately in evaluate by finite differencing.

public: virtual const discontinuity_info&

curve::get_disc_info (

) const;

Returns read-only access to a discontinuity_info object, if there is one. The default version of the function returns NULL.

public: virtual int curve::high_curvature (

double k,

// maximum curvature

SPAinterval*& spans

// interval list

);

Finds regions of high curvature of the curve. This method stores an array of intervals in spans argument over which the curvature exceeds k. It returns the number of intervals stored.

public: virtual law* curve::law_form ();

Returns a law pointer that is the same the curve or else a NULL pointer.

public: virtual double curve::length (

double,

// first parameter

double

// second parameter

) const = 0;

Arc length. Returns the algebraic distance along the curve between the given parameters. The sign is positive if the parameter values are given in increasing order and negative if they are in decreasing order.

public: virtual double curve::length_param (

double,

// datum parameter

double

// arc length

) const = 0;

The inverse of the length function. Returns the parameter value of the point on the curve at the given algebraic arc length from that defined by the datum parameter. The result is not defined for a bounded nonperiodic curve if the datum parameter is outside the parameter range, or if the length is outside the range bounded by the values for the ends of the parameter range.

public: void curve::limit (

SPAinterval const&

// given range

);

Subset this curve in place, ensuring canonical results if the underlying curve is bounded or periodic.

public: virtual curve* curve::make_copy () const = 0;

Make a copy of the given curve. This is a pure virtual function to ensure that each derived class defines its own.

public: virtual curve_evaldata*

curve::make_evaldata () const;

Construct a data object to retain evaluation information across calls to evaluate_iter(). This is to allow subsidiary calls within an iterative evaluator to start iteration much closer to the required result than is possible just using the curve information itself. The default returns NULL, indicating that no special information is required or usable.

public: virtual curve& curve::negate () = 0;

Reverse the sense of the curve.

public: logical curve::operator!= (

curve const& rhs

// curve name

) const;

Tests two curve for equality.

public: virtual curve& curve::operator*= (

SPAtransf const&

// transformation

) = 0;

Transforms a curve.

public: virtual logical curve::operator== (

curve const&

// curve

) const;

Tests two curves for equality. This is not guaranteed to state equal for effectively-equal curves, but is guaranteed to state not equal if the curves are not equal. The result can be used for optimization. The default is not equal.

public: virtual double curve::param (

SPAposition const&,

// point

SPAparameter const&

// param guess

= * (SPAparameter* ) NULL_REF

) const = 0;

Finds the parameter value of a given point on the curve.

public: virtual double

curve::param_period () const = 0;

Returns the period of a periodic curve, 0 if the curve is not periodic.

public: virtual SPAinterval curve::param_range (

SPAbox const&

// region of interest

= * (SPAbox* ) NULL_REF

) const = 0;

Returns the principal parameter range of a curve. The definition of a periodic curve is for all parameter values, by reducing the given parameter modulo the period into this principal range. For an open unbounded curve, the principal range is conventionally the empty interval. For bounded open or nonperiodic curves the curve evaluation functions are defined only for parameter values in this range. If a region of interest is provided, a valid range is always returned, even for an unbounded curve, representing a portion of the curve that is guaranteed to include all segments that lie within the region of interest.

public: virtual pcurve* curve::pcur (

int

// integer denoting the

// parameter curve

) const;

Returns nth parametric curve. If this curve is defined with respect to n or more surfaces and the nth is parametric, NULL if not. If the argument is negative, then returns the pcurve corresponding to the absolute value of the argument, but reversed in sense.

public: virtual logical curve::pcur_present (

int

// integer denoting the

// parameter curve

) const;

Determines if the nth parameter-space curve is defined.

public: virtual logical curve::periodic () const = 0;

Indicates if a curve is periodic; i.e., joins itself smoothly at the ends of its principal parameter range, so that edges span the seam.

public: virtual SPAvector curve::point_curvature (

SPAposition const&,

// point

SPAparameter const&

// param guess

= * (SPAparameter* ) NULL_REF

) const = 0;

Finds the curvature of the curve at given point.

public: virtual SPAunit_vector curve::point_direction (

SPAposition const&,

// point

SPAparameter const&

// param guess

= * (SPAparameter* ) NULL_REF

) const = 0;

Finds tangent direction of curve at given point.

public: virtual void curve::point_perp (

SPAposition const&,

// point

SPAposition&,

// foot

SPAunit_vector&,

// vector

SPAvector&,

// curvature

SPAparameter const&

// param guess

= * (SPAparameter* ) NULL_REF,

SPAparameter&

// actual param

= * (SPAparameter* ) NULL_REF,

logical f_weak

// weak flag

= FALSE

) const = 0;

Finds the foot of the perpendicular from the given point to the curve and tangent to the curve at that point, and its parameter value. If an input parameter value is supplied (as the first parameter argument), the perpendicular found is the one nearest to the supplied parameter position; otherwise, it is the one that the curve is nearest to the given point. Any of the return value arguments may be a NULL reference, in which case it is simply ignored.

public: void curve::point_perp (

SPAposition const& pos,

// point

SPAposition& foot,

// foot

SPAparameter const&

// parameter

param_guess

// param guess

= * (SPAparameter* ) NULL_REF,

SPAparameter& param_actual

// actual param

= * (SPAparameter* ) NULL_REF,

logical f_weak

// weak flag

= FALSE

) const;

Finds the foot of the perpendicular from the given point to the curve and tangent to the curve at that point, and its parameter value. If an input parameter value is supplied (as the first parameter argument), the perpendicular found is the one nearest to the supplied parameter position; otherwise, it is the one that the curve is nearest to the given point. Any of the return value arguments may be a NULL reference, in which case it is simply ignored.

public: void curve::point_perp (

SPAposition const& pos,

// point

SPAposition& foot,

// foot

SPAunit_vector& norm,

// dir. vector

SPAparameter const&

// parameter

param_guess

// param guess

= * (SPAparameter* ) NULL_REF,

SPAparameter& param_actual

// actual param

= * (SPAparameter* ) NULL_REF,

logical f_weak

// weak flag

= FALSE

) const;

Finds the foot of the perpendicular from the given point to the curve and tangent to the curve at that point, and its parameter value. If an input parameter value is supplied (as the first parameter argument), the perpendicular found is the one nearest to the supplied parameter position; otherwise, it is the one that the curve is nearest to the given point. Any of the return value arguments may be a NULL reference, in which case it is simply ignored.

public: void curve::restore_data ();

Restore the data for a curve of known type. The base class version only restores the subset_range member. For convenience it can be called by derived class versions.

The restore operation switches on a table defined by static instances. This invokes a simple friend function which constructs an object of the right derived type. Then it calls the appropriate base class member function to do the actual work. The restore_data function for each class can be called in circumstances when it is known what type of surface is to be expected and a surface of that type is on hand to be filled in.

if (restore_version_number >= BNDCUR_VERSION)

read_interval

Interval for the subset range.

public: virtual void curve::save () const = 0;

Function to save a curve of unknown type, together with its type code for later retrieval.

public: void curve::save_curve () const;

Function to be called to save a curve of unknown type, or NULL. Just checks for NULL, then calls save.

public: void curve::save_data () const;

Function to save a curve of a known type, where the context determines the curve type, so no type code is necessary. The base class version just saves the subset_range member - for convenience it can be called by derived class versions.

public: virtual curve* curve::split (

double,

// parameter

SPAposition const&

// position

= * (SPAposition* ) NULL_REF

);

Splits curve at given parameter value if possible (if the curve is defined or approximated by one or more splines). Constructs a new curve coincident with nd with the same parameterization as the given parameter value and modify the given curve to represent only the remainder of the curve. If the curve cannot be split, returns NULL. The default is to make the curve nonsplittable.

public: curve* curve::subset (

SPAinterval const&

// range

) const;

Constructs a subsetted copy.

public: logical curve::subsetted () const;

Indicates whether the curve has a significant subset range.

public: virtual curve_tancone curve::tangent_cone (

SPAinterval const&,

// given range

logical

// approximation ok

= FALSE,

SPAtransf const&

// transformation

= * (SPAtransf* ) NULL_REF

) const = 0;

Returns a cone bounding the tangent direction of a curve. The curve is deemed to have its apex at the origin and have a given axis direction and (positive) half angle. If the logical argument is TRUE, then a quick approximation may be found. The approximate result may lie wholly within or wholly outside the guaranteed bound (obtained with a FALSE argument), but may not cross from inside to outside. Flags in the returned object indicate whether the cone is in fact the best available and if not whether this result is inside or outside the best cone.

public: logical curve::test_point (

SPAposition const& pos,

// point

SPAparameter const&

// parameter

param_guess

// param guess

= * (SPAparameter* ) NULL_REF,

SPAparameter& param_actual

// actual param

= * (SPAparameter* ) NULL_REF

) const;

Tests point-on-curve, optionally returning the exact parameter value if the point is on the curve.

public: virtual logical curve::test_point_tol (

SPAposition const&,

// position

double

// parameter

= 0,

SPAparameter const&

// first param

= * (SPAparameter* ) NULL_REF,

SPAparameter&

// second param

= * (SPAparameter* ) NULL_REF

) const = 0;

Test point-on-curve, optionally returning the exact parameter value if the point is on the curve

public: virtual int curve::type () const = 0;

Returns an identifier that specifies the curve type.

public: virtual char const*

curve::type_name () const = 0;

Returns the string "curve".

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

Indicates whether the curve is properly defined. A NULL or generic curve is always undefined--other curves depend on their contents.

public: logical curve::undefined () const;

Indicates whether the curve is properly defined. A NULL or generic curve is always undefined--other curves depend on their contents.

public: void curve::unlimit ();

Removes the parameter limits from this curve.

public: curve* curve::unsubset () const;

Constructs a copy of the unbounded curve underlying this one.

Internal Use:

full_size

Related Fncs:

restore_curve

PDF/KERN/29CLC.PDF
HTM/DATA/KERN/KERN/29CLC/0006.HTM