Surface

Tutorial Toolkit Function Descriptions > Geometry > Surface

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">

Surface


asm_db_get_next_patch_label	( domessage, integerlabel, stringlabel )


Description:
Get the next highest patch label from the database.
Input:
LOGICAL	domessage	Tells the routine to issue an error message if an error occurs.
Output:
INTEGER	integerlabel	The next highest curve label.
STRING	stringlabel[]	The next highest curve label.
INTEGER	<Return Value>	Success or an error code.

Example:

Please see asm_db_get_next_patch_label (p. 522) in the MSC Acumen Toolkit - Code Example.


db_count_surface	( count )


Description:
Counts all surfaces in the database.
Input:
none
Output:
INTEGER	count	The integer number of surfaces in the database.
INTEGER	<Return Value>	Integer indicating success or failure of the routine. If the routine failed, this value contains an indication of the reason.

Example:

Please see db_count_surface (p. 537) in the MSC Acumen Toolkit - Code Example.


db_get_max_surface_label	( label )


Description:
Gets the largest surface label from the database.
Input:
none
Output:
INTEGER	label
INTEGER	<Return Value>	Integer indicating success or failure of the routine. If the routine failed, this value contains an indication of the reason.

Example:

Please see db_get_max_surface_label (p. 554) in the MSC Acumen Toolkit - Code Example.


db_get_min_surface_label	( label )


Description:
Gets the smallest surface label from the database.
Input:
none
Output:
INTEGER	label	Highest surface label used.
INTEGER	<Return Value>	Integer indicating success or failure of the routine. If the routine failed, this value contains an indication of the reason.

Example:

Please see db_get_min_surface_label (p. 559) in the MSC Acumen Toolkit - Code Example.


db_get_surface_coo_and_type	( id, coo, type )


Description:
Gets a geometric coo and type from the database given an id.
Input:
INTEGER	id	The unique internal surface id identifying the association of the information to be retrieved from the database.
Output:
INTEGER	coo	The geometric company of origin stored in the database.
INTEGER	type	The geometric type of data stored in the database.
INTEGER	<Return Value>	Integer indicating success or failure of the routine. If the routine failed, this value contains an indication of the reason.

Example:

Please see db_get_surface_coo_and_type (p. 573) in the MSC Acumen Toolkit - Code Example.


db_get_surface_id	( label, id )


Description:
Gets a surface id from the database given a surface label.
Input:
INTEGER	label	The unique external surface id identifying the surface to be retrieved from the database.
Output:
INTEGER	id	The unique internal surface id identifying the surface retrieved from the database.
INTEGER	<Return Value>	Integer indicating success or failure of the routine. If the routine failed, this value contains an indication of the reason.

Example:

Please see db_get_surface_id (p. 574) in the MSC Acumen Toolkit - Code Example.


db_get_surface_label	( id, label )


Description:
Gets a surface label from the database given a surface id.
Input:
INTEGER	id	The unique internal surface id identifying the surface to be retrieved from the database.
Output:
INTEGER	label	The unique external surface id identifying the surface to be retrieved from the database.
INTEGER	<Return Value>	Integer indicating success or failure of the routine. If the routine failed, this value contains an indication of the reason.

Example:

Please see db_get_surface_label (p. 575) in the MSC Acumen Toolkit - Code Example.


sgm_create_surface_composite_c	(output_labels, surface_list, flag, gap_tolerance, delete_cons, implicit_topology, created_labels)


Description:
This function creates composite trimmed surfaces.
Input:
STRING	output_labels[ ]	This value specifies the label of the surface to be created.
STRING	surface_list[ ]	This value specifies the surfaces from which the composite will be created.
INTEGER	flag	Inner Loop Options : 0 for All, 1 for None and 2 for Select Edge.
REAL	gap_tolerance	This value specifies the gap distance for the surface builder.
LOGICAL	delete_cons	This value specifies, when set to TRUE, that the surfaces in the input value surface_list be deleted after the composite trimmed surfaces are created.
LOGICAL	implicit_topology	This value specifies, when set to TRUE, that the edges of the created surfaces are defined by the chain links. When this value is set to FALSE the chain link edges will be combined if there is slope continuity in the 2D segments.
Output:
STRING	created_labels[VIRTUAL]	This value returns the label of the composite surface created.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.

Example:

Please see sgm_create_surface_composite_c (p. 588) in the MSC Acumen Toolkit - Code Example.


sgm_create_surface_comptrim_v1	(output_ids, surface_list, outer_curve_list, inner_curve_list,gap_dist,delete_surface, outer_curve_delete, inner_curve_delete, implicit_topology, created_ids)


Description:
This function constructs a trimmed surface from a parent surface and/or outer and inner boundary curves with an option of how to define the edges of the trimmed surfaces.
Input:
STRING	output_ids[]	This value specifies the surface ID list. If this value is set to an empty string or to “#”, the function will automatically allocate and assign a sequential list of surface IDs.
STRING	surface_list[]	This value specifies the parent surface to trim.
STRING	outer_curve_list[]	This value specifies the outer boundary trim curves.
STRING	inner_curve_list[]	This value specifies the inner boundary trim curves.
REAL	gap_dist	The gap distance tolerance between the surfaces to be trimmed.
LOGICAL	delete_surface	This value is set to TRUE if the parent surface is to be deleted after trimmed surface is created.
LOGICAL	outer_curve_delete	This value is set to TRUE if the outer boundary trim curves are to be deleted after trimmed surface is created.
LOGICAL	inner_curve_delete	This value is set to TRUE if the inner boundary trim curves are to be deleted after trimmed surface is created.
LOGICAL	implicit_topology	This value is set to TRUE if the edges are defined from the chain links, or to FALSE if the edges are to be derived from the slope continuity in the 2D segments.
Output:
STRING	created_ids[VIRTUAL]	This value returns the created ID list.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.

Example:

Please see sgm_create_surface_comptrim_v1 (p. 591) in the MSC Acumen Toolkit - Code Example.


sgm_create_surface_from_elems1	(output_ids, elem_list, preview, node_list, in_options, in_nodes, delete_original, s_option, corner_nodes, deleted_ids, created_ids)


Description:
This function constructs surface from any 2D element.
Input:
INTEGER	output_ids[]	This value specifies the surface ID list. If this value is set to an empty string or to “#”, the function will automatically allocate and assign a sequential list of surface IDs.
STRING	elem_list[]	This value specifies the list of elements.
INTEGER	preview	= 1 will return 4 corner nodes.
STRING	node_list[]	List of nodes that represent vertices.
INTEGER	in_options	Defines which loops to be preserved 0 = All, 1 = None, 3 = Selected Loops
STRING	in_nodes	List of nodes on the loop that need to be preserved.
LOGICAL	delete_original[]	FALSE will delete the original elements.
INTEGER	s_option[]	Value for Smoother options. 0 = Fast 1 = Better Parametrization.
INTEGER	corner_nodes()	Returns the array of corner nodes if preview = 1
STRING	deleted_ids[VIRTUAL]	Deleted items.
Output:
STRING	created_ids[VIRTUAL]	This value returns the created ID list.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.

Example:

Please see sgm_create_surface_from_elems1 (p. 594) in the MSC Acumen Toolkit - Code Example.


sgm_db_get_num_loops_face	( surfaceid, getedges, numloops, numedges, numegploop, status )


Description:
Gets the number of loops for a surface, and the total number of edges and if desired, the number of edges per loop.
Input:
INTEGER	surfaceid	The ID of the surface.
LOGICAL	getedges	TRUE if routine should get number of edges per loop. FALSE if not.
Output:
INTEGER	numloops	The number of loops.
INTEGER	numedges	The total number of edges.
INTEGER	numegploop ( )	The number of edges per loop (dimension is numberLoops).
INTEGER	status	Success or an error code.
Comments:
The usual way to use this routine is: 1. Call it to get the number of loops numberLoops with getEdges == False (0) 2. User allocates array numberEdgesPerLoop as (INT ) MemAlloc ( arg, numberLoops sizeof(INT)). 3. User calls routine again with getEdges == True (1) to get the array of number of edges per loop for all loops (numberEdgesPerLoop).
Error Conditions:
1000025	Error attempting to allocate virtual memory.

Example:

Please see sgm_db_get_num_loops_face (p. 619) in the MSC Acumen Toolkit - Code Example.


sgm_db_get_surface	( surfaceid, blobsize, blob, status )


Description:
Get the geometric definition of a surface from the database.
Input:
INTEGER	surfaceid	The ID of the surface.
INTEGER	blobsize	Size of the blob in words.
REAL	blob ( )	Array to be filled in with Geometric description of a surface as a blob.
Output:
REAL	blob ( )	Geometric description of the surface.
INTEGER	status	0: no error. -1: database error. -2: insufficient array length for the blob.
Error Conditions:
38000001	The allocated space for the blob is too small

Example:

See example for sgm_db_get_curve, 215. See also sgm_db_get_surface (p. 625) in the MSC Acumen Toolkit - Code Example.


sgm_edit_surface_edge_match	(type_option, surface_list_1,surface_list_2, delete_flag, created_ids)


Description:
This function matches the edges for adjacent surfaces which have gaps inbetween. This is particularly relevant when surface models are imported. Such models tend to have gaps which require closing to avoid any errors regarding continuity with adjacent surfaces. This function works with topologically incongruent models and matches topology (edges and vertices).
Input:
INTEGER	type_option[]	The type of edge match to be done. 1 for surface-point 2 for surface-surface.
STRING	surface_list_1[]	The first list of surfaces.
STRING	surface_list_2[]	The second list of surfaces.
LOGICAL	delete_flag	This value is set to TRUE if the original surfaces are to be deleted.
Output:
STRING	created_ids[]	This value returns the created ID list.
INTEGER	<Return_value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.

Example:

Please see sgm_edit_surface_edge_match (p. 638) in the MSC Acumen Toolkit - Code Example.


sgm_edit_surface_sew	(surface_list, created_ids)


Description:
This function sews surfaces which have gaps inbetween. This is relevant when surface models are imported. Such models tend to have gaps which require closing to avoid any errors regarding continuity of the surfaces. This function will sew edges into a common boundary between surfaces. This function was introduced to handle cases and close up gaps not possible with just edge_match.
Input:
STRING	surface_list[]	The list of surfaces to be sewed.
Output:
STRING	created_ids[]	This value returns the created ID list.
INTEGER	<Return_value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.

Example:

Please see sgm_edit_surface_sew (p. 643) in the MSC Acumen Toolkit - Code Example.


sgm_get_surface_area	( surfid, area )


Description:
Gets the area of a surface.
Input:
INTEGER	surfid	The ID of the surface.
Output:
REAL	area	The area of the surface.
INTEGER	<Return Value>	SUCCESS or an error code.

Example:

Please see sgm_get_surface_area (p. 653) in the MSC Acumen Toolkit - Code Example..


sgm_node_on_surface	( geo_tolerance, number_surfaces, surface_list, number_nodes, init_flag, number_nodes_found, node_id_list, node_uv_list )


Description:
This function will get the nodes close to the given surfaces within the geometric tolerance.
Input:
REAL	geo_tolerance	This value specifies the geometric tolerance.
INTEGER	number_surfaces	This value specifies the number of offsets in the input value surface_list
INTEGER	surface_list(number_nodes)	This value specifies a list of surface identifier values.
INTEGER	number_nodes	This value specifies the number of offsets defined for the output values node_id_list and node_uv_list.
INTEGER	init_flag	This value specifies when set to 0 that the initial call to get the number of nodes on the surfaces is being made. This value specifies, when set to 1 that the call to retrieve the list of nodes on the surfaces is being made.
Output:
INTEGER	number_nodes_found (1)	This value returns the number of the nodes found on the list of surfaces.
INTEGER	node_id_list (number_nodes)	This value returns a list of the node identifiers found on the specified surfaces.
REAL	node_uv_list (number_nodes * 2)	This value returns a list of parametric U and V values for the nodes specified by the return value node_id_list. The U and V values are listed in the order of U1,V1,U2,V2,U3,V3,....
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
This is only a partial list of the error values that can be returned by this function.
9999	See the remarks listed below.
1000025	Error attempting to allocate virtual memory.
1000716	Data for surface %I% not found.
1000707	No surfaces were found to exist in the database as defined in the surface list. The surface list input was %A%.
1000025	No Node found !

Remarks:

The number of nodes on a surface which is needed to correctly allocate the space for the return values node_id_list and node_uv_list can be found by calling sgm_node_on_surface() with the input value init_flag set to 0, the input value number_nodes set to 1, and with the output values node_id_list and node_uv_list allocated to a size of 1. The sgm_node_of_surface() function should return with a return value of 9999 and the output value number_nodes_found will be set to the number of nodes found on the list of surfaces.

The complete node list can then be obtained by calling the sgm_node_of_surface() function with the input value init_flag set to 1. Continue calling the sgm_node_of_surface() function until it no longer returns a value of 9999, indicating that all of the node identifiers have been retrieved.

Example:

Please see sgm_node_on_surface (p. 666) in the MSC Acumen Toolkit - Code Example.


sgm_show_surface_normals	( surflist, scaled, numsurf, segid, redflag, vecdens, veclen )


Description:
Routine that calculates and shows the surface normals.
Input:
STRING	surflist[]	The list of surfaces.
LOGICAL	scaled	TRUE if user wants to scale the normals to a percentage of the surface area, FALSE otherwise.
INTEGER	numsurf	The number of surfaces (or segments).
INTEGER	segid	The ID of the segment.
INTEGER	redflag	0 to show vectors on the interior and boundary, 1 to show vectors on the boundary only.
INTEGER	vecdens	The number of vectors in the u and v directions.
REAL	veclen	The length of the vectors if they are not scaled.
Output:
INTEGER	<Return Value>	0 if successful, else returns error code.
Error Conditions:
14000010	In the list being used, the current sublist does not match the sublist filter.
14000015	LpSublistNext: End of current list has been reached.
1000025	Error attempting to allocate virtual memory.
1000707	No surfaces were found to exist in the database as defined in the surface list. The surface list input was %A%.

Example:

Please see sgm_show_surface_normals (p. 670) in the MSC Acumen Toolkit - Code Example.


sgm_surface_evaluate	(surface_data, ui, vi, derivative_use, surface_info, error_code )


Description:
This function evaluates a surface, returning information that defines the characteristics of a surface.
Input:
REAL	surface_data()	This value specifies a surface data table or a blob. See the remarks below for more information.
REAL	ui	This value specifies a parametric coordinate.
REAL	vi	This value specifies a parametric coordinate.
INTEGER	derivative_use	This value specifies the type of information that will be returned by this function. See below for more information.
Output:
REAL	surface_info(21)	This value returns the evaluated surface information. See the remarks below for information on how to interpret the values returned.
INTEGER	error_code	This value returns an error code and will be set to 0 if the surface evaluation was successful and a non zero value to indicate an error.
Error Conditions:
This is only a partial list of the error values that can be returned by this function.
1	A malformed surface data table or blob has been found. This problem is most likely caused by an error in the input value surface_data.
2	This value indicates that the input value drivative_use has been set to request normal information and that the current input values for ui and vi fall on an unresolvable singularity. All of the other return vectors are valid at this point. Only the normal vector is not to be used.

Remarks:

The size of the input value surface_data can be obtained with a call to the function sgm_db_get_blob_size, 187. The surface data table or blob information can then be retrieved with a call to sgm_db_get_surface, 225.

The input value derivative_use specifies the type of information that will be returned. The following table explains the allowed values.


derivative_use value	Information Returned
0	x, y, z
1	x,y,z,nx,ny,nz,xu,yu,zu,xv,yv,zv
2	x,y,z,nx,ny,nz,xu,yu,zu,xv,yv,zv,xuu,yuu,zuu, xvv,yvv,zvv
3	x,y,z,nx,ny,nz,xu,yu,zu,xv,yv,zv,xuu,yuu,zuu, xvv,yvv,zvv,xuv,yuv,zuv

Example:

Please see sgm_surface_evaluate (p. 674) in the MSC Acumen Toolkit - Code Example.