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.

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) → Union[Attrib, AttDef, None]

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 position as tuple (x, y[, z])

  • dxfattribs – additional DXF attributes for the ATTRIB entity

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()

Reset block reference parameters location, rotation and extrusion vector.

New in version 0.11.

ucs() → UCS

Returns an UCS placed at the block reference insert location, UCS axis aligned to the block axis.

New in version 0.11.

transform_to_wcs(ucs: UCS) → Insert

Transform INSERT entity and attached ATTRIB entities from local UCS coordinates to WCS coordinates.

New in version 0.11.