Insert¶

Block reference (DXF Reference) with maybe attached attributes (Attrib).

Subclass of	`ezdxf.entities.DXFGraphic`
DXF type	`'INSERT'`
Factory function	`ezdxf.layouts.BaseLayout.add_blockref()`
Inherited DXF attributes	Common graphical DXF attributes

See also

Tutorial for Blocks

Warning

Do not instantiate entity classes by yourself - always use the provided factory functions!

TODO: influence of layer, linetype, color DXF attributes to block entities

class ezdxf.entities.Insert¶

dxf.name¶: BLOCK name (str)

dxf.insert¶: Insertion location of the BLOCK base point as (2D/3D Point in OCS)

dxf.xscale¶: Scale factor for x direction (float)

dxf.yscale¶

Scale factor for y direction (float)

Not all CAD applications support non-uniform scaling (e.g. LibreCAD).

dxf.zscale¶

Scale factor for z direction (float)

Not all CAD applications support non-uniform scaling (e.g. LibreCAD).

dxf.rotation¶: Rotation angle in degrees (float)

dxf.row_count¶: Count of repeated insertions in row direction (int)

dxf.row_spacing¶: Distance between two insert points in row direction (float)

dxf.column_count¶: Count of repeated insertions in column direction (int)

dxf.column_spacing¶: Distance between two insert points in column direction (float)

attribs¶: A list of all attached Attrib entities.

has_scaling¶: Returns True if any axis scaling is applied.

New in version 0.12.

has_uniform_scaling¶: Returns True if scaling is uniform in x-, y- and z-axis ignoring reflections e.g. (1, 1, -1) is uniform scaling.

New in version 0.12.

set_scale(factor: float)¶: Set uniform scaling.

New in version 0.12.

block() → Optional[BlockLayout]¶: Returns associated BlockLayout.

New in version 0.12.

place(insert: Vertex = None, scale: Tuple[float, float, float] = None, rotation: float = None) → Insert¶

Set block reference placing location insert, scaling and rotation attributes. Parameters which are None will not be altered.

Parameters

insert – insert location as (x, y [,z]) tuple
scale – (x-scale, y-scale, z-scale) tuple
rotation – rotation angle in degrees

grid(size: Tuple[int, int] = 1, 1, spacing: Tuple[float, float] = 1, 1) → Insert¶

Place block reference in a grid layout, grid size defines the row- and column count, spacing defines the distance between two block references.

Parameters

size – grid size as (row_count, column_count) tuple
spacing – distance between placing as (row_spacing, column_spacing) tuple

has_attrib(tag: str, search_const: bool = False) → bool¶

Returns True if ATTRIB tag exist, for search_const doc see get_attrib().

Parameters

tag – tag name as string
search_const – search also const ATTDEF entities

get_attrib(tag: str, search_const: bool = False) → Optional[Union[Attrib, AttDef]]¶

Get attached Attrib entity with dxf.tag == tag, returns None if not found. Some applications may not attach constant ATTRIB entities, set search_const to True, to get at least the associated AttDef entity.

Parameters

tag – tag name
search_const – search also const ATTDEF entities

Returns

ATTRIB or ATTDEF object

get_attrib_text(tag: str, default: str = None, search_const: bool = False) → str¶

Get content text of attached Attrib entity with dxf.tag == tag, returns default if not found. Some applications may not attach constant ATTRIB entities, set search_const to True, to get content text of the associated AttDef entity.

Parameters

tag – tag name
default – default value if ATTRIB tag is absent
search_const – search also const ATTDEF entities

add_attrib(tag: str, text: str, insert: Vertex = 0, 0, dxfattribs: dict = None) → Attrib¶

Attach an Attrib entity to the block reference.

Example for appending an attribute to an INSERT entity with none standard alignment:

e.add_attrib('EXAMPLETAG', 'example text').set_pos((3, 7), align='MIDDLE_CENTER')

Parameters

tag – tag name as string
text – content text as string
insert – insert loaction as tuple (x, y[, z]) in WCS
dxfattribs – additional DXF attributes for the ATTRIB entity

add_auto_attribs(values: Dict[str, str]) → ezdxf.entities.insert.Insert¶

Attach for each Attdef entity, defined in the block definition, automatically an Attrib entity to the block reference and set tag/value DXF attributes of the ATTRIB entities by the key/value pairs (both as strings) of the values dict. The ATTRIB entities are placed relative to the insert location of the block reference, which is identical to the block base point.

This method avoids the wrapper block of the add_auto_blockref() method, but the visual results may not match the results of CAD applications, especially for non uniform scaling. If the visual result is very important to you, use the add_auto_blockref() method.

Parameters: values – Attrib tag values as tag/value pairs

delete_attrib(tag: str, ignore=False) → None¶

Delete an attached Attrib entity from INSERT. If ignore is False, an DXFKeyError exception is raised, if ATTRIB tag does not exist.

Parameters

tag – ATTRIB name
ignore – False for raising DXFKeyError if ATTRIB tag does not exist.

Raises

DXFKeyError – if ATTRIB tag does not exist.

delete_all_attribs() → None¶: Delete all Attrib entities attached to the INSERT entity.

reset_transformation() → None¶: Reset block reference parameters location, rotation and extrusion vector.

New in version 0.11.

transform(m: Matrix44) → Insert¶

Transform INSERT entity by transformation matrix m inplace.

Unlike the transformation matrix m, the INSERT entity can not represent a non orthogonal target coordinate system, for this case an InsertTransformationError will be raised.

New in version 0.13.

translate(dx: float, dy: float, dz: float) → Insert¶: Optimized INSERT translation about dx in x-axis, dy in y-axis and dz in z-axis, returns self (floating interface).

New in version 0.13.

virtual_entities(skipped_entity_callback: Callable[[DXFGraphic, str], None] = None) → Iterable[DXFGraphic]¶

Yields “virtual” entities of a block reference. This method is meant to examine the block reference entities at the “exploded” location without really “exploding” the block reference. The skipped_entity_callback() will be called for all entities which are not processed, signature: skipped_entity_callback(entity: DXFEntity, reason: str), entity is the original (untransformed) DXF entity of the block definition, the reason string is an explanation why the entity was skipped.

This entities are not stored in the entity database, have no handle and are not assigned to any layout. It is possible to convert this entities into regular drawing entities by adding the entities to the entities database and a layout of the same DXF document as the block reference:

doc.entitydb.add(entity)
msp = doc.modelspace()
msp.add_entity(entity)

Warning

Non uniform scaling returns incorrect results for text entities (TEXT, MTEXT, ATTRIB) and some other entities like HATCH with arc or ellipse path segments.

Parameters: skipped_entity_callback – called whenever the transformation of an entity is not supported and so was skipped

New in version 0.12: experimental feature

Changed in version 0.13: deprecated non_uniform_scaling argument

explode(target_layout: BaseLayout = None) → EntityQuery¶

Explode block reference entities into target layout, if target layout is None, the target layout is the layout of the block reference.

Transforms the block entities into the required WCS location by applying the block reference attributes insert, extrusion, rotation and the scaling values xscale, yscale and zscale. Multiple inserts by row and column attributes is not supported.

Attached ATTRIB entities are converted to TEXT entities, this is the behavior of the BURST command of the AutoCAD Express Tools.

Returns an EntityQuery container with all “exploded” DXF entities.

Warning

Non uniform scaling lead to incorrect results for text entities (TEXT, MTEXT, ATTRIB) and some other entities like HATCH with arc or ellipse path segments.

Parameters: target_layout – target layout for exploded entities, None for same layout as source entity.

New in version 0.12: experimental feature

Changed in version 0.13: deprecated non_uniform_scaling argument

ucs() → UCS¶: Returns the block reference coordinate system as ezdxf.math.UCS object.