# Synopsis

PDX_MSGT iges_MapEntity(long option, int tf_map_cnt, IGES_TF_MAP *tf_map, MDA_PTR db_ptr, EAM_STACK *stack, IGES_DISPATCH *dispatcher, void *data)

# Purpose

Map an entity to another entity type and pass to dispatcher

# Description

This function provides a high-level interface for an application to perform entity type conversion and structure decomposition. The intended use of this function is to map a valid entity which is not supported by the application into one or more entities which are. Depending on the original entity type, the resulting entities may be an exact conversion/mapping (e.g. 112 -> 126) or an approximation (e.g. 112 -> 106:12).

The mapped entities are passed to the application function defined by dispatcher. This function must have the following binding:

.RS 3 PDX_MSGT dispatch (MDA_PTR db_ptr, EAM_STACK *stack, void *data) .RE

iges_MapEntity must be called after initialization with iges_MapInitialize. After initialization, iges_MapEntity can be called from the dispatcher function to recursively convert an entity to lower-order approximations until it has been reduced to an acceptable entity type. Once all need for iges_MapEntity has passed, iges_MapTerminate should be called to clean up. Note that due to the recursive intertwining association of this function and the dispatcher, invocation of iges_MapInitialize and iges_MapTerminate must reside OUTSIDE of the dispatcher.

A new approximation workspace will be created at the initiation of iges_MapInitialize. This workspace will statically remain in memory until all mapping has transpired, and iges_MapTerminate has been called. iges_MapEntity makes considerable use of linear approximation, and for that reason, the workspace it creates must remain current. It is therefore imperative that any application approximation in the interim of entity mapping create and free any necessary workspace dynamically prior to either invoking the next recursion of iges_MapEntity or leaving the dispatcher. Because most entities have a variety of possible mappings, a mapping array may be specified in the tf_map argument which defines how each type of entity is to be mapped. Each entity has a default mapping which is used if the tf_map argument is NULL or if there is no entry for a particular type in tf_map. Most entities also have a set of alternate mappings which can be specified. The tf_map can be easily initialized in the calling function as shown below:

.nf static IGES_TF_MAP tf_map[] = { {IGES_100_0, IGES_126_2}, {IGES_110_0, IGES_126_1}, {IGES_112_0, IGES_126_0}}; static int tf_map_cnt = sizeof(tf_map) / sizeof(tf_map[0]); .fi

As can be seen above, the format of the entries is simply a list of TFs specifying the from and to mappings. Note that the list must be specified in sorted order. In the case above, types 100:0, 110:0, and 112:0, would all be mapped to type 126 entities. It is very important to set the table and any options used in a manner that will not cause infinite recursion. The following table defines the defaults for each entity type and the list of alternative mappings. A type followed by "s" indicates that one or more of that type entity may result. A mapping of "explode" indicates that each referenced entity will be passed to the dispatcher function. A mapping of "ana_form" indicates that the entity will be converted to its corresponding analytical form if possible (e.g. 126:0 or 126:2 -> 100:0). A mapping of "project" indicates that all entities visible in the view will be projected through the view and passed to the dispatcher function as 2D entities. A mapping of "none" indicates that the entity will generate a return of IGES_UNSUPPORTED_MAP. All entities not listed in the table will generate a return of IGES_UNSUPPORTED_MAP. If an error occurs while mapping an entity, IGES_MAPPING_ERR will be returned. .TS center box tab (/); l l l . TF /Default /Alternative mappings

_

100:0 /106:11 /110:0s, 112:0, 126:2 102:0 /explode /106:12, 110:0s, 112:0, 126:0 104:0 /106:11 /110:0s, 112:0, 126:0 104:1 /106:11 /110:0s, 112:0, 126:3 104:2 /106:11 /110:0s, 112:0, 126:5 104:3 /106:11 /110:0s, 112:0, 126:4 106:1-3 /116:0 106:11-13 /110:0s /112:0, 126:0 106:20-21 /110:0s /112:0s, 126:1s 106:31-38 /110:0s /112:0s, 126:1s 106:40 /110:0s /112:0s, 126:1s 106:63 /106:11 /110:0s, 112:0, 126:0 108:1 /106:12s /110:0s, 112:0s, 114:0, 126:0s, 128:1 110:0 /none /112:0, 126:1 112:0 /106:12 /110:0s, 126:0 114:0 /106:12s /110:0s, 112:0s, 126:0s, 128:0 116:0 /explode 118:0 /106:12s /110:0s, 112:0s, 114:0, 126:0s, 128:8 118:1 /106:12s /110:0s, 112:0s, 114:0, 126:0s, 128:8 120:0 /106:12s /110:0s, 112:0s, 114:0, 126:0s, 128:6 122:0 /106:12s /110:0s, 112:0s, 114:0, 126:0s, 128:7 125:0 /explode 125:1 /100:0 /106:11, 110:0s, 112:0, 126:2 125:2 /106:11 /110:0s, 112:0, 126:0 125:3 /100:0s /106:11s, 110:0s, 112:0s, 126:2s 125:4 /100:0s & 110:0s /106:11, 110:0s, 112:0, 126:0 126:0 /ana_form /106:12, 110:0s, 112:0 126:1 /110:0 /106:12, 112:0 126:2 /100:0 /106:12, 110:0s, 112:0 126:3 /104:1 /106:12, 110:0s, 112:0 126:4 /104:3 /106:12, 110:0s, 112:0 126:5 /104:2 /106:12, 110:0s, 112:0 128:0 /ana_form /106:12s, 110:0s, 112:0s, 114:0s, 126:0s 128:1 /108:1 /106:12s, 110:0s, 112:0s, 114:0s, 126:0s 128:2-5 /106:12s /110:0s, 112:0s, 114:0s, 126:0s 128:6 /120:0 /106:12s, 110:0s, 112:0s, 114:0s, 126:0s 128:7 /122:0 /106:12s, 110:0s, 112:0s, 114:0s, 126:0s 128:8 /118:0 /106:12s, 110:0s, 112:0s, 114:0s, 126:0s 128:9 /106:12s /110:0s, 112:0s, 114:0s, 126:0s 130:0 /106:12 /110:0s, 112:0, 126:0 132:0 /explode & 212:0 140:0 /106:12's /110:0s, 112:0s, 114:0, 126:0s, 128:0 141:0 /106:12 /110:0s, 112:0, 126:0, 141:0 (NURBS or parametric) 142:0 /106:12 /110:0s, 112:0, 126:0, 142:0 (NURBS or parametric) 143:0 /106:12's /144:0, 110:0s, 112:0s, 126:0s, 143:0 144:0 /106:12's /110:0s, 112:0s, 126:0s, 144:0 202:0 /explode 204:0 /explode 206:0 /explode 208:0 /explode & 106:11 /110:0s, 112:0, 126:0 210:0 /explode 212:* /106:11s 213:0 /T{ .na 212:0, 100:0s, 106:11s, & 110:0s .ad T}/110:0s, 112:0s, 126:0s 214:* /100:0s & 106:11 /106:11s, 110:0s, 126:0s, 112:0s 216:* /explode 218:* /explode 220:0 /explode 222:* /explode 228:* /explode 230:* /explode & 106:31-38 /110:0s, 112:0s, 126:0s, 106:11s 308 /explode 320 /explode & 212:0 404:0 /explode 408 /explode 410 /project 412 /explode /408:0s 414 /explode /408:0s 420 /explode & 212:0 .TE

The application which calls this function must be careful not to specify a series of maps and options which could result in infinite recursion.

Entity data to be mapped must be valid for successful mapping.

For correspondence between the original and mapped entities, the denum field in each mapped entity will be set equal to the directory entry number of the original entity. The text strings specified in 132s, 320s, and 420s will only be mapped to 212:0s if there is a 312 attached to the entity and the text string is not null.

Mapping a 116 simply explodes any subordinate display symbol geometry. No entities are created to represent its geometric location.

The default targets of the 128 and 126 do not currently work as specified in the table. Routines for mapping 128 and 126 entities to an analytical format is not yet available. The default representation for all forms of the 128 and 126 will therefore be 106:12's until this functionality is ready.

Mapping alternatives for 141 and 142 allow the ability to go to NURBS based 141s and 142s respectively. This capability is invoked by either placing it in the tf_map or by specifying the IGES_NURBS option. Parametric based 141s and 142s will result if the IGES_PARAMETRIC option is specified.

Mapping alternatives for 143 and 144 allow the ability to go to NURBS based 143s and 144s respectively. The surface components will therefore be 128's. This capability is invoked by either placing it in the tf_map or by specifying the IGES_NURBS option. Parametric based 143s and 144s will result if the IGES_PARAMETRIC option is specified. Explosion will always occur when mapping the 208. The alternative target type-forms only apply to the geometry of the flag box.

For the 213 alternative mappings, a 212:0 will always be created in addition to the geometry entity type selected. Some assumptions were made concerning 213 mapping... If intercharacter spacing is set to a nonstandard value (the assumed standard is 1.5 * character height), or if a nonzero character angle exists, a text string will be broken down to single character strings within one 212:0 entity. If a control code within a 213 turns on italics text, each character being mapped to the 212 will be slanted a decremental .320796 radians to its preexisting slant angle. Variable character width is unsupported. All characters are currently mapped as fixed width. Bold text is unsupported. Text and symbol placement is based solely on the text xyloc. Control codes specifying text placement (new lines, tolerances, fractions, etc.) are ignored. Enclosing symbols are built under the assumption that the area to be enclosed is big enough to enclose all characters specified within a enclosing symbol start control code and a enclosing symbol end code. The enclosing symbol will be rotated according to the rotation angle of the enclosed text. Attempting to enclose text with multiple rotation angles is assumed to be invalid. The symbol size is computed with character height and width. Since character height and width are measurements of character size with neglect to its slant or character angle, strings containing slanted or nonzero character angle text may extend beyond the boundary of the enclosing symbol. In addition to the above assumptions, the following bugs are known to exist: Enclosing symbols, underscore, overscore, and enclosing separator geometry is incorrectly positioned when mirrored text is used. The enclosing separator does not yet extend the full height of the enclosing symbol.

For the 214 mappings, circular leaders will be created for the first two leader segments if the 214 was referenced from a 202. If the output preference as set by either target_tf or through the options is for 126:0s, 126:2s will also be created for representation of the circular parts of the leader. 214s which contain filled arrowheads, fill the arrowheads using four iterations.

The section lines generated for a 230 will always be created and passed to the dispatcher function. The boundary curves referenced by the 230 will always be exploded if they are physically subordinate to the 230. For default case, the form of section entity (106:31-38) that is mapped depends on the filltype code in the sectioned area. It is not important to the geometry of the output 106, but just gives a logical association between a certain fill pattern and its form. The table below illustrates which form is used for each fill code.

.TS center box tab (/); c c . 230 Fill code /Form of 106 _ 0 /No section mapped (blank) 1 /106:31 2 /106:32 3 /106:34 4 /106:34 5 /106:36 6 /106:33 7 /106:33 8 /106:33 9 /106:33 10 /106:33 11 /106:33 12 /106:35 13 /106:36 14 /106:36 15 /106:36 16 /106:37 17 /106:38 18 /106:37 19 /106:31 .TE

Mapping a 404 drawing entity will set the global variable, iges__Map410_origin, before dispatching on each subordinate view. This will be used as the origin for each 410 view entity. It will be reset to the default value once 404 processing has completed.

Mappings for types 408 and 420 do not call the dispatcher with their corresponding definition entities, 308 and 320. Instead, they call the definition mapping routines directly.

Mapping a 412 or 414 to 408s may necessitate the creation of a new 308 if the base entity of either the 412 or 414 is not a 308. If this 308 creation is required, the subfigure definition will reference the original base entity of the 412/414 directly. If the 412 or 414 originally has a 308 as the base entity, the new 408 will reference it.

Certain options can be specified to change the default mappings so that the output is oriented to a particular type of entity. The available options are:

.IP IGES_NURBS 18 Changes the default output to be 126s for any non-surface entities which can be mapped as such (i.e. a type of 126 is listed in either the default or alternative mappings). Changes the default output of surfaces to 128s. This option will map 141-144 entities to a NURBS based entity of the same original type. This option does not override mappings specified in tf_map. For example, specifying the IGES_NURBS option will change the default map for a 100 entity to be a 126:2. However, if an entry of "IGES_100_0, IGES_106_11" is specified in tf_map, arcs will be still be mapped as 106:11s.

.IP IGES_PARAMETRIC Changes the default output to be 112s for any non-surface entities or 114s for any surface entities which can be mapped as such. This option will change the output of 141-144 conversion to parametric based 141-144. Like the IGES_NURBS option, this does not override mappings specified in tf_map. .LP

One more option exists if this routine is to be utilized while backpointers are turned on:

.IP IGES_SET_BACK_PTRS If backpointers are to be used in conjunction with the Map Entity routines, this option must be specified. It informs the low level routines used to map the entities that backpointers are being used and therefore adds pointer references when mapping attributes dependent on hierarchy. The affected attributes are font, level, color, view, and matrix. After being mapped and called back into the dispatcher, these pointers are deleted as are the temporary entities. .LP

Attribute information will be handled through the Entity Attribute Manager (EAM). The dispatcher will be able to access this by using eam_GetAppliedAttr to set a pointer to the attribute information resulting when the attributes of the current entity are combined with the attributes of entities above it on the hierarchical ladder. The attributes supported through this functionality are the font, color, level, view, matrix, and blanking. The remaining attributes in the entity directory entry structure are just set to default values. The hierarchy flag, however, is copied from the incoming entity to any entities created for its representation. Properties and associativities are defaulted. The only other field in the DE struct which will carry important information is denum. The denum will be set equal to that of the original entity so that the end user may associate the new entities back to the old.

The following dispatch function shows how this can be used to create a simple IGES file viewer. The draw_arc and draw_line functions displays IGES arcs and lines respectively on the screen.

.nf PDX_MSGT dispatch (MDA_PTR db_ptr, EAM_STACK *stack, void *data) { DDF_TF tf;

mda_ReadTF (db_ptr, &tf);

if (tf == IGES_100_0) { draw_arc (db_ptr, stack); } else if (tf == IGES_110_0) { draw_line (db_ptr, stack); } else { iges_MapEntity (IGES_NOOPT, 0, NULL, db_ptr, stack, dispatch, data) } return (IGES_NOERR); } .fi The dispatcher first checks to see if the passed entity is an arc or line and if so calls the appropriate display function. Otherwise it recursively calls iges_MapEntity to further map the entity. The NULL argument indicates that the default mappings should be used.

The mapping algorithm starts by determining the type of entity specified by db_ptr. If it is a structural entity (identified by a default mapping of explode), each entity referenced from it will be passed to the dispatcher function. If the entity also contains implicit graphics (e.g. a 208), the graphics will be represented as temporary entities that are passed to the dispatcher function. These entities are deleted upon return from the dispatcher function. These transient entities are read-only. They must not be modified and unlocked with the MDA_INVALIDATE or MDA_MODIFIED options. The reason for this is that temporary entities are not unlocked and swapped to disk in order to keep extraneous processing to a minimum. If the entity is not a structural entity, its target type is determined from the tf_map argument or the default mapping table and it is mapped to that type and the resulting entity is passed to the dispatcher function. If the entity type is not supported, an error of IGES_UNSUPPORTED_MAP will be returned.

# Input

## option

### IGES_NURBS

Changes the default output to be 126s for non-surface entities which can be mapped to 126s and 128s for surface entities. The form of the 126 or 128 will be determined by the type of entity being mapped. 141-144 entities are mapped to NURBS based 141-144 entities.

### IGES_PARAMETRIC

Changes the default output to be 112s for non-surface entities which can be mapped to 112s and 114s for surface entities. 141-144 entities are mapped to parametric based 141-144 entites.

### IGES_SET_BACK_PTRS

Backpointers are turned on.

## tf_map_cnt

Number of entries in the tf_map array

## tf_map

TF map

## db_ptr

Entity to be mapped

## stack

Attribute stack to add mapped entry to

## dispatcher

Function to invoke with the resulting mapped entities

## data

User defined data

# Tolerances

Must be set by the application .nf MODEL_LINEAR_APPROX_TOL MODEL_SPACE_PNT_COIN_TOL .fi

# Return

IGES_UNSUPPORTED_MAP

Type of db_ptr can not be mapped .IP IGES_BAD_MAP Map specified type of db_ptr is bad .IP IGES_MAPPING_ERR Error occurred while mapping entity .LP