VBL_SURF
List of: Classes
Subjects: Blending, SAT Save and Restore
Contents: Kernel

Purpose: Defines the vertex blend surface class.

Derivation: VBL_SURF : spl_sur : subtrans_object : subtype_object : ACIS_OBJECT : -

SAT Identifier: "vertexblendsur"

Filename: kern/kernel/kerngeom/d3_vbl/vbl.hxx

Description: This class defines the vertex blend surface class. It is defined entirely by the n boundaries that make it up.

References: KERN BDY_GEOM

Data: protected VBL_SURF* _self;

Holds a nonconstant pointer to this object. It is so that we can make SVECs on the blend surface by first making a spline on the blend surface, for which we need the nonconstant pointer.

Constructor: public: VBL_SURF::VBL_SURF ();


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






public: VBL_SURF::VBL_SURF (


const VBL_SURF& // vertex blend surface


);


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






public: VBL_SURF::VBL_SURF (


int n // # boundary curves


);


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




Destructor: public: VBL_SURF::~VBL_SURF ();


C++ destructor, deleting a VBL_SURF.



Methods: public: virtual int VBL_SURF::accurate_derivs (


const SPApar_box&
// bounding box



= * (SPApar_box*) NULL_REF


) const;


Returns the number of curve derivatives over the given interval (which defaults to the whole range).






public: virtual void VBL_SURF::append_u (


spl_sur& // spline surface


);


Appends the given surface to the end of this surface in the u-parameter direction. This function is intended to be called after split_u has been called, so that the surfaces are guaranteed to be compatible.






public: virtual void VBL_SURF::append_v (


spl_sur& // spline surface


);


Appends the given surface to the end of this surface in the v-parameter direction. This function is intended to be called after split_v has been called, so that the surfaces are guaranteed to be compatible.






public: logical VBL_SURF::bdy_relax (


const SPAposition&, // position


double&, // double


int& // integer


) const;


Returns the relaxed body.






public: BDY_GEOM& VBL_SURF::boundary (


int i // ith boundary


) const;


Returns the ith boundary in a VBL_SURF.






public: virtual curve* VBL_SURF::boundary_curve (


int i,
// ith boundary


double& start_par,
// start parameter


double& end_par,
// end parameter


SPApar_pos& start_uv
// start uv-parameter



= * (SPApar_pos*) NULL_REF,


SPApar_pos& end_uv
// end uv-parameter



= * (SPApar_pos*) NULL_REF


) const;


Returns the ith boundary as a three-space curve on the heap, its range on the blend surface (which may not be the actual range of the curve), and its uv range on the blend surface.






public: virtual logical


VBL_SURF::boundary_degenerate (


int i // ith boundary


) const;


Returns whether the ith boundary is degenerate.






public: check_status_list* VBL_SURF::check () const;


Performs a quick check of the surface, returning FALSE if we think it is illegal. This may be called as soon as all the boundaries are set. At the moment all we do is a rough check that the normal does not flip obviously anywhere round the boundary. This is sufficient to catch cases of unreasonable boundary data being given.






public: virtual check_status_list* VBL_SURF::check (


const check_fix& input

// flags for



= * (const check_fix*)
// allowed



NULL_REF,

// fixes


check_fix& result

// fixes applied



= * (check_fix*) NULL_REF,


const check_status_list*

// checks to be



= (const check_status_list*) // made,default



NULL_REF

// is none


);


Check for any data errors in the surface, and correct 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 surface on exit.


The default for the set of flags which say which fixes are allowable is none (nothing is 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: subtrans_object* VBL_SURF::copy () const;


Constructs a duplicate of this object in free storage.






public: double VBL_SURF::cos_angle () const;


Returns the cosine angle, which is pi divided by the number of boundaries.






public: virtual void VBL_SURF::debug (


char const*, // leader string


logical, // brief output OK?


FILE* // file pointer


) const;


Writes debug information to the specified output file.






public: virtual spl_sur* VBL_SURF::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.


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 void VBL_SURF::eval (


SPApar_pos const&, // parameter value


SPAposition&, // point on surface


SPAvector* // first derivatives



= NULL,


SPAvector* // second derivatives



= NULL


) const;


Evaluates the vertex blend surface up to two derivatives.






public: virtual int VBL_SURF::evaluate (


const SPApar_pos&,

// parameter


SPAposition&,

// pt on surface


SPAvector** deriv

// array of ptrs






// to arrays of






// vectors



= NULL,


int nd

// # derivatives



= 0,


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 it was able to calculate; this equals to the number requested in all but the most exceptional circumstances. 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 are not 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 VBL_SURF::eval_outdir (


SPApar_pos const&
// position


) const;


Find an outward direction from the surface at a point with given parameter values.






public: int VBL_SURF::get_continuity () const;


Returns the continuity at the surface boundaries.






public: int VBL_SURF::grid () const;


Returns the grid size used for the approximating surface, if there is one.






public: static int VBL_SURF::id ();


Returns the ID for the VBL_SURF list.






public: bs3_surface


VBL_SURF::make_approximating_patch (


int i,
// number of int_fit


int ns,
// number of s tol


int nt,
// number of t tol


double& int_fit
// tolerances for int



= * (double* ) NULL_REF,


double& fit_s
// tolerances for s



= * (double* ) NULL_REF,


double& fit_t
// tolerances for t



= * (double* ) NULL_REF,


int approx_s_fit
// flag for



= 0,
// approximating s


int approx_t_fit
// flag for



= 0
// approximating t


) const;


The bs3_surface inside the patch and on the boundaries is calculated. If the logical argument approx_s_fit is set to TRUE and any of the errors along the s parameter boundary are found to be greater than the requested tolerance, the errors are calculated approximately. Similarly for the logical approx_t_fit. If either of the logical arguments are set to TRUE, the references int_fit, fit_s, and fit_t should be used to pass the requested fit tolerances into the function.






public: bs3_surface* VBL_SURF::make_output_surs (


int& n_sfs, // number of surfaces


double& interior_fit, // interior tolerance


double& boundary_fit, // boundary tolerance


logical approx_error // approximate errors?



= FALSE


) const;


Function to make up several four-sided approximating bs3_surface's to cover the vbl surface. The arguments supplied are an integer, which will be used to return the number of surfaces made, and the requested fit tolerances, for the interior and the boundary of the patches. These references will return the fit tolerances actually obtained. The function returns an array of _n bs3_surface's.






public: bs3_surface VBL_SURF::make_sur (


double, // fit tolerance


int& // grid size



= * (int*) NULL_REF,


int
// test code?



= 0,


double // check fit tolerance?



= -1


);


Makes the approximating bs3_surface to the specified fit tolerance. This method returns NULL if a bs3_surface cannot be constructed. Call this method after setting all the boundaries. Pass the first int only to find out the resulting grid size used; if the value is larger than 1, the value is used as the initial attempt at grid size. The next int is for testing code only and may be removed at any time. The final double is the input member function; it passes the correct fit tolerance so if the desired grid size is also passed, there is no need to check the achieved fit. The default of -1 means that the fit tolerance must be checked.






public: int VBL_SURF::n () const;


Returns the number of boundaries in a VBL_SURF.






public: virtual VBL_OFFSURF* VBL_SURF::offset (


double offset_dist // offset distance


) const;


Make an offset vertex blend on the heap. May also be called on an already offset vertex blend. These two are the only VBL_SURF functions in vbl_off.cxx.






public: logical VBL_SURF::on_surface (


const SPApar_pos& // uv-parameter


) const;


Returns TRUE if the uv-parameter is on the surface; otherwise, it returns FALSE.






public: virtual void VBL_SURF::operator*= (


const SPAtransf& // transformation


);


Transform this blend by the given transformation.






public: virtual VBL_SURF& VBL_SURF::operator= (


const VBL_SURF& // vertex blend surface


);


Implements an assignment operator, which makes a copy of a VBL_SURF.






public: virtual SPApar_pos VBL_SURF::param (


const SPAposition&,
// point


const SPApar_pos&
// parameter guess



= * (SPApar_pos*) NULL_REF


) const;


Returns the parameter values of a point on the vertex blend surface. The parameter is that for the intersection of the approximating surface with the true surface normal at the given point.






public: SPApar_pos VBL_SURF::param_guess (


const SPAposition&,
// guess position


logical&
// position correct?



= * (logical* ) NULL_REF


) const;


Guesses the uv-parameter for position, and optionally whether it thinks that the guess is correct.






public: virtual SPApar_vec VBL_SURF::param_unitvec (


const SPAunit_vector&, // normal to surface


const SPApar_pos& // parameter value


) const;


Finds the change in the surface parameter corresponding to a unit offset in a given direction at a given position on the surface.






public: virtual SPAunit_vector VBL_SURF::point_outdir (


SPAposition const&,
// position on





// surface


SPApar_pos const&
// parameter value



= * (SPApar_pos* ) NULL_REF


) const;


Returns a direction that points outward from the surface. This should be the outward normal if the point is not singular; otherwise, it is an arbitrary outward direction.






public: virtual void VBL_SURF::point_perp (


const SPAposition&, // given point


SPAposition&, // point on surface


SPAunit_vector&, // normal to surface


surf_princurv&, // principle curvature


const SPApar_pos&, // guess parameter value


SPApar_pos&, // actual parameter value


logical // weak flag



= FALSE


) const;


Finds the point on the surface nearest to the given point, iterating from the given parameter values (if supplied). This function returns the found point, the normal to the surface at that point, and the parameter values at the found point.






public: void VBL_SURF::restore_data ();


Restore the data for a VBL_SURF from a save file. This method is never called directly. It is called by a higher hierarchical function if an item in the SAT file is determined to be of this class type. An instance of this class will already have been created through the allocation constructor. This method then populates the class instance with the appropriate data from the SAT file.


read_int Number of boundaries

for ( int i = 0; i < n; i++ )

restore_BDY_GEOM Restore n BDY_GEOM from the SAT file.

read_int Grid

read_real


Fit tolerance






public: virtual void VBL_SURF::save_data () const;


Save the information for the VBL_SURF to a save file .Stores the information from this class to the save file. This method is never called directly. It is called by a higher hierarchical function if an item in the SAT file is determined to be of this class type.






public: void VBL_SURF::set_geometry (


int, // number of boundaries


const curve&, // curve


const SPAunit_vector&, // normal to plane


double, // u-parameter value


double, // v-parameter value


double // fullness



= 0,


logical // marks as cross curve?



= FALSE,


logical // smooth at beginning



= TRUE,


logical // smooth at end?



= TRUE,


const SPAunit_vector& // bulge faceter



= * (SPAunit_vector*) // direction



NULL_REF


);


Sets the boundaries for the geometry as a curve on a plane. If logical (smooth GI interpolation) is TRUE, it indicates that smooth GI interpolation is required across the boundary. Sometimes, it is possible to have one corner, but not the other. If logical (nonsmooth boundaries) is TRUE, the cross-boundary data is not known. If logical (mark as a cross curve) is TRUE, it means that the magic vector is used for shape control. Usually, the function determines the magic vector; but occasionally, it cannot (e.g., the normals at s=0 and s=1 are parallel or if there is no normal information at all); in these cases, the magic vector should be passed if required.






public: void VBL_SURF::set_geometry (


int, // number of boundaries


const curve&, // curve


double, // start parameter


double, // end parameter


double // fullness



= 0,


logical // mark as a cross curve?



= FALSE,


const SPAunit_vector& // bulge faceter



= * (SPAunit_vector*) // direction



NULL_REF


);


Sets the boundaries for the geometry as a curve across which the blend is not smooth.






public: void VBL_SURF::set_geometry (


int, // number of boundaries


const ellipse&, // ellipse


double, // start parameter


double, // end parameter


const pcurve&, // pcurve


double // fullness



= 0,


logical // mark as a cross curve?



= TRUE,


logical // smooth at beginning?



= TRUE,


logical // smooth at end?



= TRUE,


const SPAunit_vector& // bulge faceter



= * (SPAunit_vector*) // direction



NULL_REF


);


Sets the boundaries for the geometry as a circle on the end of a pipe.






public: void VBL_SURF::set_geometry (


int, // number of boundaries


const ellipse&, // ellipse


double, // start parameter


double, // end parameter


const SPAposition&, // point


double // fullness



= 0,


logical // mark as cross curve?



= TRUE,


logical // smooth at beginning?



= TRUE,


logical // smooth at end?



= TRUE,


const SPAunit_vector& // bulge faceter



= * (SPAunit_vector*) // direction



NULL_REF


);


Sets the boundaries for the geometry as a circle on the end of a torus.






public: void VBL_SURF::set_geometry (


int, // number of boundaries


const ellipse&, // ellipse


double, // start parameter


double, // end parameter


const SPAvector&, // first twist vector


const SPAvector&, // second twist vector


double // fullness



= 0,


logical // mark as cross curve?



= TRUE,


logical // smooth at beginning?



= TRUE,


logical // smooth at end?



= TRUE,


const SPAunit_vector& // bulge faceter



= * (SPAunit_vector*) // direction



NULL_REF


);


Sets the boundaries for the geometry as a circle with given twist vectors at the ends of the boundary.






public: void VBL_SURF::set_geometry (


int, // number of boundaries


const ellipse&, // ellipse


double, // start parameter


double, // end parameter


double // fullness



= 0,


logical // mark as cross curve?



= TRUE,


logical // smooth at beginning?



= TRUE,


logical // smooth at end?



= TRUE,


const SPAunit_vector& // bulge faceter



= * (SPAunit_vector*) // direction



NULL_REF


);


Sets the boundaries for the geometry as a circle on the end of a cylinder.






public: void VBL_SURF::set_geometry (


int, // number of boundaries


const pcurve&, // pcurve


logical cross_curve, // cross curve


const curve&, // curve


double // fullness



= 0,


logical // mark as cross curve?



= TRUE,


logical // smooth at beginning?



= TRUE,


const SPAunit_vector& // bulge faceter



= * (SPAunit_vector*) // direction



NULL_REF


);


Sets the boundaries for the geometry as a pcurve.






public: void VBL_SURF::set_geometry (


int, // number of boundaries


const SPAposition&, // position


const SPAunit_vector&, // normal at start


const SPAunit_vector&, // normal at end


double // fullness



= 0,


logical // mark as a cross curve?



= TRUE,


logical // smooth at beginning?



= TRUE,


logical // smooth at end?



= TRUE,


const SPAunit_vector& // bulge faceter



= * (SPAunit_vector*) // direction



NULL_REF


);


Sets the boundaries for the geometry as a degenerate zero-radius cross curve or as a point.






public: virtual void VBL_SURF::split_u (


double, // u-parameter value


spl_sur* [ 2 ] // two pieces


);


Divides a surface into two pieces at the given u-parameter value. If the split is at the end of the parameter range, the spl_sur returns as the appropriate half (in increasing parameter order), and the other is NULL. Otherwise, a new spl_sur is used for one part, and the old one is modified for the other.






public: virtual void VBL_SURF::split_v (


double, // v-parameter value


spl_sur* [ 2 ] // two pieces


);


Divides a surface into two pieces at the given v-parameter value. If the split is at the end of the parameter range, the spl_sur returns as the appropriate half (in increasing parameter order), and the other is NULL. Otherwise, a new spl_sur is used for one part, and the old one is modified for the other.






public: int VBL_SURF::st_evaluate (


int i,

// which patch


SPApar_pos const& st,

// where to






// evaluate


SPApar_pos& uv,

// calculated uv


SPAposition& pos,

// calculated pos


SPAvector** derivs,

// array of deriv


int n_derivs,

// number of






// derivatives


evaluate_surface_quadrant
// quadrant for



quadrant

// mapping



= evaluate_surface_unknown


) const;


Mapping function which, given an stSPApar_pos on the four-sided kite-shaped patch i of the VBL_SURF, calculates and returns the u and v parameter values, and if required, the position, the first partial derivatives with respect to s and t, and the second partial derivative with respect to s and t. The function returns a logical, which denotes the success of the function.






public: double VBL_SURF::st_measure_interior_fit (


bs3_surface bs3_sf,

// surface


int i,

// number


error_type& err_type

// enumeration






// for what to do



= * (error_type*)NULL_REF,


double requested_fit

// tolerance



= 0.0


) const;


Function to find the maximum error on the interior of a four-sided patch of the VBL_SURF and its approximating bs3_surface (parameterized in s and t). If the enumeration err_type is of type exact_error, then the function VBL_SURF_ERROR_FUNC_2V::turning_point is used to find the errors over each of the spans in the interior of the surface.


If err_type is of type approximate_error, then the error over the interior is simply approximated to be the maximum of the errors at the mid-points of the spans. If err_type is of type approx_if_too_big, then the function starts to calculate the errors using the turning_point function. But if the error exceeds the requested tolerance, err_type is changed to approximate_errors, and the errors are approximated from this point onwards.






public: double VBL_SURF::st_measure_side_fit (


bs3_surface bs3_sf, // approaching




// surface


int i, // number of sides


int side, // which side


error_type& err_type // how to handle errors



= * (error_type*) NULL_REF,


double requested_fit // tolerance



= 0.0


) const;


Function to find the maximum error between one side of a four-sided patch of the VBL_SURF and its approximating bs3_surface (parameterized in s and t), along the given side only (0 => t=0, 1 => t=1, 2 => s=0, 3 => s=1).


If the enum err_type is of type exact_error, then the function VBL_SURF_ERROR_FUNCTION::find_maximum will be used to find the maximum errors over each of the spans of the supplied side.


If err_type is of type approximate_error, then the error over the side will simply be approximated to be the maximum of the errors at the mid-points of the spans.


If err_type is of type approx_if_too_big, then the function will start to calculate the errors using the find_maximum function. If the error exceeds the requested tolerance, err_type will be changed to approximate_error, and the errors will be approximated from this point onwards.






public: virtual SPAinterval


VBL_SURF::suggest_offset () const;


Suggests a range of legitimate offset distances.






public: virtual logical VBL_SURF::test_point_tol (


const SPAposition&, // given point


double, // fit tolerance


const SPApar_pos&, // guess parameter


SPApar_pos& // actual parameter


) const;


Tests whether a given point lies on the surface to within a given fit tolerance. The parameter value of the closest point on the surface to the given point is returned.






public: int VBL_SURF::type () const;


Returns the type of VBL_SURF.






public: const char* VBL_SURF::type_name () const;


Returns the string "vertexblendsur".






public: logical VBL_SURF::u_for_v_on_i (


int,
// ith boundary


double,
// v-parameter value


double&,
// length along





// edge in u


double&
// length along





// edge in v



= * (double*) NULL_REF


) const;


Returns the value of u for the given v, on the ith boundary. This method returns TRUE if there is a value v; otherwise, it returns FALSE. If requested, this method returns the value of lambda; i.e., how far along the edge.






public: virtual curve* VBL_SURF::u_param_line (


double, // v value


const spline& // owning surface


) const;


Returns the u-parameter line, given a v value.






public: SPAinterval VBL_SURF::u_range_for_v (


double // v value


) const;


Returns the valid range for u for the given value of v.






public: virtual SPAbox VBL_SURF::vbl_bound () const;


Returns the bound of the variable blend, whether or not there is an approximating surface.






public: SPApar_box VBL_SURF::vbl_param_range () const;


Returns the vertex blend parameter range, whether or not there is an approximating surface.






public: SPAinterval


VBL_SURF::vbl_param_range_u () const;


Returns the variable blend u-parameter range, whether or not there is an approximating surface.






public: SPAinterval


VBL_SURF::vbl_param_range_v () const;


Returns the variable blend v-parameter range, whether or not there is an approximating surface.






public: const SPApar_pos& VBL_SURF::vertex (


int i // ith vertex


) const;


Returns the uv coordinates of ith vertex.






public: logical VBL_SURF::v_for_u_on_i (


int,
// ith boundary


double,
// u-parameter value


double&,
// length along





// edge in u


double&
// length along





// edge in v



= * (double*) NULL_REF


) const;


Returns the value of v for the given u, on the ith boundary. This method returns TRUE if there is a value u; otherwise, it returns FALSE. If requested, this method returns the value of lambda; i.e., how far along the edge.






public: virtual curve* VBL_SURF::v_param_line (


double, // u value


const spline& // owning surface


) const;


Returns the v-parameter line, given a u value.






public: SPAinterval VBL_SURF::v_range_for_u (


double // u value


) const;


Returns the valid range for v for the given value of u.






protected: void VBL_SURF::_copy_vbl (


const VBL_SURF& // vertex blend surface


);


Copies a VBL_SURF. Required for VBL_OFFSURF.






protected: blend_coord_type


VBL_SURF::_eval_no_offset (


SPApar_pos const&, // position parameter


SPAposition&, // position array


SPAvector* // ptrs to vectors



= NULL,


SPAvector* // of size (nd* (nd+3))/2



= NULL


) const;


Returns finite difference evaluations excluding any offset (for VBL_OFFSURFs). VBL_OFFSURFs need to call this.

Internal Use: deep_copy_vbl, _deep_copy_vbl, full_size
PDF/KERN/39CLU.PDF
HTM/DATA/KERN/KERN/39CLU/0009.HTM