Insert

The INSERT entity (DXF Reference) represents a block reference with optional attached attributes as (Attrib) entities.

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!

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, MINSERT entity if > 1 (int)

dxf.row_spacing

Distance between two insert points (MINSERT) in row direction (float)

dxf.column_count

Count of repeated insertions in column direction, MINSERT entity if > 1 (int)

dxf.column_spacing

Distance between two insert points (MINSERT) in column direction (float)

attribs

A list of all attached Attrib entities.

has_scaling

Returns True if scaling is applied to any axis.

has_uniform_scaling

Returns True if the scale factor is uniform for x-, y- and z-axis, ignoring reflections e.g. (1, 1, -1) is uniform scaling.

mcount

Returns the multi-insert count, MINSERT (multi-insert) processing is required if mcount > 1.

set_scale(factor: float)

Set a uniform scale factor.

block() → BlockLayout | None

Returns the associated BlockLayout.

place(insert: UVec | None = None, scale: tuple[float, float, float] | None = None, rotation: float | None = None) → Insert

Set the location, scaling and rotation attributes. Arguments which are None will be ignored.

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 the INSERT entity has an attached ATTRIB entity with the given tag. Some applications do not attach constant ATTRIB entities, set search_const to True, to check for an associated AttDef entity with constant content.

Parameters:

  • tag – tag name fo the ATTRIB entity

  • search_const – search also const ATTDEF entities

get_attrib(tag: str, search_const: bool = False) → Attrib | AttDef | None

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

Parameters:

  • tag – tag name of the ATTRIB entity

  • search_const – search also const ATTDEF entities

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

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

Parameters:

  • tag – tag name of the ATTRIB entity

  • default – default value if ATTRIB tag is absent

  • search_const – search also const ATTDEF entities

add_attrib(tag: str, text: str, insert: UVec = (0, 0), dxfattribs=None) → Attrib

Attach an Attrib entity to the block reference.

Example for appending an attribute to an INSERT entity:

e.add_attrib('EXAMPLETAG', 'example text').set_placement(
    (3, 7), align=TextEntityAlignment.MIDDLE_CENTER
)
Parameters:

  • tag – tag name of the ATTRIB entity

  • text – content text as string

  • insert – insert location as (x, y[, z]) tuple in OCS

  • dxfattribs – additional DXF attributes for the ATTRIB entity

add_auto_attribs(values: dict[str, str]) → 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. Raises an DXFKeyError exception, if no ATTRIB for the given tag exist if ignore is False.

Parameters:

  • tag – tag name of the ATTRIB entity

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

Raises:

DXFKeyError – no ATTRIB for the given tag exist

delete_all_attribs() → None

Delete all Attrib entities attached to the INSERT entity.

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 and an InsertTransformationError will be raised in that case.

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.

virtual_entities(*, skipped_entity_callback: Callable[[DXFGraphic, str], None] | None = None, redraw_order=False) → Iterator[DXFGraphic]

Yields the transformed referenced block content as virtual entities.

This method is meant to examine the block reference entities at the target location without exploding the block reference. These entities are not stored in the entity database, have no handle and are not assigned to any layout. It is possible to convert these 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 scale factors may return incorrect results for some entities (TEXT, MTEXT, ATTRIB).

This method does not resolve the MINSERT attributes, only the sub-entities of the first INSERT will be returned. To resolve MINSERT entities check if multi insert processing is required, that’s the case if the property Insert.mcount > 1, use the Insert.multi_insert() method to resolve the MINSERT entity into multiple INSERT entities.

This method does not apply the clipping path created by the XCLIP command. The method returns all entities and ignores the clipping path polygon and no entity is clipped.

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.

Parameters:

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

  • redraw_order – yield entities in ascending redraw order if True

multi_insert() → Iterator[Insert]

Yields a virtual INSERT entity for each grid element of a MINSERT entity (multi-insert).

explode(target_layout: BaseLayout | None = None, *, redraw_order=False) → EntityQuery

Explodes the block reference entities into the target layout, if target layout is None, the layout of the block reference will be used. This method destroys the source block reference entity.

Transforms the block entities into the required WCS location by applying the block reference attributes insert, extrusion, rotation and the scale factors xscale, yscale and zscale.

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

Warning

Non-uniform scale factors may lead to incorrect results some entities (TEXT, MTEXT, ATTRIB).

Parameters:

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

  • redraw_order – create entities in ascending redraw order if True

Returns:

EntityQuery container referencing all exploded DXF entities.

ucs()

Returns the block reference coordinate system as ezdxf.math.UCS object.

matrix44() → Matrix44

Returns a transformation matrix to transform the block entities from the block reference coordinate system into the WCS.

reset_transformation() → None

Reset block reference attributes location, rotation angle and the extrusion vector but preserves the scale factors.