Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  IDL Reference  >  I/O - Other Data Formats  >  IDLffDXF::GetEntity

IDLffDXF::GetEntity

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

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


5.2

Introduced



© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us