 |
PK_BODY_create_topology_2 |
|
PK_ERROR_code_t PK_BODY_create_topology_2
(
--- received arguments ---
int n_topols, --- number of topols
const PK_CLASS_t classes[], --- class of each topol
int n_relations, --- number of relations
const int parents[], --- parents
const int children[], --- children
const PK_TOPOL_sense_t senses[], --- sense in which child
--- is used by parent
const PK_BODY_create_topology_2_o_t *options, --- options
--- returned arguments ---
PK_BODY_create_topology_2_r_t *const creation --- result
)
This function creates the topology of a general body.
Specific Errors:
PK_ERROR_bad_class (MILD) bad class in 'classes' array
PK_ERROR_bad_value (MILD) a value in 'parents' or 'children'
array is not a valid index to 'classes'
array
PK_ERROR_empty_body (MILD) no PK_CLASS_body entry in classes
array
PK_ERROR_fragment (MILD) there is a value in the 'classes'
array, other than the body, that has no
parent
The array 'classes' specifies the class of each topological entity.
The allowed values are:
PK_CLASS_body
PK_CLASS_region
PK_CLASS_shell
PK_CLASS_face
PK_CLASS_loop
PK_CLASS_fin
PK_CLASS_edge
PK_CLASS_vertex
Each topological entity is referred to by its index in this array.
All of the body's regions, shells, faces, loops, edges and vertices must be
present in the input. It is optional whether fins are present. The
existence of a fin may be inferred from an edge being a child of a loop.
The arrays 'parents', 'children' and 'senses' are all the same length which
is 'n_relations'.
`parents[i]', `children[i]' and `senses[i]' define one relation between
two topological entities. The values put into 'parents' and 'children'
are indices of the 'classes' array.
The following rules apply to the order of the relations:
- the child relations to a common parent need not be contiguous.
- edge or fin children of a loop must appear in order around the loop.
- vertex children of an edge must appear in the order of the direction of
the edge.
- loop or fin children of a non-manifold edge must appear in order around the
edge
- the first relation given between the body and a region must refer to
the body's outer region
'senses' indicate the manner in which a child is used by its parent. In
relations in which sense matters it should be set to one of:
PK_TOPOL_sense_positive_c or
PK_TOPOL_sense_negative_c.
In relations where sense does not matter it should be set to:
PK_TOPOL_sense_none_c.
The relations in which sense matters are:
- region as child of body:
PK_TOPOL_sense_positive_c means region is solid and
PK_TOPOL_sense_negative_c means region is void
- face as child of shell:
PK_TOPOL_sense_positive_c means the face normal points to the interior of
the shell and
PK_TOPOL_sense_negative_c means the face normal points away from the
interior of the shell
As a special case, if a face is child of a shell twice, with each sense
then this may be expressed in a single relation with the sense set to
PK_TOPOL_sense_none_c
- an edge as a child of a fin or loop:
PK_TOPOL_sense_positive_c means the edge is in the same direction as the
fin or loop
PK_TOPOL_sense_negative_c means the edge is in the opposite direction to
the fin or loop
- a fin or loop as a child of an edge:
PK_TOPOL_sense_positive_c means the edge is in the same direction as the
fin or loop
PK_TOPOL_sense_negative_c means the edge is in the opposite direction to
the fin or loop
The permitted classes and numbers of children and parents are as follows:
--------------------------------------------------------------------
Entity Children No. of children Parents No. of parents
--------------------------------------------------------------------
Body Regions >=1 - -
Region Shells >=1 Body 1
Shell Faces >=1 Region 1
Edges >=1
Vertex 1
Face Loops >=1 Shell 2
Loop Edges >=1 Face,Edge >=1
Fins >=1
Vertex 1
Fin Edge 1 Loop,Edge <=2
Edge Vertices <=2 Loop,Fin,Shell 1
Loop >=1
Fin >=1
Vertex - 0 Edge,Loop,Shell >=1
--------------------------------------------------------------------
NB: - Each face must be used twice as a child, once with each sense (this
may be in the same shell).
- A loop must have either a number of edges (with senses) as children, or
a number of fins as children, or a single vertex; it cannot have any
mixture of edges, fins and vertices, or more than one vertex.
- a shell may contain a mixture of faces and edges (an edge which is the
child of a shell is a wireframe edge), but if the shell contains a vertex
then it must be a single vertex and the shell may not have any faces or
edges
- A vertex must have a number of edges as parents, or a number of loops
or a single shell.
The application may indicate the expected body type in the options structure.
If the given topology is the topology of a body of that type, then the returned
body will be of that type, otherwise the returned body will be of type
PK_BODY_type_general_c. If the expected body type is set to
PK_BODY_type_unspecified_c then, if possible, PK_BODY_create_topology_2 will
return a manifold body of the lowest dimension. If this is not possible the
returned body will be of type PK_BODY_type_general_c.
Success of the function is indicated by there being no PK error returned
and by the return structure 'creation' holding:
- the created body in 'body'
- the entities corresponding to the entries in the 'classes' array are
returned in the 'topols' array.
- the structure 'create_fault' will hold the token PK_BODY_state_ok_c.
- if an expected body type had been specified but a body of this type could
not be created the structure 'create_fault' will hold the token
PK_BODY_state_ok_but_alt_type_c to indicate this.
If the creation is unsuccessful but no PK error is returned then the following
is true regarding the return structure 'creation':
- no body is returned in 'body'.
- 'topols' is empty.
- the fault structure 'create_fault' is filled in. For each detected fault
the return structure holds one PK_check_state_t fault token and, if
possible, the indices (of the 'classes' array) of the offending
topologies. If the body that PK_BODY_create_topology_2 attempted to
construct had more than than one fault then the function does not
guarantee to return all the faults.