Home | Categories | Alphabetical | Classes | All Contents | [ < ] | [ > ]

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 the null 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:

Structure IDL_DXF_ELLIPSE

Field
Data Type
PT0
Double [3]
PT1_OFFSET
Double [3]
MIN_TO_MAJ_RATIO
Double
START_ANGLE
Double
END_ANGLE
Double
EXTRUSION
Double [3]
LINESTYLE
Integer [2]
THICKNESS
Double
COLOR
Integer
DXF_TYPE
Integer
BLOCK
String
LAYER
String

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

Field
Data Type
VERTICES
Pointer (to an array of 3-D points)
CONNECTIVITY
Pointer (to an array of integers)
VERTEX_COLORS
Pointer (to an array of integers)
MESH_DIMS
Integer [2]
CLOSED
Integer [2]
COLOR
Integer
EXTRUSION
Double [3]
FIT_TYPE
Integer
CURVE_FIT
Integer
SPLINE_FIT
Integer
DXF_TYPE
Integer
BLOCK
String
LAYER
String

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]).

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

Field
Data Type
VERTICES
Pointer (to an array of 3-D points)
CONNECTIVITY
Pointer (to an array of integers)
VERTEX_COLORS
Pointer (to an array of integers)
COLOR
Integer
MESH_DIMS
Integer [2]
CLOSED
Integer [2]
THICKNESS
Double
LINESTYLE
Integer [2]
EXTRUSION
Double [3]
FIT_TYPE
String
CURVE_FIT
Integer
SPLINE_FIT
Integer
DXF_TYPE
Integer
BLOCK
String
LAYER
String

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

Field
Data Type
PT0
Double [3]
UCSX_ANGLE
Double
THICKNESS
Double
COLOR
Integer
DXF_TYPE
Integer
BLOCK
String
LAYER
String

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

Field
Data Type
CTR_PTS
Pointer
FIT_PTS
Pointer
KNOTS
Pointer
WEIGHTS
Pointer
COLOR
Integer
DEGREE
Integer
PERIODIC
Integer
RATIONAL
Integer
PLANAR
Integer
LINEAR
Integer
KNOT_TOLERANCE
Double
CTL_TOLERANCE
Double
FIT_TOLERANCE
Double
START_TANGENT
Double [3]
END_TANGENT
Double [3]
THICKNESS
Double
LINESTYLE
Integer [2]
EXTRUSION
Double [3]
DXF_TYPE
Integer
BLOCK
String
LAYER
String

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

Field
Data Type
PT0
Double [3]
TEXT_STR
String
COLOR
Integer
HEIGHT
Double
WIDTH_FACTOR
Double
BOX_WIDTH
Double
DIRECTION
Double [3]
ROT_ANGLE
Double
JUSTIFICATION
Integer (0=left, 1=center, 2=right, 3=aligned, 4=middle, 5=fit)
VERTICAL_ALIGN
Integer (0=baseline, 1=bottom, 2=middle, 3=top)
SHAPE_FILE
String
THICKNESS
Double
EXTRUSION
Double [3]
DXF_TYPE
Integer
BLOCK
String
LAYER
String

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

Field
Data Type
PT0
Double [3]
UNIT_VEC
Double [3]
COLOR
Integer
THICKNESS
Double
LINESTYLE
Integer [2]
EXTRUSION
Double [3]
DXF_TYPE
Integer
BLOCK
String
LAYER
String

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

Field
Data Type
SCALE
Double [3]
PT0
Double [3]
ROTATION
Double
INSTANCE_BLOCK
String
NUM_ROW_COL
Integer [2]
DISTANCE_BETWEEN
Double [2]
DXF_TYPE
Integer
BLOCK
String
COLOR
Integer
LAYER
String

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

Field
Data Type
PT0
Double [3]
COLOR
Integer
NAME
String
DXF_TYPE
Integer

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

Field
Data Type
COLOR
Integer
NAME
String
DXF_TYPE
Integer

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 IDLDE 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

Introduced: 5.2

Home | Categories | Alphabetical | Classes | All Contents | [ < ] | [ > ]