Using Facet Options
From DocR23
| ||
| ||
This technical article describes how to control the ACIS Faceter using facet_options objects. Refer to Quad Tree Gridding for illustration examples of what these settings mean.
The purpose of the interface is to allow you to choose a workflow (for instance, visualization), make a facet_options object for that workflow, and then choose the settings you need to achieve your desired behavior. If the built-in settings do not satisfy your requirements, you may convert any facet_options object into a facet_options_expert object. The facet_options_expert interface allows you to access all controls of the ACIS Faceter, but is more complex to use than the preset objects.
Contents |
Facet Options Objects
You may instantiate one of three flavors of facet options:
- facet_options_visualization,
- facet_options_precise, or
- facet_options_expert.
facet_options_visualization
The facet_options_visualization options object is designed to give you an accurate view of parts. The two user-specifiable parameters are:
- Face Quality and
- Edge Quality.
facet_options_precise
The facet_options_precise object is designed for analysis-type customers. The principal differences between this options object and the facet_options_visualization options object are:
- The facet_options_precise has more controls. These include:
- Surface Tolerance
- Normal Tolerance
- Grid Aspect Ratio
- Maximum Edge Length
- Minimum Number of U Grid Lines
- Minimum Number of V Grid Lines
- Polygon Type
- The Faceter operates in a mode that places more importance on robustness than speed.
Note that the increased emphasis on robustness and the quality of the output mesh has a performance cost. The repair functionality used with facet_options_precise may make faceting as much as three times slower than visualization mode.
facet_options_expert
A facet_options_visualization or facet_options_precise object can be converted into a facet_options_expert object to allow further customization. This is achieved by calling the get_expert_options member function. For example, if you prefer the visualization defaults, but do not want the Faceter to produce quads with a very high aspect ratio, you could implement the following to limit the grid aspect ratio to 4.
facet_options_visualization my_opts; my_opts.get_expert_options().set_grid_aspect_ratio( 4 ); api_facet_entity( my_entity, &my_opts );
Refer to Examples Using Facet Options for more examples on customizing a particular facet_options object for your application's specific needs.
When using a facet_options_expert object multiple modes are available for specifying the surface tolerance:
- Using refinements,
- Using a specified tolerance value, or
- Using a fraction of the bounding box diagonal.
Only one such mode is available at a time. If you begin with a visualization options object, then call set_surface_tolerance. This changes the tolerance specification mode from a fraction of the bounding box diagonal to a specified tolerance value.
Two modes are available for controlling all properties, except for surface tolerance. These parameters can be read from the REFINEMENT objects attached to topological entities (usually bodies or faces), or read from facet_options settings for the entire model. Both visualization and precise facet_options ignore refinements.
Settings Defined
Normal tolerance Specifies the maximum angle between surface normals at adjacent points on the facet mesh. Surface tolerance Specifies the maximum allowed distance between the surface and the mesh. No point on the surface should be farther than surface tolerance from the mesh. Max grid lines Specifies the maximum number of quad rulings in either direction. Grid Aspect ratio Specifies the maximum ratio of the long side to the short side of a quad in 3D space. The aspect ratio setting does not guarantee that triangles will have a particular aspect ratio; it applies only to the aspect ratio of quads. Minimum U Grid Lines Specifies the minimum number of u grid lines. Minimum V Grid Lines Specifies the minimum number of v grid lines. Polygon Type Specifies the desired polygon shapes for the output mesh. Maximum Edge Length Specifies the maximum length of a facet edge.
Face Quality
The face quality controls how accurately faces are faceted. The settings are as follows:
coarse Specifies normal tolerance is 40 degrees, and surface tolerance is .004 times the diagonal of the body bounding box. medium_coarse Specifies normal tolerance is 30 degrees, and surface tolerance is .002 times the diagonal of the body bounding box. (This is the default setting for facet_options_visualization objects.) medium_fine Specifies normal tolerance is 20 degrees, and surface tolerance is .001 times the diagonal of the body bounding box. fine Specifies normal tolerance is 10 degrees, and surface tolerance is .0005 times the diagonal of the body bounding box.
coarse face quality should be used for viewing larger models with relatively few facets. Each successive increase in face quality level makes faces look smoother. The fine face quality setting is not recommended, except for small models (that is, models with very few faces), because it produces a large number of facets.
Edge Quality
The edge quality setting controls how much better edges are faceted than faces. The settings are as follows:
medium Specifies that both faces and edges are faceted to the same tolerances. better Specifies that the edge tolerances are twice as tight. best Specifies that edge tolerances are four times as tight.
medium edge quality causes the edges to be faceted with the same settings as faces. better quality tightens the edge tolerances by a factor of two relative to the face tolerances. best quality facets the edges to tolerances four times tighter than the faces.
facet_options vs REFINEMENT
Using REFINEMENTS with the Post-R20 Interface
Using REFINEMENT objects with the Faceter is generally more cumbersome, but they offer a high degree of flexibility. For example, specific REFINEMENT objects may be attached to specific faces, or multiple REFINEMENT objects may be attached to a body and be tailored to specific surface types. Because of the complexity of using REFINEMENT objects, Spatial strongly recommends using one of the facet_options objects for most users. If you do use REFINEMENTS, evaluate the settings you need because the Faceter takes considerable effort to meet your specified tolerances; your REFINEMENT settings may indicate something different than what was meant in pre-R21 releases. Refer to Refinements for more information on the complex possibilities for controlling the Faceter with REFINEMENTS.
The example below illustrates how to instruct the Faceter to use REFINEMENTs with the post-R20 interface.
#include "facet_options.hxx" #include "af_api.hxx" facet_options_expert my_opts; my_opts.set_tolerance_specification_mode( af_surface_tolerance_from_refinement ); outcome res = api_facet_entity( my_ent, &my_opts ); process_outcome_problems( res );
Refer to Faceter Problem Reporting for a sample implementation of how to process problems lists returned by the Faceter.
Comparison of Controls
The first two columns of the table indicate the property names (each having a get and set method) used by REFINEMENTS and facet_options_expert. The third column lists the defaults that are used for facet_options_visualization. The forth column lists the defaults that are used for facet_options_expert.
In order to simplify the choices, the interface for facet_options_visualization and facet_options_precise has been limited; the full expert interface is available by using facet_options::get_expert_options.
| REFINEMENT Control | facet_options Control | Visualization Default | Precise Default | Comments | |
|---|---|---|---|---|---|
| surface_tol | surface_tolerance | .002*(body bounding box diagonal length) | unspecified | ||
| normal_tol | normal_tolerance | 30 degrees | unspecified | ||
| max_grid_lines | max_grid_lines | 2000 | 2000 | set high enough so that normal parts are not affected | |
| grid_aspect_ratio | grid_aspect_ratio | 0 (that is, no restriction) | 0 (that is, no restriction) | controls only quads, not triangles | |
| min_u_grid_lines | min_grid_lines_u | 0 | 0 | ||
| min_v_grid_lines | min_grid_lines_v | 0 | 0 | ||
| triang_mode | polygon_type | all triangles | all triangles | ||
| edge_sag_tolerance_as_fraction_of_surface_tolerance | .5 | 1 | sets the ratio between face surface/normal tolerance and edge surface/normal tolerance | ||
| surface_tolerance_as_fraction_of_body_diagonal | .002 | N/A | specifies surface tolerance as a fraction of body bounding box diagonal length | ||
| do_narrow_region_repair | FALSE | TRUE | performance cost, but improves robustness against loops where projected edges are very close together | ||
| check_and_generate_pcurves | FALSE | TRUE | performance cost, but improves robustness against overly loose pcurves. Model is not changed; recalculated pcurves only used for faceting. Refer to api_set_pcurve_tightness . | ||
| grid_mode | use_grid_to_edges | true for splines | true for all surface types | ||
| surf_mode | N/A | N/A | N/A | facet_options settings generally apply to all surface types | |
| adjust_mode | N/A | not used | not used | we discourage use of adjust_mode other than AF_ADJUST_NONE; breaks tolerance contracts and causes other defects | |
| max_edge_length | max_edge_length | 0 (no restriction) | 0 (no restriction) | ||
| postcheck_mode | N/A | N/A | N/A | do not use | |
| silhouette_tol | N/A | N/A | N/A | do not use | |
| pixel_area_tol | N/A | N/A | N/A | do not use | |
| flatness_tol | N/A | N/A | N/A | do not use | |
| dynamic_surtol | N/A | N/A | N/A | internal use only |
Examples Using Facet Options
Visualization with Known Minimum Feature Size
The following code snippet illustrates how to start with the default visualization settings and specify a specific value for the surface tolerance. This approach overrides the default surface tolerance set in the facet_options_visualization object.
double min_feature_size = size_of_smallest_feature; facet_options_visualization fov; double surface_tolerance = .25 * min_feature_size; fov.get_expert_options().set_surface_tolerance( surface_tolerance ); api_facet_entities( owner, &stuff_to_facet, &fo);
This type of customization would be particularly useful, for example, if you are visualizing sheet metal and you know the thickness of the metal. In this case min_feature_size would be at least as small as the thickness of the metal.
Adjusting max_grid_lines
The following code snippet illustrates how to adjust max_grid_lines. You should do this only if you notice parts, for example, helices with many turns, where tolerances were not met because max_grid_lines was exceeded. max_grid_lines is meant to prevent the Faceter from taking too much time or memory, creating too many facets. This can happen when faceting poorly-defined geometry. Generally, the value of max_grid_lines should be 512 or greater.
Note: The default setting for max_grid_lines was changed in ACIS R21, making the need to adjust it less likely.
facet_options_visualization fov; fov.get_expert_options().set_max_grid_lines( 10000 );
