IDLffDXF::GetEntity
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
| 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]).
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
| 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
heartFile = FILEPATH(’heart.dxf’, $
SUBDIRECTORY = [’examples’, ’data’])
oHeart = OBJ_NEW(’IDLffDXF’)
status = oHeart->Read(heartFile)
heartTypes = oHeart->GetContents(COUNT = heartCounts)
PRINT, ’Entity Types: ’, heartTypes
PRINT, ’Count of Types: ’, heartCounts
oModel = OBJ_NEW(’IDLgrModel’)
tissue = oHeart->GetEntity(heartTypes[1])
HELP, tissue
HELP, tissue, /STRUCTURE
tissueColor = [255, 0, 0]
vertices = tissue.vertices
connectivity = tissue.connectivity
oTissue = OBJ_NEW(’IDLgrPolygon’, $
*vertices, POLYGONS = *connectivity, $
COLOR = tissueColor)
oModel->Add, oTissue
PTR_FREE, tissue.vertices, tissue.connectivity, $
tissue.vertex_colors
PTR_FREE, vertices, connectivity
XOBJVIEW, oModel, /BLOCK, SCALE = 0.75
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