[Previous]   [Next]   [Contents]   [Index]   [Books]   

2D Application Interface

Overview

The 2D AI contains all functions to create, modify, delete and inquire 2D model elements and their connections (topology) except dimensions. It contains also access and modify functions for environment variables and modeler parameters.

2D Model

The 2D model consists of groups of 2D elements called Parts which are connected together in a non-cyclic directed graph structure. Each part may contain simple elements such as lines, arcs, circles, fillets, text and/or composite elements such as contours or faces, and also subparts referred to as subparts. Each 2D element is identified by a pointer to its data structure.

Parts

Parts are used to gather 2D elements into a group so that the system can treat them as one single entity. The hierarchical parts model is reflected in a parts graph. The parts graph is set up in a way that there is a Top or Root part which may have references to subparts. The parts graph has to be cycle free which means it's, for example, not allowed that a part has a reference to itself.

If a subpart is referenced more than once (for example, by 2 different parent parts), then it's called a shared part. This actual appearance of the part at a specific position is called an instance of a part. Often the term part is used instead of Instance of a part. In the following sections there are some definitions.

Instance of a Part

An instance of a part consists of one instance definition and one part definition.

An instance definition refers to one part definition by means of a pointer. If a part is shared then more than one instance definition may exist, but they all refer to the same part definition.

Instance Definition

An Instance Definition contains information as to how and where a specific part finally appears on the screen or on the drawing.

An Instance Definition consists of

The Geo Operator is applied to the elements of the Part definition. Each instance contains a Geo Operator for transforming the element members of the part definition to which it points. Geo Operator is also used as a synonym for a transformation matrix. Sometimes there is the term relative transformation matrix which means the Geo Operator applied to the underlaying part definition. The geometric appearance of a part can be modified by modifying the transformation matrix. This is a very effective way of doing any kind of transformation (translate, scale, rotate, mirror) of given parts.

Part Definition

A part definition consists of:

Part Access and Parts Tree Navigation

A part can be accessed by a part name specifier.

The part name within a 2D model does not have to be unique. There are several possibilities to access each part in a parts tree:

Suppose the following parts tree is given:


Figure 8. Example of a Parts Tree

When current part points to part a on level 1, the part c can then be accessed by the name b/c (relative access).

The root for the 2D model part tree is, by default, a part named Top which is identified by (the pointer) me_root_part.

There is also another pointer called me_curr_part pointing to the part in which all interactively created geometric elements are inserted. When new elements are created, they have to be inserted into the current part. The related coordinate system is me_current_2d_cs.

Parts Mapping and Visual Appearance

The transformation matrices of a given parts tree have all to be applied to the given elements of that part and to the subparts in order to get its final appearance on the display or drawing. Given a hierarchical parts tree with, for example, Top-a-b-c (see example above) the following algorithm takes place to get the positional layout of the part: For each branch do (in this case 1):
Starting at the bottom level (c) for every element in the part definition of c, the relative matrix of part instance c has to be applied. This step has to be repeated for each level up to the top level.

On top of this, the user coordinate system transformations have to be applied.

Model Points

All 2D elements reference one or more 2D points, also called model points (abbrev. mp) which indicates special points for an element. Each model point is a member of a 2D part. Before building new 2D elements in a part the model points normally must be created in the same part as the element resides or existing model points in this part can be used to create the elements.

All model points are identified by struct mp* and contain a struct fvec3 to describe the location of the model point in the part's coordinate system.

Related Functions

2D Elements

All 2D elements belong to one of these groups:

The following types of 2D elements are available in the AI:

Related Functions

where xxxx is substituted with, for example, a point or line. See elem2d in ME10 AI Reference.

Geometric Elements

AI provides functions to create and get parameters of 2D geometric elements such as lines and circles.

Topological Elements

Connectivity: Points, Edges, Contours, Faces, Polyelements

The 2D topological model consists of four elements:

The relations between these elements are:

Edges are directed, therefore the relation "edge -> points" can be split into the relations "edge -> begin point" and "edge -> end point".

Points and edges are both geometrical and topological elements. Refer to the section on Geometric Elements for details of the creation of points and edges. Contours and faces contain only topological information.

Related Functions

Contours

Description see "Topological Elements"

Related Functions

Faces

Description see "Topological Elements"

Related Functions


Figure 9. Topological Elements

Annotation Elements/Attributes

Text Elements

A text element consists of one or more lines, so it is more appropriate to speak of a text block with all its lines left bound. It is positioned by an origin model point that can occupy one of the nine possible origin adjustment positions within a text block.

The characters of a text block are defined by a text font. If a certain character was not defined by the font, or if the appropriate text font was not loaded, a default box is drawn for a character.


Figure 10. Parameters for Text

A text block is defined by the following parameters:

slist: the stringlist containing the text strings for each text block line.

origin_mp: the model point defining the text origin position.

fontname: the name of the text font used for character layout definition.

char_height: the height of a character cell defined by the font height parameter and measured perpendicular to the text baseline.

ratio: the width of a character cell defined by the font width parameter relative to the char_height (for example, character width= ratio*char_height) and measured in the direction of the text baseline.

char_slant: the slant angle of the characters within a text line. It has a direct influence on the shape of a character since it tilts the upright direction of the character layout vectors. A positive slant tilts the vectors to the right, a negative one to the left of the perpendicular from the character base line. The user can set the char_slant by the TEXT_SLANT function.

Possible values: -80 deg <= char_slant <= +80 deg

block_slant: the slant of the entire text block. The block_slant moves whole text lines parallel to the text baseline and therefore tilts the text block upright direction. A positive block_slant tilts to the right, a negative one to the left of the perpendicular from the text baseline. The block_slant cannot be set directly by the user. It is changed automatically after affine modifications of a text element.

Possible values:
-80 deg <= block_slant <= +80 deg and
-80 deg <= block_slant + char_slant <= +80 deg

angle: the angle of the text block baseline relative to the horizontal direction.

linedist: the ratio of the distance between two lines in a text block to the char_height, measured perpendicular to the baseline. The real distance is therefore equal to linedist * char_height.

adjust: the position of the text origin model point within the text block. Possible values are 1 to 9:

Table 4. Origin Positions in Text Block
Value Origin Position in Text Block
1 Lower left endpoint of bottom text baseline
2 Middle of bottom text baseline
3 Lower right endpoint of bottom text baseline
4 Left boundary of text block at half of its height
5 Center of text block
6 Right boundary of text block at half of its height
7 Upper left text block corner
8 Upper text block boundary at half of its width
9 Upper right text block corner


Note
Adjust positions 1 to 3 are on the bottom text baseline, which is not necessarily the same as the lower text block boundary. So the origin model point can never be positioned within the character underlength area of the bottom text line.

frame: describes the type of frame around the text block

Possible values: NO_FRAME
  BOX_FRAME
  BALLOON_FRAME

fill: if the text font used is fillable, the text characters will be displayed filled.

keep_orientation:Possible values:

1: The upright direction for the text block and for the character vectors is +90 deg from the text block baseline.
0: The upright direction for the text block and for the character vectors is -90 deg from the text block baseline, for example, the entire text block is mirrored about the text block baseline.

For the strings of a text element, we use the data type:

struct strlist {
  struct strlist *nxt;
  char *str;
}

for a list of strings. Please note that this data type for string lists is different from the data type of AI lists described in another chapter of this document.

Related Functions


Note
For a drawing function for text elements, see the general 2D element drawing functionality

Hatch

Hatch is an attribute of faces. Refer to the section on Topological Elements for details of how to create faces. Hatch is defined by a hatch pattern and three parameters specifying a transformation to adjust the hatch pattern to the face.

These three parameters are :

Hatch Pattern

A hatch pattern consists of a list of sub-patterns, each of which defines a set of parallel hatch lines.

A sub-pattern is defined by:

A pattern/sub-pattern is transformed by the hatch parameters in the following way:

The virtual pattern origin is located at the hatch match point. The sub-pattern angle is added to the hatch angle to give the direction of the lines. The location of the lines is calculated by adding a vector to the hatch match point. This vector is counterclockwise perpendicular to the line direction and has the length of the sub-pattern distance, scaled by the hatch distance.

Related Functions

Element Attributes

All elements have several attributes depending on the element type. Most of the elements have one or more color and linetype attributes.

Color

The color attributes of interactively created elements such as line color or hatch color are affected by the current color settings. These color settings can be changed directly or interactively by the COLOR functions. The COLOR functions specify the color attribute used by all commands belonging to the same group as the currently active command. If the COLOR functions are used inside the LINE command, for example, they specify the color of all newly created geometric elements. If they are used during the DIM_LINE command, all future dimension elements will be affected. BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, and WHITE directly specify one of the eight primary colors. For any non-primary color, use RGB_COLOR and specify the red, green, and blue intensity (range 0..1), or use HSL_COLOR and specify the hue, saturation and luminosity (range 0..1).

If the COLOR functions are used at the Enter command: prompt, they act on normal geometric elements.

The standard colors have the following rgb and hsl values:

  r g b h s l
BLACK 0 0 0 x x 0
RED 1 0 0 0 1 1
GREEN 0 1 0 2/6 1 1
YELLOW 1 1 0 1/6 1 1
BLUE 0 0 1 4/6 1 1
MAGENTA 1 0 1 5/6 1 1
CYAN 0 1 1 3/6 1 1
WHITE 1 1 1 x 0 1

where x = any value

The following groups of elements share the same color attribute:

Within AI, the color for elements can be changed directly without using the current color settings. But it is also possible to use the current group settings and modify them.

Related Functions

where xxx is substituted with text or hatch. See COLOR in ME10 AI Reference.

Linetype

The linetype attributes for elements control the display of straight or curved lines or specify the marker type for point elements. All interactively created 2D elements are affected by the current linetype settings for the different group of elements. These linetype settings can be changed by AI or by the linetype functions. The linetype functions specifies the current linetype for the components that are to be created with the current active command (LINE C_LINE HATCH). For the eight standard patterns the SOLID ...... DOTTED functions can be used.

Within AI the linetype for elements can be changed directly without using the current linetype settings. Here it is also possible to use the current group settings and modify them.

The groups of elements, with the exception of texts, are the same as for the color attributes.

Related Functions

where xxx is substituted with hatch or ptr. See LINETYPE in ME10 AI Reference.

Linewidth

The linewidth attribute for elements controls the display of straight or curved lines. All interactively created 2D elements are affected by the current linewidth setting for geometry elements. The linewidth setting can be changed by AI or by the linewidth command. The linewidth function specifies the current linewidth for the components that are to be created with the current active command (for example, LINE).

Within AI, the linewidth for elements can be changed directly without using the current linewidth setting. Here, it is possible to use the current setting and modify it.

Related Functions

Associated Text for 2D Elements

An arbitrary number of text strings can be attached to any 2D element supported in AI (struct elem2d*). With these strings you can add supplementary information to the elements in memory. This info mechanism is described in more detail from an interactive user's point of view in the Design and Drafting with ME10.

The Associated Texts, also known under the name INFO at interactive ME10 user level will be stored in the Model Interface (MI) file together with the elements to which they are associated.

The Application Interface offers functions to create, access, change or delete the so-called infostrings.

Each infostring attached to one or more elements is kept in a global infolist as well as in the elements' infolists. Even if more than one element refers to the same string this infostring exists only once in the global infolist.

If you change or delete an infostring in the global list this string is changed or deleted automatically for all elements that refer to it.

Most of the AI functions for infostrings operate on a list of infostrings rather than only on a single string. For this purpose, we use the data type

struct strlist {
  struct strlist *nxt;
  char *str;
}

for a list of infostrings. Please note that this data type for stringlists is different from the data type of AI lists described in another chapter of this document.

Besides this global infolist that reflects the already used infos of all existing elements, we keep a current infolist that contains the infostrings to be attached to all newly created elements. This current infolist is independent of the global infolist mentioned above.

Related Functions

Catching

The following description explains the catch concept in ME10: The interactive CATCH function sets the catching mode. This mode controls how input points are interpreted, and allows the user to select a point on the screen without having to put the cursor directly on that point. The system catches to a point only if it lies within the imaginary circle around the edges of the small cursor.

The option ALL is the default. It looks for a vertex, then for an intersection, then for a grid point, then for an element (point anywhere on an element). If it finds a vertex within the catch range, it catches to the closest such vertex. Otherwise, it proceeds with intersections and so on. Vertices are normally endpoints of arcs, splines, or straight elements, though with SHOW VERTEX ON you can see (and catch to) a few additional vertices. Intersections can be between any two elements, or between an element and the ruler. If the system cannot find any of these, it uses the input point as given.

VERTEX, INTERSECTION, GRID, and ELEM allow you to say what kind of catching you want, saving some time over the more general ALL option. CENTER catches to the center of circles, fillets and arcs, and midpoints of lines, in which case it is the element that you pick with the cursor, and not the midpoint. OFF turns off catching completely. These options are normally in force for only one catch, after which the mode switches automatically back to ALL. If you use the PERMANENT option, the selected catch mode stays in effect until you change it again.

OFF allows you to enter all points without any catch correction.

The definition of grid points varies, depending on the catch mode and whether you have a ruler, dot or line grid, or no grid at all. If the catch mode is GRID, the grid points are the ones you would see if you turned on a grid, whether you have actually done so or not. You are reminded of this by the x-y display in the status line, which hops from grid point to grid point as you move the cursor around. If the catch mode is ALL, then the grid points are only the ones you see, that is, if you have a line or dot grid on your screen, those are the grid points. If you have a ruler, the grid points are only the ticks on the axes; if you have neither grid nor ruler, there are no grid points.

The RANGE option allows you to change the catch range. The argument is the size of the new range in pixels. The small cursor changes to match this new range.

Catch works on the basis of the me_model2d_cs coordinate system.

Normally there is no catching if points are read from the keyboard, from macros, or from files. With the option NO_VIEWPORT_RANGE, you can specify the search range in user units to allow the catching of this kind of point entry.

Switching to the large cursor has no effect on the catch range or mode.

The catch mode (but not the range) is irrelevant when the digitized points are used to identify elements, as in DELETE, for example.

All controlling parameters for this catch mechanism are accessible and modifiable by AI.

Related Functions

Coordinate Systems

AI provides a module to handle coordinate systems and the transformations between them. A coordinate system is defined by the coordinate transformation matrix and the reference coordinate system.

On AI level, a coordinate system is a data structure element, which carries the information to perform the coordinate transformations.

Coordinate transformations for the following listed geometric entities are available:

Related Functions

Predefined Coordinate Systems of the 2D Model

Coordinate Systems on the 2D Action Routine Level

There are different types of 2D action routines :

User Coordinate System

As mentioned above there is a predefined coordinate system, called "me_2d_user_cs". All the geometric user input comes in this coordinate system. It can be set on the user interface level. The variable me_angle_per_rad is the ratio of the ME10 user angle units to angle units in radians used on the AI level.

Related Functions

Windows (Viewport/Data-Structure Mapping)

AI provides functions to handle operations with windows.

Intersection Calculations

The Application Interface offers a function that covers the following intersection cases:

line line
line arc
line circle
line bspline
arc arc
arc circle
arc bspline
circle circle
circle bspline
bspline bspline

The function uses vector parameters only and thus is independent of real 2D elements or 2D model points. It can generally be used as a mathematical vector function outside the 2D model.

To make intersection calculations more general and independent of existing 2D model elements, the intersection function does not refer to model elements but uses two elemdefs as input parameters instead.

For each available element type (at present line, arc, circle, and B-spline) a C struct is used as a parameter that describes the geometric element by means of vectors and numbers only, for example, without any references to the model data structure. This element specific struct (that is, linedef2d, circledef2d, arcdef2d, or bsplinedef2d) has to be casted to a struct elem2d when used as an input parameter for the intersection function. So a model independent but general element definition type (that is, elemdef2d) is available without the need to have the referred input elements created and inserted into the model data structure before calling this function.

struct linedef2d  {
  int32         type;
  struct fvec2  begpnt,
                endpnt;
 }

struct circledef2d  {
  int32         type;
  struct fvec2  cenpnt;
  float64       radius;
 }

struct arcdef2d  {
  int32         type;
  struct fvec2  cenpnt;
  float64       radius,
                begang,
                endang;
 }

struct bsplinedef2d {
    int32 type;
    int32 pnt_type;
    float64 *knots;
    int32 closed;
    int32 order;
    struct bspl_pts *pts;
    int32 n_pts;
}

struct elemdef2d  {
  int32  type;
 }

where type may be LINE2D, CIRCLE2D, ARC2D, or BSPLINE2D. For calculations with fillets, you can use struct arcdef2d.

struct bspl_pts is defined as follows:

struct fvec3 pt; the coordinates of the point
int32 conditions; condition indicator
float64 tangent; TANGENT_COND -- the tangent of the curve at position pt measured in radians (0 <=tangent <= 2pi)
float64 curvature; the curvature of the curve at pt measured as the inverse of the radius of a tangential circle, touching the curve at position pt, where the circle has the same curvature as the curve. The curvature-condition is currently not supported and therefore not considered.

The struct bsplinedef2d is described by:

type must be BSPLINE2D
pnt_type CTRL_PTS -- the points stored in pts are treated as the control-polygon for describing the curve
  INTP_PTS -- the points stored in pts are treated as interpolation points that the resulting curve must pass through. In this case, conditions are considered for each of the interpolation points. Which condition to take into consideration is defined by the member 'conditions':
  • NO_COND = do not look at tangent and curvature
  • TANGENT_COND = look at the tangent
  • CURV_COND = look at curvature
  • TANGENT_COND | CURV_COND = look at both
knots an optional knot-vector. An array of floats in parameter space forming an increasing sequence of values. If not specified (knots = NULL) the system calculates a non-uniform knot-vector based on the distances of the points in pts.
closed OPEN, CLOSED, or CLOSED_PERIODIC
order the order of the B-spline
pts a pointer to an array of shape defining points
n_pts the length of the array

For a description of me_create_elem_bspline2d, refer to GEO2D(3X) in ME10 AI Reference.

Here is an example of how to call the intersection function for a line and a circle:

struct linedef2d  ldef;
struct circledef  cdef;

ldef.type     = LINE2D;
ldef.begpnt.x = 0.0;
ldef.begpnt.y = 0.0;
ldef.endpnt.x = 100.0;
ldef.endpnt.y = 100.0;
cdef.type     = CIRCLE2D;

cdef.cenpnt.x = 50.0;
cdef.cenpnt.y = 50.0;
cdef.radius   = 25.0;

me_intsect_2_elemdefs(....,(struct elemdef2d *) &ldef,
                        (struct elemdef2d *) &cdef,....);

Related Functions

Selection of Elements

For the selection of 2D elements a very general set of functions is offered. Element selection is done by scanning all appropriate elements, either starting at the top part and scanning through all parts top down (that is, global selection), or scanning only in the current part. The search only includes elements whose type matches a given set of element types.

Elements can be selected either directly one by one via the functions me_select2d_select_elem and me_select2d_unselect_elem, or by using one of the selection functions that search for all elements matching a specified criterion, for example, for all elements contained in a box.

To access the currently selected elements you can call me_select2d_list_selected_elems to create a list containing pointers to all selected elements as your selection result.

Each time you start a selection, you first have to call the general selection initialization function me_select2d_initialize to reset the whole selection mechanism. This function unselects all existing elements and removes all previous selection results. All subsequently called selection functions have a cumulative effect until the selection is initialized again.

The selection functions provided can select the following selection criteria:

Related Functions

Draw

Filing

The filing-capability provided by the Application Interface is limited to me_fopen and me_fclose, which allow a file to be opened and closed for different purposes similar to the library-call "fopen" and "fclose" in UNIX. The difference between me_fopen and fopen is mainly that the filename in me_fopen may be a fully user-definable name with up to 60 characters even on file systems that do not allow long filenames. To provide this, a catalog is created in each directory where a file is accessed with this function, or if one is already available, this one is updated. In the catalog, the filename given by the user, called logical filename, is stored together with a so-called physical filename. If the logical filename is not valid, that is, it is too long or contains characters not allowed by the operating system, a physical filename is created, otherwise logical and physical filenames are the same. The file is stored under the physical filename. Besides some other system-generated information such as create_date or number_of_accesses, the catalog also contains some application-dependent information such as a short file description or the name and revision of the program that generated the file. This information is stored as item-values in the catalog, when a file is newly created and can be specified as parameters of "me_fopen".

(Details about the items stored in the catalog and the CATALOG function are given in the ME10 manuals.)

Related Function


[Previous]   [Next]   [Contents]   [Index]   [Books]