HM_ExtAPI::CreateGeomFaceTrimmed()
Creates trimmed face in the HyperMesh database.
Syntax
bool CreateGeomFaceTrimmed(
HM_EntityGeomFace& new_face,
const HM_EntityGeometrySurface& base_surf,
int number_of_loops,
const int* loop_coedge_counts,
const HM_EntityGeometryCurve* loop_coedge_curves,
const double* curve_start_params,
const double* curve_end_params,
const bool* coedge_curve_dirs,
int option_flags,
HM_EntityComponent comp
);Type
HyperMesh Ext API Function
Description
Created face must have at least one loop that defines its external boundary in parametric space.
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().
Loop direction is defined in such a way that the loop is counterclockwise with respect to an outward pointing face normal. In other words, in a view where the face normal is directed towards the observer, the loop would have the face area on the left side.
In parametric space, the direction of the loops depends on geometric normal use defined by the flag HM_ExtAPI::CF_SURF_REV in the parameter option_flags. If the flag is not set, then the face normal is oriented in the same direction as the geometric surface normal and the "face on the left" rule applies in parametric space as well. The external loop of the face is oriented counterclockwise while all internal loops are oriented clockwise.
If the HM_ExtAPI::CF_SURF_REV flag is set, then the face normal is reversed with respect to the geometric surface normal and all loops have the face on their right in parametric space. In this case, the external loop of the face is oriented clockwise while all internal loops are oriented counterclockwise.
Direction of the geometric normal of the surface is defined by the surface parameterization function S(U, V) as the direction of the cross-product of parametric derivatives:
N = ∂S(U, V)/∂U X ∂S(U, V)/∂V
The parameter loop_coedge_curves points to the array of curve handles corresponding to curves used to construct loop co-edges. Each curve is interpreted either as parametric curve, or, if the flag HM_ExtAPI::CF_EDGES_3D is set in the option_flags parameter, as a 3D curve that is assumed to be reasonably close to the surface geometry. If 2D parametric curves are used, then the x and y coordinates of each curve point is used as, respectively, U and V coordinates in the parametric surface space. The z coordinate of the curve points is ignored.
The array contains curves for all loops. The order of the curves for each loop is defined by the direction of the loop. The curves for the co-edges of the external loop must appear first in the array.
If direction of the loop is not defined, the flag HM_ExtAPI::CF_CHECK_LOOP_DIR should be set in the option_flags parameter to make sure consistent loop orientation is determined internally.
Both curve_start_params and curve_end_params must be NULL or not NULL at the same time. If both parameters are NULL, the default parametric range of each curve is used to create the co-edge. Use the function HM_ExtAPI::GeomCurveGetParameterBounds to obtain the curve parametric range.
Curve directions in the loop can be defined by using the coedge_curve_dirs parameter. If this parameter is NULL, then all curves are assumed to be oriented in the loop direction. If the curve's orientation is not known, the flag HM_ExtAPI::CF_CHECK_EDGE_DIR should be set to make sure that the correct curve orientation is determined internally.
Requires including hm_extapi.h.
Inputs
- new_face
- [out] - Handle to a new face object.
- base_surf
- [in] - Handle to surface objects that was returned by previous calls to API functions. This parameter can also be NULL, in which case the function attempts to calculate the surface that fits the geometry of the input loop curves.
- number_of_loops
- [in] - Number of face loops.
- loop_coedge_counts
- [in] - Pointer to the array that contains the number of co-edges in each loop. The number of entries in the array must equal the number_of_loops.
- loop_coedge_curves
- [in] - Pointer to the array of the curve handles returned by previous calls to API functions. Each handle represents the curve geometry for each of the corresponding co-edges defining face loops. The number of entries in the array must be equal to the sum of the loop co-edge counts given by the array loop_coedge_counts. The curves are defined in either 2D parametric space of the surface base_surf or, if the flag HM_ExtAPI::CF_EDGES_3D is set in option_flags, in 3D space.
- curve_start_params
- [in] - If not NULL, then points to the array of values that define the lower parametric bound of the corresponding curve from the array loop_coedge_curves used to create the co-edge. The number of entries in the array must equal the number of entries in the array loop_coedge_curves.
- curve_end_params
- [in] - If not NULL, then points to the array of values that define the upper parametric bound of the corresponding curve from the array loop_coedge_curves used to create the co-edge. The number of entries in the array must equal the number of entries in the array loop_coedge_curves.
- coedge_curve_dirs
- [in] - If not NULL, then points to the array of flags that define the direction of the curves given by loop_coedge_curves with respect to the loop direction. The value of true indicates that the direction of the curve within the co-edge is the same as the loop direction. The value of false indicates that the direction of the curve is opposite to the direction of the loop. If the parameter is NULL, then the value of true is assumed for all curves.
- option_flags
- [in] – bitwise combination of additional option flags. The following flags are defined in the hm_extapi.h header file:
- comp
- [in] - If not NULL, then the component where the face is created. If NULL, the line is created in the current component.
Errors
If some inconsistencies are found in the input parameters or geometries, the function may fail and return false.