Open topic with navigation

IDLffDXF::GetEntity

Syntax | Return Value | Arguments | Keywords | Examples | Version History

The IDLffDXF::GetEntity function method returns an array of data for the requested entity type.

Syntax

Result = Obj->[IDLffDXF::]GetEntity(Type [, BLOCK=string] [, INDEX=value] [, LAYER=string])

Return Value

Returns one of the named structure formats described in Structure Formats.

Arguments

Type

The integer DXF entity type from which to obtain the geometry information.

Keywords

BLOCK

Set this keyword to a block name specifying the graphic block from which to obtain the entity geometry information. The default is all blocks. Setting this keyword to an empty string '' '' will cause this method to only return entities from the default DXF entity block.

INDEX

Set this keyword to a scalar index or a long array of indices of entities of the given type to return. If not set, this method returns all entities for the given type.

LAYER

Set this keyword to a string value containing the layer name to obtain the entities from. The default is all layers.

Fields Common to All Structures

BLOCK

The name of the block this entity is in (these may be in the default block “”).

COLOR

A color index value into the current object palette with 0=use block color and 256=use layer color.

EXTRUSION

The DXF extrusion vector (if any).

LAYER

The name of the layer this entity is in (the default layer is '0').

LINESTYLE

Defined the same as the user linestyle for IDLgrPolyline::Init.

Note: IDL will always return a solid line regardless of the linestyle in DXF

THICKNESS

In AutoCAD units.

DXF_TYPE

Set to one of the values listed in IDLffDXF::GetContents.

Note: It is the user’s responsibility to free all the pointers returned in these structures when the entity is no longer needed.

Structure Formats

These structure formats are documented in the following sections:

• IDL_DXF_ELLIPSE
• IDL_DXF_POLYGON
• IDL_DXF_POLYLINE
• IDL_DXF_POINT
• IDL_DXF_SPLINE
• IDL_DXF_TEXT
• IDL_DXF_XLINE
• IDL_DXF_INSERT
• IDL_DXF_BLOCK
• IDL_DXF_LAYER

Structure IDL_DXF_ELLIPSE

This object is centered at PT0 and has a radius defined by the vector PT1_OFFSET. This vector determines the length and orientation of the major axis of an ellipse as well.

The MIN_TO_MAJ_RATIO value specifies the length of the minor axis as a fraction of the major axis length. For a circle, this value is 1.0.

The START_ANGLE and END_ANGLE values select the portion of the curve to be drawn. If they are equal, the entire circle or ellipse is drawn.

Structure IDL_DXF_POLYGON

VERTICES is a pointer to an array of dimension [3, n] containing the points for this entity.

CONNECTIVITY is the array used to connect these points into polygons (see the POLYGONS keyword for IDLgrPolygon::Init). If this array is not present, the connectivity is implicit in (U, V) space defined by the values in MESH_DIMS; the vertices represent a quad mesh of dimensions (MESH_DIMS[0], MESH_DIMS[1]).

Note: If a connectivity array is not supplied and the MESH_DIMS are left at 0,0, then IDL will tessellate the vertex list and store the polygon with the resulting connectivity list. If tessellation fails, IDL will throw an error that should be detected and dealt with using the CATCH mechanism. An alternative to this is to pass the polygon to the IDLgrTessellator object, which returns a zero instead of throwing an error if tessellation fails. The results of a successful tessellation can be put into a DXF entity and passed to the IDLffDXF object, which will not attempt to tessellate the polygon as it has already been tessellated.

VERTEX_COLORS points to an array of color index values for each of the vertices. If a quad mesh is being returned, it can be closed in either dimension according to the CLOSED array.

FIT_TYPE, CURVE_FIT, and SPLINE_FIT return the type of curve fit (if any) this polygon assumes.

Structure IDL_DXF_POLYLINE

VERTICES is a pointer to an array of dimension [3, n] containing the points for this entity.

CONNECTIVITY is the array used to connect these points into polylines (see the POLYLINES keyword for IDLgrPolyline::Init). If this array is not present, the connectivity is implicit in (U, V) space defined by the values in MESH_DIMS; the vertices represent a quad mesh of dimensions (MESH_DIMS[0], MESH_DIMS[1]).

VERTEX_COLORS points to an array of color index values for each of the vertices. If a quad mesh is being returned, it can be closed in either dimension according to the CLOSED array.

FIT_TYPE, CURVE_FIT, and SPLINE_FIT return the type of curve fit (if any) this polyline assumes.

Structure IDL_DXF_POINT

PT0 is the location of the point in space.

UCSX_ANGLE is an internal DXF orientation parameter used for symbol plotting.

Structure IDL_DXF_SPLINE

This structure is returned verbatim from the DXF spline structure without interpretation. It is up to the user to interpret these values.

Structure IDL_DXF_TXT

PT0 is the location of the text string.

TEXT_STR is the actual string.

HEIGHT specifies the overall scaling of the glyphs while WIDTH_FACTOR is a correction in the baseline direction (anisotropic scaling). For multi-line text, BOX_WIDTH determines where the line breaks should be placed (0.0 for single line text).

The text baseline is specified by DIRECTION and its rotation about the z-axis is specified by ROT_ANGLE. Justification is specified by JUSTIFICATION and VERTICAL_ALIGN. SHAPE_FILE is the name of the glyph file used to image this string. The shape file is NOT read by IDL.

Structure IDL_DXF_XLINE

PT0 is the start of a ray or a point on a infinite line in space in the case of an XLINE entity.

UNIT_VEC determines the direction of the line in space.

Structure IDL_DXF_INSERT

The insert entity allows for the “instancing” of a block in a grid fashion.

INSTANCE_BLOCK is the name of a block to repeat.

The block is scaled by SCALE and rotated about the Z axis by ROTATION. The grid begins at PT0 and contains the number of rows and columns specified by NUM_ROW_COL (Note: 0 rows or columns will always give a single instance of the block).

The spacing of the grid is specified by DISTANCE_BETWEEN.

Structure IDL_DXF_BLOCK

This entity specifies a BLOCK. Blocks have a location in space (PT0) [objects in the block are interpreted relative to this point], a name, and a COLOR. They are not contained in layers or other blocks, so these fields are not present.

Structure IDL_DXF_LAYER

This entity specifies a LAYER. Layer is a NAME and a COLOR. They are not contained in layers or other blocks, so these fields are not present.

Examples

This example illustrates the difference between the GetEntity and GetContents methods within the IDLffDXF object method. The GetContents method gives a description of the content of the file read, listing the entity types and the number of occurrences. GetEntity accesses the values returned by GetContents and determines how the entities can be logically combined into common structures for drawing efficiency.

PRO view_heart

; Determine path to data file.

heartFile = FILEPATH(’heart.dxf’, $

SUBDIRECTORY = [’examples’, ’data’])

; Initialize DXF data access object.

oHeart = OBJ_NEW(’IDLffDXF’)

; Read data within DXF file into access object.

status = oHeart->Read(heartFile)

; Determine what type of entities (and how many of

; each entity) exist in the file.

heartTypes = oHeart->GetContents(COUNT = heartCounts)

PRINT, ’Entity Types: ’, heartTypes

PRINT, ’Count of Types: ’, heartCounts

; Initialize a model for displaying polygon and polyline

; objects.

oModel = OBJ_NEW(’IDLgrModel’)

; Obtain the tissue data. The tissue is accessed into

; IDL as a single polygon.

tissue = oHeart->GetEntity(heartTypes[1])

HELP, tissue

HELP, tissue, /STRUCTURE

; Initialize color parameter.

tissueColor = [255, 0, 0]

; Initialize polygon data.

vertices = tissue.vertices

connectivity = tissue.connectivity

; Initialize the polygon object.

oTissue = OBJ_NEW(’IDLgrPolygon’, $

*vertices, POLYGONS = *connectivity, $

COLOR = tissueColor)

; Add the polygon to the model.

oModel->Add, oTissue

; Clean-up all the related pointers.

PTR_FREE, tissue.vertices, tissue.connectivity, $

tissue.vertex_colors

PTR_FREE, vertices, connectivity

; Display the polylines and the polygon in the XOBJVIEW

; utility.

XOBJVIEW, oModel, /BLOCK, SCALE = 0.75

; Clean-up the object references.

OBJ_DESTROY, [oHeart, oModel]

END

An XOBJVIEW window with the mesh heart object appears when this program is compiled and run. The following lines are found in the workbench Output Log window.

IDL> view_heart

% Compiled module: VIEW_HEART.

% Compiled module: FILEPATH.

% Loaded DLM: DXF.

Entity Types: 7 10 18 20

Count of Types: 13 1624 1 2

The Entity Types (7, 10, 18, and 20) are the GetContents method return values corresponding to the occurrence of DXF ENTITY types found in the object: POLYLINES, FACE3D, BLOCK, and LAYER, respectively. Note there are a total of 1624 FACE3D entity types, but for efficiency and speed IDL logically combines all of the similar entities into a single structure that can be used in an IDLgrPolygon object. This is illustrated by the output resulting from the first Help command in the program as shown below.

TISSUE STRUCT =->IDL_DXF_POLYGON Array[1]

** Structure IDL_DXF_POLYGON, 13 tags, length=72:

EXTRUSION DOUBLE Array[3]

VERTICES POINTER <PtrHeapVar3>

CONNECTIVITY POINTER <PtrHeapVar4>

VERTEX_COLORS POINTER <PtrHeapVar5>

MESH_DIMS INT Array[2]

CLOSED INT Array[2]

COLOR INT 256

FIT_TYPE INT -1

CURVE_FIT INT 0

SPLINE_FIT INT 0

DXF_TYPE INT 10

BLOCK STRING ’’

LAYER STRING ’0----’

% Compiled module: XOBJVIEW.

% Compiled module: UNIQ.

% Compiled module: IDENTITY.

% Compiled module: XMANAGER.

Note that the tissue is represented as an array of polygons having 1 element. This is evident by the mesh representation of the heart object showing the 1624 individual polygons as a single object.

Version History